TrailAccess
@iota/audit-trails API documentation
Class: TrailAccess
Access-control API scoped to a specific trail.
Remarks
Exposes role-management and capability-management operations for one trail. Per-role operations live on RoleHandle, which is reached through TrailAccess.forRole.
Methods
toJSON()
toJSON():
Object
- Return copy of self without private attributes.
Returns
Object
toString()
toString():
string
Return stringified version of self.
Returns
string
cleanupRevokedCapabilities()
cleanupRevokedCapabilities():
TransactionBuilder<CleanupRevokedCapabilities>
Builds a cleanup transaction for expired revoked-capability entries.
Returns
TransactionBuilder<CleanupRevokedCapabilities>
A TransactionBuilder wrapping the CleanupRevokedCapabilities transaction.
Remarks
Only prunes denylist entries whose stored validUntil is non-zero and strictly less than
the current clock time. Entries with validUntil == 0 (revocations without a known expiry)
remain on the denylist indefinitely. Does not revoke additional capabilities and does not
destroy any objects.
Requires the Permission.RevokeCapabilities permission.
Throws
When the wrapper was created from a read-only client.
Emits a RevokedCapabilitiesCleanedUp event on success.
destroyCapability()
destroyCapability(
capability_id):TransactionBuilder<DestroyCapability>
Builds a capability-destruction transaction.
Parameters
capability_id
string
Returns
TransactionBuilder<DestroyCapability>
A TransactionBuilder wrapping the DestroyCapability transaction.
Remarks
Consumes the owned capability object and removes any matching denylist entry. This path is for ordinary capabilities only — initial-admin capabilities must use TrailAccess.destroyInitialAdminCapability.
Requires the Permission.RevokeCapabilities permission.
Throws
When capabilityId is malformed or the wrapper was created from a read-only
client.
Emits a CapabilityDestroyed event on success.
destroyInitialAdminCapability()
destroyInitialAdminCapability(
capability_id):TransactionBuilder<DestroyInitialAdminCapability>
Builds an initial-admin-capability destruction transaction.
Parameters
capability_id
string
Returns
TransactionBuilder<DestroyInitialAdminCapability>
A TransactionBuilder wrapping the DestroyInitialAdminCapability transaction.
Remarks
Self-service: the holder consumes their own initial-admin capability without presenting another authorization capability. Initial-admin capability IDs are tracked separately and cannot be removed through the generic destroy path. Warning: if every initial-admin capability is destroyed (and none was issued separately), the trail is permanently sealed with no admin access possible.
Throws
When capabilityId is malformed or the wrapper was created from a read-only
client.
Emits a CapabilityDestroyed event on success.
forRole()
forRole(
name):RoleHandle
Returns a role-scoped handle for the given role name.
Parameters
name
string
Role name to bind the handle to.
Returns
A RoleHandle bound to name inside this trail.
Remarks
The returned handle only identifies the role. If a role with name does not yet exist, the
handle can still be used to create it via RoleHandle.create.
revokeCapability()
revokeCapability(
capability_id,capability_valid_until?):TransactionBuilder<RevokeCapability>
Builds a capability-revocation transaction.
Parameters
capability_id
string
capability_valid_until?
bigint | null
Returns
TransactionBuilder<RevokeCapability>
A TransactionBuilder wrapping the RevokeCapability transaction.
Remarks
Adds capabilityId to the trail's revoked-capability denylist. Initial-admin capabilities
cannot be revoked through this path — use
TrailAccess.revokeInitialAdminCapability instead.
Requires the Permission.RevokeCapabilities permission.
Throws
When capabilityId is malformed or the wrapper was created from a read-only
client.
Emits a CapabilityRevoked event on success.
revokeInitialAdminCapability()
revokeInitialAdminCapability(
capability_id,capability_valid_until?):TransactionBuilder<RevokeInitialAdminCapability>
Builds an initial-admin-capability revocation transaction.
Parameters
capability_id
string
capability_valid_until?
bigint | null
Returns
TransactionBuilder<RevokeInitialAdminCapability>
A TransactionBuilder wrapping the RevokeInitialAdminCapability transaction.
Remarks
Same denylist semantics as TrailAccess.revokeCapability but uses the dedicated entry point reserved for initial-admin capability IDs. Warning: revoking every initial-admin capability permanently seals the trail with no admin access possible.
Requires the Permission.RevokeCapabilities permission.
Throws
When capabilityId is malformed or the wrapper was created from a read-only
client.
Emits a CapabilityRevoked event on success.