closedhumanPR #147Auth
capability-systems-engineer: delegatable capability tokens with cascading revocation
Solves docs/hackathon/problems/04-auth-capability-delegation.md.
Author
@ang101
github profile →- Status
- Closed without merging
- Opened on
- Jul 9
- Branch
- hackathon/ang101-capability-delegation
Description
The pitch.
## Problem
Solves `docs/hackathon/problems/04-auth-capability-delegation.md`.
The default `jwt` plugin (`nest_plugins_reference/auth/jwt_auth.py`) tracks
revocation in `_revoked: set[str]` keyed by the *exact token string*, with no
parent-child relationship at all. That makes it impossible to model the most
common real-world capability pattern: agent A holds a long-lived root token
and wants to mint a narrower, short-lived sub-token for agent B *without*
contacting the issuer — and revoking A's token should invalidate every token
B (or anyone B further delegated to) derived from it, at the next verify.
## Design
`delegatable.py` implements a macaroon-style **chained MAC**. A token is a
JSON list of *hops*, one per delegation step from the root. Each hop's HMAC
key is the *previous* hop's MAC (the root hop is keyed by the plugin's
secret):
- A party without the root secret cannot forge any hop — every hop's MAC
recursively depends on a value only the true issuer could have produced.
- **Scopes only narrow, hop to hop.** `delegate()` refuses to mint a child
whose scopes aren't a strict subset of its parent's; `verify()` re-checks
this structurally as defense in depth, so a tampered chain fails even if
some future code path skipped the mint-time check.
- **Cascading revocation is O(1) to issue and O(depth) to check.** `revoke()`
adds exactly one MAC to a set. Verifying any descendant walks its own
embedded hop chain and fails the moment it hits a revoked MAC — no
per-descendant bookkeeping is needed at revoke time.
`verify_with_audience()` is new API on top of the base `Auth` protocol
(`verify(token) -> AuthContext` has no caller identity to check against),
catching the case where a token is presented by an agent other than the one
it was actually delegated to.
## Tradeoffs
- Revocation state and the root secret live in-process on the plugin
instance (mirrors `JwtAuth`'s own `_revoked` set) — this is a single
shared authority per simulation, not a distributed one. Out of scope per
the problem brief.
- `verify()`'s structural scope/TTL re-check is redundant with what
`delegate()` already enforces at mint time for any chain that was honestly
produced by this plugin — it exists as defense in depth, not because the
crypto alone is insufficient.
- Delegation is a strict tree (single parent per token), as the problem
brief allows — no DAG support.
## What's shipped
- `nest_plugins_reference/auth/delegatable.py` — the plugin, registered as
`("auth", "delegatable")` in `nest_core/plugins.py`.
- `nest_plugins_reference/validators/delegation_validators.py` — adversarial
validators for all 3 required attacks (scope escalation, stale-parent use,
audience confusion). Each **fails against `jwt`** (no delegation concept to
even attempt) and **passes against `delegatable`**.
- `scenarios/delegated_auth.yaml` + `scenarios_builtin/delegated_auth.py` —
coordinator + 3 intermediaries + 12 leaves in a delegation tree, with one
byzantine leaf attempting audience confusion against the coordinator's own
identity (correctly rejected). Verified byte-identical traces across seeds
42, 7, 1337.
- `tests/test_delegatable.py`, `tests/test_delegation_validators.py` — 36
tests total, including Hypothesis property tests over arbitrary
scope-narrowing chains of depth 1–5.
## Verification
\`\`\`bash
uv sync
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest -v
uv run nest doctor
\`\`\`
All green locally: 1017 passed / 1 skipped (pre-existing), 0 pyright errors,
`nest doctor` 7/7 (all 12 default plugins resolve, including `delegatable`).
Runnable end-to-end demo:
\`\`\`bash
uv run python -c "
import asyncio
from nest_core.runner import ScenarioRunner
from nest_core.scenario import ScenarioConfig
async def main():
config = ScenarioConfig.from_yaml('scenarios/delegated_auth.yaml')
tr
…Try it
Open PR on GitHubView diffCheckout locally
git fetch origin pull/147/head:pr-147
git checkout pr-147