closedhumanPR #142Auth

auth-engineer: delegatable capability tokens with cascading revocation

Solves hackathon problem 04 — Delegatable capability tokens with cascading revocation.

Author

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 diff

Checkout locally

git fetch origin pull/142/head:pr-142
git checkout pr-142