Glossary
Shared protocol terms used across the technical documents.
Published from docs/glossary.md (GitHub)
This glossary defines shared protocol terms used across the Tearleads docs. It is a reading aid; executable request, response, and verifier behavior remains defined by the shared validators, crypto verifiers, API workflows, and app workflows named in protocol-specification.md.
Access Epoch
The monotonically advancing epoch of an access manifest or encrypted content key. Document updates are epoch-bound: clients decrypt an update only with the document key material for the update’s epoch.
Related docs:
Access Event
A signed mutation statement for an access-relevant change, such as
container.grant, document.link, or attachment.bind. The event commits to
the object, previous manifest, dependency manifests, event body hash, signer
identity, timestamp, and signature.
Related docs:
Access Manifest
A canonical, client-verifiable snapshot derived from signed access events. A manifest commits to object identity, organization, epoch, predecessor, event hash, structural state, grants, referenced principal heads, and key-target hash. Projection rows are caches of manifest state; they are not authority.
Related docs:
Access Plane
The protocol plane that owns authorization state and key-target derivation. It includes signed principal policies, access manifests, container KEKs, content-key bundles, and write headers.
Related docs:
Attachment Binding
A server-visible signed relationship between a document slot and a blob. Active bindings are the authority for attachment listing, blob reachability, blob read access, replacement, and detach behavior.
Related docs:
Attachment Plane
The protocol plane for encrypted blob staging and signed attachment bind/detach metadata. Attachment metadata stays server-indexable even though blob bytes and document content remain encrypted.
Related docs:
Attachment Slot
An opaque stable identifier inside a document, such as a product-level “front
image” or “back image” slot. The protocol only treats it as a slotId; at
most one active binding may occupy a slot at a time.
Related docs:
Authorizing Container Path
A verified chain of container manifest heads from an access root toward a target container. The path proves that a user has read, write, or admin access through signed container state rather than through a server-authored ACL row.
Related docs:
Blob
An encrypted binary object stored separately from document CRDT updates. Blob access is derived from active signed attachment bindings and the linked document/container access graph.
Related docs:
Blob Content-Key Bundle
The wrapped blob content key plus the derived container KEK target envelopes for the blob’s active attachment bindings. The bundle is persisted in blob content-key epoch and target rows, returned by attachment listing or bind responses, and is not embedded in committed blob encrypted bytes.
Related docs:
Blob Stage
A temporary holding record for encrypted blob bytes before an attachment bind promotes them to committed blob storage. The server validates byte length, digest, ownership, and expiry, but does not decrypt the bytes. Stages are multipart uploads that the attachment bind assembles and verifies.
Related docs:
Commit LSN
The Postgres WAL log sequence number returned by sync responses after accepted writes or read-only observations. Clients can use it as a consistency hook for replica-safe read-after-write behavior.
Related docs:
Container
The tree-structured object where access control is applied. A container carries direct grants, parent linkage, a metadata document id, and a current container KEK epoch. Documents appear under containers through document link-set manifests; a document may be linked to more than one container in the same organization.
Related docs:
Container KEK
A container key-encryption key. Container KEKs deliver document and blob content keys to authorized targets without exposing plaintext content keys to the server. Each container has a current KEK epoch, and child containers may inherit through parent KEK edges.
Related docs:
Container KEK Keyring
The container’s complete predecessor KEK history sealed under the current epoch’s KEK — the snapshot read path for history-inclusive access. One decrypt yields every retained historical KEK; each entry is verified against its material-committing epoch id, and the sealed length is an exact function of the epoch number. Rewritten at every rotation by re-sealing the previous entries plus the retiring key. Distinct from the Local Keyring, which wraps a device’s root key material.
Related docs:
Container KEK Predecessor Bridge
The write-once append-only log entry a rotation stores alongside the keyring:
the retiring KEK encrypted under the new KEK, hash-committed by the signed
rotation event. Never rewritten by later rotations, which makes the bridge
log ground truth for rebuilding a damaged keyring via
GET /containers/:id/kek-log.
Related docs:
Content Key
The symmetric key used to encrypt a document update stream or blob record. It is wrapped to the current verified target set rather than stored in plaintext server-side.
Related docs:
Content-Key Bundle
The collection of wrapped content-key material for one document or blob content key epoch. A bundle must match the target hash derived from verified access state before the API or app accepts it.
Related docs:
DEK
Data-encryption key. In these docs, DEK usually means the plaintext symmetric content key for a document epoch or blob record. The server stores ciphertext and wrapped keys, not plaintext DEKs.
Related docs:
Document
An encrypted CRDT object whose plaintext is opaque to the server. Documents do not own direct ACLs. Access is resolved through their signed link-set manifest and the active linked container paths.
Related docs:
Document Link-Set Manifest
The access manifest for a document’s linked container set. It names the
containers that project the document into navigation and access decisions, and
it is advanced by signed document.link and document.unlink events.
Related docs:
Document Plane
The protocol plane for encrypted Loro updates plus visible causal metadata. The server indexes and relays encrypted updates but does not decrypt document content.
Related docs:
Effective Access
The access level derived by walking the relevant signed manifest graph, such as the root-to-target container path and referenced managed-principal policy heads. Effective access is computed from verifiable state, not trusted from a single mutable projection row.
Related docs:
Epoch
A monotonically increasing version for access state or key material. Epochs let clients distinguish current state from historical state and reject stale, conflicting, or unsafe key reuse.
Related docs:
Fail Closed
The rule that missing, stale, malformed, or inconsistent policy and key material causes rejection instead of fallback to a weaker authorization path. Unavailable verification material is an availability failure, not permission to bypass checks.
Related docs:
Grant
A signed read, write, or admin container assignment to a user or group,
inherited along container paths. Group grants require active signed group
policy; organizations receive no grants and use the reserved groups instead.
Related docs:
Key Target
One recipient target for wrapped key material: a user’s encapsulation key, a group principal key, or a container KEK. The target hash commits to the sorted derived target set.
Related docs:
Local Keyring
The SDK helper that wraps one account-root secret with a host-provided wrapping key keystore, persists a manifest through a host-provided manifest store, and derives local SQLite, blob-store, identity-persistence, or custom-purpose keys from that root.
Related docs:
Loro Update
An encrypted CRDT update produced by the Loro document layer. The server can see causal metadata such as version-vector spans, but the update payload remains encrypted with the document content key.
Related docs:
Managed Principal
A group or organization whose membership and key epoch are represented by a signed principal policy chain. Managed-principal grants fail closed when the policy state or member envelopes needed for verification are missing or stale.
Related docs:
Member Envelope
Encrypted key material that delivers a managed principal’s active key epoch to one direct member. Member envelopes must match the active direct membership projection and recipient key fingerprints.
Related docs:
Organization
The top-level ownership and policy boundary for user data. Registration creates
a default organization, reserved Admins and Members groups, and a root
container. The organization row stores adminGroupId and memberGroupId.
Reachability through Admins is org-admin authority. Reachability through
Members is organization membership. Org-manager directory lifecycle is stored
in organization roster entries so disabled users can remain visible after access
removal. Organization policy commits authority, not container grants;
org-manager product roles come from the reserved groups.
Related docs:
Organization Admins Group
The reserved organization-scoped Admins group. Reachable users have
organization-admin authority, including admin-only org-manager mutations and
org-scoped principal policy successor signing when the API verifies that
authority.
Related docs:
Organization Members Group
The reserved organization-scoped Members group. Reachable users belong to the
organization. Active roster entries are synchronized from this group’s signed
reachability, but disabled roster entries may remain visible without granting
access. Admins is not nested into Members — principals contain only users —
so the policy write instead rejects any managed principal naming a user who is
not an active roster entry, which keeps every admin an organization member.
Organization Roster Entry
An organization-scoped product row that records directory lifecycle state for a
user. It stores server-visible routing/status metadata such as status,
joinedAt, disabledAt, disabledByUserId, and optional profileDocumentId.
It does not store plaintext profile fields such as email, first name, or last
name; those belong in encrypted documents.
Related docs:
Principal
An entity that can receive access or key material. Users are principals with registered signing and encapsulation keys; groups and organizations are managed principals with signed policy state.
Related docs:
Principal Policy State
The signed state chain for a managed principal. It commits to membership, projection roots, key epoch, encrypted payload hash, signer, and predecessor state so clients can verify group or organization authority.
Related docs:
Projection Row
A relational index or cache derived from signed protocol state. Projection rows help list, lookup, and sync performance, but clients must not treat them as authorization authority by themselves.
Related docs:
Rekey
The operation of advancing key material to a new epoch. Container rekeys rotate container KEKs; document or blob rekeys advance content-key material for later writes.
Related docs:
Rewrap
An additive-access operation that keeps the same plaintext content key but adds or updates wrapped key material for a changed target set. Rewrap does not by itself require re-encrypting document content.
Related docs:
Rotate
A subtractive-access operation that stops using prior plaintext key material for future writes. For documents, rotate means later writes use a fresh DEK and normally begin from a fresh encrypted baseline.
Related docs:
Root Container
The top container for an organization. It has no parent container and anchors the container hierarchy used for path-based access resolution.
Related docs:
Signed Write Header
A signed commitment that binds an encrypted document update or blob record to the object id, access manifest hash, content-key epoch, target hash, metadata hash, ciphertext hash, nonce domain, writer identity, and encryption suite.
Related docs:
Target Hash
The digest of the sorted derived key target set for a document, blob, or manifest state. A submitted content-key bundle or write header must match the expected target hash before it is accepted.
Related docs:
Version Vector
Visible causal metadata for Loro sync. Clients submit their local frontier, and the server uses stored update spans to return encrypted updates not covered by that frontier.
Related docs:
Writer Projection
A server response that packages an object’s signed access history, wrapped key material, and key targets so a client can unwrap its keys and prepare writes. Serving one requires current read access; write authorization is checked when a write commits.
Related docs: