Skip to main content
Version: v0.9.0a2
Spec

Spec-06-Capability-Tokens

3 min readSpec contributor · Node operatorDraft · v0.9.0aN

What this spec defines

Short-lived, signed grants used for federated and delegated operations. Capability tokens are scoped credentials: they grant a subject a verb on a specific object for a bounded time window.

Extraction status​

This file contains the ADR-010 prose extraction for capability-token shape, issuance, verification, and revocation. It intentionally does not define peer admission, manifest schema, replay-window policy, or capability-based instruction semantics.

Token purpose​

Capability tokens are portable credentials.

Static API keys are node-local credentials. Capability tokens provide a portable credential that a receiving peer can verify from issuer manifest material without calling back to the issuer on every operation.

Token shape​

CapabilityToken {
  issuer:    URI
  subject:   URI
  verb:      string
  object:    URI
  issued_at: ISO 8601 UTC
  expiry:    ISO 8601 UTC
  nonce:     lowercase hex string
  key_id:    string
  signature: base64url Ed25519 signature
}
Field
Type
Meaning
issuer
URI
The authority that signed the token.
subject
URI
The principal receiving the grant.
verb
string
The allowed action.
object
URI
The target scope, garden, entity, or route family.

Signing​

The signature covers a canonical encoding of the token body with signature omitted. The signing key MUST correspond to an active key in the issuer's manifest. Receivers MUST verify the issuer manifest before trusting the token.

Issuance​

Capability-token issuance is exposed through the HTTP route owned by Spec-03-HTTP-API:

POST /v1/federation/capability-tokens

Only authorized administrative callers may issue capability tokens. Issuance MUST record token id, issuer, subject, verb, object, expiry, and nonce so that revocation and audit can refer to the token later.

Verification​

Receivers MUST verify:

  1. The token signature.
  2. The issuer manifest and active key id.
  3. The token has not expired.
  4. The nonce is well-formed.
  5. The token has not been revoked.
  6. The requested operation is within the (verb, object) grant.

Verification failure MUST deny the operation. Implementations SHOULD distinguish signature, expiry, revocation, and scope/verb failures in audit logs.

Revocation​

Revocation is exposed through:

POST /v1/federation/capability-tokens/{token_id}/revoke

Revocation invalidates a token before its natural expiry. Nodes SHOULD publish revocation evidence through the same transparency-log mechanism used for manifests when configured.

Receivers MUST treat revoked tokens as invalid even if signature and expiry are otherwise valid.

Replay relationship​

The token nonce identifies a token instance. Runtime replay windows and inbound request nonce caches are owned by Spec-11-Replay-Protection; this spec only requires the token to carry a verifiable nonce.

Grant boundaries​

Capability tokens are additive grants, not proof of broad identity authority.

A token granting write on one object MUST NOT be interpreted as a grant to write any other object. A token granting access to a garden or scope MUST still pass the local ACL and scope enforcement rules that apply to that operation.

Out of scope​

This spec does not define:

API-key creation

Local operator credentials.

Peer-token handshakes

That are separate from capability tokens.

Capability-based instruction

interpret_as enforcement.

Replay cache implementation

Token UI or CLI workflows