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 #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 avatar

@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 diff

Checkout locally

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