key
menu

Core Concepts Primer

Understanding ULDA's core concepts is key to using the library effectively. Below are the main components:

  • Master File:

    • A master file is the top-level container for organizing content files. It acts as a secure vault that stores metadata and access controls for associated content files.
    • Created using createMasterFile(name, password) and accessed via connect(masterFileIdOrName, password).
    • The password can be updated using changeMasterFilePassword(newPassword: string) to enhance security or recover access.
    • Naming Rule: Master file names must be unique within the scope of a single API key to prevent conflicts.
    • Encrypted with AES-CBC and protected by a password-derived key using PBKDF2.
    • Example: A master file named userVault might store multiple user profiles as content files. For personalized naming, you can use a user’s nickname (e.g., alice123) or email address (e.g., alice@example.com) as the master file name, ensuring uniqueness within your API key’s scope. For instance, createMasterFile('alice@example.com', ' securePass') creates a master file tied to Alice’s email.

  • Content File:

    • Content files are individual data objects stored within a master file. They contain user-defined JSON data (e.g., { username: 'Bob', email: 'bob@example.com' }).
    • Managed via the ulda.data object, where each content file is accessible by its name (e.g., ulda.data['bobProfile']).
    • Support operations like creation (createContentFile), updating (ulda.data[name].update), and deletion ( ulda.data[name].delete).
    • Naming Rule: Content file names must be unique within the same master file to ensure proper organization and access.
    • Encrypted and signed for security, ensuring data integrity and confidentiality.

  • ulda.data Object:

    • A dynamic map that provides intuitive access to content files. Each entry includes:
      • id: Unique identifier (number).
      • name: File name (string).
      • content: The file's data (JSON object or string).
      • update(newData): Merges new data into the file.
      • delete(): Removes the file.
    • Example: ulda.data['myFile'].content retrieves the data, and ulda.data['myFile'].update({ key: 'value' }) updates it.

  • WebSocket Communication:

    • ULDA uses WebSockets (via socket.io-client) for real-time synchronization between clients and the server.
    • Methods like connectToUpdateContentFile allow you to listen for updates or deletions, ensuring immediate data consistency.
    • Example: Setting up a listener to log content file updates in real time.

  • Cryptographic Signatures:

    • ULDA employs the Web Crypto API to generate and verify signatures, ensuring data integrity.
    • The ulda0 object provides advanced cryptographic utilities (e.g., generateSignatures, sha256) for custom tasks.
    • Signatures are used internally to validate file operations and can be customized for specific use cases.

These concepts form the foundation of ULDA's secure, real-time data management capabilities. Master files organize your data, content files store it, the ulda.data object simplifies access, WebSockets keep it synchronized, and cryptographic signatures protect it.

Getting Started