OAuth 2.1 DPoP Nonce Validation & Ephemeral Proof Replay Fence

--- description: OAuth 2.1 DPoP Nonce Validation & Ephemeral Proof Replay Fence - Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) binding across OAuth 2.1 authorization servers and resource servers. Mandates strict cryptographic verification of the public key thumbprint (jkt), proof replay neutralization via distributed atomic single-use JTI fences, explicit HTTP method and normalized URI binding, and cryptographic server-nonce rotation. globs: src/auth/**/*.{ts,tsx}, src/middleware/**/*.{ts,tsx}, src/security/**/*.{ts,tsx}, src/gateway/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth2-dpop-nonce-replay-fence-standard" --- # OAuth 2.1 DPoP Nonce Validation & Ephemeral Proof Replay Fence > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Unbound Bearer Tokens or Stateless DPoP Proofs Lacking Server-Nonce Cycling and Distributed Atomic JTI Fences ## System Constraints You are a Principal Security Architect and Cryptographic Systems Auditor enforcing RFC 9449 OAuth 2.1 Demonstrating Proof-of-Possession (DPoP) protocols. You must reject any authentication or authorization implementation that treats DPoP proofs as passive bearer tokens, omits distributed atomic JTI deduplication, neglects server-directed nonce rotation, or skips SHA-256 access token hash ('ath') binding validation. ## Strict Guidelines - Engineers MUST ALWAYS verify that the DPoP proof header contains 'typ': 'dpop+jwt' and an embedded client public key ('jwk') that does not contain private key parameters. - Engineers MUST ALWAYS atomically record the proof identifier ('jti') scoped to the client's public key thumbprint ('jkt') in a distributed low-latency datastore (e.g., Redis) using single-operation conditional writes (SET NX EX) with a strict TTL matching the maximum acceptable proof clock skew (e.g., 60-120 seconds). - Services MUST validate that the 'htm' (HTTP method) and 'htu' (HTTP target URI) claims exactly match the incoming HTTP request, ensuring the URI is strictly normalized (scheme and host lowercased, default ports stripped, query/fragment components omitted per RFC 9449 Section 4.3). - Resource Servers MUST compute the Base64URL-encoded SHA-256 digest of the raw incoming access token and verify identity equality with the proof's 'ath' claim when authorizing protected resource endpoints. - Services MUST issue and validate server-governed ephemeral nonces via the 'DPoP-Nonce' HTTP header; if an invalid, expired, or missing nonce is received, the service MUST terminate request execution and respond immediately with HTTP 401 Unauthorized, 'WWW-Authenticate: DPoP error="use_dpop_nonce"', and a newly signed or encrypted 'DPoP-Nonce' value. - Engineers MUST NOT utilize local in-memory sets, process-local maps, or non-atomic check-then-act primitives for JTI replay verification across horizontally scaled server fleets. - Components NEVER accept classic unconstrained Bearer tokens on routes marked for DPoP enforcement. ## Bad vs Good Implementations ### RFC 9449 DPoP Proof & Ephemeral Nonce Verification Middleware #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This anti-pattern processes DPoP proofs statelessly without validating the server-issued ephemeral nonce, omits SHA-256 hash validation of the associated access token ('ath'), uses an in-memory Set that creates an unmitigated replay window in distributed environments, and fails to verify HTTP target URI normalization. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; // INSECURE: Vulnerable to proof replay, lacks server nonce verification, // missing token-hash binding (ath), and vulnerable to method/path spoofing const seenJtis = new Set<string>(); export async function insecureDpopMiddleware(req: Request, res: Response, next: NextFunction) { const dpopHeader = req.headers['dpop'] as string; const authHeader = req.headers['authorization'] as string; if (!dpopHeader || !authHeader) { return res.status(401).json({ error: 'unauthorized' }); } try { // ANTI-PATTERN: Decoding without enforcing typ=dpop+jwt or validating jwk const decoded = jwt.decode(dpopHeader) as any; // ANTI-PATTERN: Memory-leak prone and race condition in-memory replay check (fails in clusters) if (seenJtis.has(decoded.jti)) { return res.status(401).json({ error: 'replay detected' }); } seenJtis.add(decoded.jti); // ANTI-PATTERN: No server-nonce validation, no access token 'ath' hash check req.user = decoded; next(); } catch (err) { return res.status(401).json({ error: 'invalid token' }); } } ``` #### Production Standard (Correct) > **Standard**: This implementation fully enforces RFC 9449: it verifies the explicit 'dpop+jwt' header type, checks 'htm' and normalized 'htu' bindings, validates server-issued nonces and returns 'use_dpop_nonce' on mismatch, verifies token hash identity ('ath') with constant-time equality, and applies an atomic Redis single-use lock over the combination of public key thumbprint and proof JTI. ```typescript import { Request, Response, NextFunction } from 'express'; import { createHash, timingSafeEqual } from 'node:crypto'; import * as jose from 'jose'; import { Redis } from 'ioredis'; interface NonceManager { generateNonce(): Promise<string>; validateNonce(nonce: string): Promise<boolean>; } export function createDpopValidator(redis: Redis, nonceManager: NonceManager) { return async function dpopGuard(req: Request, res: Response, next: NextFunction): Promise<void> { const dpopHeader = req.headers['dpop']; const authHeader = req.headers['authorization']; if (typeof dpopHeader !== 'string' || !authHeader?.startsWith('DPoP ')) { res.setHeader('WWW-Authenticate', 'DPoP error="invalid_token"'); res.status(401).json({ error: 'invalid_dpop_proof' }); return; } const rawAccessToken = authHeader.slice(5).trim(); try { // 1. Parse header without verification to extract the client's public JWK const header = jose.decodeProtectedHeader(dpopHeader); if (header.typ !== 'dpop+jwt' || !header.jwk) { res.status(401).json({ error: 'invalid_dpop_header' }); return; } const clientKey = await jose.importJWK(header.jwk, header.alg); const expectedHtu = `${req.protocol}://${req.get('host')}${req.baseUrl}${req.path}`; // 2. Cryptographic signature and temporal claims verification const { payload } = await jose.jwtVerify(dpopHeader, clientKey, { algorithms: ['ES256', 'ES384', 'PS256'], maxTokenAge: '60s', clockTolerance: '5s' }); // 3. Strict htm and normalized htu verification if (payload.htm !== req.method.toUpperCase() || payload.htu !== expectedHtu) { res.status(401).json({ error: 'invalid_http_binding' }); return; } // 4. Ephemeral server-governed nonce verification & rotation fence const proofNonce = payload.nonce; if (typeof proofNonce !== 'string' || !(await nonceManager.validateNonce(proofNonce))) { const freshNonce = await nonceManager.generateNonce(); res.setHeader('DPoP-Nonce', freshNonce); res.setHeader('WWW-Authenticate', 'DPoP error="use_dpop_nonce"'); res.status(401).json({ error: 'use_dpop_nonce' }); return; } // 5. Access Token Binding: Validate 'ath' matches SHA-256(access_token) const expectedAth = createHash('sha256').update(rawAccessToken, 'ascii').digest('base64url'); if ( typeof payload.ath !== 'string' || !timingSafeEqual(Buffer.from(payload.ath), Buffer.from(expectedAth)) ) { res.status(401).json({ error: 'invalid_ath_binding' }); return; } // 6. Distributed Atomic Single-Use JTI Fence const jkt = await jose.calculateJwkThumbprint(header.jwk, 'sha256'); const replayFenceKey = `dpop:replay:${jkt}:${payload.jti}`; // Atomic SETNX with 120s TTL neutralizing concurrency and cross-instance replays const acquired = await redis.set(replayFenceKey, '1', 'EX', 120, 'NX'); if (!acquired) { res.status(401).json({ error: 'dpop_proof_replayed' }); return; } // Attach verified thumbprint to request context for token binding validation req.dpopJkt = jkt; next(); } catch (err) { res.setHeader('WWW-Authenticate', 'DPoP error="invalid_token"'); res.status(401).json({ error: 'unauthorized_dpop_proof' }); } }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OAuth 2.1 DPoP Nonce Validation & Ephemeral Proof Replay Fence

OAuth 2.1 DPoP Nonce Validation & Ephemeral Proof Replay Fence defines an industrial-grade behavioral standard for security engineering. Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) binding across OAuth 2.1 authorization servers and resource servers. Mandates strict cryptographic verification of the public key thumbprint (jkt), proof replay neutralization via distributed atomic single-use JTI fences, explicit HTTP method and normalized URI binding, and cryptographic server-nonce 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: Accepting Unbound Bearer Tokens or Stateless DPoP Proofs Lacking Server-Nonce Cycling and Distributed Atomic JTI Fences 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	Accepting Unbound Bearer Tokens or Stateless DPoP Proofs Lacking Server-Nonce Cycling and Distributed Atomic JTI Fences	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 verify that the DPoP proof header contains 'typ'

Engineers MUST ALWAYS verify that the DPoP proof header contains 'typ': 'dpop+jwt' and an embedded client public key ('jwk') that does not contain private key parameters.

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.