in reviewhumanPR #102Auth
hackathon/yashjadhav1595-projects: Macaroon-style capability tokens with cascading revocation (Problem 04)
The default jwt_auth plugin handles root token issuance, but lacks any mechanism to safely delegate scoped access down a hierarchy, and critically, it lacks parent-child revocation.
Author
@yashjadhav1595-projects
github profile →- Status
- In review
- Opened on
- Jul 8
- Branch
- hackathon/yashjadhav-delegatable-auth
Description
The pitch.
### What this solves (Problem 04: Delegatable Auth)
The default `jwt_auth` plugin handles root token issuance, but lacks any mechanism to safely delegate scoped access down a hierarchy, and critically, it lacks parent-child revocation. Revoking a root token does not automatically invalidate tokens delegated from it.
### Implementation Checklist
- [x] **Implement HMAC-chained token trees** where child tokens carry a `parent_sig`.
- [x] **Enforce cascading revocation** (revoking a parent instantly poisons all downstream descendants).
- [x] **Strict Scope Escalation Prevention** (`delegate()` refuses to issue scopes broader than the parent).
- [x] **Audience Binding** to mitigate audience-confusion attacks.
- [x] **137 Unit Tests & Adversarial Scenarios** passing (scope escalation, stale parent, audience confusion).
### The Solution: Macaroon-inspired Cascading Revocation
This PR implements `DelegatableAuth`, a complete cryptographic token tree that natively supports cascading revocation and strict scope-bounding.
**Key Features:**
* **HMAC-chained token tree**: Delegated tokens carry a `parent_sig` pointing back up the chain.
* **Cascading Revocation**: When `verify()` is called, the plugin walks the ancestor chain. If *any* ancestor has been revoked or expired, the descendant token immediately fails validation—without needing to index or revoke every child individually.
* **Strict Scope Escalation Prevention**: `delegate()` enforces that a child token can only be issued if its scopes are a strict subset of the parent's scopes.
* **Audience Binding**: Mitigates audience-confusion attacks by binding delegated tokens to a specific agent identity.
### Validation & Testing
This implementation passes the full `delegated_auth` adversarial validator scenario out-of-the-box, correctly catching:
1. **Scope escalation** (rejects child scopes ⊃ parent scopes)
2. **Stale parent** (rejects child verification after parent revocation)
3. **Audience confusion** (rejects tokens presented by the wrong agent)
Includes **137 new specific unit tests** proving deterministic cascading revocation and boundary safety.
```mermaid
graph TD
%% Styling
classDef agent fill:#1e1e1e,stroke:#4a4a4a,stroke-width:2px,color:#fff;
classDef token fill:#2b3a42,stroke:#3b82f6,stroke-width:2px,color:#fff;
classDef revoked fill:#4a1e1e,stroke:#ef4444,stroke-width:2px,color:#fff;
classDef action fill:#1e1e1e,stroke:#10b981,stroke-width:2px,color:#fff,stroke-dasharray: 5 5;
subgraph The Delegation Tree
C[Coordinator Agent]:::agent
I[Intermediary Agent]:::agent
L[Leaf Worker Agent]:::agent
RT[Root Token<br>Scopes: read, write, admin<br>Sig: root_sig_xyz]:::token
IT[Intermediary Token<br>Scopes: read, write<br>Parent Sig: root_sig_xyz]:::token
LT[Leaf Token<br>Scopes: read<br>Parent Sig: interm_sig_abc]:::token
C -->|1. Issues Root| RT
RT -->|2. Delegates| IT
I -->|Receives| IT
IT -->|3. Delegates| LT
L -->|Receives| LT
end
subgraph The Cascading Revocation Attack Defense
R((Revocation Registry)):::agent
V{Verify Token}:::action
C -.->|4. Revokes Root Token| R
R -.->|Adds root_sig_xyz<br>to Revoked Set| R
L -.->|5. Attempts to act| V
V -->|Checks Leaf Sig| IT
V -->|Walks to Parent Sig| RT
V -->|Checks Root Sig in Registry| R
R -->|6. REJECTS Leaf Token<br>due to revoked ancestor| L
end
class RT revoked;
Try it
Open PR on GitHubView diffCheckout locally
git fetch origin pull/102/head:pr-102
git checkout pr-102