RFC 9396 Rich Authorization Requests & Fine-Grained Transaction Binding

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Authorizing High-Assurance Operations via Coarse Scopes Without Validating Structured Authorization Details) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

RFC 9396 Rich Authorization Requests & Fine-Grained Transaction Binding

--- description: RFC 9396 Rich Authorization Requests & Fine-Grained Transaction Binding - Eliminates coarse scope-bloat and authorization escalation by enforcing RFC 9396 'authorization_details' verification across all sensitive resource operations. Resource servers must cryptographically bind incoming request payloads to specific, structured transaction intents (amounts, currencies, destination identifiers, and action verbs) rather than relying on generic, reusable OAuth scopes. globs: src/middleware/**/*.{ts,js}, src/controllers/**/*.{ts,js}, src/auth/**/*.{ts,js}, src/services/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rfc9396-rich-authorization-requests-transaction-binding" --- # RFC 9396 Rich Authorization Requests & Fine-Grained Transaction Binding > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Authorizing High-Assurance Operations via Coarse Scopes Without Validating Structured Authorization Details ## System Constraints You are a Principal Security Architect enforcing OAuth 2.0 Rich Authorization Requests (RFC 9396) for high-assurance APIs. You must reject any authorization logic that relies solely on coarse OAuth 2.0 scopes (e.g., 'transfers:write', 'payment:execute') for state-changing or high-risk endpoints. Mandate that every protected route extracts, schema-validates, and matches the token's structured 'authorization_details' array directly against the runtime request payload. If 'authorization_details' is absent, structurally invalid, or fails to strictly envelop the requested transaction parameters, the operation MUST fail closed with HTTP 403 Forbidden and an 'insufficient_authorization_details' error code. ## Strict Guidelines - Resource servers MUST extract and validate the RFC 9396 'authorization_details' array from the verified JWT claims or token introspection response. - Engineers MUST NOT rely on coarse OAuth 2.0 'scope' claims to authorize operations involving financial transfer, resource delegation, or irreversible mutations. - Handlers MUST verify that the target operation matches a specific 'type' in 'authorization_details' (e.g., 'urn:example:auth:payment:transfer'). - Validators MUST verify exact-match or subset-enveloping constraints between the token's 'authorization_details' fields (e.g., amount, currency, beneficiary_account, merchant_id) and the incoming HTTP request payload. - Services MUST return HTTP 403 Forbidden with RFC 9396 error response headers ('error="insufficient_authorization_details"') when the token lacks a compatible authorization detail entry. - Components NEVER accept ambiguous wildcards in high-assurance authorization detail fields unless strictly constrained by bounded numeric/geographic thresholds. ## Bad vs Good Implementations ### Verifying RFC 9396 Structured Authorization Details vs Coarse Scope Fallback #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Checking only the 'payments:execute' coarse scope allows a compromised or replayed token generated for a low-value transaction to execute arbitrary high-value transfers or transfer to malicious destination accounts without intent binding. ```typescript import { Request, Response, NextFunction } from 'express'; interface AuthenticatedUser { sub: string; scopes: string[]; } // VULNERABLE: Coarse scope allows token re-use across unauthorized amounts, accounts, or targets export function authorizePaymentExecution(req: Request & { user?: AuthenticatedUser }, res: Response, next: NextFunction) { const userScopes = req.user?.scopes ?? []; if (!userScopes.includes('payments:execute')) { return res.status(403).json({ error: 'insufficient_scope' }); } // DANGER: No validation that the user consented to this specific transfer amount or recipient next(); } ``` #### Production Standard (Correct) > **Standard**: Validates the RFC 9396 'authorization_details' claim against the runtime HTTP body, strictly verifying that the token was explicitly authorized for the specified target account, currency, and monetary threshold. ```typescript import { Request, Response, NextFunction } from 'express'; import { z } from 'zod'; const PaymentAuthDetailSchema = z.object({ type: z.literal('urn:ietf:params:oauth:rar:payment_initiation'), actions: z.array(z.string()).refine((actions) => actions.includes('execute')), instructedAmount: z.object({ amount: z.string().regex(/^\d+(\.\d{2})?$/), currency: z.string().length(3), }), creditorAccount: z.object({ iban: z.string(), }), }); type PaymentAuthDetail = z.infer<typeof PaymentAuthDetailSchema>; interface AuthenticatedTokenClaims { sub: string; authorization_details?: unknown[]; } export function enforcePaymentTransactionBinding(req: Request & { claims?: AuthenticatedTokenClaims }, res: Response, next: NextFunction) { const rawDetails = req.claims?.authorization_details; if (!Array.isArray(rawDetails) || rawDetails.length === 0) { res.setHeader('WWW-Authenticate', 'Bearer error="insufficient_authorization_details"'); return res.status(403).json({ error: 'insufficient_authorization_details', error_description: 'RFC 9396 authorization_details required.' }); } const { amount, currency, targetIban } = req.body; // Find authorization detail strictly matching the explicit transaction request const isAuthorized = rawDetails.some((detail) => { const parsed = PaymentAuthDetailSchema.safeParse(detail); if (!parsed.success) return false; const auth = parsed.data; const amountMatches = parseFloat(amount) <= parseFloat(auth.instructedAmount.amount); const currencyMatches = currency === auth.instructedAmount.currency; const accountMatches = targetIban === auth.creditorAccount.iban; return amountMatches && currencyMatches && accountMatches; }); if (!isAuthorized) { res.setHeader('WWW-Authenticate', 'Bearer error="insufficient_authorization_details"'); return res.status(403).json({ error: 'insufficient_authorization_details', error_description: 'Transaction parameters exceed bound authorization intent.' }); } return next(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: RFC 9396 Rich Authorization Requests & Fine-Grained Transaction Binding

RFC 9396 Rich Authorization Requests & Fine-Grained Transaction Binding defines an industrial-grade behavioral standard for security engineering. Eliminates coarse scope-bloat and authorization escalation by enforcing RFC 9396 'authorization_details' verification across all sensitive resource operations. Resource servers must cryptographically bind incoming request payloads to specific, structured transaction intents (amounts, currencies, destination identifiers, and action verbs) rather than relying on generic, reusable OAuth scopes. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Authorizing High-Assurance Operations via Coarse Scopes Without Validating Structured Authorization Details Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Authorizing High-Assurance Operations via Coarse Scopes Without Validating Structured Authorization Details	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Resource servers MUST extract and validate the RFC 9396 'authorization_details' array from the verified JWT claims or token introspection response.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.