OAuth 2.1 RFC 9449 DPoP Ephemeral Nonce Fencing & Replay Defense

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Accepting static bearer tokens or omitting cryptographic nonce verification in DPoP validation pipelines) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

OAuth 2.1 RFC 9449 DPoP Ephemeral Nonce Fencing & Replay Defense

--- description: OAuth 2.1 RFC 9449 DPoP Ephemeral Nonce Fencing & Replay Defense - Enforces strict Demonstrating Proof-of-Possession (DPoP) verification across zero-trust API boundaries according to RFC 9449. Mandates server-side ephemeral nonce generation, cryptographic binding of the access token hash (ath), HTTP method (htm), URI (htu), and single-use nonce validation to neutralize token exfiltration and replay attacks. globs: src/auth/**/*.{ts,js}, src/middleware/**/*.{ts,js}, src/security/**/*.{ts,js}, src/api/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth-2-1-dpop-ephemeral-nonce-fencing" --- # OAuth 2.1 RFC 9449 DPoP Ephemeral Nonce Fencing & Replay Defense > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting static bearer tokens or omitting cryptographic nonce verification in DPoP validation pipelines ## System Constraints You are a Principal Security Architect enforcing OAuth 2.1 RFC 9449 DPoP (Demonstrating Proof-of-Possession) standards. You must ensure that every protected endpoint requires cryptographically bound proof headers, enforces ephemeral server-provided nonces, validates method/URI invariants, and verifies access token thumbprints (ath) to eliminate replay and token theft vectors. ## Strict Guidelines - Engineers MUST ALWAYS validate the 'DPoP' proof header alongside the 'Authorization: DPoP <token>' header on all protected zero-trust API routes. - Services MUST issue and validate an ephemeral, cryptographically random 'DPoP-Nonce' with strict time-to-live (< 60s) stored in a fast atomic key-value store (e.g., Redis). - Services MUST reject requests with HTTP 401 Unauthorized, header 'WWW-Authenticate: DPoP error="use_dpop_nonce"', and a fresh 'DPoP-Nonce' header whenever the nonce is missing, invalid, or expired. - Engineers MUST ALWAYS verify that the DPoP proof claims match the request context: 'htm' MUST match the canonical HTTP verb, 'htu' MUST match the canonical request URI without query/fragment, and 'ath' MUST match the base64url-encoded SHA-256 hash of the presented access token. - Engineers MUST NOT accept traditional 'Bearer' tokens on endpoints configured for DPoP binding. - Engineers MUST ALWAYS enforce unique DPoP JWT IDs ('jti') within an ephemeral window to prevent concurrent in-flight replay attacks. ## Bad vs Good Implementations ### DPoP Ephemeral Nonce and Proof Verification Middleware #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This implementation fails RFC 9449 compliance. It accepts unauthenticated Bearer tokens, fails to enforce the DPoP proof header, completely omits server-issued ephemeral nonces, and ignores the cryptographic binding between the access token, HTTP method, URI, and client private key. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; // INSECURE: Accepts static bearer tokens, fails to bind proof, skips nonce & ath verification export async function verifyAuth(req: Request, res: Response, next: NextFunction) { const authHeader = req.headers.authorization; if (!authHeader) { return res.status(401).json({ error: 'unauthorized' }); } const token = authHeader.replace(/^Bearer /i, '').replace(/^DPoP /i, ''); try { // Naive verification: token is vulnerable to exfiltration and replay const decoded = jwt.verify(token, process.env.JWT_PUBLIC_KEY!); req.user = decoded; return next(); } catch (err) { return res.status(401).json({ error: 'invalid_token' }); } } ``` #### Production Standard (Correct) > **Standard**: Enforces RFC 9449 specifications: verifies that the authorization scheme is 'DPoP', ensures the DPoP proof is signed by the client's public JWK, validates HTTP method ('htm') and clean URI ('htu'), cryptographically asserts the token hash ('ath'), enforces atomic single-use nonce challenge fencing via Redis, and protects against 'jti' replay attacks. ```typescript import { Request, Response, NextFunction } from 'express'; import { createHash, timingSafeEqual } from 'crypto'; import * as jose from 'jose'; import { Redis } from 'ioredis'; const redis = new Redis(process.env.REDIS_URL!); const NONCE_TTL_SECONDS = 60; function computeAth(accessToken: string): string { return createHash('sha256').update(accessToken, 'ascii').digest('base64url'); } async function generateDPoPNonce(): Promise<string> { const nonce = jose.base64url.encode(crypto.getRandomValues(new Uint8Array(24))); await redis.set(`dpop:nonce:${nonce}`, '1', 'EX', NONCE_TTL_SECONDS); return nonce; } export async function verifyDPoP(req: Request, res: Response, next: NextFunction) { const authHeader = req.headers.authorization; const dpopHeader = req.headers['dpop'] as string | undefined; if (!authHeader?.startsWith('DPoP ') || !dpopHeader) { const newNonce = await generateDPoPNonce(); res.setHeader('WWW-Authenticate', 'DPoP error="invalid_token"'); res.setHeader('DPoP-Nonce', newNonce); return res.status(401).json({ error: 'dpop_required' }); } const accessToken = authHeader.slice(5).trim(); try { // 1. Decode unverified header to extract JWK const { header } = jose.decodeProtectedHeader(dpopHeader); if (header.typ !== 'dpop+jwt' || !header.jwk) { throw new Error('invalid_dpop_header'); } const publicKey = await jose.importJWK(header.jwk, header.alg); const { payload } = await jose.jwtVerify(dpopHeader, publicKey, { typ: 'dpop+jwt', maxTokenAge: '60s' }); // 2. Validate Nonce fencing (ephemeral single-use or active window) const proofNonce = payload.nonce as string | undefined; const isValidNonce = proofNonce ? await redis.del(`dpop:nonce:${proofNonce}`) : 0; if (!proofNonce || isValidNonce === 0) { const freshNonce = await generateDPoPNonce(); res.setHeader('WWW-Authenticate', 'DPoP error="use_dpop_nonce"'); res.setHeader('DPoP-Nonce', freshNonce); return res.status(401).json({ error: 'use_dpop_nonce' }); } // 3. Validate HTM, HTU, and ATH const expectedHtu = `${req.protocol}://${req.get('host')}${req.baseUrl}${req.path}`; if (payload.htm !== req.method.toUpperCase() || payload.htu !== expectedHtu) { return res.status(401).json({ error: 'invalid_dpop_proof_target' }); } const expectedAth = computeAth(accessToken); if (!payload.ath || typeof payload.ath !== 'string' || !timingSafeEqual(Buffer.from(payload.ath), Buffer.from(expectedAth))) { return res.status(401).json({ error: 'invalid_token_binding' }); } // 4. JTI replay fence check const jtiKey = `dpop:jti:${payload.jti}`; const isFirstUse = await redis.set(jtiKey, '1', 'EX', NONCE_TTL_SECONDS, 'NX'); if (!isFirstUse) { return res.status(401).json({ error: 'replay_detected' }); } req.tokenPayload = { accessToken, dpopJwk: header.jwk }; return next(); } catch (err) { const newNonce = await generateDPoPNonce(); res.setHeader('WWW-Authenticate', 'DPoP error="invalid_dpop_proof"'); res.setHeader('DPoP-Nonce', newNonce); return res.status(401).json({ error: 'invalid_dpop_proof' }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OAuth 2.1 RFC 9449 DPoP Ephemeral Nonce Fencing & Replay Defense

OAuth 2.1 RFC 9449 DPoP Ephemeral Nonce Fencing & Replay Defense defines an industrial-grade behavioral standard for security engineering. Enforces strict Demonstrating Proof-of-Possession (DPoP) verification across zero-trust API boundaries according to RFC 9449. Mandates server-side ephemeral nonce generation, cryptographic binding of the access token hash (ath), HTTP method (htm), URI (htu), and single-use nonce validation to neutralize token exfiltration and replay attacks. 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 static bearer tokens or omitting cryptographic nonce verification in DPoP validation pipelines 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 static bearer tokens or omitting cryptographic nonce verification in DPoP validation pipelines	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 the 'DPoP' proof header alongside the 'Authorization

Engineers MUST ALWAYS validate the 'DPoP' proof header alongside the 'Authorization: DPoP <token>' header on all protected zero-trust API routes.

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.