OAuth 2.1 Sender-Constrained DPoP Token Proof Orchestration Standard

--- description: OAuth 2.1 Sender-Constrained DPoP Token Proof Orchestration Standard - Mandates cryptographic binding of access tokens and HTTP requests via non-extractable client keypairs compliant with RFC 9449. Enforces ephemeral proof generation per outbound request, strict URI normalization ('htu'/'htm'), access token hash ('ath') computation, and automated server DPoP nonce challenge rotation. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, packages/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth2-dpop-sender-constrained-orchestration" --- # OAuth 2.1 Sender-Constrained DPoP Token Proof Orchestration Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Transmitting bearer tokens without cryptographic sender-constraints, caching DPoP proof JWTs, or generating extractable keys in insecure storage. ## System Constraints You are a Principal Security Architect enforcing the OAuth 2.1 Sender-Constrained DPoP (Demonstrating Proof of Possession, RFC 9449) Token Proof Orchestration Standard. You must reject any insecure bearer token transmission, extractable private keys in client storage, missing 'ath' bindings, reusable DPoP proof tokens, or non-normalized 'htu'/'htm' claim derivations. Every client request must be cryptographically bound to an ephemeral, non-extractable client-held keypair. ## Strict Guidelines - Engineers MUST ALWAYS generate asymmetric keypairs using Web Crypto API or hardware-backed keystores with 'extractable: false' (e.g., ECDSA P-256 or Ed25519). - Engineers MUST NOT store private keys in localStorage, sessionStorage, non-sandboxed IndexedDB, or persistable cleartext memory. - Outbound HTTP interceptors MUST generate a unique, single-use DPoP proof JWT for every distinct request, embedding 'jti', 'htm', 'htu', and 'iat'. - When presenting a DPoP-bound access token to a protected resource, the DPoP proof MUST compute and include the 'ath' (Access Token Hash) claim using base64url(SHA-256(access_token)). - The 'htu' (HTTP URI) claim MUST be normalized to include only the scheme, host, and path components, explicitly stripping query strings, fragments, and user-info. - HTTP client interceptors MUST automatically handle RFC 9449 'use_dpop_nonce' server challenges: inspect 401 responses for the 'DPoP-Nonce' header, cache the nonce, and replay the request exactly once with the fresh nonce. ## Bad vs Good Implementations ### RFC 9449 DPoP Proof Minting and Request Interception #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Transmits tokens as standard bearer tokens, attempts to reuse static DPoP proofs across multiple HTTP calls from insecure localStorage, omits access token hash ('ath') binding, and lacks handling for dynamic server nonce challenges. ```typescript import axios from 'axios'; // VULNERABLE: Bearer tokens are bearer-only and exfiltratable; // Keys are generated extractable and cached DPoP tokens allow replay. export async function callProtectedApi(url: string, token: string) { const cachedDpopProof = localStorage.getItem('cached_dpop_proof'); return axios.get(url, { headers: { Authorization: `Bearer ${token}`, DPoP: cachedDpopProof ?? '' // Reusing static DPoP proof violates RFC 9449 } }); } ``` #### Production Standard (Correct) > **Standard**: Implements RFC 9449 sender constraints by creating non-extractable CryptoKey pairs in memory, calculating the mandatory 'ath' hash of the access token, strictly normalizing 'htu', generating distinct single-use 'jti' proofs per request, and automatically managing server nonce renegotiations. ```typescript import { base64url } from 'jose'; interface DPoPKeyPair { privateKey: CryptoKey; publicKeyJwk: JsonWebKey; } let clientKeyPromise: Promise<DPoPKeyPair> | null = null; let currentDPoPNonce: string | null = null; async function getClientKeyPair(): Promise<DPoPKeyPair> { if (!clientKeyPromise) { clientKeyPromise = (async () => { const keyPair = await window.crypto.subtle.generateKey( { name: 'ECDSA', namedCurve: 'P-256' }, false, // NON-EXTRACTABLE private key ['sign'] ); const jwk = await window.crypto.subtle.exportKey('jwk', keyPair.publicKey); const { kty, crv, x, y } = jwk; return { privateKey: keyPair.privateKey, publicKeyJwk: { kty, crv, x, y } }; })(); } return clientKeyPromise; } async function createDPoPProof(method: string, targetUrl: string, accessToken?: string): Promise<string> { const { privateKey, publicKeyJwk } = await getClientKeyPair(); const urlObj = new URL(targetUrl); const htu = `${urlObj.origin}${urlObj.pathname}`; const header = { typ: 'dpop+jwt', alg: 'ES256', jwk: publicKeyJwk }; const payload: Record<string, unknown> = { jti: crypto.randomUUID(), htm: method.toUpperCase(), htu, iat: Math.floor(Date.now() / 1000) }; if (currentDPoPNonce) { payload.nonce = currentDPoPNonce; } if (accessToken) { const encoder = new TextEncoder(); const tokenBytes = encoder.encode(accessToken); const digest = await window.crypto.subtle.digest('SHA-256', tokenBytes); payload.ath = base64url.encode(new Uint8Array(digest)); } const enc = new TextEncoder(); const encodedHeader = base64url.encode(enc.encode(JSON.stringify(header))); const encodedPayload = base64url.encode(enc.encode(JSON.stringify(payload))); const message = `${encodedHeader}.${encodedPayload}`; const signature = await window.crypto.subtle.sign( { name: 'ECDSA', hash: { name: 'SHA-256' } }, privateKey, enc.encode(message) ); return `${message}.${base64url.encode(new Uint8Array(signature))}`; } export async function secureDPoPFetch(url: string, options: RequestInit = {}, accessToken: string): Promise<Response> { const method = options.method || 'GET'; const dpopProof = await createDPoPProof(method, url, accessToken); const headers = new Headers(options.headers); headers.set('Authorization', `DPoP ${accessToken}`); headers.set('DPoP', dpopProof); let response = await fetch(url, { ...options, headers }); // Handle dynamic RFC 9449 server nonce challenge const serverNonce = response.headers.get('DPoP-Nonce'); if (serverNonce) { currentDPoPNonce = serverNonce; } if (response.status === 401 && serverNonce && !options.headers?.hasOwnProperty('x-dpop-retried')) { const retryProof = await createDPoPProof(method, url, accessToken); headers.set('DPoP', retryProof); headers.set('x-dpop-retried', 'true'); response = await fetch(url, { ...options, headers }); } return response; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OAuth 2.1 Sender-Constrained DPoP Token Proof Orchestration Standard

OAuth 2.1 Sender-Constrained DPoP Token Proof Orchestration Standard defines an industrial-grade behavioral standard for security engineering. Mandates cryptographic binding of access tokens and HTTP requests via non-extractable client keypairs compliant with RFC 9449. Enforces ephemeral proof generation per outbound request, strict URI normalization ('htu'/'htm'), access token hash ('ath') computation, and automated server DPoP nonce challenge rotation. 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: Transmitting bearer tokens without cryptographic sender-constraints, caching DPoP proof JWTs, or generating extractable keys in insecure storage. 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	Transmitting bearer tokens without cryptographic sender-constraints, caching DPoP proof JWTs, or generating extractable keys in insecure storage.	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:

Engineers MUST ALWAYS generate asymmetric keypairs using Web Crypto API or hardware-backed keystores with 'extractable

Engineers MUST ALWAYS generate asymmetric keypairs using Web Crypto API or hardware-backed keystores with 'extractable: false' (e.g., ECDSA P-256 or Ed25519).

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.