Capabilities - API reference

Immutable value carrying an authorization to mount a designated namespace subtree with a given set of rights. Both wire presentations (the signed delegation token and the compact bearer name) resolve to a mount-directive; the namespace assembler consumes these objects to build per-connection views.

This is a pure value type: no side effects, no crypto imports, no 9P symbols.

(mount-directive-designation object)

Undocumented: this exported symbol needs a docstring.

(mount-directive-rights object)

Undocumented: this exported symbol needs a docstring.

(mount-directive-rights-bitmask object)

Undocumented: this exported symbol needs a docstring.

(bitmask->rights bits)

Convert integer bitmask BITS back to a keyword list. The returned list preserves declaration order: (:read :write :mount :delegate).

(bitmask->rights 3) => (:READ :WRITE) (bitmask->rights 8) => (:DELEGATE)

(designation-prefix-p parent-designation child-designation)

Return true if CHILD-DESIGNATION is PARENT-DESIGNATION or a path-segment extension of it. Used for attenuation checking: a delegated designation must lie within the granting subtree. The match must land on a path separator, so a grant does not leak across sibling boundaries that merely share a leading substring.

(designation-prefix-p "/proto" "/proto/smtp") => T (designation-prefix-p "/proto" "/proto") => T (designation-prefix-p "/proto/smtp" "/proto") => NIL (designation-prefix-p "/pro" "/proto/smtp") => NIL (designation-prefix-p "/proto" "/protox") => NIL

(make-mount-directive designation rights)

Construct an immutable MOUNT-DIRECTIVE from DESIGNATION (a non-empty string) and RIGHTS (a list of keywords from {:read :write :mount :delegate :admit}).

Signals an error if DESIGNATION is not a non-empty string, or if RIGHTS contains any keyword outside the closed set.

(make-mount-directive "/proto/smtp" '(:read :write)) => a MOUNT-DIRECTIVE with designation "/proto/smtp" and bitmask 3

(rights->bitmask rights)

Convert a keyword list RIGHTS to an integer bitmask. Each keyword in the list must be a member of {:read :write :mount :delegate :admit}. Returns 0 for an empty list.

(rights->bitmask '(:read :write)) => 3 (rights->bitmask '(:delegate)) => 8

(rights-subset-p child-rights parent-rights)

Return true if every right in CHILD-RIGHTS is also in PARENT-RIGHTS. Both arguments are keyword lists from the closed rights set. Used for attenuation checking: a delegated grant must not claim rights the granting token does not itself hold.

(rights-subset-p '(:read) '(:read :write)) => T (rights-subset-p '(:read :write) '(:read)) => NIL

(capability-name-bound-generation instance)

Undocumented: this exported symbol needs a docstring.

(capability-name-designation instance)

Undocumented: this exported symbol needs a docstring.

(capability-name-expiry instance)

Undocumented: this exported symbol needs a docstring.

(capability-name-nonce instance)

Undocumented: this exported symbol needs a docstring.

(capability-name-rights-bitmask instance)

Undocumented: this exported symbol needs a docstring.

(capability-name-signature instance)

Undocumented: this exported symbol needs a docstring.

(decode-capability-name name-string)

Decode a "valis:"-prefixed capability name string.

Returns a DECODED-CAPABILITY-NAME struct with six fields: capability-name-designation : string capability-name-rights-bitmask : integer capability-name-expiry : Unix timestamp integer capability-name-nonce : 16-byte octet vector capability-name-bound-generation : head generation integer capability-name-signature : 64-byte octet vector

The wire decode is the shared hekate bearer-name codec (fail-closed on a wrong prefix, invalid base58btc, a payload too short for the fixed layout, or a length inconsistent with the encoded designation length). This wrapper carries the recovered fields into valis's own struct so OCAP callers keep a stable accessor surface independent of the wire codec's representation.

(encode-capability-name designation rights expiry-unix nonce-16 sig-64 &optional (bound-generation 0))

Encode a capability name as a "valis:"-prefixed base58btc string.

DESIGNATION: a non-empty string naming the namespace subtree granted. RIGHTS: either an integer bitmask or a keyword list from {:read :write :mount :delegate}. If a list, it is converted to a bitmask via RIGHTS->BITMASK. EXPIRY-UNIX: Unix timestamp integer (seconds since 1970-01-01T00:00:00Z). NONCE-16: 16-byte octet vector. SIG-64: 64-byte Ed25519 signature over (NAME-CANONICAL-BYTES …) produced by the owner's custody store. BOUND-GENERATION: the head generation current at mint time, stamped inside the signed canonical bytes. Defaults to 0 (the genesis generation, never fenced) so a caller without a head still encodes a valid genesis-stamped name.

The rights vocabulary is valis's OCAP concern; the wire marshalling is the shared hekate bearer-name codec. Returns a string beginning with "valis:".

(name-canonical-bytes designation rights-bitmask expiry-unix nonce-16 bound-generation)

Lay out the deterministic bytes a bearer-name signature covers.

DESIGNATION is a string, RIGHTS-BITMASK a u8 integer, NONCE-16 a 16-byte octet vector. Two calls with equal fields return EQUALP vectors — the byte-for-byte contract every already-minted name depends on.

Append-only set of 32-byte SHA-256 hashes identifying revoked tokens and capability names. The TABLE maps hash vectors to T for O(1) membership tests (EQUALP so byte-vector keys compare by value). PATH is the backing flat file (a pathname or NIL for in-memory-only stores used in tests). LOCK is held across each revoke, so a reader of the backing file taking it never sees half of an append.

Signalled when no file exists at the requested path, before any store object is made.

Signalled when the bytes at the requested path are not a whole number of 32-byte hashes; LENGTH is the observed file length.

Root of the ways a revocation store cannot be opened; PATH is the path the caller asked for.

(revocation-store-corrupt-length condition)

Undocumented: this exported symbol needs a docstring.

(revocation-store-error-path condition)

Undocumented: this exported symbol needs a docstring.

(fence-epoch-hash superseded-generation)

The 32-byte revocation-set member expressing that SUPERSEDED-GENERATION is fenced: a SHA-256 over a fixed ASCII prefix and the 8-byte big-endian generation.

A head bump appends this hash to the same append-only set that holds revoked token and name hashes, so the verifier's existing membership check rejects a write capability bound to a superseded generation on the same path it rejects a revoked token. The literal ASCII prefix is the collision firewall: token and name hashes are a SHA-256 over canonical bytes and a signature and never begin with a constant string, so a fence-epoch hash can never alias one. Consumers call this constructor rather than re-deriving the format, so the verifier, the eviction sweep, and the tests all agree on one encoding.

(install-revocation-store-octets path octets)

Install OCTETS, a whole revocation store file, at PATH at mode 0600 and return the number of hashes the installed file holds. Where a store already is, the installed file holds every hash of both. Octets that are not a whole number of hashes signal revocation-store-corrupt and nothing is written.

(load-or-create-revocation-store path)

Return a REVOCATION-STORE holding every hash recorded at PATH. Signals REVOCATION-STORE-ABSENT when no file is there, offering the CREATE-EMPTY-STORE restart; signals REVOCATION-STORE-CORRUPT when the bytes are not a whole number of hashes.

(make-revocation-store &key path)

Construct an empty in-memory revocation store. If PATH is non-nil the store is backed by that file; REVOKE-HASH will persist hashes there. No file I/O is performed at construction time.

(revocation-store-contains-p store hash-32-bytes)

Return T if HASH-32-BYTES has been revoked in STORE, NIL otherwise. HASH-32-BYTES must be a 32-byte octet vector (EQUALP comparison).

(revocation-store-file-octets path &key store)

The octets of the revocation store file at PATH, or NIL when no file is there, read under STORE's lock when STORE is the open store backed by PATH. Signals revocation-store-corrupt when the bytes are not a whole number of hashes.

(revoke-hash store hash-32-bytes)

Add HASH-32-BYTES (a 32-octet vector) to STORE, appending it durably to the backing file at mode 0600 when STORE has one, and return no values.

A function of one argument (HASH-32-BYTES) called by REVOKE-HASH after the hash is persisted. Set by start-fabric to #'evict-by-hash from the assembler package; cleared by stop-fabric.

This seam breaks the compile-time dependency cycle: revocation is upstream of assembler (verifier → cap → assembler → root; verifier also imports revocation), so revocation cannot import assembler back. Fabric is downstream of both and installs the hook at start time, matching the base-view-fn pattern in root.

Immutable UCAN-mould capability token. Carries the grant (issuer, audience, capabilities, expiry, nonce) plus the cryptographic proof (signature, canonical-hash) and the ancestry (inline proof chain). All slots are reader-only; the minter constructs a complete instance with MAKE-TOKEN after obtaining the signature and hash from custody.

(token-audience-did object)

Undocumented: this exported symbol needs a docstring.

(token-bound-generation object)

Undocumented: this exported symbol needs a docstring.

(token-canonical-hash object)

Undocumented: this exported symbol needs a docstring.

(token-capabilities object)

Undocumented: this exported symbol needs a docstring.

(token-expiry object)

Undocumented: this exported symbol needs a docstring.

(token-issuer-did object)

Undocumented: this exported symbol needs a docstring.

(token-nonce object)

Undocumented: this exported symbol needs a docstring.

(token-proofs object)

Undocumented: this exported symbol needs a docstring.

(token-signature object)

Undocumented: this exported symbol needs a docstring.

(make-token issuer-did audience-did capabilities proofs expiry nonce signature canonical-hash &optional (bound-generation 0))

Construct a CAPABILITY-TOKEN from the supplied fields.

ISSUER-DID, AUDIENCE-DID: non-empty DID strings. CAPABILITIES: a list of MOUNT-DIRECTIVE objects. PROOFS: a list of parent CAPABILITY-TOKEN objects (empty list for root tokens), ordered immediate-parent first through to the owner-issued root last. EXPIRY: a positive Unix timestamp (nil or zero expiry is rejected: expiry is mandatory on every token). NONCE: a 16-byte octet vector. SIGNATURE: a 64-byte Ed25519 signature over TOKEN-CANONICAL-BYTES. CANONICAL-HASH: a 32-byte SHA-256 hash of (canonical-bytes then signature). BOUND-GENERATION: the head generation current at mint time, stamped inside the signed canonical bytes. A non-negative integer below 2⁶⁴. Defaults to 0 (the genesis generation, which is never fenced) so a caller that does not carry a head still mints a valid genesis-stamped token.

Signals an error if EXPIRY is non-positive, BOUND-GENERATION is out of range, or any fixed-width field is the wrong length: the value type fails closed rather than emit canonical bytes a conformant verifier cannot reconstruct.

(token-canonical-bytes tok)

Produce the deterministic octet vector encoding TOK's grant fields, the bytes the token signature covers. Proofs are excluded: the canonical encoding covers this token's own claim, not its ancestry. Two calls with the same field values return EQUALP vectors.

A thin adapter: it reads TOK's slots and delegates the byte layout to the shared hekate token-wire codec, so valis and every sister that marshals a token lay down byte-identical canonical bytes. Capabilities are handed over as (designation . rights-bitmask) pairs, the field shape hekate's encoder takes.

(token-expired-p tok)

Return T if TOK's expiry (a Unix timestamp) is in the past.

(unix-now &aux (ut (get-universal-time)))

Current time as a Unix timestamp (seconds since 1970-01-01T00:00:00Z).

(token-grant-hash tok)

The 32-byte revocation identity of capability token TOK: SHA-256 of (canonical-bytes || signature). This is the hash the revocation store is keyed by, so recording it at mint time and revoking it later name exactly the token the verifier rejects: the minter, the revocation store, and the enrolled-client record all agree on one encoding because they all call this. Exported so the mint-on-proof driver records the grant hash the verifier will consult, without re-deriving the format.

(verify-capability-name-sig name-string owner-ed25519-pub-bytes revocation-store &key expiry-judged-at)

Verify a capability name string against the owner's Ed25519 public key.

NAME-STRING is a "valis:"-prefixed bearer name. OWNER-ED25519-PUB-BYTES is the 32-byte raw Ed25519 public key that signed it. REVOCATION-STORE is consulted to detect revoked names (revocation applies to names too).

The generation a write-bearing name was bound to is a field on the name (stamped inside the owner-signed canonical bytes at mint time), not a caller- supplied argument. When the name carries the write right, it is fenced using the stamp read from the decoded name: a write-bearing name minted under a superseded generation is rejected on the same revocation store that holds revoked name hashes, so the two share one membership test and cannot drift. A read-only name never reaches the fence path. A write-bearing name whose stamp is missing is rejected (fail closed); the codec normally guarantees the stamp is present.

EXPIRY-JUDGED-AT, a Unix time, is the moment the name's expiry is judged at; when it is NIL expiry is judged now. The signature, revocation and the fence are always judged now.

Returns (values mount-directive nil) if valid; the mount-directive carries the decoded designation and rights for use by the namespace assembler. Returns (values nil reason-string) on any failure. All conditions are caught internally.

(verify-token-chain token owner-ed25519-pub-bytes revocation-store &key expiry-judged-at)

Verify a capability token chain against the owner's Ed25519 public key.

TOKEN is the leaf (or sole) token; its PROOFS list carries parent tokens forming an inline chain. OWNER-ED25519-PUB-BYTES is the 32-byte raw Ed25519 public key of the owner who issued the root token. REVOCATION-STORE is a REVOCATION-STORE object consulted for every token.

The generation a write authority was bound to is a field on the capability (stamped inside the owner-signed canonical bytes at mint time), not a caller- supplied argument. When the leaf token carries the write right, the chain is fenced using the stamp read from the token: a write capability minted under a superseded generation is rejected on the same revocation store that holds revoked token hashes, so the fence and the revocation log share one membership test and cannot drift. A read-only capability never reaches the fence path. A write- bearing token whose stamp is somehow missing is rejected (fail closed); the codec normally guarantees the stamp is present.

EXPIRY-JUDGED-AT, a Unix time, is the moment every link's expiry is judged at; when it is NIL expiry is judged now. It governs the expiry comparison and nothing else: signatures, revocation, the child-outlives-parent check and the fence are judged as they stand now, so a revoked credential stays refused whatever time its expiry is judged at.

Returns (values T nil) if the chain is valid. Returns (values nil reason-string) on any failure. All conditions are caught internally: callers never receive an unhandled signal.

What the store holds for one module designation: the publisher's vouch and the owner's grant as received (bearer text, or NIL when not held), and the Unix time the module was admitted (or NIL until the install path records one).

The owner-held vouch store. STATE is the vouch-state it holds now; a change builds a new state and replaces this one in a single assignment, so a reader sees either the old state or the new one and never a mix. PATH is the backing file, or NIL for a store held only in memory. LOCK is held by every change, so changes never interleave.

Signalled when text offered as a publisher anchor is not an Ed25519 did:key written canonically; DID-KEY is the text offered.

Signalled when a standing grant is filed for a publisher that already holds a different active one. PUBLISHER names the publisher, GRANT is the active grant's text, and GRANT-HASH, when the caller knows it, is that grant's hash as hex. Nothing is written.

Signalled when a standing grant the store holds as withdrawn is filed again. GRANT is its text. Nothing is written.

Signalled when no file exists at the requested path, before any store object is made.

Signalled when the bytes at the requested path do not frame as a vouch store; REASON says where framing failed.

Signalled as a warning when a vouch store write has renamed its new file into place but the directory sync after it fails. The change is on disk and in the store; only its survival of a crash is in doubt.

Root of the ways a vouch store cannot be opened; PATH is the path the caller asked for.

(publisher-anchor-invalid-did-key condition)

Undocumented: this exported symbol needs a docstring.

(standing-grant-already-active-grant condition)

Undocumented: this exported symbol needs a docstring.

(standing-grant-already-active-grant-hash condition)

Undocumented: this exported symbol needs a docstring.

(standing-grant-already-active-publisher condition)

Undocumented: this exported symbol needs a docstring.

(standing-grant-withdrawn-grant condition)

Undocumented: this exported symbol needs a docstring.

(vouch-store-corrupt-reason condition)

Undocumented: this exported symbol needs a docstring.

(vouch-store-error-path condition)

Undocumented: this exported symbol needs a docstring.

(call-with-vouch-store-lock store thunk)

Call THUNK holding STORE's lock and return its values, so a caller can read the store, decide, and change it with no other change landing in between. Changes made inside THUNK take the same lock again without blocking.

(clear-publisher-anchor store did-key)

Stop trusting the publisher DID-KEY names and persist. Returns T when it was filed.

(clear-vouch-designation store designation)

Drop everything held for DESIGNATION and persist. Returns T when anything was held.

(clear-vouch-slot store designation slot)

Empty one SLOT (:publisher-vouch, :owner-grant or :admission-time) for DESIGNATION and persist. An entry left holding nothing is dropped. Returns T when something was held there.

(decode-vouch-store-octets octets &optional path)

The vouch store OCTETS encode, as a store backed by PATH. Signals vouch-store-corrupt, naming PATH, when they do not frame as a store in the layout this node reads.

(file-owner-grant store designation grant)

Hold GRANT, the owner's grant for the module DESIGNATION names, exactly as received, replacing any held before, and persist. Nothing about GRANT is checked here beyond its being non-empty text: verifying it is the caller's job, and no caller does so yet.

(file-publisher-anchor store did-key)

File DID-KEY, a publisher's creating identity as an Ed25519 did:key, as a publisher this node trusts, and persist. Signals publisher-anchor-invalid, filing nothing, when DID-KEY is not an Ed25519 did:key.

(file-publisher-list store list-octets issuer sequence issued-at withdrawn-targets revoked-targets)

Hold LIST-OCTETS, the list ISSUER (a publisher's did:key) signed, as received, with SEQUENCE, ISSUED-AT (its signed Unix issue time) and WITHDRAWN-TARGETS as its facts, replacing the list ISSUER filed before and leaving every other publisher's list alone; add each of REVOKED-TARGETS to the revocations remembered under ISSUER; and persist, all in one write. A target is a 32-byte token hash or a did:key string. The store verifies nothing: its caller has verified the list and taken these facts from it, and the facts are held so that no reader has to decode the list after it is filed. Nothing here removes a remembered revocation.

(file-publisher-vouch store designation vouch)

Hold VOUCH, the publisher's vouch for the module DESIGNATION names, exactly as received, replacing any held before, and persist. Nothing about VOUCH is checked here beyond its being non-empty text: verifying it is the caller's job, and no caller does so yet.

(file-standing-grant store grant-text publisher-of)

Hold GRANT-TEXT, an owner's standing grant naming a publisher, exactly as received and marked active, and persist. PUBLISHER-OF answers, for a grant's text, the publisher it names, or NIL when it names none or no longer stands for one. A publisher holds one active standing grant at a time: filing a different grant for a publisher that holds an active one signals standing-grant-already-active and writes nothing, and the owner withdraws or backs out the active grant first. Filing a grant already held and active holds it as it was. A grant once withdrawn stays withdrawn: filing it again signals standing-grant-withdrawn and writes nothing. Nothing else about GRANT-TEXT is checked here beyond its being non-empty text: verifying it is the caller's job.

(held-publisher-list-issued-at store issuer)

The signed Unix issue time of the list ISSUER last filed, or NIL when ISSUER has filed none.

(held-publisher-list-issuers store)

The did:key of every publisher whose list STORE holds, sorted.

(held-publisher-list-sequence store issuer)

The sequence number of the list ISSUER last filed, or NIL when ISSUER has filed none.

(held-publisher-list-withdrawn-targets store issuer)

The targets the list ISSUER last filed marks withdrawn, sorted as the remembered set sorts, or NIL when ISSUER has filed none.

(install-vouch-store-octets path octets)

Write OCTETS, a whole vouch store file, to PATH at mode 0600 the way every change is written, and return the store they decode to. Octets that do not frame as a store signal vouch-store-corrupt and nothing is written.

(load-vouch-store path)

Return the vouch store recorded at PATH. Signals vouch-store-absent when no file is there, offering the create-empty-store restart (which writes an empty store at mode 0600 and returns it); signals vouch-store-corrupt, with no restart, when the bytes do not frame as a store.

(lookup-vouch store designation)

Return a copy of the vouch-entry held for DESIGNATION, or NIL when nothing is held: the fail-closed answer, since a module with no held credentials is admitted by nothing.

(make-vouch-store &key path)

Construct an empty vouch store backed by PATH (or held only in memory when PATH is NIL). No file I/O is performed; the first write creates the file.

(missing-directories path)

The directories above PATH that do not exist yet, deepest first.

(publisher-anchor-filed-p store did-key)

T when DID-KEY is a publisher anchor the owner has filed in STORE.

(publisher-anchors store)

Every filed publisher did:key, sorted.

(publisher-revocation-list store issuer)

A copy of the list ISSUER last filed, as received, or NIL when ISSUER has filed none.

(record-admission store designation publisher-vouch owner-credential unix-time)

Record, in one write, that the module DESIGNATION names was freshly admitted at UNIX-TIME on PUBLISHER-VOUCH and OWNER-CREDENTIAL, the credentials exactly as admission accepted them. Its owner slot then holds the credential that admitted it, so withdrawing a standing grant leaves the module in place and backing that grant out refuses it.

(record-admission-time store designation unix-time)

Record UNIX-TIME, a non-negative integer Unix time, as the moment the module DESIGNATION names was admitted, and persist. Neither credential is touched.

(remembered-publisher-revocation-p store issuer target)

T when a list ISSUER signed has named TARGET revoked and this store was told of it. TARGET is a 32-byte token hash, compared by octets, or a did:key, compared as a string. Anything else is never remembered.

(remembered-publisher-revocations store issuer)

Every revocation remembered under ISSUER, sorted: token hashes by octets, then did:keys.

(restore-vouch-entry store designation entry)

Put back ENTRY, a vouch-entry lookup-vouch returned earlier for DESIGNATION, or NIL when nothing was held, as exactly what STORE holds for DESIGNATION, and persist. Used to take back a record whose admission did not complete.

(standing-grant-state store grant-text)

The state of the standing grant GRANT-TEXT: :active, :withdrawn, or NIL when it has not been filed.

(standing-grants store)

Every standing grant held, active or withdrawn, as the text received, sorted.

(vouch-entry-admission-time instance)

Undocumented: this exported symbol needs a docstring.

(vouch-entry-designation instance)

Undocumented: this exported symbol needs a docstring.

(vouch-entry-owner-grant instance)

Undocumented: this exported symbol needs a docstring.

(vouch-entry-publisher-vouch instance)

Undocumented: this exported symbol needs a docstring.

(vouch-store-designations store)

Every designation the store holds anything for, sorted.

(vouch-store-file-octets path &key store)

The octets of the vouch store file at PATH, or NIL when no file is there. When STORE is the open store backed by that same file, it is read holding STORE's lock.

(vouch-store-path instance)

Undocumented: this exported symbol needs a docstring.

(withdraw-standing-grant store grant-text)

Mark the standing grant GRANT-TEXT withdrawn and persist, so it admits nothing new; what it already admitted is untouched. Returns T when the grant is held, and NIL, writing nothing, when it is not.

(write-vouch-store-if-absent store)

Write STORE to its file when it has a path and no file is there yet, holding its lock. Returns T when it wrote.