ACLChain
Defined in: packages/core/src/acl-chain.ts:458
An append-only, hash-linked log of signed ACL changes.
Each entry is verified before being applied:
- Its signature must match its declared signer key.
- The signer must be a writer in the state immediately before this entry (or in ACLChainConfig.genesisAuthorizedKeys for the first entry).
- Its
parentHashmust match the hash of the current head. - Its
sequenceNumbermust be exactly the prior length.
Verified entries are appended and the chain’s state is advanced.
Type Parameters
Section titled “Type Parameters”ChangesType
Section titled “ChangesType”ChangesType
The CRDT change block type produced by the ACL.
PrivateKey
Section titled “PrivateKey”PrivateKey
The private key type used by the auth provider.
PublicKey
Section titled “PublicKey”PublicKey
The public key type used by the auth provider.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new ACLChain<
ChangesType,PrivateKey,PublicKey>(_config,serializeChange):ACLChain<ChangesType,PrivateKey,PublicKey>
Defined in: packages/core/src/acl-chain.ts:481
Parameters
Section titled “Parameters”_config
Section titled “_config”ACLChainConfig<ChangesType, PrivateKey, PublicKey>
serializeChange
Section titled “serializeChange”(change) => Uint8Array
Adapter for converting an opaque ChangesType to bytes for signing
and hashing. Required because the chain has no direct knowledge of
the CRDT change format.
Returns
Section titled “Returns”ACLChain<ChangesType, PrivateKey, PublicKey>
Accessors
Section titled “Accessors”headHash
Section titled “headHash”Get Signature
Section titled “Get Signature”get headHash():
Uint8Array<ArrayBufferLike> |undefined
Defined in: packages/core/src/acl-chain.ts:506
Hash of the most recently appended entry, or undefined if the chain
is empty.
Use this as the parentHash for the next entry you author.
Returns
Section titled “Returns”Uint8Array<ArrayBufferLike> | undefined
length
Section titled “length”Get Signature
Section titled “Get Signature”get length():
number
Defined in: packages/core/src/acl-chain.ts:496
Number of entries currently in the chain.
Returns
Section titled “Returns”number
Get Signature
Section titled “Get Signature”get state():
ACLState<ChangesType,PublicKey> |undefined
Defined in: packages/core/src/acl-chain.ts:1035
Current state of the ACL after applying every entry in the chain.
undefined if the chain is empty (no entries have been applied yet).
Returns
Section titled “Returns”ACLState<ChangesType, PublicKey> | undefined
Methods
Section titled “Methods”authorAndAppend()
Section titled “authorAndAppend()”authorAndAppend(
change,signerPublicKey,signerPrivateKey,timestamp?):Promise<ACLEntry<ChangesType>>
Defined in: packages/core/src/acl-chain.ts:566
Build, sign, and append a new entry authored by signerKey.
The signer must currently be authorized (a writer in the chain’s
current state, or in genesisAuthorizedKeys for the genesis entry).
On success the entry is verified, applied to the chain’s internal
state, and returned for transmission to peers.
Concurrent authorAndAppend / ingestEntry calls are
serialized via an internal queue, so each call sees a consistent
_entries.length, head hash, and ACL state during its checks.
Parameters
Section titled “Parameters”change
Section titled “change”ChangesType
signerPublicKey
Section titled “signerPublicKey”PublicKey
signerPrivateKey
Section titled “signerPrivateKey”PrivateKey
timestamp?
Section titled “timestamp?”number = ...
Returns
Section titled “Returns”Promise<ACLEntry<ChangesType>>
Throws
Section titled “Throws”Error if the signer is not authorized — this is a programmer
error and indicates a misuse of the API, not a network attack.
Network-supplied entries should be passed through ingestEntry
instead, which returns a structured error rather than throwing.
Errors from ACLChainConfig.serializeKey (e.g. unsupported key
types) and from ACLChainConfig.auth’s sign method (e.g.
WebCrypto failures, key/algorithm incompatibility, hardware backend
errors) also propagate as a rejected promise.
entries()
Section titled “entries()”entries(): readonly
ACLEntry<ChangesType>[]
Defined in: packages/core/src/acl-chain.ts:524
Snapshot of the chain’s entries. Returns a shallow copy so callers can iterate without risk of seeing live mutations from concurrent appends.
The entries themselves are the chain’s internal snapshots of the
originally-ingested entries (see _ingestEntryInternal); their byte
fields are private copies that do not alias caller-owned buffers.
They are still not frozen, so do not mutate the returned objects —
doing so would corrupt subsequent reads through entries() and
could desynchronize a serialized chain on the wire from this
instance’s view.
Returns
Section titled “Returns”readonly ACLEntry<ChangesType>[]
ingestEntry()
Section titled “ingestEntry()”ingestEntry(
entry,signerPublicKey):Promise<ACLChainVerifyResult>
Defined in: packages/core/src/acl-chain.ts:619
Verify and apply a (presumably network-supplied) entry.
Returns a structured result rather than throwing so callers can log
and discard malicious or stale entries without unwinding their own
control flow. Malformed runtime data (wrong field types, oversized
byte buffers, exceptions thrown by serializeKey/serializeChange)
is surfaced as a 'malformed-entry' result rather than propagating
as an exception, so a single hostile entry cannot DoS the caller.
Concurrent invocations are serialized via an internal queue so each call observes a consistent prior chain state.
Parameters
Section titled “Parameters”ACLEntry<ChangesType>
The signed entry to apply.
signerPublicKey
Section titled “signerPublicKey”PublicKey
The public key that the caller claims signed
entry. The chain verifies that this key matches
entry.signerKeyId (via SerializePublicKey) AND that it
actually signed the payload.
Returns
Section titled “Returns”Promise<ACLChainVerifyResult>
replay()
Section titled “replay()”replay(
entries,resolveKey):Promise<ACLChainVerifyResult>
Defined in: packages/core/src/acl-chain.ts:971
Re-verify the entire chain from genesis. Used at load time when receiving a chain snapshot from a peer.
Stops at the first invalid entry and returns its index. On success
the chain has the same state as if every entry had been ingested
individually.
Runs under the mutation queue, so concurrent ingestEntry /
authorAndAppend / replay calls observe a consistent chain
throughout the replay.
Partial-success contract: replay() first resets _entries,
_entryHashes, and _state, then ingests the supplied entries in
order. If verification fails at entry i, the method returns early
with that failure result and the chain is left containing the valid
prefix entries[0..i-1] along with the corresponding _state. The
prior chain contents are not restored. Callers who need transactional
“all-or-nothing” semantics should snapshot the chain before calling
replay() and decide what to do based on the returned result.
Parameters
Section titled “Parameters”entries
Section titled “entries”readonly ACLEntry<ChangesType>[]
The full chain to verify. Each entry’s signer key must
be resolvable via resolveKey(signerKeyId). If resolveKey
returns undefined, the entry is rejected with
'unknown-signer-key'.
resolveKey
Section titled “resolveKey”(signerKeyId) => Promise<PublicKey | undefined>
Returns
Section titled “Returns”Promise<ACLChainVerifyResult>