Mandating RFC 9449 Demonstrating Proof-of-Possession (DPoP) Cryptographic Binding

--- description: Mandating RFC 9449 Demonstrating Proof-of-Possession (DPoP) Cryptographic Binding - RFC 9449 DPoP tethers OAuth 2.0 access and refresh tokens to an ephemeral, client-held asymmetric key pair, rendering exfiltrated bearer tokens unusable without the private key. Resource servers and OAuth clients must strictly validate the DPoP proof header (`typ: dpop+jwt`), bound thumbprint (`jkt`), HTTP method, URI target (`htu`/`htm`), and anti-replay nonces (`jti` and server-issued nonces). globs: src/auth/**/*.{ts,js,py,go}, src/middleware/**/*.{ts,js,py,go}, src/api/**/*.{ts,js,py,go}, src/gateway/**/*.{ts,js,py,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rfc-9449-dpop-asymmetric-token-binding-invariant" --- # Mandating RFC 9449 Demonstrating Proof-of-Possession (DPoP) Cryptographic Binding > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Unbound Bearer Tokens or Incomplete DPoP Proof Validation Subject to Token Theft and Replay ## System Constraints You are a Principal Security Architect enforcing RFC 9449 Demonstrating Proof-of-Possession (DPoP) at the Application Layer. You must prohibit bare Bearer authorization schemes where DPoP is mandated. All inbound requests to protected resource servers must strictly enforce DPoP proof verification: validating header typ ('dpop+jwt'), asymmetric signature against the embedded public JWK ('jwk' header parameter), strict match of 'htm' (HTTP method) and 'htu' (HTTP target URI without query/fragment), time window freshness ('iat' within ±60 seconds), persistent cache-backed unique 'jti' nonce check, server-issued nonce synchronization, and SHA-256 calculation matching the access token's 'jkt' confirmation claim (ath/cnf.jkt). ## Strict Guidelines - Resource servers MUST enforce scheme 'DPoP' in the Authorization header (`Authorization: DPoP <token>`) and reject bare 'Bearer' tokens when DPoP is enabled. - The DPoP proof JWT header MUST contain `typ: "dpop+jwt"` and the public key `jwk`; it MUST NOT contain private key material or references (`x5u`, `jku`). - Resource servers MUST verify that the proof's `htm` matches the exact incoming HTTP request method and `htu` matches the exact normalized target URI scheme, host, port, and path. - Engineers MUST compute the SHA-256 base64url thumbprint of the embedded JWK and verify it identically matches the `jkt` claim of the access token's `cnf` confirmation claim. - Engineers MUST reject DPoP proofs whose `iat` exceeds a strict maximum skew threshold (MUST NOT exceed ±60 seconds) and MUST verify `jti` uniqueness via distributed cache (e.g., Redis) within that window to prevent replays. - Resource servers MUST issue a `DPoP-Nonce` challenge header and reject the request with `use_dpop_nonce` error if the client proof lacks a valid, recently issued server nonce. ## Bad vs Good Implementations ### RFC 9449 DPoP Token and Proof Verification Middleware #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The middleware accepts standard Bearer tokens without verifying proof-of-possession. If an attacker intercepts the Bearer token via logs, SSRF, or proxy leaks, they can replay the token unrestricted from any machine. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; export async function verifyAuth(req: Request, res: Response, next: NextFunction) { const authHeader = req.headers['authorization']; // Flaw 1: Accepts standard Bearer tokens without asymmetric proof-of-possession if (!authHeader?.startsWith('Bearer ')) { return res.status(401).json({ error: 'unauthorized' }); } const token = authHeader.substring(7); try { // Flaw 2: Verifies token validity but does not verify cryptographic key binding to the client const decoded = jwt.verify(token, process.env.JWT_PUBLIC_KEY!) as jwt.JwtPayload; req.user = decoded; next(); } catch { return res.status(401).json({ error: 'invalid_token' }); } } ``` #### Production Standard (Correct) > **Standard**: Implements RFC 9449 compliance by demanding the 'DPoP' scheme, verifying the ephemeral public JWK signature against the proof, matching method ('htm') and canonical target URI ('htu'), computing the JWK SHA-256 thumbprint against the token's 'cnf.jkt' claim, and enforcing distributed replay defense on the 'jti'. ```typescript import { Request, Response, NextFunction } from 'express'; import * as jose from 'jose'; import crypto from 'node:crypto'; import { redisClient } from '../services/redis.js'; interface TokenPayload extends jose.JWTPayload { cnf?: { jkt: string }; } export async function verifyDPoPAuth(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).json({ error: 'invalid_dpop_proof', message: 'DPoP authorization and proof required' }); } const accessToken = authHeader.substring(6); try { // 1. Verify Access Token signature and extract thumbprint binding const asPublicKey = await jose.importSPKI(process.env.AUTH_SERVER_PUBLIC_KEY!, 'RS256'); const { payload: tokenPayload } = await jose.jwtVerify<TokenPayload>(accessToken, asPublicKey); if (!tokenPayload.cnf?.jkt) { return res.status(401).json({ error: 'invalid_token', message: 'Token missing cnf.jkt binding' }); } // 2. Decode DPoP proof header to extract ephemeral public key const header = jose.decodeProtectedHeader(dpopHeader); if (header.typ !== 'dpop+jwt' || !header.jwk) { return res.status(401).json({ error: 'invalid_dpop_proof', message: 'Invalid proof header or missing jwk' }); } // 3. Verify asymmetric signature of the DPoP proof itself const clientPublicKey = await jose.importJWK(header.jwk, header.alg); const normalizedHtu = `${req.protocol}://${req.get('host')}${req.baseUrl}${req.path}`; const { payload: dpopPayload } = await jose.jwtVerify(dpopHeader, clientPublicKey, { maxTokenAge: '60s', clockTolerance: '5s' }); // 4. Assert method (htm) and target URI (htu) match incoming request precisely if (dpopPayload.htm !== req.method || dpopPayload.htu !== normalizedHtu) { return res.status(401).json({ error: 'invalid_dpop_proof', message: 'htm or htu claim mismatch' }); } // 5. Verify thumbprint of proof public key matches the token's bound jkt const computedJkt = await jose.calculateJwkThumbprint(header.jwk, 'sha256'); if (computedJkt !== tokenPayload.cnf.jkt) { return res.status(401).json({ error: 'invalid_dpop_proof', message: 'JWK does not match cnf.jkt binding' }); } // 6. Prevent replay attacks using jti check in distributed cache const jti = dpopPayload.jti as string; const isNew = await redisClient.set(`dpop_jti:${jti}`, '1', { NX: true, EX: 120 }); if (!isNew) { return res.status(401).json({ error: 'invalid_dpop_proof', message: 'DPoP jti replayed' }); } req.user = tokenPayload; next(); } catch (err) { return res.status(401).json({ error: 'invalid_dpop_proof', details: (err as Error).message }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandating RFC 9449 Demonstrating Proof-of-Possession (DPoP) Cryptographic Binding

Mandating RFC 9449 Demonstrating Proof-of-Possession (DPoP) Cryptographic Binding defines an industrial-grade behavioral standard for security engineering. RFC 9449 DPoP tethers OAuth 2.0 access and refresh tokens to an ephemeral, client-held asymmetric key pair, rendering exfiltrated bearer tokens unusable without the private key. Resource servers and OAuth clients must strictly validate the DPoP proof header (`typ: dpop+jwt`), bound thumbprint (`jkt`), HTTP method, URI target (`htu`/`htm`), and anti-replay nonces (`jti` and server-issued nonces). 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 Unbound Bearer Tokens or Incomplete DPoP Proof Validation Subject to Token Theft and Replay 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 Unbound Bearer Tokens or Incomplete DPoP Proof Validation Subject to Token Theft and Replay	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:

Resource servers MUST enforce scheme 'DPoP' in the Authorization header (`Authorization

Resource servers MUST enforce scheme 'DPoP' in the Authorization header (`Authorization: DPoP <token>`) and reject bare 'Bearer' tokens when DPoP is enabled.

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.