closedhumanPR #142Auth
auth-engineer: delegatable capability tokens with cascading revocation
Solves hackathon problem 04 — Delegatable capability tokens with cascading revocation.
Author
@erin-adams
github profile →- Status
- Closed without merging
- Opened on
- Jul 9
- Branch
- hackathon/erin-adams-delegated-auth
Description
The pitch.
# Delegatable capability tokens with cascading revocation (auth layer) Solves hackathon problem **04 — Delegatable capability tokens with cascading revocation**. Persona: an auth engineer who cares about least-privilege delegation and clean revocation. ## Motivation The default `jwt` auth plugin (`jwt_auth.py`) can only *issue* and *revoke* whole tokens, and its revocation set is keyed by the exact token string. It cannot express the most common multi-agent auth pattern: an orchestrator holds a long-lived root capability, mints a **narrower, time-bounded** sub-capability for a worker agent *without* asking the issuer, and can pull the whole subtree back by revoking one ancestor. Today, revoking a parent does nothing to a child that was handed out separately — the child sails through `verify`. This is exactly what you need to model an LLM agent sub-renting a tool to another agent and cleanly withdrawing it. It was one of the ten open problems and the only one with no plugin on `main`. ## Design A macaroon (Birgisson et al., 2014). A token carries an ordered **chain of caveats** (root → leaf). Each link is MAC'd with an HMAC **keyed by its parent's signature**, so: - **Delegation needs no issuer round-trip.** Any holder of a valid parent can append a caveat and re-chain the MAC (`delegate(parent, audience, scopes_subset, ttl)`). The root secret never leaves the issuer. - **Restriction is enforced at verify, not at mint.** A holder knows the parent signature (the child's MAC key), so it *can* forge a MAC-valid caveat with wider scopes. `verify` therefore re-checks that every child only **narrows** its parent — scopes ⊆ parent, expiry ≤ parent, `parent_tid` linked. A widened caveat is cryptographically well-formed but rejected. **This is what actually stops scope escalation** (see the `test_forged_wide_caveat_rejected_at_verify` test — the honest `delegate`-time check alone is not enough). - **Revocation cascades by construction.** Every caveat carries a `tid`; `verify` checks every `tid` in the chain against the revocation set. Revoke a parent's `tid` and every descendant fails at the next `verify` — no per-child bookkeeping. - **Audience binding.** The leaf caveat is bound to an `aud`; `verify(token, presenter=...)` rejects a mismatched presenter. `presenter` is optional, so the plugin still satisfies the `Auth` protocol exactly (`isinstance(plugin, Auth)` is `True`). ### Tradeoffs (explicit) - **Chain grows with depth.** Each hop adds one caveat + re-MAC; verify is O(depth). For agent delegation trees (depth ≤ a handful) this is negligible; I did not add QC aggregation. - **Third-party caveats / discharge macaroons are out of scope.** Only first-party caveats (scope, expiry, audience) are implemented — enough for the problem. - **Revocation is a growing set of `tid`s.** Bounded by tokens issued; no GC. Fine for a simulation; a real deployment would TTL the revocation entries. - **Errors subclass `ValueError`** so existing callers that already guard `verify` with `except ValueError` keep working unchanged. ## Determinism (Tier 1) Token ids are `sha256` over the caveat's own fields — no RNG, no wall clock. Timestamps come from an injected logical clock (`set_clock`), exactly as `JwtAuth` uses its `clock`. Same inputs → byte-identical tokens; the scenario trace is **byte-identical under seeds 42, 7, 1337**. ## Adversarial validators (FAIL on `jwt`, PASS on `delegatable`) Under the `delegated_auth` scenario, three validators stage the three attacks the problem names and read the outcome the *configured* plugin actually returned: | Validator | Attack | `jwt` | `delegatable` | | ----------------------------- | ----------------------------------------- | ------------------------- | ------------------------ | | `auth_no_scope_escalation` | …
Try it
Open PR on GitHubView diffCheckout locally
git fetch origin pull/142/head:pr-142
git checkout pr-142