Entities & Memberships

Entities are Literal's way of organizing users into groups — like companies, teams, or institutions. Even the membership roster is protected from the server.

Consumer vs. Institutional Scope

Literal operates in two scopes:

• Consumer scope — a user manages their own documents and keys independently.
• Institutional scope — users operate as members of an organization; documents, search indexes, and encryption keys are shared across the entity's membership.

A single user can operate in both scopes simultaneously.

What Is An Entity?

An entity represents an organization in Literal — a company, institution, or group that needs to share and manage documents collaboratively. When created, the secure enclave generates a unique organization secret (EMK) that roots all entity-level encryption: the entity's name, metadata, member keys, and search indexes.

The server stores only ciphertext and cannot read the organization's name or any descriptive information.

How Membership Works

Entities support two roles:

• Admin — can add and remove members and perform all member operations.
• Member — can access entity documents and search the entity's document pool.

Persistent membership records use three blind tokens in place of plaintext foreign keys: entity_token identifies the entity, entity_member_token identifies a member within the entity, and user_member_token identifies the user across all their memberships. The server can match these tokens for equality but cannot reverse them to recover the underlying identifiers. API responses do return entity_id and membership_id as routing identifiers for the authenticated caller.

Adding A Member

When an administrator adds someone to an entity:

1. The admin provides the new member's public encryption key.
2. A cryptographic commitment (a one-way hash of the member's signing key) is stored as a hash-lock — this ensures that only the intended person can complete the membership claim.
3. The membership record is created in a pending state.

Claiming Membership

The new member completes the process by claiming their membership:

1. The member presents their signing key and produces a cryptographic signature proving they possess the private key that matches the hash-lock commitment.
2. The server verifies the hash-lock and the signature.
3. The secure enclave derives the entity encryption key (EEK) and wraps it with the member's hybrid public key (ML-KEM + X25519).
4. The member stores their wrapped EEK — only they can unwrap it to decrypt organization metadata client-side.

After claiming, the member can derive all the keys needed to access entity documents, search the entity's document pool, and participate in the organization.

Delivery Keys

Completing the claim also populates two delivery public keys on the membership record: delivery_mlkem_ek (ML-KEM-1024 encapsulation key) and delivery_dsa_vk (hybrid ML-DSA-65 + Ed25519 verifying key). These are returned on the member list and used by entity admins to target a delivery at a specific member.

Members who have not completed the claim have no delivery keys and are excluded from the list. If a member appears in GET /v1/entities/{id}/memberships, they can receive deliveries.

Why This Is Secure

• The hash-lock ensures that only the intended recipient can claim the membership — even if an attacker intercepts the invitation, they cannot complete the claim without the correct signing key.
• The member key wrapping uses the member's own public key, so only the member can unwrap it.
• Both the hash-lock verification and signature verification use hybrid cryptographic schemes that resist both current and future quantum computing attacks.

Zero-Knowledge Membership

Literal goes further than just encrypting entity data — the membership records themselves are protected:

• No plaintext user or entity IDs are stored in membership records. Traditional database foreign keys have been replaced with one-way cryptographic tokens.
• The server can look up a membership by matching tokens, but it cannot determine which user belongs to which entity by reading the database.
• When a member needs to perform operations that require their identity (like re-indexing documents), their user ID is encrypted — encrypted inside the secure enclave with a key bound to the specific entity. The server stores only the opaque encrypted blob and cannot read it.

Encrypted Membership Identity

Each membership record stores a sealed_user_id — an AES-256-GCM ciphertext of the member's user ID, sealed with a key derived as:

SEAL_KEY = HKDF-SHA256(ikm=EMK, salt="kyndex-user-id-seal-v1", info=entity_id)
AAD      = "kyndex-sealed-userid-v1:{entity_id}"

The sealed blob is written by the enclave during the GrantEntityAccess operation — not at membership creation. The server stores only the opaque blob and passes it back to the enclave during BatchReindex, where it is unsealed internally to recover the user ID for key derivation. The plaintext user ID never leaves the enclave.

Cross-entity replay is prevented cryptographically: the AAD binds the blob to a specific entity, so a blob sealed for one entity will fail decryption in another.

This ensures that even the membership roster cannot be used to correlate users to organizations.

Entity-Level Encryption

Each entity has its own set of derived keys:

• Organization encryption key — encrypts the entity's name and metadata.
• Organization search key — generates blind index tokens for entity-scoped document search.
• Member keys — per-member keys that enable access to entity documents through the member's own key chain.

All of these keys are derived from the entity's master secret inside the secure enclave. The server never sees any of them in plaintext.

Related Concepts

• Key Hierarchy — detailed breakdown of how entity master keys, member keys, and document keys are derived
• Grants & Sharing — how documents are shared within and across entities using cryptographic grants
• Entity Deliveries — push an encrypted document key directly to a specific member
• Blind Routing — how Literal routes requests without learning which entity or user is involved
• Zero-Knowledge Model — the broader security model that underpins entity privacy and encrypted membership identity