closedhumanPR #87Auth
macaroon-delegation: delegatable capability tokens with cascading revocation
The default jwt auth plugin tracks revocation by exact token string and has no parent/child relationship, so it cannot model the common pattern: A holds a root token, A mints a narrow short-lived sub-token for B offline, and revoking A…
Author
@SwasthikaDev
github profile →- Status
- Closed without merging
- Opened on
- Jul 7
- Branch
- hackathon/swasthika-macaroon-delegation
Description
The pitch.
## Problem 04 — auth: delegatable capability tokens with cascading revocation
The default `jwt` auth plugin tracks revocation by exact token string and has no parent/child relationship, so it cannot model the common pattern: A holds a root token, A mints a narrow short-lived sub-token for B offline, and revoking A should invalidate B automatically. This adds a `macaroons` auth plugin that does exactly that.
## Design
A token is a chain of caveats. Each delegation appends a caveat and re-chains the HMAC, keying each link with the previous link's signature (`sig_i = HMAC(sig_{i-1}, caveat_i)`, root keyed by the secret). Verification replays the chain from the root secret, so tampering, scope widening, TTL extension, and parent-link substitution all fail closed.
Because a child's signature is anchored to its parent, **revoking any ancestor's id invalidates every descendant by construction** — there is no per-child revocation list, just one set of revoked ids checked along the chain.
- `delegate(parent, audience, scopes_subset, ttl)` mints a child offline. Child scopes must be a strict subset of the parent's and the child cannot outlive the parent (both enforced at delegate and re-checked at verify, since a malicious holder controls the wire bytes).
- `verify` / `verify_for(token, presenter)` — the latter binds a token to its audience and rejects presentation by anyone else.
- Sync cores (`issue_sync`, `delegate_sync`, `verify_sync`, ...) with thin async wrappers, so the plugin is usable both from the async `Auth` protocol and from a synchronous scenario factory.
## Adversarial validator
`validators/delegation_validators.py` runs concrete attacks and reports whether the plugin defended. It **fails against the default `jwt` plugin and passes against `macaroons`**, covering: scope escalation, stale/revoked parent (cascading revocation), audience confusion, and TTL extension.
## Scenario
`scenarios/delegated_auth.yaml` + `nest_core/scenarios_builtin/delegated_auth.py`: a 16-agent tree (1 coordinator, 3 intermediaries, 12 leaves). Every leaf presents its token; two Byzantine leaves are rejected (`leaf-5` forges a broader scope, `leaf-10` steals a peer's token). After all present, the coordinator revokes `intermediary-0` and its four honest leaves fail re-verification. The scenario is RNG-free, so a given seed replays to a byte-identical trace (tested under seeds 42, 7, 1337).
## Tradeoffs
- Strict tree (single parent per token), not a DAG — enough for delegation and keeps verification linear in chain length.
- In-band, JSON-inspectable tokens (no third-party discharge caveats) so every token is legible in a JSONL trace.
- Revocation is an in-memory set of ids; a distributed deployment would replicate it, but that is out of scope here.
## Verification
```bash
uv sync
uv run pytest packages/nest-plugins-reference/tests/test_macaroons.py \
packages/nest-plugins-reference/tests/test_delegated_auth_scenario.py -v
uv run nest run delegated_auth # runs the scenario end to end
# Full gate:
uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run pytest -v
```
All of `ruff`, `ruff format --check`, `pyright` (strict), and `pytest` pass. Tests include unit tests, Hypothesis property tests for the attenuation invariant, the adversarial jwt-vs-macaroons discrimination, and the full-simulator scenario under the seed bank.Try it
Open PR on GitHubView diffCheckout locally
git fetch origin pull/87/head:pr-87
git checkout pr-87