closedhumanPR #37Auth

Auth: manifest-bound delegatable capability tokens

Problem #04 — Delegatable capability tokens with cascading revocation.

Author

Charanarravindaa avatar

@Charanarravindaa

github profile →
Status
Closed without merging
Opened on
Jun 24
Branch
hackathon/charan-policy-enforcement

Description

The pitch.

# [Hackathon] Auth: manifest-bound delegatable capability tokens

## Problem Picked

**Problem #04 — Delegatable capability tokens with cascading revocation.**

**Layer 5 — Auth.**

This PR adds `auth: delegatable`, a reference Auth-layer plugin for manifest-bound delegatable capability tokens, plus the required adversarial validators and `scenarios/delegated_auth.yaml` proof scenario. It stays inside the existing 12-layer stack and does not introduce a new framework layer.

## Why

The default `jwt` auth plugin can issue and verify bearer tokens, but it cannot model the delegation pattern called out in problem #04:

> agent A holds a root token; agent A mints a short-lived, narrower token for agent B; revoking A's token invalidates B's token at the next verify.

That pattern matters for agent swarms because orchestrators routinely need constrained handoffs:

- "You may call this tool, but not pass broader authority onward."
- "You may buy this item, but only within my delegated capability."
- "You may act for me until this parent token expires or is revoked."
- "You may use this sub-capability, but only as the declared audience."

This PR makes that capability-delegation contract testable under attack in Nanda Town.

## Core Idea

`DelegatableAuth` issues root tokens whose scopes are clamped to a signed manifest. A holder can mint a child token for another audience, but only under stricter caveats:

- **Manifest-bound roots:** root scopes are clamped to tools allowed by the signed `PolicyManifest`.
- **Strict scope narrowing:** child scopes must be a strict subset of parent scopes.
- **TTL containment:** child expiry cannot exceed parent expiry.
- **Audience binding:** a token minted for one agent cannot be presented by another.
- **Cascading revocation:** revoking any token invalidates that token and all descendants.
- **Tamper resistance:** manifest tampering and token payload/signature tampering are rejected.

The plugin is a deterministic, in-memory reference implementation for the Nanda Town test rig. Distributed revocation and cross-process token registry replication are intentionally out of scope.

## Adversarial Contract

Problem #04 requires validators that catch three attacks. This PR ships all three:

| Attack | Baseline `auth: jwt` | This PR `auth: delegatable` |
|---|---|---|
| Scope escalation | FAIL: broader child authority can be accepted via baseline re-issuance | PASS: child scopes must be a strict subset of parent scopes |
| Stale parent | FAIL: revoking parent authority does not invalidate separately issued child token | PASS: descendant verification checks revoked ancestors |
| Audience confusion | FAIL: baseline verification does not bind delegated presentation to the child audience | PASS: presenter must match token audience |

The bundled scenario builds the required delegation tree: one coordinator, three intermediaries, and twelve leaves.

## What Ships

- `nest_plugins_reference.auth.delegatable.DelegatableAuth`
- minimal signed-manifest primitives used to clamp Auth scopes
- entry-point registration for `auth: delegatable`
- `scenarios/delegated_auth.yaml`
- `delegated_auth` built-in scenario with coordinator, 3 intermediaries, and 12 leaves
- adversarial validators:
  - `delegated_auth_scope_containment`
  - `delegated_auth_no_stale_parent`
  - `delegated_auth_audience_binding`
- unit tests for scope clamping, delegation, revocation, TTL, audience binding, tampering, and plugin resolution
- property tests for strict scope containment, transitive revocation, and deterministic token generation
- end-to-end tests showing `auth: delegatable` PASS and `auth: jwt` FAIL

## Security Properties Covered By Tests

- unsigned manifests are deny-all
- signed manifests widened after signing do not grant new authority
- duplicate root scopes are deduplicated
- child scopes must be narrower than parent scopes
- equal-scope delegation is rejected
- out-of-parent scope escalation is rejected
- child TTL beyond par

…

Try it

Open PR on GitHubView diff

Checkout locally

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