OAuth 2.1 RFC 9449 DPoP Cryptographic Token Binding & Nonce Enforcement

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Accepting Bearer tokens on sensitive APIs or validating DPoP proofs without thumbprint confirmation and nonce verification) 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 Cryptographic Token Binding & Nonce Enforcement

--- description: OAuth 2.1 RFC 9449 DPoP Cryptographic Token Binding & Nonce Enforcement - Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) at the API gateway layer to prevent credential theft and replay attacks. Access tokens must be cryptographically bound via thumbprint (jkt) to ephemeral asymmetric key pairs, validated against incoming DPoP proof JWTs, and subject to strict single-use server nonce cycling. globs: src/middleware/**/*.{ts,js}, src/gateway/**/*.{ts,js}, src/auth/**/*.{ts,js}, src/security/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth-2-1-dpop-token-binding-guardrail" --- # OAuth 2.1 RFC 9449 DPoP Cryptographic Token Binding & Nonce Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Bearer tokens on sensitive APIs or validating DPoP proofs without thumbprint confirmation and nonce verification ## System Constraints You are a Principal Security Architect enforcing RFC 9449 OAuth 2.1 DPoP token binding across all edge and gateway services. You must reject any code that treats DPoP tokens as standard Bearer tokens, fails to verify the JWK SHA-256 thumbprint (jkt) against the access token cnf claim, or bypasses server-managed nonce validation. ## Strict Guidelines - Engineers MUST ALWAYS require the 'DPoP' authorization scheme (Authorization: DPoP <access_token>) instead of 'Bearer' on high-security endpoints. - Engineers MUST ALWAYS verify that the incoming DPoP proof JWT contains a valid 'typ': 'dpop+jwt' header and an asymmetric public key ('jwk') matching allowed algorithms (e.g., ES256, EdDSA). - Gateway middleware MUST compute the RFC 7638 SHA-256 thumbprint of the embedded JWK and verify exact byte equality against the 'cnf.jkt' claim in the validated access token. - Gateway middleware MUST strictly validate the DPoP proof claims: 'htm' (HTTP method), 'htu' (HTTP target URI stripped of query and fragment), and 'iat' within a bounded clock skew window (<= 60 seconds). - Services MUST enforce server-provided nonces ('nonce' claim in proof) and issue HTTP 401 with 'use_dpop_nonce' error and a fresh 'DPoP-Nonce' header when absent or expired. - Engineers MUST NOT allow symmetric key algorithms (HS256) or unpinned public keys for DPoP proof signing. - Components NEVER store private DPoP keys in unencrypted browser storage (localStorage/sessionStorage); clients must use non-exportable WebCrypto keys (IndexedDB) or secure enclaves. ## Bad vs Good Implementations ### RFC 9449 Gateway Middleware DPoP Proof & Token Binding Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The middleware accepts a DPoP scheme token but handles it as a standard static bearer token. It completely skips checking the DPoP proof header, fails to confirm the asymmetric key thumbprint match (cnf.jkt), ignores server nonces, and enables trivial token replay if intercepted. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; export function authenticateDPoP(req: Request, res: Response, next: NextFunction) { const authHeader = req.headers.authorization; if (!authHeader?.startsWith('DPoP ')) { return res.status(401).json({ error: 'invalid_token' }); } const token = authHeader.substring(5); // VULNERABILITY 1: Only verifies access token, ignores proof header // VULNERABILITY 2: No validation that client holds corresponding private key // VULNERABILITY 3: No replay prevention or nonce validation try { const payload = jwt.verify(token, process.env.ACCESS_TOKEN_PUBLIC_KEY!); req.user = payload; next(); } catch { return res.status(401).json({ error: 'unauthorized' }); } } ``` #### Production Standard (Correct) > **Standard**: Implements full RFC 9449 compliance: validates DPoP proof type 'dpop+jwt', verifies signature using the embedded public JWK, validates HTTP method/canonical URI binding, enforces strictly consumed server nonces (issuing 'use_dpop_nonce' challenge upon expiry), and computes the SHA-256 JWK thumbprint to guarantee strict binding with the access token's 'cnf.jkt' claim. ```typescript import { Request, Response, NextFunction } from 'express'; import { createHash } from 'node:crypto'; import * as jose from 'jose'; interface NonceStore { consume(nonce: string): Promise<boolean>; generate(): Promise<string>; } declare const nonceStore: NonceStore; export async function verifyDPoPBinding(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 nonceStore.generate(); res.setHeader('DPoP-Nonce', newNonce); return res.status(401).setHeader('WWW-Authenticate', 'DPoP error="invalid_dpop_proof"').json({ error: 'missing_dpop_proof' }); } const accessToken = authHeader.slice(5).trim(); try { // 1. Parse and verify DPoP proof JWT header const { protectedHeader } = jose.decodeProtectedHeader(dpopHeader); if (protectedHeader.typ !== 'dpop+jwt' || !protectedHeader.jwk) { throw new Error('Invalid DPoP header typography or missing embedded JWK'); } // 2. Import JWK and verify signature and claims (htm, htu) const key = await jose.importJWK(protectedHeader.jwk, protectedHeader.alg); const canonicalUrl = `${req.protocol}://${req.get('host')}${req.baseUrl}${req.path}`; const { payload: proof } = await jose.jwtVerify(dpopHeader, key, { algorithms: ['ES256', 'PS256', 'EdDSA'], clockTolerance: 60, maxTokenAge: '120s' }); if (proof.htm !== req.method || proof.htu !== canonicalUrl) { return res.status(401).json({ error: 'invalid_dpop_proof', message: 'HTTP method or URI mismatch' }); } // 3. Validate and rotate Server Nonce if (typeof proof.nonce !== 'string' || !(await nonceStore.consume(proof.nonce))) { const freshNonce = await nonceStore.generate(); res.setHeader('DPoP-Nonce', freshNonce); return res.status(401).setHeader('WWW-Authenticate', 'DPoP error="use_dpop_nonce"').json({ error: 'use_dpop_nonce' }); } // 4. Verify Access Token and match thumbprint (cnf.jkt) const tokenJwks = jose.createRemoteJWKSet(new URL(process.env.JWKS_URI!)); const { payload: tokenClaims } = await jose.jwtVerify(accessToken, tokenJwks, { issuer: process.env.ISSUER, audience: process.env.AUDIENCE }); const expectedJkt = (tokenClaims.cnf as { jkt?: string })?.jkt; const actualJkt = await jose.calculateJwkThumbprint(protectedHeader.jwk, 'sha256'); if (!expectedJkt || actualJkt !== expectedJkt) { return res.status(401).json({ error: 'invalid_token', message: 'DPoP key thumbprint mismatch with access token cnf' }); } req.user = tokenClaims; next(); } catch (err) { return res.status(401).json({ error: 'invalid_dpop_proof', details: (err as Error).message }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OAuth 2.1 RFC 9449 DPoP Cryptographic Token Binding & Nonce Enforcement

OAuth 2.1 RFC 9449 DPoP Cryptographic Token Binding & Nonce Enforcement defines an industrial-grade behavioral standard for security engineering. Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) at the API gateway layer to prevent credential theft and replay attacks. Access tokens must be cryptographically bound via thumbprint (jkt) to ephemeral asymmetric key pairs, validated against incoming DPoP proof JWTs, and subject to strict single-use server nonce cycling. 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 Bearer tokens on sensitive APIs or validating DPoP proofs without thumbprint confirmation and nonce verification 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 Bearer tokens on sensitive APIs or validating DPoP proofs without thumbprint confirmation and nonce verification	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 require the 'DPoP' authorization scheme (Authorization

Engineers MUST ALWAYS require the 'DPoP' authorization scheme (Authorization: DPoP <access_token>) instead of 'Bearer' on high-security endpoints.

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.