ACL
Defined in: packages/core/src/acl.ts:83
An ACL keeps track of a list of user’s public keys and produces changes that can be sent to other swarm peers.
Implementations must compare public keys by their provider-defined canonical key material, not JavaScript object reference. Security wrappers may pass a fresh detached object that represents the same canonical identity to each operation.
Implementations that serialize access may reject overlapping calls with ACLOperationInProgressError. External orchestration can use retryACLConflict; backing implementations must propagate the conflict without waiting on it.
Type Parameters
Section titled “Type Parameters”ChangesType
Section titled “ChangesType”ChangesType
A block of CRDT change(s).
PublicKey
Section titled “PublicKey”PublicKey
Type of a user’s public key.
Methods
Section titled “Methods”add(
publicKey):Promise<ChangesType>
Defined in: packages/core/src/acl.ts:90
Add a new user to the ACL.
Parameters
Section titled “Parameters”publicKey
Section titled “publicKey”PublicKey
User’s public key.
Returns
Section titled “Returns”Promise<ChangesType>
A block of change(s) for the addition to the ACL.
check()
Section titled “check()”check(
publicKey,capability?):Promise<boolean>
Defined in: packages/core/src/acl.ts:163
Checks to see if the specified user has a specific capability. If capability is undefined, checks if the user is in the ACL at all.
Parameters
Section titled “Parameters”publicKey
Section titled “publicKey”PublicKey
User’s public key.
capability?
Section titled “capability?”string
Optional capability string to check for.
Returns
Section titled “Returns”Promise<boolean>
true if the user has the specified capability (or is in the ACL if no capability specified).
current()
Section titled “current()”current():
ChangesType
Defined in: packages/core/src/acl.ts:135
Gets a block of change(s) describing the current state of the ACL.
Returns
Section titled “Returns”ChangesType
A block of change(s) describing the whole ACL.
merge()
Section titled “merge()”merge(
changes):boolean|void
Defined in: packages/core/src/acl.ts:153
Applies a block of change(s) to the ACL.
A thrown ACLOperationInProgressError certifies that the merge was rejected at its pre-mutation admission boundary and can be retried after settlement. A thrown ACLMergeRejectedError certifies that the merge was rejected without changing the ACL and must not be retried with the same changes. Generic callers cannot assume any other exception left a custom implementation unchanged, so authorization-sensitive orchestration must fail closed.
Parameters
Section titled “Parameters”changes
Section titled “changes”ChangesType
A block of change(s) to apply.
Returns
Section titled “Returns”boolean | void
false when the merge left the ACL state unchanged, for example
because the block was already merged. An implementation that cannot tell
may return nothing, and callers then treat the merge as a change.
prepareAdd()
Section titled “prepareAdd()”prepareAdd(
publicKey):Promise<PreparedACLChange<ChangesType>>
Defined in: packages/core/src/acl.ts:105
Stage a user addition without mutating the live ACL.
Callers can finish fallible publication work before invoking the
synchronous commit. Implementations MUST detach changes from both the
caller and the private staged state and reject a repeated or stale commit
before mutation. A successful commit MUST apply the staged state
completely. Generic callers MUST treat any other commit exception as an
indeterminate backing state and fail closed; they cannot assume a custom
implementation rolled back a partially applied commit. The shipped CRDT
adapters complete fallible work during preparation and atomically swap
their private staged state only after all commit checks pass.
Parameters
Section titled “Parameters”publicKey
Section titled “publicKey”PublicKey
Returns
Section titled “Returns”Promise<PreparedACLChange<ChangesType>>
prepareRemove()
Section titled “prepareRemove()”prepareRemove(
publicKey):Promise<PreparedACLChange<ChangesType>>
Defined in: packages/core/src/acl.ts:128
Stage a user removal without mutating the live ACL.
Callers can finish fallible publication work before invoking the
synchronous commit. Implementations MUST detach changes from both the
caller and the private staged state and reject a repeated or stale commit
before mutation. A successful commit MUST apply the staged state
completely. Generic callers MUST treat any other commit exception as an
indeterminate backing state and fail closed; they cannot assume a custom
implementation rolled back a partially applied commit. The shipped CRDT
adapters complete fallible work during preparation and atomically swap
their private staged state only after all commit checks pass.
Parameters
Section titled “Parameters”publicKey
Section titled “publicKey”PublicKey
Returns
Section titled “Returns”Promise<PreparedACLChange<ChangesType>>
remove()
Section titled “remove()”remove(
publicKey):Promise<ChangesType>
Defined in: packages/core/src/acl.ts:113
Remove a user from the ACL.
Parameters
Section titled “Parameters”publicKey
Section titled “publicKey”PublicKey
User’s public key.
Returns
Section titled “Returns”Promise<ChangesType>
A block of change(s) for the removal from the ACL.
users()
Section titled “users()”users(
capability?):Promise<PublicKey[]>
Defined in: packages/core/src/acl.ts:171
Returns the list of users with a specific capability. If capability is undefined, returns all users.
Parameters
Section titled “Parameters”capability?
Section titled “capability?”string
Optional capability to filter users by.
Returns
Section titled “Returns”Promise<PublicKey[]>