OAuth 2.1 DPoP Proof Validation, Nonce Enforcement, and Token Binding Verification

--- description: OAuth 2.1 DPoP Proof Validation, Nonce Enforcement, and Token Binding Verification - Mandates strict RFC 9449 compliance for DPoP (Demonstrating Proof-of-Possession) verification across Authorization Servers and Resource Servers. Enforces asymmetric key thumbprint matching (jkt/cnf), cryptographic validation of DPoP proof headers and claims (typ, htm, htu, ath, nonce), and distributed jti cache tracking to prevent replay attacks within clock skew bounds. globs: src/auth/**/*.{ts,tsx}, src/middleware/**/*.{ts,tsx}, src/security/**/*.{ts,tsx}, src/tokens/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth2-dpop-replay-and-binding-verification-standard" --- # OAuth 2.1 DPoP Proof Validation, Nonce Enforcement, and Token Binding Verification > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Bypassing DPoP Nonce Validation, Ignoring Access Token Hash (ath), or Accepting Unbound Bearer Tokens ## System Constraints You are a Principal Security Architect and Rules Author enforcing OAuth 2.1 RFC 9449 DPoP invariants. Reject any implementation that treats DPoP proofs as plain JWTs, skips asymmetric key thumbprint confirmation (jkt/cnf), fails to validate access token hashes (ath), omits strict htm/htu matching, or allows DPoP proof replay without jti and nonce checks. ## Strict Guidelines - Services MUST verify that the DPoP proof header contains typ equal to 'dpop+jwt' and an asymmetric jwk (public key only) with no private key parameters. - Services MUST reject symmetric algorithms (e.g., HS256) or 'none'; only approved asymmetric signing algorithms (e.g., ES256, EdDSA, PS256) MUST be accepted. - Resource Servers MUST compute the SHA-256 hash of the received Access Token (ath claim) and verify it matches the ath claim in the DPoP proof JWT payload. - Resource Servers MUST verify that the proof's public key SHA-256 thumbprint matches the cnf.jkt claim embedded within the bound access token. - Services MUST validate that the htm claim strictly matches the HTTP request method and the htu claim matches the normalized HTTP request URI without query or fragment components. - Services MUST enforce server-provided DPoP nonces and atomically verify and store the proof jti with a TTL matching max acceptable clock skew (max 60 seconds) to strictly prevent replay attacks. ## Bad vs Good Implementations ### DPoP Proof Validation Middleware with Nonce and JTI Cache #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to verify the DPoP JWT signature against the embedded JWK, accepts insecure headers, ignores the 'dpop+jwt' typ enforcement, does not validate htm, htu, ath, or server nonces, and omits jti replay cache enforcement. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; export async function badDpopMiddleware(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).send('Missing headers'); // VULNERABILITY 1: Decode without cryptographic key verification from jwk // VULNERABILITY 2: No check for typ === 'dpop+jwt' const proof = jwt.decode(dpopHeader) as any; const token = authHeader.replace('Bearer ', ''); // VULNERABILITY 3: No validation of htm, htu, ath, or server nonce // VULNERABILITY 4: No jti tracking allows instant replay attacks if (proof && proof.iat > Date.now() / 1000 - 300) { return next(); } return res.status(401).send('Invalid proof'); } ``` #### Production Standard (Correct) > **Standard**: Implements RFC 9449 compliant verification: validates typ header ('dpop+jwt'), enforces asymmetric algorithms, calculates the SHA-256 access token hash (ath), checks canonical HTTP method (htm) and URI (htu), issues and validates DPoP nonces, prevents replays using jti caching, and calculates the JWK thumbprint (jkt). ```typescript import { Request, Response, NextFunction } from 'express'; import crypto from 'node:crypto'; import * as jose from 'jose'; interface ReplayCache { has(jti: string): Promise<boolean>; set(jti: string, ttlSeconds: number): Promise<void>; } interface NonceManager { isValid(nonce: string): Promise<boolean>; generate(): string; } export function createDPoPVerifier(replayCache: ReplayCache, nonceManager: NonceManager) { return async function verifyDPoP(req: Request, res: Response, next: NextFunction) { const dpopProof = req.headers['dpop']; const authHeader = req.headers['authorization']; if (typeof dpopProof !== 'string' || !authHeader?.startsWith('DPoP ')) { return res.status(401).setHeader('WWW-Authenticate', 'DPoP error="invalid_token"').json({ error: 'Missing or malformed DPoP token/proof' }); } const rawAccessToken = authHeader.slice(5).trim(); try { const header = jose.decodeProtectedHeader(dpopProof); if (header.typ !== 'dpop+jwt' || !header.jwk || header.alg === 'none' || header.alg.startsWith('HS')) { return res.status(401).json({ error: 'Invalid DPoP header typography or insecure algorithm' }); } const publicKey = await jose.importJWK(header.jwk, header.alg); const { payload } = await jose.jwtVerify(dpopProof, publicKey, { algorithms: ['ES256', 'PS256', 'EdDSA'], maxTokenAge: '60s' }); // Strict HTM and HTU verification const expectedHtu = `${req.protocol}://${req.get('host')}${req.baseUrl}${req.path}`; if (payload.htm !== req.method || payload.htu !== expectedHtu) { return res.status(401).json({ error: 'DPoP proof htm/htu mismatch' }); } // Nonce Verification if (!payload.nonce || !(await nonceManager.isValid(String(payload.nonce)))) { const newNonce = nonceManager.generate(); res.setHeader('DPoP-Nonce', newNonce); return res.status(401).setHeader('WWW-Authenticate', 'DPoP error="use_dpop_nonce"').json({ error: 'Invalid or expired DPoP-Nonce' }); } // Access Token Hash (ath) Verification const expectedAth = crypto.createHash('sha256').update(rawAccessToken, 'ascii').digest('base64url'); if (payload.ath !== expectedAth) { return res.status(401).json({ error: 'Access token hash (ath) mismatch' }); } // JTI Replay Prevention const jti = String(payload.jti); if (!jti || (await replayCache.has(jti))) { return res.status(401).json({ error: 'DPoP proof replayed or jti missing' }); } await replayCache.set(jti, 60); // Key-binding thumbprint computation for downstream consumption const thumbprint = await jose.calculateJwkThumbprint(header.jwk, 'sha256'); (req as any).dpopJkt = thumbprint; return next(); } catch (err) { return res.status(401).json({ error: 'DPoP proof cryptographic verification failed' }); } }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OAuth 2.1 DPoP Proof Validation, Nonce Enforcement, and Token Binding Verification

OAuth 2.1 DPoP Proof Validation, Nonce Enforcement, and Token Binding Verification defines an industrial-grade behavioral standard for security engineering. Mandates strict RFC 9449 compliance for DPoP (Demonstrating Proof-of-Possession) verification across Authorization Servers and Resource Servers. Enforces asymmetric key thumbprint matching (jkt/cnf), cryptographic validation of DPoP proof headers and claims (typ, htm, htu, ath, nonce), and distributed jti cache tracking to prevent replay attacks within clock skew bounds. 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: Bypassing DPoP Nonce Validation, Ignoring Access Token Hash (ath), or Accepting Unbound Bearer Tokens 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	Bypassing DPoP Nonce Validation, Ignoring Access Token Hash (ath), or Accepting Unbound Bearer Tokens	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:

Services MUST verify that the DPoP proof header contains typ equal to 'dpop+jwt' and an asymmetric jwk (public key only) with no 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.