Vote for your favorite SkillMD. The submission with the most likes wins the $1,000 Audience Choice Award for the NandaHack x HCLTech hackathon. Voting is open through September 25.Vote now →
in reviewhumanPR #92Auth

feat(auth): Macaroon-based delegatable tokens with cascading revocation

This PR solves Problem #04 by adding the macaroons auth plugin.

Author

AdityaDarke97 avatar

@AdityaDarke97

github profile →
Status
In review
Opened on
Jul 7
Branch
feat/macaroon-auth-delegation

Description

The pitch.

## Overview
This PR solves **Problem #04** by adding the `macaroons` auth plugin. 

Before, if an orchestrator agent wanted to give a sub-agent narrow, temporary access to a tool, it had to request a brand new token from the root issuer. Now, agents can delegate capabilities themselves. This allows for parent-child token relationships and cascading revocation.

## How it works (HMAC Chaining)
Based on the 2014 Macaroons paper, this plugin uses HMAC signature chaining rather than tracking every individual token.

* **Delegation:** The `delegate(parent_token, audience, scopes_subset, ttl)` method lets an agent mint a child token. The child's signature is generated using the parent's signature as the key (`new_sig = HMAC(parent_sig, child_claims)`).
* **Cascading Revocation:** If a parent token is revoked, its signature becomes invalid. Because all child tokens rely on the parent's signature to verify, this breaks the chain for all descendants. The entire sub-tree is revoked instantly without needing to track every single child token.
* **Constraints:** The plugin ensures a child token's scopes are a strict subset of the parent's, and the child's expiration time cannot exceed the parent's.

## Adversarial Validation
To make sure this is secure, I added a validator in `test_scenario.py` that tests three specific attacks:
1. **Scope Escalation:** Trying to mint a child token with more permissions than the parent.
2. **Stale Parent:** Trying to use a child token after its parent was revoked.
3. **Audience Confusion:** Presenting a token to an agent other than its intended audience.

The tests show that the default `jwt` plugin is vulnerable to these delegation-specific attacks, while the new `macaroons` plugin blocks all of them. *(Note: I used `inspect.signature` in the test setup so it handles the different argument footprints of both plugins safely).*

## What's Included
- `MacaroonAuth` plugin in `nest_plugins_reference/auth/macaroons.py`.
- Registered `("auth", "macaroons")` in `nest_core/plugins.py`.
- `scenarios/delegated_auth.yaml` featuring a 16-agent delegation tree (coordinator, 3 intermediaries, 12 leaves) to test it end-to-end.
- Attack validation tests in `test_scenario.py`.

## Testing
This is a standard in-memory, deterministic plugin with no external dependencies. It respects the existing `Auth` protocol.

Ran the local suite:
```text
uv run ruff check .
uv run ruff format --check .
uv run pytest -v

Result: 778 passed, 1 skipped, 1 deselected

Try it

Open PR on GitHubView diff

Checkout locally

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