Capability Tokens

Capability tokens are signed, scoped, non-replayable authorization tokens that gate custody-critical operations in loopctl. Without a valid cap, the forbidden operation is structurally unreachable.

Token types

Type	Minted at	Consumed by	Gates
`start_cap`	claim_story	start_story	Starting implementation
`report_cap`	start_story	report_story	Reporting work as done
`review_complete_cap`	request_review	review_complete	Recording review
`verify_cap`	request_review	verify_story	Verifying work

Token structure

Each token contains:

typ — the operation type
story_id — the story this cap authorizes
issued_to_lineage — exact dispatch lineage path of the recipient
nonce — 32 random bytes (replay protection)
signature — ed25519 signature by the tenant’s audit key
expires_at — TTL (default 1 hour)

Presenting a cap

Include the cap_id in your request body. The server verifies:

Signature matches the tenant’s public key
Type matches the endpoint
Story matches the URL parameter
Lineage exactly matches the caller’s current lineage
Not expired
Not already consumed (replay protection)

Why caps matter

Without caps, an implementer could forge a verify request. With caps, the verify_cap is never minted to the implementer’s lineage — they literally cannot construct a valid verify request.

See Chain of Custody for the full trust model. See Dispatch Lineage for how lineages work.