macaroon-capability-credentials

name	macaroon-capability-credentials
description	Implement macaroons (Birgisson et al. 2014) as unforgeable, attenuate-only bearer capability credentials, with cross-language byte-parity. Use for capability tokens, bearer-credential attenuation, third-party caveats + discharge gates, delegation chains, "rent-paid"/compulsion caveats, or keeping a Rust and a TypeScript macaroon impl byte-identical via shared test vectors. Covers HMAC-chained first-party caveats, the two vid (verification-id) constructions (HMAC commitment vs AES-GCM sealing) and when to use each, per-hop verification soundness, request-binding, constant-time + fail-closed verification, and the structured caveat grammar. Pairs with agentic-zero-trust-security and rust-kernel-ffi. NOT for: OAuth/OIDC/JWT web-session auth, centralized token servers, or confining a malicious same-UID process (that needs OS/VM isolation — macaroons make the gate unforgeable, not the holder confined).
allowed-tools	Read, Write, Edit, Bash, Grep, Glob, WebSearch
io-contract	{"kind":"deliverable","produces":[{"kind":"design-doc","description":"Capability-credential design with caveat/attenuation model, verification chain, and revocation strategy"},{"kind":"code","description":"Macaroon mint/attenuate/verify implementation for the target runtime"}]}

Macaroon Capability Credentials

A macaroon (Birgisson et al., 2014, USENIX Security) is a bearer credential whose holder can attenuate (narrow) but never broaden authority. The holder appends caveats; each folds into a chained HMAC, so removing or tampering with one breaks the signature. The root key that seeds the chain never leaves the minter — the holder can present-and-verify but cannot forge or re-sign.

Canonical in-repo impl: core/kernel/pd-anchor/src/macaroon.rs (Rust, the source of truth). Deprecated parity-target: lib/macaroon/ (TS). Schema: ADR-0053 Appendix A.

The chain (load-bearing — get the bytes exactly right)

sig_0   = HMAC_SHA256(root_key, identifier)
sig_i   = HMAC_SHA256(sig_{i-1}, caveat_bytes_i)
first-party caveat_bytes = utf8(cid)
third-party caveat_bytes = vid_raw_bytes || utf8(cid)     // vid first, then cid

No length prefixes, no type tags, UTF-8 for text. Any divergence in encoding or concat order makes two implementations produce different signatures. Shared test vectors (fixed keys + caveats → expected signature_hex) generated from the canonical impl and asserted in BOTH test suites are the only real proof of byte-parity.

Decision point — which vid construction?

The third-party caveat's vid binds the discharge key into the chain. Two ways:

Construction	vid =	Verifier needs	Use when
HMAC commitment	HMAC(chain_sig, caveat_key)	the caveat key, from its own store (keyed by caveat id)	the verifier IS the key-holder (daemon-is-verifier-and-keyholder). No AEAD. Port Daddy canonical.
AEAD sealing	AES-GCM(KDF(chain_sig), caveat_key)	only the root key (recovers caveat_key by decrypting the vid)	decentralized verifiers with no key store (libmacaroons reference)

Pick HMAC commitment when one trusted process mints, stores keys, and verifies — it's simpler and needs no AEAD. Pick AEAD sealing only when verifiers can't share a key store. Never run both in two live verifiers of the same credential — that's the dual-runtime divergence (Port Daddy's TS once used AES-GCM, Rust uses HMAC commitment). That divergence is now CLOSED (ADR-0054 Phase 6, verified 2026-07-14): lib/macaroon/ is realigned to the Rust HMAC-commitment vid and is a deprecated byte-parity fallback, locked to the canonical impl by shared vectors in tests/fixtures/macaroon-parity-vectors.json (asserted by both the Rust parity_vectors test and tests/unit/macaroon-parity.test.js).

Verification MUST be per-hop (the unsound shortcut)

Recompute the chain hop by hop. At a first-party caveat, check the predicate against the request context. At a third-party caveat: resolve/confirm the caveat key, verify the binding commitment, find the matching discharge (by identifier), recursively verify it and require its signature to equal the request-bound value, then fold the caveat in. The root is checked against its own signature; a discharge against HMAC(BIND_KEY, root_sig || discharge_sig).

The naive "compare the final signature to a root-derived value" verifier is UNSOUND for third-party/delegation chains — proven in ProVerif on defense/anchor-attenuation-soundness. Always verify per-hop.

Request-binding (prepare_for_request): before presenting a discharge the holder rebinds discharge.sig = HMAC(BIND_KEY, root_sig || discharge_sig) (BIND_KEY = 32 zero bytes), so a stolen discharge can't be replayed against a different root.

Failure modes

Symptom	Cause	Fix
A grant with two third-party caveats false-rejects the second as a "cycle"	a never-popped seen visited-set used as a recursion guard	use a depth bound (MAX_DISCHARGE_DEPTH), not a visited-set — siblings don't poison each other
Expired grants verify when a caller forgets the clock	RequestContext::default() leaves now_ms = 0; 0 <= expires is always true (fail-open)	expires check fails closed when now_ms <= 0; document the clock as required
Tag comparison leaks via timing	early-return on first differing byte	constant-time fold-XOR over full length
Rust and TS signatures differ on the same inputs	byte-encoding / concat-order drift (UTF-16 vs UTF-8, cid||vid vs vid||cid)	pin the exact bytes; assert against shared vectors
Hostile macaroon crashes the verifier	unwrap/throw on malformed hex/JSON/oversized field	fail closed — bounded hex decode, every parse returns a clean refusal, never throws/panics
Discharge replayed against a different grant	discharge presented unbound	require prepare_for_request binding; the verifier checks the bound signature

Caveat grammar (Appendix A — structured, not free text)

Predicates field op value over a fixed, daemon-controlled field set; conjunctive evaluation (every caveat must hold) is what makes authority one-directional — adding spend_usd <= 100 over an existing <= 2 can't broaden, both hold and the tighter wins.

op = push|api-call · repo = <id> · branch = <glob> / branch != <name> · host = <fqdn> · spend_usd <= <n> · expires = <unix-ms> (fail-closed if now_ms<=0) · session = <id>. Glob via a small *-only two-pointer matcher (no regex). Fail closed on an unparseable predicate or an absent context field.

Quality gates

• HMAC chain bytes match the spec exactly (utf8 cid; vid||cid for third-party); proven by shared vectors asserted in every language
• Per-hop verification (never final-vs-root); each discharge recursively verified + request-bound
• Constant-time tag compare; fail-closed on all malformed input (no throw/panic)
• Recursion is depth-bounded, not visited-set-guarded
• expires fails closed on an unset clock; verifier takes injected now_ms, never reads the system clock
• prepare_for_request binding required before a discharge is presented
• One canonical implementation; any second-language port is a byte-parity fallback locked by shared vectors, never an independent re-derivation
• Honest scope stated: unforgeable gate + verifiable audit, NOT same-UID confinement

NOT for

OAuth/OIDC/JWT web auth · centralized token servers (issue scoped tokens directly) · secrets inside caveats (caveats are constraints, not secrets) · confining a malicious same-UID holder who can copy a live discharge mid-window (that needs OS/VM isolation — Layer 3).

References

• Birgisson, Politz, Erlingsson, Taly, Vrable, Lentczner (2014), Macaroons: Cookies with Contextual Caveats for Decentralized Authorization in the Cloud, USENIX Security.
• core/kernel/pd-anchor/src/macaroon.rs — canonical impl (HMAC-commitment vid, per-hop verify, depth bound, fail-closed clock, caveat grammar).
• docs/adr/0053-out-of-band-enforcement.md Appendix A — the caveat schema + rent-paid discharge.
• defense/anchor-attenuation-soundness (branch) — ProVerif proof that per-hop verification is sound and final-vs-root is not.
• libmacaroons (rescrv) — reference C impl, AEAD-sealing model, 32-byte BIND_KEY.