RFC 9449 DPoP Ephemeral Nonce and Cryptographic Key-Binding Invariant

--- description: RFC 9449 DPoP Ephemeral Nonce and Cryptographic Key-Binding Invariant - Enforces strict RFC 9449 Demonstrating Proof-of-Possession (DPoP) at zero-trust edge boundaries and microservice gateways. Mandates cryptographic thumbprint binding (jkt) between asymmetric client key pairs and access tokens, alongside distributed ephemeral nonce verification to eliminate token replay and exfiltration vectors. globs: src/auth/**/*.{ts,js}, src/middleware/**/*.{ts,js}, src/gateway/**/*.{ts,js}, src/security/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rfc-9449-dpop-key-binding-nonce-guardrail" --- # RFC 9449 DPoP Ephemeral Nonce and Cryptographic Key-Binding Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Bearer Tokens or Unbound DPoP Proofs with Stale or Missing Nonce Verification ## System Constraints You are a Principal Security Architect enforcing RFC 9449 DPoP Ephemeral Nonce and Key-Binding Invariants. You must ensure all OAuth2/OIDC token exchanges and resource server requests cryptographically bind access tokens to client ephemeral asymmetric keys via the 'cnf.jkt' claim. You must reject static Bearer tokens at zero-trust edge boundaries, enforce distributed single-use ephemeral nonces, strictly validate HTTP method and URI bindings (htm/htu), and reject any token where the DPoP proof's public key (jwk) does not match the token's bound thumbprint. ## Strict Guidelines - Services MUST inspect the 'DPoP' header and compute the RFC 7638 SHA-256 JWK thumbprint ('jkt') of the embedded public key, matching it identically to the access token's 'cnf.jkt' confirmation claim. - Services MUST reject requests missing a valid ephemeral server-issued nonce with HTTP 401 and include a fresh 'DPoP-Nonce' header in the response. - Engineers MUST NOT validate DPoP proofs without checking the 'htm' (HTTP method) and 'htu' (HTTP target URI normalized without query/fragment) against the executing request context. - Services MUST verify the 'iat' (issued at) timestamp of the DPoP proof within an aggressive skew envelope (maximum 60 seconds) and assert single-use state using a distributed TTL cache (e.g., Redis) keyed by 'jti'. - Services MUST NOT allow symmetric keys, RSA keys under 2048 bits, or non-approved elliptic curves in the DPoP JWK header; algorithms MUST be restricted to ES256, ES384, ES512, or Ed25519. ## Bad vs Good Implementations ### RFC 9449 Invariant DPoP Verification and Nonce Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to enforce RFC 9449 invariants: the DPoP proof header is completely ignored, the asymmetric key binding ('cnf.jkt') is not matched against the proof's JWK, and ephemeral nonces are omitted, leaving the service vulnerable to token theft and replay attacks. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; export async function verifyDPoP(req: Request, res: Response, next: NextFunction) { const authHeader = req.headers.authorization; if (!authHeader?.startsWith('DPoP ')) { return res.status(401).json({ error: 'invalid_token' }); } const accessToken = authHeader.substring(5); // VULNERABILITY: Verifying access token without validating DPoP proof binding or nonce const decoded = jwt.verify(accessToken, process.env.JWT_PUBLIC_KEY!) as jwt.JwtPayload; req.user = decoded; return next(); } ``` #### Production Standard (Correct) > **Standard**: Implements RFC 9449 end-to-end: derives and matches the SHA-256 JWK thumbprint to the access token's 'cnf.jkt', validates 'htm' and 'htu', enforces server-issued ephemeral single-use nonces, and prevents proof replay attacks via distributed 'jti' tracking. ```typescript import { Request, Response, NextFunction } from 'express'; import { calculateJwkThumbprint, importJWK, jwtVerify } from 'jose'; import { NonceStore } from './nonce-store'; interface DPoPClaims { htm: string; htu: string; nonce: string; jti: string; iat: number; } export function createDPoPVerifier(nonceStore: NonceStore, expectedOrigin: string) { return async (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 freshNonce = await nonceStore.generateNonce(); res.setHeader('DPoP-Nonce', freshNonce); return res.status(401).json({ error: 'use_dpop_nonce', message: 'DPoP proof required' }); } try { const rawAccessToken = authHeader.slice(5); const { payload: tokenClaims } = await jwtVerify(rawAccessToken, process.env.TOKEN_SIGNING_KEY!); const cnfJkt = (tokenClaims.cnf as { jkt?: string } | undefined)?.jkt; if (!cnfJkt) { return res.status(401).json({ error: 'invalid_token', message: 'Token missing cnf.jkt binding' }); } const unverifiedHeader = JSON.parse(Buffer.from(dpopHeader.split('.')[0], 'base64url').toString('utf8')); const proofJwk = unverifiedHeader.jwk; if (!proofJwk || proofJwk.kty !== 'EC' || !['ES256', 'ES384', 'ES512'].includes(unverifiedHeader.alg)) { return res.status(400).json({ error: 'invalid_dpop_proof', message: 'Unsupported algorithm or key' }); } const calculatedJkt = await calculateJwkThumbprint(proofJwk, 'sha256'); if (calculatedJkt !== cnfJkt) { return res.status(401).json({ error: 'invalid_token', message: 'Thumbprint mismatch' }); } const proofKey = await importJWK(proofJwk, unverifiedHeader.alg); const { payload: proofClaims } = await jwtVerify(dpopHeader, proofKey, { typ: 'dpop+jwt', algorithms: [unverifiedHeader.alg], clockTolerance: 10 }) as { payload: DPoPClaims }; const expectedHtu = `${expectedOrigin}${req.baseUrl}${req.path}`; if (proofClaims.htm !== req.method || proofClaims.htu !== expectedHtu) { return res.status(400).json({ error: 'invalid_dpop_proof', message: 'Method or URI mismatch' }); } const isValidNonce = await nonceStore.consumeNonce(proofClaims.nonce); if (!isValidNonce) { const freshNonce = await nonceStore.generateNonce(); res.setHeader('DPoP-Nonce', freshNonce); return res.status(401).json({ error: 'use_dpop_nonce', message: 'Nonce invalid or expired' }); } const isJtiUnique = await nonceStore.claimJti(proofClaims.jti, proofClaims.iat); if (!isJtiUnique) { return res.status(401).json({ error: 'invalid_dpop_proof', message: 'Replayed DPoP proof' }); } req.user = tokenClaims; return next(); } catch (err) { return res.status(401).json({ error: 'invalid_dpop_proof', message: 'Proof verification failed' }); } }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: RFC 9449 DPoP Ephemeral Nonce and Cryptographic Key-Binding Invariant

RFC 9449 DPoP Ephemeral Nonce and Cryptographic Key-Binding Invariant defines an industrial-grade behavioral standard for security engineering. Enforces strict RFC 9449 Demonstrating Proof-of-Possession (DPoP) at zero-trust edge boundaries and microservice gateways. Mandates cryptographic thumbprint binding (jkt) between asymmetric client key pairs and access tokens, alongside distributed ephemeral nonce verification to eliminate token replay and exfiltration vectors. 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 or Unbound DPoP Proofs with Stale or Missing 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 or Unbound DPoP Proofs with Stale or Missing 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:

Services MUST inspect the 'DPoP' header and compute the RFC 7638 SHA-256 JWK thumbprint ('jkt') of the embedded public key, matching it identically to the access token's 'cnf.jkt' confirmation claim.

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.