BeeKEM
Defined in: packages/core/src/beekem/beekem.ts:128
BeeKEM: Binary ratchet tree for decentralized group key agreement.
Based on Ink & Switch’s Keyhive specification. Tree paths are logarithmic. V2 updates additionally carry a linear public snapshot and an exact parent commitment; every transition must be applied in order, or the member must recover from persisted current ratchet state or a fresh authenticated Welcome/remove-rejoin. An ordinary encrypted document load cannot reconstruct private tree state.
Tree layout uses left-balanced binary tree indexing:
- Leaf nodes (even indices) hold member ECDH key pairs
- Internal nodes (odd indices) hold derived key pairs
- The root node’s key material is the shared group secret
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new BeeKEM():
BeeKEM
Returns
Section titled “Returns”BeeKEM
Accessors
Section titled “Accessors”generation
Section titled “generation”Get Signature
Section titled “Get Signature”get generation():
number|null
Defined in: packages/core/src/beekem/beekem.ts:910
Monotonic generation, or null before initialization.
Returns
Section titled “Returns”number | null
memberCount
Section titled “memberCount”Get Signature
Section titled “Get Signature”get memberCount():
number
Defined in: packages/core/src/beekem/beekem.ts:900
Number of leaves in the tree (including blanked positions).
Returns
Section titled “Returns”number
myLeafIndex
Section titled “myLeafIndex”Get Signature
Section titled “Get Signature”get myLeafIndex():
number
Defined in: packages/core/src/beekem/beekem.ts:905
Our leaf index in the tree.
Returns
Section titled “Returns”number
Methods
Section titled “Methods”addMember()
Section titled “addMember()”addMember(
memberPublicKey):Promise<{pathUpdate:PathUpdateV2;rootSecret:Uint8Array;welcome:BeeKEMWelcomeV2; }>
Defined in: packages/core/src/beekem/beekem.ts:188
Add a new member to the group. Creates a new leaf and derives keys along the path to root. Returns a path update message to broadcast and a welcome for the new member.
Parameters
Section titled “Parameters”memberPublicKey
Section titled “memberPublicKey”CryptoKey
Returns
Section titled “Returns”Promise<{ pathUpdate: PathUpdateV2; rootSecret: Uint8Array; welcome: BeeKEMWelcomeV2; }>
Throws
Section titled “Throws”If a live leaf already owns memberPublicKey.
addMemberTransactionally()
Section titled “addMemberTransactionally()”addMemberTransactionally<
T>(memberPublicKey,commit):Promise<T>
Defined in: packages/core/src/beekem/beekem.ts:203
Add a member and run a caller-supplied commit inside the same tree transaction. If the commit rejects, every BeeKEM mutation is restored.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”memberPublicKey
Section titled “memberPublicKey”CryptoKey
commit
Section titled “commit”(result) => Promise<T>
Returns
Section titled “Returns”Promise<T>
clone()
Section titled “clone()”clone():
BeeKEM
Defined in: packages/core/src/beekem/beekem.ts:138
Copy stable tree state for a document membership transaction.
Returns
Section titled “Returns”BeeKEM
compact()
Section titled “compact()”compact():
void
Defined in: packages/core/src/beekem/beekem.ts:1035
Remove blanked leaf nodes and their parent path nodes from the tree when an entire subtree is blanked. This reclaims memory for nodes that can never contribute to key derivation.
Returns
Section titled “Returns”void
compactAsync()
Section titled “compactAsync()”compactAsync():
Promise<void>
Defined in: packages/core/src/beekem/beekem.ts:1045
Queue compaction behind any active BeeKEM transition.
Returns
Section titled “Returns”Promise<void>
findLeafByPublicKey()
Section titled “findLeafByPublicKey()”findLeafByPublicKey(
publicKey):Promise<number|undefined>
Defined in: packages/core/src/beekem/beekem.ts:983
Find the node index of the unique live leaf whose public key matches
publicKey, or undefined if no such leaf exists or the key appears in
more than one non-blanked leaf.
Used by PeerborneDocument as the canonical source of truth for live
leaf-index lookup during reader revocation and writer promotion. The
writer’s in-memory leaf-index cache can be missing, so role transitions
must be able to recover an unambiguous assignment from tree state alone.
Comparison is done over the raw exported ECDH public key bytes:
CryptoKeyinputs are exported viacrypto.subtle.exportKey('raw', ...)so the caller doesn’t need to pre-export.Uint8Arrayinputs must be genuine, unshared, exactlyECIES_P256_PUBLIC_KEY_LENGTH(65) byte SEC1-uncompressed P-256 keys, the same shape stored on the wire and accepted byaddMember/PeerborneDocument._prepareBeeKEMReaderRegistration. They are copied before any await, so later caller mutation cannot redirect the lookup.
Blanked leaves (publicKey === null) are skipped: their slot index is meaningless to a “find this member” query, and a match against a blanked leaf would let stale public-key references re-resolve to an already-removed slot.
Returns the node index (even-indexed tree slot), which is the
form removeMember consumes. Callers that need the dense
leaf-position form should convert via TreeMath.nodeToLeafIndex.
Parameters
Section titled “Parameters”publicKey
Section titled “publicKey”Uint8Array<ArrayBufferLike> | CryptoKey
Returns
Section titled “Returns”Promise<number | undefined>
Throws
Section titled “Throws”If a Uint8Array input is not a genuine, unshared 65-byte view, or a CryptoKey input exports to raw bytes of another length.
getRootSecret()
Section titled “getRootSecret()”getRootSecret():
Promise<Uint8Array<ArrayBufferLike>>
Defined in: packages/core/src/beekem/beekem.ts:824
Get the current root secret (shared by all members). Hashes extractable root key material; a single-member tree with the canonical non-extractable KEM key uses a domain-separated ECDH transcript.
Returns
Section titled “Returns”Promise<Uint8Array<ArrayBufferLike>>
hasLiveLeafWithPublicKey()
Section titled “hasLiveLeafWithPublicKey()”hasLiveLeafWithPublicKey(
publicKey):Promise<boolean>
Defined in: packages/core/src/beekem/beekem.ts:945
Return whether any live leaf owns publicKey, including duplicates.
publicKey follows the same input rules as findLeafByPublicKey.
Parameters
Section titled “Parameters”publicKey
Section titled “publicKey”Uint8Array<ArrayBufferLike> | CryptoKey
Returns
Section titled “Returns”Promise<boolean>
Throws
Section titled “Throws”If a Uint8Array input is not a genuine, unshared 65-byte view, or a CryptoKey input exports to raw bytes of another length.
hasOnlyLocalLiveLeaf()
Section titled “hasOnlyLocalLiveLeaf()”hasOnlyLocalLiveLeaf():
boolean
Defined in: packages/core/src/beekem/beekem.ts:922
Return true only when the tree contains exactly one live leaf and that leaf is the local member. Blanked and missing leaf slots do not count.
This is intentionally stricter than checking memberCount === 1 because
removed members leave blanked positions behind. Callers use this as proof
that no remote member remains when identity-to-leaf caches are absent.
Returns
Section titled “Returns”boolean
initialize()
Section titled “initialize()”initialize(
privateKey,publicKey):Promise<void>
Defined in: packages/core/src/beekem/beekem.ts:160
Initialize as the first member of a new group. Creates a single-leaf tree with the creator’s key pair.
Parameters
Section titled “Parameters”privateKey
Section titled “privateKey”CryptoKey
publicKey
Section titled “publicKey”CryptoKey
Returns
Section titled “Returns”Promise<void>
processPathUpdate()
Section titled “processPathUpdate()”processPathUpdate(
update):Promise<Uint8Array<ArrayBufferLike>>
Defined in: packages/core/src/beekem/beekem.ts:403
Process a path update from another member. Decrypts the relevant encrypted key and derives the new root.
Parameters
Section titled “Parameters”update
Section titled “update”Returns
Section titled “Returns”Promise<Uint8Array<ArrayBufferLike>>
processPathUpdateTransactionally()
Section titled “processPathUpdateTransactionally()”processPathUpdateTransactionally<
T>(update,commit):Promise<T>
Defined in: packages/core/src/beekem/beekem.ts:420
Internal
Apply an update and a caller-supplied commit as one BeeKEM transaction.
If validation, epoch binding, or durable key installation fails in the
callback, the ratchet state is restored to its exact prior snapshot.
The callback receives duplicate for an exact v2 replay so callers can
validate its epoch binding without appending the same durable key again.
Used by the document wire handler to couple tree advancement with installation of the document key derived from the new root.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”update
Section titled “update”commit
Section titled “commit”(rootSecret, disposition) => Promise<T>
Returns
Section titled “Returns”Promise<T>
processWelcome()
Section titled “processWelcome()”processWelcome(
welcome,privateKey,publicKey):Promise<Uint8Array<ArrayBufferLike>>
Defined in: packages/core/src/beekem/beekem.ts:693
Process a welcome message to join an existing group. Requires a fresh instance: callers replace a live tree by swapping in a newly joined one.
Parameters
Section titled “Parameters”welcome
Section titled “welcome”privateKey
Section titled “privateKey”CryptoKey
publicKey
Section titled “publicKey”CryptoKey
Returns
Section titled “Returns”Promise<Uint8Array<ArrayBufferLike>>
removeMember()
Section titled “removeMember()”removeMember(
memberLeafIndex):Promise<{pathUpdate:PathUpdateV2;rootSecret:Uint8Array; }>
Defined in: packages/core/src/beekem/beekem.ts:282
Remove a member from the group. Blanks the member’s leaf and all nodes on their direct path. Returns a path update with fresh key material.
Parameters
Section titled “Parameters”memberLeafIndex
Section titled “memberLeafIndex”number
Returns
Section titled “Returns”Promise<{ pathUpdate: PathUpdateV2; rootSecret: Uint8Array; }>
removeMemberTransactionally()
Section titled “removeMemberTransactionally()”removeMemberTransactionally<
T>(memberLeafIndex,commit):Promise<T>
Defined in: packages/core/src/beekem/beekem.ts:296
Remove a member and run a caller-supplied commit inside the same tree transaction. If the commit rejects, every BeeKEM mutation is restored.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”memberLeafIndex
Section titled “memberLeafIndex”number
commit
Section titled “commit”(result) => Promise<T>
Returns
Section titled “Returns”Promise<T>
update()
Section titled “update()”update():
Promise<{pathUpdate:PathUpdateV2;rootSecret:Uint8Array; }>
Defined in: packages/core/src/beekem/beekem.ts:372
Perform a self-update that rotates key material along our path. This operation alone does not establish post-compromise security, secret erasure, or recovery after a compromise.
Returns
Section titled “Returns”Promise<{ pathUpdate: PathUpdateV2; rootSecret: Uint8Array; }>