closedhumanPR #103Auth

hackathon/mwarsss-delegatable-auth

Implements Problem 04 -> Auth Capability Delegation from the NandaHack charter. Adds a DelegatableAuth plugin that extends the existing Auth protocol surface with HMAC-chained capability tokens, cascading revocation, and audience-binding.

Author

Status
Closed without merging
Opened on
Jul 8
Branch
hackathon-mwarsss-delegatable-auth

Description

The pitch.

## Summary

Implements **Problem 04 -> Auth Capability Delegation** from the NandaHack charter.  Adds a `DelegatableAuth` plugin that extends the existing `Auth` protocol surface with HMAC-chained capability tokens, cascading revocation, and audience-binding.

- **Plugin** -> `DelegatableAuth` (auth layer, name `delegatable`).  Extends the `Auth` protocol (`issue` / `verify` / `revoke`) with an additive `delegate(parent_token, audience, scopes, ttl) → Token` method.  No existing callers are modified.
- **Three attacks blocked** -> scope escalation, stale-parent revocation, audience confusion.  Each attack raises a distinct typed exception (`ScopeEscalationError`, `RevokedAncestorError`, `AudienceConfusionError`), all `ValueError` subclasses for drop-in compatibility.
- **HMAC chain** -> based on Birgisson et al. 2014 (Macaroon construction).  Each child token's signing key is derived from the parent's HMAC output, so revoking a parent transitively invalidates every descendant without a per-child revocation list.
- **Audience binding** -> `verify(token, *, caller: AgentId | None = None)` keyword-only arg; backward-compatible with all `Auth` protocol callers that don't supply `caller=`.
- **Three adversarial validators** -> `check_scope_escalation_blocked`, `check_stale_parent_blocked`, `check_audience_confusion_blocked` in `nest_plugins_reference/validators/auth_validators.py`, returning `ValidatorReport` (same type as `gossip_validators.py`).
- **Scenario** -> 16-agent two-level tree: 1 coordinator → 3 intermediaries → 12 leaves.  Scenario YAML at `scenarios/delegated_auth.yaml` with `layers.auth: delegatable`.
- **Wiring** -> `_BUILTINS` in `plugins.py`, `_try_load_builtin` in `scenarios.py`, and a `[project.entry-points."nest.plugins.auth"]` entry in `pyproject.toml`.

## Design choices

- **No types.py modification** ->`AuthContext` has no `metadata` field; audience is carried in the token payload itself and checked via the `caller=` keyword argument rather than polluting shared types.
- **Constructor mirrors `JwtAuth`** -> `__init__(self, secret: bytes, clock: float | None = None)`.  Auth is a single shared service (no per-agent instances needed), matching the existing pattern.
- **No new dependencies** -> uses only `hmac`, `hashlib`, `json`, `uuid` from the standard library.

## Files changed

| File | Change |
|------|--------|
| `packages/nest-plugins-reference/nest_plugins_reference/auth/delegatable.py` | New plugin (~230 lines) |
| `packages/nest-plugins-reference/nest_plugins_reference/validators/auth_validators.py` | Three adversarial validators |
| `packages/nest-core/nest_core/scenarios_builtin/delegated_auth.py` | Scenario factory (16 agents) |
| `scenarios/delegated_auth.yaml` | Scenario YAML |
| `packages/nest-plugins-reference/tests/test_delegatable_auth.py` | 32 example-based tests |
| `packages/nest-plugins-reference/tests/test_delegatable_auth_properties.py` | 5 Hypothesis property tests |
| `packages/nest-core/nest_core/plugins.py` | +1 line: `("auth", "delegatable")` in `_BUILTINS` |
| `packages/nest-core/nest_core/scenarios.py` | +4 lines: `delegated_auth` branch in `_try_load_builtin` |
| `packages/nest-plugins-reference/pyproject.toml` | +3 lines: `[project.entry-points."nest.plugins.auth"]` |

## Test plan

- [x] `uv sync` — clean install
- [x] `uv run ruff check .` — no errors
- [x] `uv run ruff format --check .` — no reformats needed
- [x] `uv run pyright` — 0 errors, 0 warnings
- [x] `uv run pytest -v` — 828 passed, 1 skipped, 0 failed (baseline: 377 tests; +37 new, rest unchanged, +414 from other PRs already in main)

Quick smoke test:

```python
from nest_plugins_reference.auth.delegatable import DelegatableAuth
from nest_core.types import AgentId
import asyncio

auth = DelegatableAuth(secret=b"demo")
async def demo():
    root  = await auth.issue(AgentId("coord"), ["admin", "read", "write"])
    child = await auth.delegate(root, AgentId("worker")

…

Try it

Open PR on GitHubView diff

Checkout locally

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