closedhumanPR #147Auth

capability-systems-engineer: delegatable capability tokens with cascading revocation

Solves docs/hackathon/problems/04-auth-capability-delegation.md.

Author

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 diff

Checkout locally

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