AutomergeKeychain
Defined in: automerge/src/peerborne-automerge.ts:1371
Append-only keychain with canonical 32-byte identifiers.
Implements
Section titled “Implements”Keychain<BinaryChange[],CryptoKey>
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new AutomergeKeychain():
AutomergeKeychain
Returns
Section titled “Returns”AutomergeKeychain
Methods
Section titled “Methods”add():
Promise<[Uint8Array<ArrayBufferLike>,CryptoKey,Change[]]>
Defined in: automerge/src/peerborne-automerge.ts:1378
Generates and adds a new document encryption key to the keychain.
Returns
Section titled “Returns”Promise<[Uint8Array<ArrayBufferLike>, CryptoKey, Change[]]>
The new document key ID, key, and a block of change(s) describing the keychain addition.
Implementation of
Section titled “Implementation of”Keychain.add
addEpochKey()
Section titled “addEpochKey()”addEpochKey(
epochId,key):Promise<Change[]>
Defined in: automerge/src/peerborne-automerge.ts:1428
Add an epoch-based encryption key to the keychain.
Epoch keys are used for key rotation: each epoch has a unique 32-byte ID and an associated AES-GCM symmetric key. The key is cached locally and appended to the Automerge keychain document for synchronization with peers.
Parameters
Section titled “Parameters”epochId
Section titled “epochId”Uint8Array
The 32-byte epoch identifier.
CryptoKey
The AES-GCM CryptoKey for this epoch.
Returns
Section titled “Returns”Promise<Change[]>
The Automerge changes representing the keychain update for broadcasting.
Implementation of
Section titled “Implementation of”Keychain.addEpochKey
current()
Section titled “current()”current():
Promise<[Uint8Array<ArrayBufferLike>,CryptoKey]>
Defined in: automerge/src/peerborne-automerge.ts:1722
Gets the current encryption key that should be used to encrypt new changes.
Returns
Section titled “Returns”Promise<[Uint8Array<ArrayBufferLike>, CryptoKey]>
Implementation of
Section titled “Implementation of”Keychain.current
currentKeyChange()
Section titled “currentKeyChange()”currentKeyChange():
Promise<Change[]>
Defined in: automerge/src/peerborne-automerge.ts:1742
Gets a block of change(s) describing only the current (most recent) key.
Used for current_only key distribution where new members receive the
current encryption key, not the full key history. This does not itself
redact retained CRDT operations encrypted during that epoch.
The returned value MUST be safe to regenerate and replay without creating
a second logical keychain entry, and byte-stable for the same logical key
tuple across repeated calls, restored instances, and equivalent replicas.
Implementations may synthesize a standalone projection only with stable,
content-derived CRDT operation identity; otherwise they MUST reject.
A one-key keychain MUST export its live history so receivers share the
author’s lineage and can merge the author’s next add() delta. Receivers
of a projected later key hold an independent lineage and cannot merge
rotation deltas authored on the full history.
Returns
Section titled “Returns”Promise<Change[]>
A replay-safe block of change(s) containing only the current key.
Implementation of
Section titled “Implementation of”Keychain.currentKeyChange
getKey()
Section titled “getKey()”getKey(
keyIDBytes):CryptoKey|undefined
Defined in: automerge/src/peerborne-automerge.ts:1795
Looks up a document key by its ID.
Parameters
Section titled “Parameters”keyIDBytes
Section titled “keyIDBytes”Uint8Array
Returns
Section titled “Returns”CryptoKey | undefined
The requested document key.
Implementation of
Section titled “Implementation of”Keychain.getKey
history()
Section titled “history()”history():
Change[]
Defined in: automerge/src/peerborne-automerge.ts:1513
Gets a block of change(s) describing the whole state of the keychain.
Returns
Section titled “Returns”Change[]
A block of change(s) describing the keychain.
Implementation of
Section titled “Implementation of”Keychain.history
historySince()
Section titled “historySince()”historySince(
keyID):Promise<Change[]>
Defined in: automerge/src/peerborne-automerge.ts:1771
Return stable existing keychain operations when the requested boundary is the first retained key.
Automerge append operations after a later boundary depend on operations that contain the preceding keys. Reconstructing a minimal suffix under a fresh actor would merge once, but independently regenerated responses would have distinct operation IDs and duplicate entries. Reject boundaries that cannot be served from existing operation history without either that replay ambiguity or disclosure of pre-boundary keys.
Parameters
Section titled “Parameters”Uint8Array
Returns
Section titled “Returns”Promise<Change[]>
Implementation of
Section titled “Implementation of”Keychain.historySince
keys()
Section titled “keys()”keys():
Promise<[Uint8Array<ArrayBufferLike>,CryptoKey][]>
Defined in: automerge/src/peerborne-automerge.ts:1705
Gets the all document encryption keys in the keychain.
Returns
Section titled “Returns”Promise<[Uint8Array<ArrayBufferLike>, CryptoKey][]>
all document encryption keys.
Implementation of
Section titled “Implementation of”Keychain.keys
merge()
Section titled “merge()”merge(
change):void
Defined in: automerge/src/peerborne-automerge.ts:1522
Merges in a block of change(s) to the keychain.
Parameters
Section titled “Parameters”change
Section titled “change”Change[]
A block of change(s) to apply.
Returns
Section titled “Returns”void
Implementation of
Section titled “Implementation of”Keychain.merge
prepareAppend()
Section titled “prepareAppend()”prepareAppend(
changes,intent):PreparedKeychainMerge<Change[],CryptoKey>
Defined in: automerge/src/peerborne-automerge.ts:1532
Stage an authenticated, predecessor-bound standalone key append. This is
distinct from prepareMerge() because append authority must be validated
explicitly.
Implementations MUST require a canonical one-key projection matching
expectedNewKeyId. They may append only when the live current key matches
expectedPreviousKeyId, or return an unchanged exact replay when the live
sequence already ends with the expected previous/new pair and material.
Parameters
Section titled “Parameters”changes
Section titled “changes”Change[]
intent
Section titled “intent”KeychainAppendIntent
Returns
Section titled “Returns”PreparedKeychainMerge<Change[], CryptoKey>
Implementation of
Section titled “Implementation of”Keychain.prepareAppend
prepareEpochKey()
Section titled “prepareEpochKey()”prepareEpochKey(
epochId,key):Promise<PreparedKeychainEpoch<Change[]>>
Defined in: automerge/src/peerborne-automerge.ts:1437
Stage an epoch-key insertion without mutating live keychain state. BeeKEM membership transitions finish all fallible signing, sealing, serialization, and block preparation before a synchronous keychain/tree commit.
commit() MUST either apply the staged state completely or throw before
mutation. It is called at most once, after every asynchronous preparation
step has succeeded.
Core transaction wrappers inspect both this capability and the returned
claimCommit capability without invoking accessors. Implement them as
ordinary prototype methods or own data-property functions.
The epochId width contract is identical to addEpochKey(): it must equal
KeychainProvider.keyIDLength, exactly 32 bytes in the shipped providers,
and a mismatch must be rejected before any state is staged or mutated.
The current BeeKEM wire protocols derive and authenticate fixed 32-byte
epoch IDs, so a custom provider with another key-ID width cannot implement
those transitions.
Parameters
Section titled “Parameters”epochId
Section titled “epochId”Uint8Array
The full-width epoch identifier.
CryptoKey
The encryption key for this epoch.
Returns
Section titled “Returns”Promise<PreparedKeychainEpoch<Change[]>>
Implementation of
Section titled “Implementation of”Keychain.prepareEpochKey
prepareKey()
Section titled “prepareKey()”prepareKey():
Promise<PreparedKeychainAddition<Change[],CryptoKey>>
Defined in: automerge/src/peerborne-automerge.ts:1384
Stage generation and insertion of a random document key without mutating live state. Callers can finish fallible wire preparation before invoking the synchronous commit.
Returns
Section titled “Returns”Promise<PreparedKeychainAddition<Change[], CryptoKey>>
Implementation of
Section titled “Implementation of”Keychain.prepareKey
prepareMerge()
Section titled “prepareMerge()”prepareMerge(
changes):PreparedKeychainMerge<Change[],CryptoKey>
Defined in: automerge/src/peerborne-automerge.ts:1526
Stage a remote keychain merge for an atomic Welcome state commit. Core
transaction wrappers inspect this capability and the prepared
hydrateKeys, getKey, and claimCommit capabilities without invoking
accessors. Implement them as ordinary prototype methods or own
data-property functions.
Parameters
Section titled “Parameters”changes
Section titled “changes”Change[]
Returns
Section titled “Returns”PreparedKeychainMerge<Change[], CryptoKey>
Implementation of
Section titled “Implementation of”Keychain.prepareMerge
stateCommitment()
Section titled “stateCommitment()”stateCommitment():
Promise<Uint8Array<ArrayBufferLike>>
Defined in: automerge/src/peerborne-automerge.ts:1517
Commit to the validated ordered logical key sequence independently of
provider-specific CRDT operation identities. Implementations MUST use
computeKeychainStateCommitment.
Returns
Section titled “Returns”Promise<Uint8Array<ArrayBufferLike>>
Implementation of
Section titled “Implementation of”Keychain.stateCommitment