RFC 9449 DPoP Edge Nonce Validation and Token-Binding Guardrail

--- description: RFC 9449 DPoP Edge Nonce Validation and Token-Binding Guardrail - Enforces asymmetric RFC 9449 Demonstrating Proof-of-Possession (DPoP) verification and cryptographically bound token validation at edge gateways. Neutralizes access token theft and replay attacks by validating public key thumbprints (jkt), canonicalized HTTP request attributes (htm/htu), access token hashes (ath), and distributed clock-skew-tolerant edge nonces. globs: src/middleware/**/*.{ts,js}, src/auth/**/*.{ts,js}, src/edge/**/*.{ts,js}, src/gateway/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rfc-9449-dpop-edge-nonce-token-binding-guardrail" --- # RFC 9449 DPoP Edge Nonce Validation and Token-Binding Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Plain Bearer Tokens or Unbound DPoP Proofs Without Nonce and Thumbprint Verification ## System Constraints You are a Principal Security Architect enforcing strict RFC 9449 DPoP (Demonstrating Proof-of-Possession) token-binding and distributed edge nonce verification. Reject any code that accepts bearer tokens as proof-of-possession tokens without RFC 9449 validation, permits symmetric DPoP algorithms, skips access token hash (ath) verification, fails to compute and match RFC 7638 JWK thumbprints against cnf.jkt claims, or implements unvalidated, indefinite-lifespan replay nonces. ## Strict Guidelines - Engineers MUST ALWAYS require both Authorization ('DPoP <token>') and DPoP headers for protected resource access under RFC 9449 enforcement. - Engineers MUST ALWAYS verify that the DPoP proof header contains 'typ': 'dpop+jwt' and an asymmetric algorithm ('ES256', 'ES384', 'ES512', 'EdDSA', 'RS256', 'PS256'). Symmetric algorithms like 'HS256' or 'none' MUST be rejected immediately. - Engineers MUST ALWAYS compute the RFC 7638 SHA-256 JWK thumbprint ('jkt') from the ephemeral public key in the DPoP proof header ('jwk') and assert exact equality with the 'cnf.jkt' claim embedded within the access token. - Engineers MUST ALWAYS compute the SHA-256 hash of the presented access token ('ath' claim: base64url(sha256(raw_access_token))) and verify it matches the DPoP proof's 'ath' claim. - Engineers MUST ALWAYS validate that the DPoP proof claims 'htm' (HTTP method) and 'htu' (HTTP target URI normalized, stripped of query and fragments) strictly match the incoming HTTP request context. - Services MUST enforce server-provided distributed nonces ('DPoP-Nonce') generated via authenticated edge signatures (e.g., HMAC-SHA256 of timestamp + entropy) with a bounded validity window (e.g., 60-300s) to tolerate edge clock-skew while thwarting token replay attacks. - Components NEVER store or trust client-supplied public keys without verifying the cryptographic signature of the DPoP proof using that identical embedded JWK. - Engineers MUST emit HTTP 401 with 'WWW-Authenticate: DPoP error="use_dpop_nonce"' and 'DPoP-Nonce: <new_nonce>' whenever a missing, expired, or invalid nonce is encountered. ## Bad vs Good Implementations ### Edge Gateway DPoP and Distributed Nonce Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Decodes JWTs without cryptographic verification, fails to reject symmetric/none algorithms, does not compute or compare RFC 7638 JWK thumbprint with the token's cnf.jkt, ignores the access token hash (ath) claim, does not canonicalize target URI (htu), and completely lacks replay mitigation via DPoP-Nonce challenges. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; export async function insecureEdgeAuth(req: Request, res: Response, next: NextFunction) { const authHeader = req.headers['authorization']; const dpopProof = req.headers['dpop'] as string; if (!authHeader || !authHeader.startsWith('DPoP ')) { return res.status(401).json({ error: 'Missing DPoP bearer token' }); } const token = authHeader.substring(5); // VULNERABILITY: Decodes access token without validating cryptographic binding to proof const decodedToken = jwt.decode(token) as { sub: string; cnf?: { jkt: string } }; if (dpopProof) { // VULNERABILITY: Permitting 'none' or arbitrary algorithm, decoding without signature verification, // missing 'ath' hash check, missing URI/method canonical check, missing DPoP nonce verification const decodedProof = jwt.decode(dpopProof) as { htm?: string; htu?: string }; if (decodedProof?.htm !== req.method) { return res.status(400).json({ error: 'Method mismatch' }); } } req.user = decodedToken.sub; return next(); } ``` #### Production Standard (Correct) > **Standard**: Validates RFC 9449 requirements: asserts typ is 'dpop+jwt', enforces asymmetric-only algorithms, verifies cryptographic signature using public key from JWK, checks HMAC-signed distributed edge nonce with clock-skew bounds, enforces normalized htu and htm matching, validates access token hash (ath), and calculates RFC 7638 JWK thumbprint (jkt) for downstream authorization binding. ```typescript import { Request, Response, NextFunction } from 'express'; import { createHash, createHmac, timingSafeEqual } from 'node:crypto'; import * as jose from 'jose'; const EDGE_NONCE_SECRET = process.env.EDGE_DPOP_NONCE_SECRET!; const NONCE_TTL_MS = 120_000; // 2 minutes with bounded clock-skew tolerance const ALLOWED_ALGORITHMS = ['ES256', 'ES384', 'ES512', 'EdDSA', 'PS256', 'RS256']; function generateEdgeNonce(): string { const timestamp = Date.now().toString(); const hmac = createHmac('sha256', EDGE_NONCE_SECRET).update(timestamp).digest('base64url'); return `${timestamp}.${hmac}`; } function validateEdgeNonce(nonce: string): boolean { const [timestampStr, signature] = nonce.split('.'); if (!timestampStr || !signature) return false; const expectedSig = createHmac('sha256', EDGE_NONCE_SECRET).update(timestampStr).digest('base64url'); const sigValid = timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSig)); if (!sigValid) return false; const issuedAt = parseInt(timestampStr, 10); const now = Date.now(); return now >= issuedAt - 30_000 && now <= issuedAt + NONCE_TTL_MS; } export async function verifyDPoPProof(req: Request, res: Response, next: NextFunction) { const authHeader = req.headers['authorization']; const dpopHeader = req.headers['dpop']; if (!authHeader?.startsWith('DPoP ') || typeof dpopHeader !== 'string') { res.setHeader('WWW-Authenticate', `DPoP error="invalid_token", error_description="Missing DPoP token or proof"`); return res.status(401).json({ error: 'invalid_token' }); } const rawAccessToken = authHeader.substring(5).trim(); const clientNonce = req.headers['dpop-nonce'] as string | undefined; if (!clientNonce || !validateEdgeNonce(clientNonce)) { const newNonce = generateEdgeNonce(); res.setHeader('WWW-Authenticate', 'DPoP error="use_dpop_nonce"'); res.setHeader('DPoP-Nonce', newNonce); return res.status(401).json({ error: 'use_dpop_nonce' }); } try { const header = jose.decodeProtectedHeader(dpopHeader); if (header.typ !== 'dpop+jwt' || !header.alg || !ALLOWED_ALGORITHMS.includes(header.alg) || !header.jwk) { return res.status(400).json({ error: 'invalid_dpop_proof_header' }); } const jwkKey = await jose.importJWK(header.jwk, header.alg); const { payload } = await jose.jwtVerify(dpopHeader, jwkKey, { algorithms: ALLOWED_ALGORITHMS, maxTokenAge: '2m', }); if (payload.nonce !== clientNonce) { return res.status(400).json({ error: 'dpop_nonce_mismatch' }); } if (payload.htm !== req.method) { return res.status(400).json({ error: 'htm_mismatch' }); } const requestUrl = new URL(req.originalUrl || req.url, `${req.protocol}://${req.get('host')}`); const canonicalHtu = `${requestUrl.origin}${requestUrl.pathname}`; if (payload.htu !== canonicalHtu) { return res.status(400).json({ error: 'htu_mismatch' }); } const expectedAth = createHash('sha256').update(rawAccessToken, 'ascii').digest('base64url'); if (payload.ath !== expectedAth) { return res.status(400).json({ error: 'ath_mismatch' }); } const computedJkt = await jose.calculateJwkThumbprint(header.jwk, 'sha256'); res.locals.dpopJkt = computedJkt; res.locals.rawAccessToken = rawAccessToken; return next(); } catch (err) { return res.status(401).json({ error: 'invalid_dpop_proof', details: (err as Error).message }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: RFC 9449 DPoP Edge Nonce Validation and Token-Binding Guardrail

RFC 9449 DPoP Edge Nonce Validation and Token-Binding Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces asymmetric RFC 9449 Demonstrating Proof-of-Possession (DPoP) verification and cryptographically bound token validation at edge gateways. Neutralizes access token theft and replay attacks by validating public key thumbprints (jkt), canonicalized HTTP request attributes (htm/htu), access token hashes (ath), and distributed clock-skew-tolerant edge 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 Plain Bearer Tokens or Unbound DPoP Proofs Without Nonce and Thumbprint 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 Plain Bearer Tokens or Unbound DPoP Proofs Without Nonce and Thumbprint 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:

Engineers MUST ALWAYS require both Authorization ('DPoP <token>') and DPoP headers for protected resource access under RFC 9449 enforcement.

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.