RFC 9449 DPoP Ephemeral Asymmetric Key-Bound Token Rotation Standard

--- description: RFC 9449 DPoP Ephemeral Asymmetric Key-Bound Token Rotation Standard - Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) across all microservice client interactions and ingress gateways. Every outbound request must cryptographically bind access and refresh tokens to an ephemeral, client-held asymmetric key pair with single-use nonce tracking and strict thumbprint confirmation (`cnf.jkt`). This strictly eliminates bearer token exfiltration, cross-service relay, and replay attacks. globs: src/auth/**/*.{ts,tsx}, src/middleware/**/*.{ts,tsx}, src/gateway/**/*.{ts,tsx}, src/clients/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rfc-9449-dpop-ephemeral-key-rotation-standard" --- # RFC 9449 DPoP Ephemeral Asymmetric Key-Bound Token Rotation Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Transmitting Unbound Bearer Tokens or Accepting DPoP Proofs Without Nonce and `ath` Verification ## System Constraints You are a Principal Security Architect enforcing RFC 9449 DPoP (Demonstrating Proof of Possession at the Application Layer). You must ensure that all HTTP requests communicating with authenticated microservice perimeters bind their authorization credentials to an ephemeral client-side private key (ES256/Ed25519) and reject any plain 'Bearer' authorization or detached/unvalidated proof tokens. ## Strict Guidelines - Clients MUST ALWAYS generate or rotate an ephemeral asymmetric key pair (ECDSA P-256 or Ed25519) stored strictly in volatile, memory-only storage with zero persistence to disk or localStorage. - Clients MUST ALWAYS sign an RFC 9449 compliant DPoP Proof JWT with headers `typ: 'dpop+jwt'` and include the public JWK in the `jwk` header without exposing private key material. - Clients MUST ALWAYS include standard proof claims: `htm` (exact uppercase HTTP method), `htu` (normalized target URI without query string or fragment), `iat` (current epoch timestamp), `jti` (cryptographically random UUIDv4), and `ath` (base64url-encoded SHA-256 hash of the presented access token). - Clients MUST send tokens using the `DPoP <token>` authorization scheme rather than `Bearer <token>` whenever accessing protected resources. - Resource Servers MUST ALWAYS verify the signature of the DPoP Proof using the ephemeral public key embedded in the DPoP header `jwk` parameter. - Resource Servers MUST validate that `htm` and `htu` strictly match the active HTTP request method and canonical URI, accounting for reverse-proxy forwarded hosts. - Resource Servers MUST ALWAYS enforce single-use `jti` tracking in a distributed atomic cache (e.g., Redis `SET NX EX`) with a maximum proof clock-skew window not exceeding 60 seconds. - Resource Servers MUST verify that the calculated SHA-256 JWK Thumbprint (RFC 7638) of the embedded public key matches the `cnf.jkt` claim embedded in the signed Access Token payload. - Services MUST reject requests with HTTP 401 when the DPoP proof is missing, malformed, expired, replayed, or when the access token hash `ath` fails to match the provided token. ## Bad vs Good Implementations ### DPoP Inbound Verification Middleware #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This middleware accepts unbound Bearer tokens. If an attacker intercepts the access token via logging, SSRF, or upstream compromise, they can replay it anywhere without possessing the client's private key. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; // ANTI-PATTERN: Verifies standard Bearer token without checking DPoP proof, // allowing exfiltrated tokens to be freely replayed across services. export async function authenticateResource(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 { const payload = jwt.verify(token, process.env.JWT_PUBLIC_KEY!); req.user = payload; next(); } catch (err) { return res.status(401).json({ error: 'Invalid token' }); } } ``` #### Production Standard (Correct) > **Standard**: This middleware enforces all requirements of RFC 9449: it validates the DPoP signature using the embedded JWK, asserts exact HTTP method and URI equivalence, checks access token hash ('ath'), enforces anti-replay via an atomic Redis JTI registry, and confirms that the JWK thumbprint matches the token's 'cnf.jkt' binding. ```typescript import { Request, Response, NextFunction } from 'express'; import * as jose from 'jose'; import crypto from 'node:crypto'; import { redisClient } from '../cache/redis'; interface AuthenticatedDPoPRequest extends Request { tokenClaims?: jose.JWTPayload; } export async function verifyDPoPProof(req: AuthenticatedDPoPRequest, 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 token and proof header required' }); } const rawAccessToken = authHeader.slice(5).trim(); try { // 1. Decode unverified DPoP header to inspect the ephemeral public key const unverifiedHeader = jose.decodeProtectedHeader(dpopHeader); if (unverifiedHeader.typ !== 'dpop+jwt' || !unverifiedHeader.jwk) { return res.status(401).json({ error: 'invalid_dpop_proof', message: 'Malformed DPoP header' }); } const clientPublicKey = await jose.importJWK(unverifiedHeader.jwk, unverifiedHeader.alg); // 2. Verify DPoP proof signature and clock skew (max 60 seconds) const { payload: dpopPayload } = await jose.jwtVerify(dpopHeader, clientPublicKey, { maxTokenAge: '60s', clockTolerance: '5s' }); // 3. Validate HTM and HTU claims const protocol = req.headers['x-forwarded-proto'] || req.protocol; const host = req.headers['x-forwarded-host'] || req.get('host'); const canonicalUrl = `${protocol}://${host}${req.baseUrl}${req.path}`; if (dpopPayload.htm !== req.method.toUpperCase() || dpopPayload.htu !== canonicalUrl) { return res.status(401).json({ error: 'invalid_dpop_proof', message: 'htm or htu mismatch' }); } // 4. Validate Access Token Hash (ath) const expectedAth = crypto.createHash('sha256').update(rawAccessToken).digest('base64url'); if (dpopPayload.ath !== expectedAth) { return res.status(401).json({ error: 'invalid_dpop_proof', message: 'ath claim does not match access token' }); } // 5. Distributed replay prevention via atomic cache lock const jti = dpopPayload.jti as string; if (!jti) { return res.status(401).json({ error: 'invalid_dpop_proof', message: 'Missing jti claim' }); } const isNew = await redisClient.set(`dpop:jti:${jti}`, '1', 'EX', 120, 'NX'); if (!isNew) { return res.status(401).json({ error: 'use_dpop_nonce', message: 'DPoP proof replayed' }); } // 6. Verify Access Token and bind to client JWK thumbprint const accessJwks = jose.createRemoteJWKSet(new URL(process.env.OAUTH_JWKS_URI!)); const { payload: tokenClaims } = await jose.jwtVerify(rawAccessToken, accessJwks); const computedThumbprint = await jose.calculateJwkThumbprint(unverifiedHeader.jwk, 'sha256'); const confirmation = tokenClaims.cnf as { jkt?: string } | undefined; if (!confirmation?.jkt || confirmation.jkt !== computedThumbprint) { return res.status(401).json({ error: 'invalid_token', message: 'DPoP key does not match token cnf.jkt' }); } req.tokenClaims = tokenClaims; return next(); } catch (error) { return res.status(401).json({ error: 'invalid_dpop_proof', message: 'DPoP cryptographic verification failed' }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: RFC 9449 DPoP Ephemeral Asymmetric Key-Bound Token Rotation Standard

RFC 9449 DPoP Ephemeral Asymmetric Key-Bound Token Rotation Standard defines an industrial-grade behavioral standard for security engineering. Enforces RFC 9449 Demonstrating Proof-of-Possession (DPoP) across all microservice client interactions and ingress gateways. Every outbound request must cryptographically bind access and refresh tokens to an ephemeral, client-held asymmetric key pair with single-use nonce tracking and strict thumbprint confirmation (`cnf.jkt`). This strictly eliminates bearer token exfiltration, cross-service relay, 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: Transmitting Unbound Bearer Tokens or Accepting DPoP Proofs Without Nonce and `ath` 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	Transmitting Unbound Bearer Tokens or Accepting DPoP Proofs Without Nonce and `ath` 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:

Clients MUST ALWAYS generate or rotate an ephemeral asymmetric key pair (ECDSA P-256 or Ed25519) stored strictly in volatile, memory-only storage with zero persistence to disk or localStorage.

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.