OAuth 2.1 RFC 9449 DPoP Single-Use Nonce Cluster Enforcement

--- description: OAuth 2.1 RFC 9449 DPoP Single-Use Nonce Cluster Enforcement - Enforces atomic, cluster-wide verification of OAuth 2.1 Demonstrating Proof-of-Possession (DPoP, RFC 9449) proofs and ephemeral nonces across distributed edge proxies. Guarantees linearizable single-use proof validation and access token hash binding to eliminate replay attacks across multi-region ingress points. globs: src/auth/**/*.{ts,js}, src/middleware/**/*.{ts,js}, src/gateway/**/*.{ts,js}, src/security/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth2-dpop-distributed-nonce-enforcement" --- # OAuth 2.1 RFC 9449 DPoP Single-Use Nonce Cluster Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Process-Local Nonce Validation and Non-Atomic Read-Then-Write Replay Windows Across Edge Nodes ## System Constraints You are a Principal Security Architect enforcing OAuth 2.1 DPoP (RFC 9449) across distributed edge ingress proxies. You must ensure all DPoP proof validations enforce single-use nonces and unique JTIs atomically in high-throughput distributed memory tiers, strictly verifying thumbprint (jkt) and access token hash (ath) bindings. ## Strict Guidelines - Engineers MUST ALWAYS validate DPoP proofs using atomic distributed check-and-set operations (e.g., Redis EVAL Lua script or atomic SET NX EX) to ensure single-use nonce consumption across all cluster nodes. - Engineers MUST NOT rely on in-process memory structures (e.g., local Maps, LRU caches) for DPoP proof JTI or nonce validation in multi-instance or serverless deployments. - Code MUST strictly verify the 'ath' (Access Token Hash) claim inside the DPoP proof JWT against the SHA-256 base64url-encoded hash of the presented access token. - Services MUST issue a fresh, high-entropy cluster-coordinated 'DPoP-Nonce' header with an HTTP 401 response and 'error="use_dpop_nonce"' when the presented nonce is missing, expired, or already consumed. - Components NEVER accept DPoP proof JWTs whose 'htm' (HTTP method) or 'htu' (HTTP URI normalized target) fail an exact match against the incoming request's ingress envelope. ## Bad vs Good Implementations ### Distributed Atomic DPoP Nonce and Proof Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses an in-process Set to record JTIs, allowing an attacker to replay the exact same DPoP proof against another edge worker instance. It also fails to atomically validate and consume cluster nonces and completely ignores the mandatory 'ath' binding check against the access token. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; // CRITICAL FLAW: In-process memory store allows multi-node replay attacks. const localSeenJti = new Set<string>(); export async function dpopMiddleware(req: Request, res: Response, next: NextFunction) { const dpopHeader = req.header('dpop'); const authHeader = req.header('authorization'); if (!dpopHeader || !authHeader) { return res.status(401).json({ error: 'invalid_dpop_proof' }); } const decoded = jwt.decode(dpopHeader) as { jti?: string; nonce?: string }; // Non-atomic read-then-write; fails across multi-ingress clusters if (!decoded?.jti || localSeenJti.has(decoded.jti)) { return res.status(401).json({ error: 'invalid_token', error_description: 'Replayed JTI' }); } localSeenJti.add(decoded.jti); // Missing 'ath' validation and missing centralized ephemeral nonce check return next(); } ``` #### Production Standard (Correct) > **Standard**: Implements an atomic Redis Lua transaction that concurrently verifies single-use nonce consumption and records the DPoP JTI under cluster-wide synchronization. Strictly verifies the SHA-256 'ath' hash binding against the incoming DPoP access token to prevent token export and distributed replay attacks. ```typescript import { Request, Response, NextFunction } from 'express'; import crypto from 'crypto'; import { createRemoteJWKSet, jwtVerify } from 'jose'; import type { Redis } from 'ioredis'; const CONSUME_DPOP_LUA = ` local nonce_key = KEYS[1] local jti_key = KEYS[2] local jti_ttl = ARGV[1] local nonce_valid = redis.call('DEL', nonce_key) if nonce_valid == 0 then return 'INVALID_NONCE' end local jti_set = redis.call('SET', jti_key, '1', 'NX', 'EX', jti_ttl) if not jti_set then return 'REPLAYED_JTI' end return 'OK' `; export function createDPoPMiddleware(redis: Redis) { return async (req: Request, res: Response, next: NextFunction): Promise<void> => { const dpopHeader = req.header('dpop'); const authHeader = req.header('authorization'); if (!dpopHeader || !authHeader?.startsWith('DPoP ')) { res.setHeader('DPoP-Nonce', crypto.randomBytes(32).toString('base64url')); res.status(401).json({ error: 'invalid_dpop_proof', error_description: 'DPoP header required' }); return; } const token = authHeader.slice(6); const expectedAth = crypto.createHash('sha256').update(token).digest('base64url'); try { const { payload } = await jwtVerify(dpopHeader, createRemoteJWKSet(new URL('https://auth.internal/.well-known/jwks.json')), { typ: 'dpop+jwt', }); if (payload.ath !== expectedAth || payload.htm !== req.method) { res.status(401).json({ error: 'invalid_dpop_proof', error_description: 'Proof binding mismatch' }); return; } const nonce = payload.nonce as string | undefined; const jti = payload.jti; if (!nonce || !jti) { res.status(401).json({ error: 'use_dpop_nonce', error_description: 'Missing nonce or JTI' }); return; } const result = await redis.eval( CONSUME_DPOP_LUA, 2, `dpop:nonce:${nonce}`, `dpop:jti:${jti}`, '300' ); if (result !== 'OK') { const freshNonce = crypto.randomBytes(32).toString('base64url'); await redis.set(`dpop:nonce:${freshNonce}`, '1', 'EX', 120); res.setHeader('DPoP-Nonce', freshNonce); res.status(401).json({ error: 'use_dpop_nonce', error_description: 'Nonce expired or JTI replayed' }); return; } next(); } catch { res.status(401).json({ error: 'invalid_dpop_proof' }); } }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OAuth 2.1 RFC 9449 DPoP Single-Use Nonce Cluster Enforcement

OAuth 2.1 RFC 9449 DPoP Single-Use Nonce Cluster Enforcement defines an industrial-grade behavioral standard for security engineering. Enforces atomic, cluster-wide verification of OAuth 2.1 Demonstrating Proof-of-Possession (DPoP, RFC 9449) proofs and ephemeral nonces across distributed edge proxies. Guarantees linearizable single-use proof validation and access token hash binding to eliminate replay attacks across multi-region ingress points. 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: Process-Local Nonce Validation and Non-Atomic Read-Then-Write Replay Windows Across Edge Nodes 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	Process-Local Nonce Validation and Non-Atomic Read-Then-Write Replay Windows Across Edge Nodes	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 validate DPoP proofs using atomic distributed check-and-set operations (e.g., Redis EVAL Lua script or atomic SET NX EX) to ensure single-use nonce consumption across all cluster nodes.

Engineers MUST ALWAYS validate DPoP proofs using atomic distributed check-and-set operations (e.g., Redis EVAL Lua script or atomic SET NX EX) to ensure single-use nonce consumption across all cluster nodes.

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.