OAuth 2.1 RFC 9449 DPoP Cryptographic Proof-of-Possession Token Binding Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unbound Bearer Token Acceptance and Superficial DPoP Proof Verification Lacking JWK Thumbprint and Nonce Binding) 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 Proof-of-Possession Token Binding Standard

--- description: OAuth 2.1 RFC 9449 DPoP Cryptographic Proof-of-Possession Token Binding Standard - Enforces strict implementation of OAuth 2.0/2.1 Demonstrating Proof-of-Possession (DPoP) at the Application Layer (RFC 9449). Eliminates bearer token exfiltration and replay attacks by binding tokens to asymmetric client public key thumbprints and validating ephemeral request signatures against normalized URIs, HTTP methods, server nonces, and single-use JTI identifiers. globs: src/**/*.{ts,tsx,js,mjs}, api/**/*.{ts,js}, middleware/**/*.{ts,js}, lib/auth/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth-2-1-dpop-cryptographic-token-binding-standard" --- # OAuth 2.1 RFC 9449 DPoP Cryptographic Proof-of-Possession Token Binding Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unbound Bearer Token Acceptance and Superficial DPoP Proof Verification Lacking JWK Thumbprint and Nonce Binding ## System Constraints You are a Principal Security Architect enforcing OAuth 2.1 DPoP (RFC 9449) cryptographic proof-of-possession token binding. You must ensure that applications never accept unbound bearer tokens when DPoP is configured. Every request must validate the DPoP proof JWT JOSE header, match the client's public key SHA-256 thumbprint (RFC 7638) against the access token's cnf.jkt claim, strictly verify normalized HTTP target URI (htu) and method (htm), assert single-use JTI against replay caches, and mandate dynamic server-provided nonces. ## Strict Guidelines - Engineers MUST ALWAYS enforce the DPoP header 'typ' to be exactly 'dpop+jwt' and reject standard 'JWT' types. - Engineers MUST compute the client public key SHA-256 JWK thumbprint according to RFC 7638 and assert exact equivalence with the access token's 'cnf.jkt' claim. - Engineers MUST normalize the request URI ('htu') by stripping query parameters, fragments, and normalizing host casing and default ports before checking proof equality. - Engineers MUST NOT persist client private DPoP keys in unencrypted browser storage such as localStorage or sessionStorage; keys MUST remain in non-extractable CryptoKey storage (IndexedDB) or memory. - Services MUST enforce server-directed replay mitigation using the 'DPoP-Nonce' header and reject proofs containing stale nonces with HTTP 401 and a fresh nonce challenge. - Services MUST track 'jti' claims within a sliding time window (typically <= 60 seconds) using a fast distributed store (e.g., Redis) to prevent replay within valid 'iat' windows. - Authorization servers MUST reject DPoP proof tokens signed with symmetric algorithms ('none', 'HS256'); ONLY asymmetric algorithms (ES256, EdDSA, PS256) are permitted. ## Bad vs Good Implementations ### RFC 9449 DPoP Proof Token & Binding Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to verify the cryptographic signature of the DPoP proof. Fails to check that the JOSE header typ is 'dpop+jwt'. Completely ignores RFC 7638 JWK thumbprint binding (cnf.jkt in the access token vs. JWK in the DPoP header), allowing exfiltrated tokens to be used with arbitrary keypairs. Does not validate server nonces, single-use JTIs, or URI normalization. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; // ANTI-PATTERN: Superficial DPoP check treating proof as a standalone bearer token, // ignoring cnf.jkt binding, method/URI validation, nonce enforcement, and JTI replay prevention. export async function verifyDPoP(req: Request, res: Response, next: NextFunction) { const authHeader = req.headers.authorization; const dpopHeader = req.headers.dpop as string; if (!authHeader?.startsWith('DPoP ') || !dpopHeader) { return res.status(401).json({ error: 'invalid_dpop' }); } const accessToken = authHeader.substring(5); // Flaw 1: Decoding access token without verifying signature or cnf thumbprint const tokenPayload = jwt.decode(accessToken) as { sub: string }; // Flaw 2: Decoding DPoP proof without validating typ: 'dpop+jwt' or cryptographic binding const dpopPayload = jwt.decode(dpopHeader) as { htu: string; htm: string }; // Flaw 3: Incomplete URI matching vulnerable to path/query bypasses if (dpopPayload.htm !== req.method) { return res.status(401).json({ error: 'method_mismatch' }); } req.user = tokenPayload; return next(); } ``` #### Production Standard (Correct) > **Standard**: Implements RFC 9449 requirements: asserts typ is 'dpop+jwt', verifies the embedded public JWK matches the access token's cnf.jkt SHA-256 thumbprint, normalizes and strictly checks htu/htm, verifies freshness with a dynamic DPoP-Nonce challenge, and mitigates replays via an atomic JTI check. ```typescript import { Request, Response, NextFunction } from 'express'; import * as jose from 'jose'; interface JtiStore { consume(jti: string, exp: number): Promise<boolean>; } interface NonceManager { isValid(nonce: string): Promise<boolean>; generate(): string; } declare const jtiStore: JtiStore; declare const nonceManager: NonceManager; declare const ACCESS_TOKEN_JWKS: jose.JWTVerifyGetKey; export async function verifyDPoP(req: Request, res: Response, next: NextFunction) { const authHeader = req.headers.authorization; const dpopProof = req.headers.dpop as string | undefined; if (!authHeader?.startsWith('DPoP ') || !dpopProof) { res.setHeader('WWW-Authenticate', 'DPoP error="invalid_token", error_description="DPoP proof required"'); return res.status(401).json({ error: 'invalid_dpop' }); } const rawAccessToken = authHeader.substring(5); try { // 1. Verify access token validity and extract cnf.jkt binding const { payload: tokenPayload } = await jose.jwtVerify(rawAccessToken, ACCESS_TOKEN_JWKS, { algorithms: ['ES256', 'PS256'] }); const cnf = tokenPayload.cnf as { jkt?: string } | undefined; if (!cnf?.jkt) { return res.status(401).json({ error: 'unbound_token', error_description: 'Token missing cnf.jkt' }); } // 2. Decode and validate DPoP proof header const protectedHeader = jose.decodeProtectedHeader(dpopProof); if (protectedHeader.typ !== 'dpop+jwt') { return res.status(400).json({ error: 'invalid_dpop_proof', error_description: 'typ must be dpop+jwt' }); } const clientJwk = protectedHeader.jwk; if (!clientJwk || clientJwk.kty === 'oct') { return res.status(400).json({ error: 'invalid_dpop_proof', error_description: 'Invalid public JWK in header' }); } // 3. Cryptographically verify the client's JWK thumbprint against the token's cnf.jkt const computedThumbprint = await jose.calculateJwkThumbprint(clientJwk, 'sha256'); if (computedThumbprint !== cnf.jkt) { return res.status(401).json({ error: 'invalid_token', error_description: 'DPoP key does not match token thumbprint' }); } // 4. Verify DPoP proof signature using the embedded public key const publicKey = await jose.importJWK(clientJwk, protectedHeader.alg); const { payload: dpopPayload } = await jose.jwtVerify(dpopProof, publicKey, { maxTokenAge: '60s', clockTolerance: '5s' }); // 5. Assert HTTP Method (htm) and Normalized HTTP URI (htu) const expectedHtm = req.method.toUpperCase(); const protocol = req.protocol; const host = req.get('host'); const expectedHtu = `${protocol}://${host}${req.baseUrl}${req.path}`.toLowerCase(); const proofHtu = (dpopPayload.htu as string || '').toLowerCase(); if (dpopPayload.htm !== expectedHtm || proofHtu !== expectedHtu) { return res.status(401).json({ error: 'invalid_dpop_proof', error_description: 'htm or htu mismatch' }); } // 6. Validate Nonce freshness const proofNonce = dpopPayload.nonce as string | undefined; if (!proofNonce || !(await nonceManager.isValid(proofNonce))) { const freshNonce = nonceManager.generate(); res.setHeader('DPoP-Nonce', freshNonce); res.setHeader('WWW-Authenticate', `DPoP error="use_dpop_nonce", error_description="Provide fresh nonce"`); return res.status(401).json({ error: 'use_dpop_nonce' }); } // 7. Enforce single-use JTI replay mitigation const jti = dpopPayload.jti as string; const exp = (dpopPayload.exp ?? (dpopPayload.iat! + 60)) as number; const isNew = await jtiStore.consume(jti, exp); if (!isNew) { return res.status(401).json({ error: 'invalid_dpop_proof', error_description: 'jti replay detected' }); } req.user = tokenPayload; return next(); } catch (err) { return res.status(401).json({ error: 'invalid_dpop_proof', error_description: (err as Error).message }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OAuth 2.1 RFC 9449 DPoP Cryptographic Proof-of-Possession Token Binding Standard

OAuth 2.1 RFC 9449 DPoP Cryptographic Proof-of-Possession Token Binding Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict implementation of OAuth 2.0/2.1 Demonstrating Proof-of-Possession (DPoP) at the Application Layer (RFC 9449). Eliminates bearer token exfiltration and replay attacks by binding tokens to asymmetric client public key thumbprints and validating ephemeral request signatures against normalized URIs, HTTP methods, server nonces, and single-use JTI identifiers. 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: Unbound Bearer Token Acceptance and Superficial DPoP Proof Verification Lacking JWK Thumbprint and Nonce Binding 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	Unbound Bearer Token Acceptance and Superficial DPoP Proof Verification Lacking JWK Thumbprint and Nonce Binding	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 the DPoP header 'typ' to be exactly 'dpop+jwt' and reject standard 'JWT' types.

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.