intent-based-auth

Intent-bounded agent authorization demo.

Architecture

prompt → normalizer → grant-engine → agentic-workflow → downstream APIs
              ↓              ↓               ↓
        intent_class    runtime grant   bounded execution

Service	Role
gateway	Orchestrates the flow
normalizer	Parses prompt → intent_class + extracted entities
grant-engine	Deterministic policy evaluation and grant minting (safety boundary)
agentic-workflow	Agent's bounded execution layer - selects and calls operations within grant
billing-api, crm-api, comms-api	Mock downstream services

Key separation: Grant-engine is the deterministic safety boundary. It evaluates policy, narrows outcomes, and mints grants. Agentic-workflow is the agent's operating space—it cannot widen permissions.

Production note: In production, the true security boundary is at the downstream service level. Each API verifies the JWT grant and rejects unauthorized operations. The agentic-workflow safeguard is defense-in-depth.

Core Concepts

Concept	Definition
x-intent	Stable semantic metadata for an operation: effects, risk level, data classification. Attached to APIs, not requests.
intent catalog	Maps an intent_class to candidate operation_class values. Bounds what operations the system considers.
runtime grant	Short-lived JWT encoding the effective runtime authorization result for the invocation context.
grant-engine	Evaluates policy deterministically. Prunes candidates, narrows outcomes, mints grants.
agentic-workflow	Agent's bounded execution layer. Selects one or more operations from the pruned set and executes them.

Outcome Levels

Level	Meaning
read	Read-only access
draft	Create drafts requiring review
execute	Full execution

Approval Modes

Mode	Meaning
auto	No approval needed
confirm	User confirmation required
manual	Human review required
blocked	Operation denied

Project Structure

intent-based-auth/
├── demo/
│   ├── fixtures/
│   │   ├── intent-catalog.yaml    # Intent → candidate mappings
│   │   └── x-intents/*.json       # Operation metadata
│   ├── services/
│   │   ├── gateway/               # Request orchestration
│   │   ├── normalizer/            # Prompt → intent
│   │   ├── grant-engine/          # Policy + grant minting
│   │   ├── agentic-workflow/       # Agent's bounded execution
│   │   └── *-api/                 # Mock downstream services
│   └── samples/                   # Example scenarios
└── tests/                         # Unit tests for grant-engine

Example Flow

Prompt: "Refund customer 123" in prod

1. normalizer
   → intent_class: "billing.refund.process"
   → resources: ["customer:123"]

2. grant-engine
   → candidates: [billing.refund.get, billing.refund.get_eligibility, billing.refund.calculate, billing.refund.create, billing.refund.create_payout]
   → policy: billing.refund.create_payout has financial_transfer + high risk
   → decision: NARROW (execute → draft)
   → allowed_operations: [billing.refund.get, billing.refund.get_eligibility, billing.refund.calculate, billing.refund.create]
   → mints runtime grant

3. agentic-workflow
   → receives grant + pruned candidates
   → selects operations from allowed_operations
   → executes against billing-api
   → returns results

Grant-Engine Response

The /evaluate_and_mint endpoint returns a response envelope containing the policy decision and minted grant:

{
  "decision": "narrow",
  "reason_codes": ["high_risk_financial_narrowed", "operations_blocked_by_outcome"],
  "candidates": ["billing.refund.get", "billing.refund.calculate", "billing.refund.create", "billing.refund.create_payout"],
  "pruned_candidates": ["billing.refund.get", "billing.refund.calculate", "billing.refund.create"],
  "effective_outcome_max": "draft",
  "approval_mode": "confirm",
  "allowed_operations": ["billing.refund.get", "billing.refund.calculate", "billing.refund.create"],
  "runtime_grant": {
    "token": "eyJ...",
    "claims": { ... }
  }
}

Runtime Grant Token

The JWT grant encodes the effective runtime authorization result:

{
  "ver": "1",
  "iss": "intent-auth-demo",
  "iat": 1234567890,
  "nbf": 1234567890,
  "exp": 1234568190,
  "jti": "unique-grant-id",
  "env": "prod",
  "delegation": {},
  "permissions": [
    {
      "intent_class": "billing.refund.process",
      "outcome_max": "draft",
      "approval": "confirm",
      "resources": ["customer:123"]
    }
  ]
}

Note: The response envelope includes allowed_operations and reason_codes for agentic-workflow consumption. The JWT token itself contains the minimal cryptographically-signed authorization claims.

Demo Policy Rules

These are demo behaviors, not protocol requirements:

• Explore intents (*.explore) → outcome capped to read
• Delete operations → denied by default
• High-risk financial operations (e.g., billing.refund.create_payout) → narrowed to draft in prod unless actor has refund_approver role
• External notifications with PII → narrowed to draft in prod
• Financial transfers → require manual approval
• Lower-risk candidates → sorted first (preferred)

Running the Demo

cd demo
docker-compose up --build
# See demo/README.md for curl examples

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

Installation

pip install -e ".[dev]"