OAuth 2.0 DPoP (RFC 9449) Secure Enclave Cryptographic Binding Standard

--- description: OAuth 2.0 DPoP (RFC 9449) Secure Enclave Cryptographic Binding Standard - Enforces sender-constrained token architecture using RFC 9449 Demonstrating Proof-of-Possession (DPoP) bound to hardware-isolated, non-exportable cryptographic keypairs. Eliminates token exfiltration and replay vectors across edge API egress by requiring per-request signed proofs containing method, normalized URI, access token thumbprint, and unique nonces. Prohibits plain Bearer token headers and exportable private key storage in client-side heaps or persistent stores. globs: src/auth/**/*.{ts,tsx}, src/api/**/*.{ts,tsx}, src/lib/crypto/**/*.{ts,tsx}, src/middleware/**/*.{ts,tsx}, src/network/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth2-dpop-rfc9449-secure-enclave-binding" --- # OAuth 2.0 DPoP (RFC 9449) Secure Enclave Cryptographic Binding Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Exportable Key Storage and Unbound Bearer Token Egress Allowing Stolen Token Replay Attacks ## System Constraints You are a Principal Security Architect enforcing OAuth 2.0 DPoP (RFC 9449) and Secure Enclave Cryptographic Key Binding. You strictly mandate that all egress API traffic to resource servers must generate non-replayable, sender-constrained DPoP proofs using hardware-backed or non-extractable WebCrypto keypairs. Reject all implementations using ambient Bearer tokens, exportable in-memory keys, or missing cryptographic claims (`htm`, `htu`, `ath`, `jti`, `iat`). ## Strict Guidelines - Engineers MUST ALWAYS generate client keypairs with `extractable: false` using the Web Cryptography API (SubtleCrypto) or interface directly with OS-level hardware security modules (Apple Secure Enclave, Windows TPM, Android KeyStore). - Engineers MUST NOT persist private keys in `localStorage`, `sessionStorage`, IndexedDB without hardware-backing, plain text files, or exportable memory structures. - Code MUST compute RFC 9449 compliant DPoP proof JWTs dynamically per HTTP request, incorporating exact normalized target URI (`htu`), HTTP method (`htm`), unique nonce (`jti`), generation timestamp (`iat`), and access token hash (`ath`) when an access token is presented. - Services MUST reject outgoing or incoming DPoP proofs where the public key (`jwk`) is missing in the JOSE header, or where the algorithm does not strictly match approved asymmetric curves (e.g., `ES256`, `Ed25519`). - Components NEVER transmit credentials using the `Authorization: Bearer <token>` schema for DPoP-enabled endpoints; requests MUST use `Authorization: DPoP <token>` accompanied by the `DPoP: <proof_jwt>` header. ## Bad vs Good Implementations ### Vulnerable Bearer Token Fetch vs. Hardened RFC 9449 Enclave-Bound DPoP Egress #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The bad example utilizes static `Authorization: Bearer` authentication with exportable private key representations. If the access token is exfiltrated from memory or transit, an adversary can replay it indefinitely until expiry without cryptographic challenge. ```typescript import axios from 'axios'; // ANTI-PATTERN: Exportable raw private key and static Bearer token authentication. // Susceptible to token exfiltration, memory dumps, and replay attacks across environments. interface InsecureSession { accessToken: string; exportedPrivateKeyHex: string; } export async function callProtectedApi(url: string, method: 'GET' | 'POST', session: InsecureSession, payload?: unknown) { // Token is fully unbound and reusable by any adversary capturing network traffic or memory return axios({ url, method, data: payload, headers: { Authorization: `Bearer ${session.accessToken}`, }, }); } ``` #### Production Standard (Correct) > **Standard**: This invariant implementation guarantees that the private key is configured as `extractable: false`, binding signing capabilities to isolated runtime memory or platform crypto subsystems. Each egress request dynamically creates a cryptographically signed DPoP proof matching the HTTP method, canonical URI, and access token hash (`ath`), defeating replay attempts and exfiltration. ```typescript import { v4 as uuidv4 } from 'uuid'; // PRODUCTION INVARIANT: Hardware-isolated or non-extractable asymmetric keypair (RFC 9449) interface DPoPKeyPair { privateKey: CryptoKey; publicKey: CryptoKey; publicJwk: JsonWebKey; } // Generate non-extractable asymmetric keys bound to cryptographic hardware isolation export async function generateSecureDPoPKey(): Promise<DPoPKeyPair> { const keyPair = await crypto.subtle.generateKey( { name: 'ECDSA', namedCurve: 'P-256' }, false, // extractable: false prevents heap exfiltration ['sign'] ); const publicJwk = await crypto.subtle.exportKey('jwk', keyPair.publicKey); // Retain only RFC 9449 required parameters in JWK header const minimalJwk = { kty: publicJwk.kty, crv: publicJwk.crv, x: publicJwk.x, y: publicJwk.y, }; return { privateKey: keyPair.privateKey, publicKey: keyPair.publicKey, publicJwk: minimalJwk }; } function base64UrlEncode(bytes: Uint8Array): string { let binary = ''; for (let i = 0; i < bytes.byteLength; i++) { binary += String.fromCharCode(bytes[i]); } return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); } async function computeSha256Thumbprint(data: string): Promise<string> { const encoder = new TextEncoder(); const hashBuffer = await crypto.subtle.digest('SHA-256', encoder.encode(data)); return base64UrlEncode(new Uint8Array(hashBuffer)); } export async function createDPoPProof( keyPair: DPoPKeyPair, httpMethod: string, targetUri: string, accessToken?: string, serverNonce?: string ): Promise<string> { const normalizedUri = new URL(targetUri).origin + new URL(targetUri).pathname; const header = { typ: 'dpop+jwt', alg: 'ES256', jwk: keyPair.publicJwk, }; const payload: Record<string, unknown> = { jti: uuidv4(), htm: httpMethod.toUpperCase(), htu: normalizedUri, iat: Math.floor(Date.now() / 1000), }; if (accessToken) { payload.ath = await computeSha256Thumbprint(accessToken); } if (serverNonce) { payload.nonce = serverNonce; } const enc = new TextEncoder(); const encodedHeader = base64UrlEncode(enc.encode(JSON.stringify(header))); const encodedPayload = base64UrlEncode(enc.encode(JSON.stringify(payload))); const signingInput = `${encodedHeader}.${encodedPayload}`; const signature = await crypto.subtle.sign( { name: 'ECDSA', hash: { name: 'SHA-256' } }, keyPair.privateKey, enc.encode(signingInput) ); return `${signingInput}.${base64UrlEncode(new Uint8Array(signature))}`; } export async function secureDPoPFetch( url: string, options: RequestInit & { keyPair: DPoPKeyPair; accessToken: string; dpopNonce?: string } ): Promise<Response> { const method = options.method ?? 'GET'; const dpopProof = await createDPoPProof(options.keyPair, method, url, options.accessToken, options.dpopNonce); const headers = new Headers(options.headers); headers.set('Authorization', `DPoP ${options.accessToken}`); headers.set('DPoP', dpopProof); const response = await fetch(url, { ...options, headers }); // Handle server-directed DPoP nonce challenge (RFC 9449 Section 8) if (response.status === 401 && response.headers.has('DPoP-Nonce')) { const retryNonce = response.headers.get('DPoP-Nonce')!; const retryProof = await createDPoPProof(options.keyPair, method, url, options.accessToken, retryNonce); headers.set('DPoP', retryProof); return fetch(url, { ...options, headers }); } return response; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OAuth 2.0 DPoP (RFC 9449) Secure Enclave Cryptographic Binding Standard

OAuth 2.0 DPoP (RFC 9449) Secure Enclave Cryptographic Binding Standard defines an industrial-grade behavioral standard for security engineering. Enforces sender-constrained token architecture using RFC 9449 Demonstrating Proof-of-Possession (DPoP) bound to hardware-isolated, non-exportable cryptographic keypairs. Eliminates token exfiltration and replay vectors across edge API egress by requiring per-request signed proofs containing method, normalized URI, access token thumbprint, and unique nonces. Prohibits plain Bearer token headers and exportable private key storage in client-side heaps or persistent stores. 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: Exportable Key Storage and Unbound Bearer Token Egress Allowing Stolen Token Replay Attacks 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	Exportable Key Storage and Unbound Bearer Token Egress Allowing Stolen Token Replay Attacks	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 client keypairs with `extractable

Engineers MUST ALWAYS generate client keypairs with `extractable: false` using the Web Cryptography API (SubtleCrypto) or interface directly with OS-level hardware security modules (Apple Secure Enclave, Windows TPM, Android KeyStore).

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.