RFC 9449 DPoP Sender-Constrained Token Verification and Ephemeral Nonce Fencing

--- description: RFC 9449 DPoP Sender-Constrained Token Verification and Ephemeral Nonce Fencing - Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) verification across all edge gateways and APIs to neutralize bearer token exfiltration. Requires cryptographic sender-constraining of access tokens via the 'ath' thumbprint and enforces cryptographically signed ephemeral nonces with strict replay rejection across distributed regions. globs: src/auth/**/*.{ts,tsx}, src/middleware/**/*.{ts,tsx}, src/gateway/**/*.{ts,tsx}, src/lib/security/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth2-rfc9449-dpop-ephemeral-nonce-fencing" --- # RFC 9449 DPoP Sender-Constrained Token Verification and Ephemeral Nonce Fencing > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Unbound Bearer Tokens or Omitting Ephemeral Nonce and Access Token Hash (ath) Validation in DPoP Proofs ## System Constraints You are a Principal Security Architect enforcing OAuth 2.1 RFC 9449 (DPoP) across multi-region edge architectures. You must mandate strict sender-constraining for all API and token endpoints. You must reject all non-DPoP bearer tokens where DPoP is required, enforce asymmetric proof-of-possession verification with embedded JWK headers, validate the access token hash ('ath'), verify strict HTTP method ('htm') and normalized URI ('htu') claims, and require AEAD-authenticated or state-fenced ephemeral DPoP nonces to neutralize replay and exfiltration attacks across distributed edge gateways. ## Strict Guidelines - Engineers MUST ALWAYS enforce strict RFC 9449 DPoP verification on protected resources, rejecting legacy Bearer schemes when DPoP is mandated by returning HTTP 401 with 'WWW-Authenticate: DPoP error="invalid_token"'. - Services MUST validate the DPoP Proof JWT header contains 'typ': 'dpop+jwt' and an asymmetric algorithm ('alg': 'ES256', 'ES384', 'ES512', or 'EdDSA'); symmetric algorithms ('HS*') or 'none' MUST BE explicitly rejected. - Engineers MUST verify the 'ath' (access token hash) claim matches the base64url-encoded SHA-256 digest of the incoming access token to prevent cross-token proof reuse. - Edge gateways MUST validate that the 'htm' claim matches the HTTP request method and 'htu' matches the fully normalized request URI without query or fragment components. - Services MUST enforce server-issued ephemeral nonces: if the DPoP proof lacks a valid, unexpired, region-fenced 'nonce' claim, the gateway MUST reject the request with HTTP 401, 'WWW-Authenticate: DPoP error="use_dpop_nonce"', and a fresh 'DPoP-Nonce' header. - Components NEVER store or trust client-supplied public keys without validating they are public-only JWKs (containing no private key components like 'd') and verifying that the JWT signature is valid against that embedded JWK. ## Bad vs Good Implementations ### DPoP Token and Ephemeral Nonce Verification Middleware #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This anti-pattern treats DPoP as optional, accepts unverified JWTs, fails to validate the asymmetric proof signature against the embedded JWK, omits the mandatory 'ath' binding (allowing exfiltrated access tokens to be paired with arbitrary proofs), and omits ephemeral nonce verification, leaving the gateway completely vulnerable to replay attacks across edge nodes. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; // ANTI-PATTERN: Insecure DPoP handling without nonce validation, no 'ath' binding, // and allowing symmetric or missing proof tokens. export function insecureDpopMiddleware(req: Request, res: Response, next: NextFunction): void { const authHeader = req.headers.authorization; const dpopProof = req.headers.dpop as string | undefined; if (!authHeader || !authHeader.startsWith('DPoP ')) { res.status(401).json({ error: 'unauthorized' }); return; } const token = authHeader.substring(5); // Flaw 1: DPoP proof is optional or ignored if (!dpopProof) { // Treating DPoP as a standard bearer token breaks sender-constraining next(); return; } // Flaw 2: Decoding without signature verification or alg whitelisting const decoded = jwt.decode(dpopProof) as Record<string, unknown> | null; if (!decoded) { res.status(401).json({ error: 'invalid_dpop' }); return; } // Flaw 3: No 'ath' (Access Token Hash) validation, no 'nonce' replay check, no 'htm'/'htu' checks req.user = decoded; next(); } ``` #### Production Standard (Correct) > **Standard**: This implementation fully enforces RFC 9449 specifications: it checks the DPoP header typ and asymmetric algorithm whitelist, ensures the embedded JWK is public-only, verifies the cryptographic signature, matches the HTTP method and normalized URI, performs constant-time comparison on the 'ath' access token hash, and validates ephemeral nonces to prevent token replay attacks across distributed regions. ```typescript import { Request, Response, NextFunction } from 'express'; import { createHash, timingSafeEqual } from 'crypto'; import * as jose from 'jose'; interface NonceFencingService { validateAndConsumeNonce(nonce: string, region: string): Promise<boolean>; generateNonce(region: string): Promise<string>; } export function createDPoPVerifier(nonceService: NonceFencingService, currentRegion: string) { return async function dpopMiddleware(req: Request, res: Response, next: NextFunction): Promise<void> { const authHeader = req.headers.authorization; const dpopHeader = req.headers.dpop; if (!authHeader || !authHeader.startsWith('DPoP ')) { res.setHeader('WWW-Authenticate', 'DPoP error="invalid_token", error_description="DPoP scheme required"'); res.status(401).json({ error: 'invalid_token' }); return; } if (typeof dpopHeader !== 'string' || !dpopHeader.trim()) { const newNonce = await nonceService.generateNonce(currentRegion); res.setHeader('DPoP-Nonce', newNonce); res.setHeader('WWW-Authenticate', 'DPoP error="use_dpop_nonce"'); res.status(401).json({ error: 'use_dpop_nonce' }); return; } const accessToken = authHeader.slice(5).trim(); try { // Step 1: Decode header to inspect JWK and algorithm const protectedHeader = jose.decodeProtectedHeader(dpopHeader); if (protectedHeader.typ !== 'dpop+jwt') { throw new Error('Invalid DPoP header typ'); } const allowedAlgs = ['ES256', 'ES384', 'ES512', 'EdDSA']; if (!protectedHeader.alg || !allowedAlgs.includes(protectedHeader.alg)) { throw new Error('Unsupported or non-asymmetric DPoP alg'); } const jwk = protectedHeader.jwk; if (!jwk || typeof jwk !== 'object' || 'd' in jwk) { throw new Error('JWK missing or contains private key components'); } // Step 2: Verify DPoP Proof signature using the embedded public JWK const key = await jose.importJWK(jwk, protectedHeader.alg); const { payload } = await jose.jwtVerify(dpopHeader, key, { algorithms: allowedAlgs, maxTokenAge: '90s' }); // Step 3: Validate HTM and normalized HTU claims (RFC 9449 Section 4.2) const expectedMethod = req.method.toUpperCase(); const fullUrl = new URL(`${req.protocol}://${req.get('host')}${req.originalUrl}`); const normalizedHtu = `${fullUrl.protocol}//${fullUrl.host}${fullUrl.pathname}`; if (payload.htm !== expectedMethod || payload.htu !== normalizedHtu) { throw new Error('DPoP htm or htu mismatch'); } // Step 4: Validate Access Token Hash ('ath') const expectedAth = createHash('sha256').update(accessToken, 'utf8').digest('base64url'); if (typeof payload.ath !== 'string' || !timingSafeEqual(Buffer.from(payload.ath), Buffer.from(expectedAth))) { throw new Error('DPoP ath token binding verification failed'); } // Step 5: Ephemeral Nonce Fencing if (typeof payload.nonce !== 'string') { throw new Error('DPoP proof missing nonce'); } const isNonceValid = await nonceService.validateAndConsumeNonce(payload.nonce, currentRegion); if (!isNonceValid) { const freshNonce = await nonceService.generateNonce(currentRegion); res.setHeader('DPoP-Nonce', freshNonce); res.setHeader('WWW-Authenticate', 'DPoP error="use_dpop_nonce", error_description="Nonce expired or replayed"'); res.status(401).json({ error: 'use_dpop_nonce' }); return; } // Compute sender thumbprint and attach to request context const thumbprint = await jose.calculateJwkThumbprint(jwk, 'sha256'); req.dpop = { thumbprint, claims: payload }; next(); } catch (error) { res.setHeader('WWW-Authenticate', 'DPoP error="invalid_dpop_proof"'); res.status(401).json({ error: 'invalid_dpop_proof' }); } }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: RFC 9449 DPoP Sender-Constrained Token Verification and Ephemeral Nonce Fencing

RFC 9449 DPoP Sender-Constrained Token Verification and Ephemeral Nonce Fencing defines an industrial-grade behavioral standard for security engineering. Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) verification across all edge gateways and APIs to neutralize bearer token exfiltration. Requires cryptographic sender-constraining of access tokens via the 'ath' thumbprint and enforces cryptographically signed ephemeral nonces with strict replay rejection across distributed regions. 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 Omitting Ephemeral Nonce and Access Token Hash (ath) Validation in DPoP Proofs 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 Omitting Ephemeral Nonce and Access Token Hash (ath) Validation in DPoP Proofs	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 enforce strict RFC 9449 DPoP verification on protected resources, rejecting legacy Bearer schemes when DPoP is mandated by returning HTTP 401 with 'WWW-Authenticate

Engineers MUST ALWAYS enforce strict RFC 9449 DPoP verification on protected resources, rejecting legacy Bearer schemes when DPoP is mandated by returning HTTP 401 with 'WWW-Authenticate: DPoP error="invalid_token"'.

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.