OAuth 2.1 Demonstrating Proof-of-Possession (DPoP) Invariant Enforcement

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Bearer Token Pass-Through and Static Private Key Reuse Without Cryptographic Request 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 Demonstrating Proof-of-Possession (DPoP) Invariant Enforcement

--- description: OAuth 2.1 Demonstrating Proof-of-Possession (DPoP) Invariant Enforcement - Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) standards across public edge API gateways and client SDKs. Mandates cryptographic thumbprint binding of access and refresh tokens to client-generated ephemeral asymmetric keypairs (ES256/Ed25519) to eliminate token interception, exfiltration, and cross-origin replay attacks. globs: src/auth/**/*.{ts,js,py,go}, src/gateway/**/*.{ts,js,py,go}, src/middleware/**/*.{ts,js,py,go}, src/lib/api-client/**/*.{ts,js,py,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth21-dpop-ephemeral-key-guardrail" --- # OAuth 2.1 Demonstrating Proof-of-Possession (DPoP) Invariant Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Bearer Token Pass-Through and Static Private Key Reuse Without Cryptographic Request Binding ## System Constraints You are a Principal Security Architect enforcing RFC 9449 (OAuth 2.0 / 2.1 Demonstrating Proof-of-Possession). You must strictly prohibit standard bearer token authorization on public-facing APIs and ensure all access/refresh tokens are cryptographically bound via DPoP proofs. Ensure clients generate ephemeral keypairs in secure non-exportable storage (e.g., SubtleCrypto / Hardware Keystore) and verify that gateways validate HTTP method (htm), URI (htu), issued-at (iat), unique nonce, and SHA-256 JWK thumbprints (jkt). ## Strict Guidelines - Engineers MUST ALWAYS enforce DPoP token verification on API gateways using RFC 9449 compliance, checking that the 'DPoP' header contains a valid asymmetric signature matching the 'jkt' (JWK SHA-256 thumbprint) embedded inside the access token. - Engineers MUST NOT persist client DPoP private keys to disk, localStorage, or unencrypted storage; ephemeral keys MUST reside exclusively in memory or non-extractable Web Crypto API / Hardware Keystores. - Engineers MUST enforce strict validation of the DPoP proof claims: 'htm' MUST match the exact HTTP method, 'htu' MUST match the normalized target URI (ignoring query/fragment), and 'iat' MUST be within a strict skew window (default <= 60 seconds). - Gateways MUST mandate server-generated single-use or time-bounded nonces via the 'DPoP-Nonce' header when replay windows cannot be bounded solely by 'jti' tracking. - Clients MUST calculate the access token hash ('ath') as base64url(sha256(access_token)) and include it in the DPoP proof JWT payload whenever invoking protected resource endpoints. ## Bad vs Good Implementations ### Edge Gateway DPoP Proof & Token Thumbprint Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accepts static Bearer tokens with no cryptographic proof-of-possession. Any actor intercepting this token via edge proxies, logs, or XSS can freely replay it without possessing the client's asymmetric private key. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; export function authenticateRequest(req: Request, res: Response, next: NextFunction) { const authHeader = req.headers['authorization']; if (!authHeader?.startsWith('Bearer ')) { return res.status(401).json({ error: 'Missing bearer token' }); } const token = authHeader.substring(7); try { // VULNERABLE: Plain bearer token validation allows intercepted tokens to be replayed const decoded = jwt.verify(token, process.env.JWT_PUBLIC_KEY!); req.user = decoded; next(); } catch (err) { return res.status(401).json({ error: 'Invalid token' }); } } ``` #### Production Standard (Correct) > **Standard**: Validates RFC 9449 compliance: rejects traditional Bearer headers, checks the 'dpop+jwt' header type, binds the access token through the 'ath' claim, validates target URI ('htu') and method ('htm'), and guarantees that the sender holds the private key matching the 'jkt' confirmation thumbprint in the access token. ```typescript import { Request, Response, NextFunction } from 'express'; import { createHash } from 'crypto'; import { importJWK, jwtVerify, calculateJwkThumbprint } from 'jose'; 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) { return res.status(401).set('WWW-Authenticate', 'DPoP error="invalid_token"').json({ error: 'DPoP authentication token and proof required' }); } const accessToken = authHeader.substring(5); try { // 1. Verify and unpack DPoP proof JWT using the ephemeral public key in header const { payload: dpopPayload, protectedHeader } = await jwtVerify(dpopHeader, async (header) => { if (!header.jwk || header.typ !== 'dpop+jwt' || header.alg !== 'ES256') { throw new Error('Unsupported or missing DPoP JWK/typ/alg'); } return importJWK(header.jwk, 'ES256'); }); // 2. Validate Proof Claims (htm, htu, ath, iat) const expectedHtu = `${req.protocol}://${req.get('host')}${req.baseUrl}${req.path}`; if (dpopPayload.htm !== req.method || dpopPayload.htu !== expectedHtu) { return res.status(401).json({ error: 'DPoP method/URI mismatch' }); } const expectedAth = createHash('sha256').update(accessToken).digest('base64url'); if (dpopPayload.ath !== expectedAth) { return res.status(401).json({ error: 'DPoP ath token binding invalid' }); } // 3. Verify Access Token and match jkt binding claim const { payload: tokenPayload } = await jwtVerify(accessToken, process.env.GATEWAY_PUBLIC_KEY! as any); const clientJwkThumbprint = await calculateJwkThumbprint(protectedHeader.jwk!, 'sha256'); if (tokenPayload.cnf?.['jkt'] !== clientJwkThumbprint) { return res.status(401).json({ error: 'Token thumbprint does not match DPoP key' }); } req.user = tokenPayload; next(); } catch (err) { return res.status(401).json({ error: 'Cryptographic DPoP verification failed' }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OAuth 2.1 Demonstrating Proof-of-Possession (DPoP) Invariant Enforcement

OAuth 2.1 Demonstrating Proof-of-Possession (DPoP) Invariant Enforcement defines an industrial-grade behavioral standard for security engineering. Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) standards across public edge API gateways and client SDKs. Mandates cryptographic thumbprint binding of access and refresh tokens to client-generated ephemeral asymmetric keypairs (ES256/Ed25519) to eliminate token interception, exfiltration, and cross-origin 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: Bearer Token Pass-Through and Static Private Key Reuse Without Cryptographic Request 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	Bearer Token Pass-Through and Static Private Key Reuse Without Cryptographic Request 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 DPoP token verification on API gateways using RFC 9449 compliance, checking that the 'DPoP' header contains a valid asymmetric signature matching the 'jkt' (JWK SHA-256 thumbprint) embedded inside the access token.

Engineers MUST ALWAYS enforce DPoP token verification on API gateways using RFC 9449 compliance, checking that the 'DPoP' header contains a valid asymmetric signature matching the 'jkt' (JWK SHA-256 thumbprint) embedded inside the access 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.