OAuth 2.0 DPoP Proof-of-Possession and Ephemeral Nonce-Binding Standard

Enforces strict RFC 9449 compliance for Demonstrating Proof-of-Possession (DPoP) across all single-page applications and API consumers. Mandates that non-extractable CryptoKey pairs bound to Web Crypto IndexedDB generate single-use signed DPoP proofs for every mutating and token-exchange request, strictly managing server-supplied DPoP nonces with automatic replay-retry loops. Eliminates bearer token exfiltration risks by cryptographically coupling the access token and request context to asymmetric hardware/browser-isolated keys.

--- description: OAuth 2.0 DPoP Proof-of-Possession and Ephemeral Nonce-Binding Standard - Enforces strict RFC 9449 compliance for Demonstrating Proof-of-Possession (DPoP) across all single-page applications and API consumers. Mandates that non-extractable CryptoKey pairs bound to Web Crypto IndexedDB generate single-use signed DPoP proofs for every mutating and token-exchange request, strictly managing server-supplied DPoP nonces with automatic replay-retry loops. Eliminates bearer token exfiltration risks by cryptographically coupling the access token and request context to asymmetric hardware/browser-isolated keys. globs: src/**/auth/**/*.{ts,tsx}, src/**/api/**/*.{ts,tsx}, src/**/http/**/*.{ts,tsx}, src/**/services/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth2-dpop-nonce-binding-guardrail" --- # OAuth 2.0 DPoP Proof-of-Possession and Ephemeral Nonce-Binding Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Bearer-Token Fallback, Reused DPoP Proofs, and Non-Extractable Key Leakage in SPA HTTP Clients ## System Constraints You are a Principal Security Architect enforcing OAuth 2.0 Demonstrating Proof-of-Possession (DPoP - RFC 9449) and token binding standards. You must ensure that client applications never fallback to static Bearer authorization when interacting with DPoP-enabled AS/RS endpoints, guarantee private keys are created as non-extractable via Web Crypto API, enforce exact htu and htm claim binding, and require robust nonce synchronization loops on HTTP 401 'use_dpop_nonce' responses. ## Strict Guidelines - Engineers MUST ALWAYS generate DPoP keypairs using Web Crypto API (`window.crypto.subtle.generateKey`) with `extractable: false` and persistent storage via IndexedDB. - Engineers MUST NOT export or expose private keys in memory dumps, logs, global scope, or serialize them into `localStorage` / `sessionStorage`. - Code MUST generate a fresh DPoP proof JWT with a unique `jti` (UUID v4) and current epoch `iat` for every single HTTP request; proofs MUST NEVER be cached or re-sent across distinct requests. - Services MUST capture `DPoP-Nonce` response headers from authorization and resource servers and cache the latest nonce in memory for subsequent outbound requests. - HTTP interceptors MUST implement a bounded, single-retry loop (max 1 retry) when receiving an HTTP 401 response containing `error="use_dpop_nonce"`, immediately updating the stored nonce and regenerating the proof. - Tokens MUST be bound using the `DPoP <access_token>` Authorization header scheme rather than `Bearer <access_token>` whenever DPoP keys are established. - Components NEVER construct DPoP proofs with mismatched `htu` (must match exact canonical target URI without query/fragment) or `htm` (must match HTTP method in uppercase). ## Bad vs Good Implementations ### Anti-Pattern: Insecure Exportable Key & Static Bearer Token Dispatch #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Transmits tokens as raw Bearer credentials without DPoP proof headers. If the access token is exfiltrated from browser memory, an adversary can use it indefinitely until expiry. It does not establish non-extractable asymmetric keys or respect RFC 9449 proof-of-possession constraints. ```typescript import axios from 'axios'; // Flaw 1: Keys are extractable and held in memory / local storage // Flaw 2: Reusing static authorization headers without per-request DPoP proof // Flaw 3: No handling of DPoP-Nonce challenge from authorization server export async function fetchProtectedResource(url: string, accessToken: string) { return axios.get(url, { headers: { Authorization: `Bearer ${accessToken}`, }, }); } ``` #### Production Standard (Correct) > **Standard**: Implements RFC 9449 compliance. Generates an in-memory, non-extractable P-256 keypair via Web Crypto. Generates a unique, single-use proof with exact `htm`, canonical `htu`, `iat`, and `jti`. Properly binds the Authorization header with `DPoP <token>` and performs an automatic re-sign and retry loop when the server issues a fresh `DPoP-Nonce`. ```typescript import { SignJWT } from 'jose'; interface DPoPContext { keyPair: CryptoKeyPair; cachedNonce?: string; } let dpopContext: DPoPContext | null = null; async function getOrCreateDPoPKeyPair(): Promise<CryptoKeyPair> { if (dpopContext?.keyPair) return dpopContext.keyPair; const keyPair = await window.crypto.subtle.generateKey( { name: 'ECDSA', namedCurve: 'P-256' }, false, // Enforce non-extractable ['sign'] ); dpopContext = { keyPair }; return keyPair; } async function createDPoPProof(method: string, uri: string, nonce?: string): Promise<string> { const keyPair = await getOrCreateDPoPKeyPair(); const cleanUri = uri.split(/[?#]/)[0]; const publicJwk = await window.crypto.subtle.exportKey('jwk', keyPair.publicKey); return new SignJWT({ htm: method.toUpperCase(), htu: cleanUri, ...(nonce ? { nonce } : {}) }) .setProtectedHeader({ alg: 'ES256', typ: 'dpop+jwt', jwk: publicJwk }) .setIssuedAt() .setJti(crypto.randomUUID()) .sign(keyPair.privateKey); } export async function secureDPoPFetch(url: string, accessToken: string, init: RequestInit = {}): Promise<Response> { const method = init.method ?? 'GET'; let proof = await createDPoPProof(method, url, dpopContext?.cachedNonce); const execute = (dpopHeader: string) => fetch(url, { ...init, headers: { ...init.headers, Authorization: `DPoP ${accessToken}`, DPoP: dpopHeader, }, }); let response = await execute(proof); const newNonce = response.headers.get('dpop-nonce'); if (newNonce && dpopContext) { dpopContext.cachedNonce = newNonce; } // Handle server-issued nonce invalidation if (response.status === 401 && newNonce) { const retryProof = await createDPoPProof(method, url, newNonce); response = await execute(retryProof); } return response; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OAuth 2.0 DPoP Proof-of-Possession and Ephemeral Nonce-Binding Standard

OAuth 2.0 DPoP Proof-of-Possession and Ephemeral Nonce-Binding Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict RFC 9449 compliance for Demonstrating Proof-of-Possession (DPoP) across all single-page applications and API consumers. Mandates that non-extractable CryptoKey pairs bound to Web Crypto IndexedDB generate single-use signed DPoP proofs for every mutating and token-exchange request, strictly managing server-supplied DPoP nonces with automatic replay-retry loops. Eliminates bearer token exfiltration risks by cryptographically coupling the access token and request context to asymmetric hardware/browser-isolated keys. 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: Bearer-Token Fallback, Reused DPoP Proofs, and Non-Extractable Key Leakage in SPA HTTP Clients 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	Bearer-Token Fallback, Reused DPoP Proofs, and Non-Extractable Key Leakage in SPA HTTP Clients	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 DPoP keypairs using Web Crypto API (`window.crypto.subtle.generateKey`) with `extractable

Engineers MUST ALWAYS generate DPoP keypairs using Web Crypto API (`window.crypto.subtle.generateKey`) with `extractable: false` and persistent storage via IndexedDB.

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.