OAuth 2.0 DPoP (RFC 9449) Asymmetric Key Binding and Nonce Validation Boundary

--- description: OAuth 2.0 DPoP (RFC 9449) Asymmetric Key Binding and Nonce Validation Boundary - Enforces strict Demonstrating Proof-of-Possession (DPoP, RFC 9449) cryptographic verification across Backend-for-Frontend (BFF) layers and downstream service hops. Prevents token replay and demotion attacks by mandating verification of ephemeral public keys (`jwk`), access token binding (`ath`), method/URI matching (`htm`/`htu`), and stateful server-issued nonces (`DPoP-Nonce`). globs: src/**/*.{ts,tsx,js,mjs}, server/**/*.{ts,tsx,js,mjs}, middleware/**/*.{ts,tsx,js,mjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth2-dpop-rfc9449-cryptographic-attestation-boundary" --- # OAuth 2.0 DPoP (RFC 9449) Asymmetric Key Binding and Nonce Validation Boundary > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: DPoP-to-Bearer Demotion Across Service Boundaries and Missing Nonce Replay Enforcements ## System Constraints You are a Principal Security Architect enforcing OAuth 2.0 DPoP (RFC 9449) across all edge gateways, Backend-for-Frontend (BFF) entrypoints, and microservice meshes. Ensure access tokens are cryptographically bound to caller key pairs via thumbprint (`jkt`) and access token hash (`ath`). Mandate server-generated freshness nonces via 401 challenge responses (`use_dpop_nonce`). Under no circumstances allow downgrading DPoP-bound tokens to static Bearer tokens when traversing intermediate network boundaries. ## Strict Guidelines - Services MUST reject any incoming request with `Authorization: DPoP <token>` lacking a valid `DPoP` proof header. - Engineers MUST ensure proof headers use `typ: 'dpop+jwt'` and an embedded public key (`jwk`) that is not an asymmetric private key or symmetric secret. - Middleware MUST compute and strictly verify the `ath` (Access Token Hash) claim using SHA-256 with URL-safe base64 encoding (without padding) against the provided access token. - Services MUST validate that the proof claims `htm` matches the actual HTTP request method and `htu` matches the exact request URI without query and fragment components. - Engineers MUST enforce rotating server-side nonces; if the `nonce` claim is missing, expired, or invalid, the server MUST reject the request with HTTP 401, `WWW-Authenticate: DPoP error="use_dpop_nonce"`, and include a fresh `DPoP-Nonce` header. - BFF and API Gateways MUST NOT demote DPoP tokens into ambient `Bearer` tokens during downstream forwarding; downstream propagation MUST use either Token Exchange (RFC 8693) with newly minted DPoP tokens or mutual TLS (RFC 8705). ## Bad vs Good Implementations ### DPoP Token Verification and Nonce Challenge Middleware #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The bad example decodes the proof without verifying the cryptographic signature using the embedded JWK, omits validation for 'ath', 'htm', and 'htu', ignores server nonce rotation, and demotes the token to a plain Bearer token for internal microservice hops, enabling token exfiltration and replay attacks. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; // INSECURE: Strips DPoP, performs shallow verification without 'ath', 'htu', 'htm', or server nonce challenges. export async function insecureDpopAuth(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).send('Missing DPoP Authorization'); } const token = authHeader.replace('DPoP ', ''); if (dpopProof) { // Decodes proof blindly without verifying cryptographic signature, key match, ath, or nonce const decodedProof = jwt.decode(dpopProof) as any; if (!decodedProof) return res.status(401).send('Invalid DPoP Proof'); } // CRITICAL SECURITY FLAW: Demotes DPoP to Bearer token for downstream internal microservices req.headers.authorization = `Bearer ${token}`; next(); } ``` #### Production Standard (Correct) > **Standard**: This implementation fully enforces RFC 9449: it verifies the asymmetric signature using the embedded JWK, validates the token hash ('ath'), checks HTTP method and normalized URI ('htm', 'htu'), validates server nonces, challenges with 401 'use_dpop_nonce', and preserves the proof-of-possession boundary without demoting the token to Bearer. ```typescript import { Request, Response, NextFunction } from 'express'; import { createHash } from 'node:crypto'; import * as jose from 'jose'; interface NonceStore { isValid(nonce: string): Promise<boolean>; generate(): Promise<string>; } declare const nonceStore: NonceStore; export async function secureDpopMiddleware(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 newNonce = await nonceStore.generate(); res.setHeader('DPoP-Nonce', newNonce); res.setHeader('WWW-Authenticate', 'DPoP error="invalid_token"'); return res.status(401).json({ error: 'invalid_dpop_proof' }); } const accessToken = authHeader.slice(5).trim(); try { // 1. Parse header to extract JWK const { header } = jose.decodeProtectedHeader(dpopHeader) as unknown as { header: { typ: string; alg: string; jwk: jose.JWK } }; if (header.typ !== 'dpop+jwt' || !header.jwk) { return res.status(400).json({ error: 'invalid_dpop_header' }); } // 2. Cryptographically verify signature using embedded JWK const publicKey = await jose.importJWK(header.jwk, header.alg); const { payload } = await jose.jwtVerify(dpopHeader, publicKey, { algorithms: ['ES256', 'ES384', 'ES512', 'PS256', 'EdDSA'], maxTokenAge: '90s', }); // 3. Verify HTTP Method and Normalized Target URI (RFC 9449 Section 4.3) const expectedHtm = req.method.toUpperCase(); const protocol = req.headers['x-forwarded-proto'] || req.protocol; const host = req.headers['x-forwarded-host'] || req.get('host'); const expectedHtu = `${protocol}://${host}${req.baseUrl}${req.path}`; if (payload.htm !== expectedHtm || payload.htu !== expectedHtu) { return res.status(400).json({ error: 'htm_or_htu_mismatch' }); } // 4. Verify Access Token Hash (ath) const expectedAth = createHash('sha256').update(accessToken).digest('base64url'); if (payload.ath !== expectedAth) { return res.status(401).json({ error: 'ath_mismatch' }); } // 5. Verify freshness Nonce const proofNonce = payload.nonce as string | undefined; if (!proofNonce || !(await nonceStore.isValid(proofNonce))) { const freshNonce = await nonceStore.generate(); res.setHeader('DPoP-Nonce', freshNonce); res.setHeader('WWW-Authenticate', 'DPoP error="use_dpop_nonce"'); return res.status(401).json({ error: 'use_dpop_nonce' }); } // Retain proof binding, attach verified key thumbprint for downstream authentication res.locals.dpopJkt = await jose.calculateJwkThumbprint(header.jwk, 'sha256'); res.locals.accessToken = accessToken; return next(); } catch (err) { const freshNonce = await nonceStore.generate(); res.setHeader('DPoP-Nonce', freshNonce); return res.status(401).json({ error: 'invalid_dpop_proof', message: (err as Error).message }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OAuth 2.0 DPoP (RFC 9449) Asymmetric Key Binding and Nonce Validation Boundary

OAuth 2.0 DPoP (RFC 9449) Asymmetric Key Binding and Nonce Validation Boundary defines an industrial-grade behavioral standard for security engineering. Enforces strict Demonstrating Proof-of-Possession (DPoP, RFC 9449) cryptographic verification across Backend-for-Frontend (BFF) layers and downstream service hops. Prevents token replay and demotion attacks by mandating verification of ephemeral public keys (`jwk`), access token binding (`ath`), method/URI matching (`htm`/`htu`), and stateful server-issued nonces (`DPoP-Nonce`). 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: DPoP-to-Bearer Demotion Across Service Boundaries and Missing Nonce Replay Enforcements 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	DPoP-to-Bearer Demotion Across Service Boundaries and Missing Nonce Replay Enforcements	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 reject any incoming request with `Authorization

Services MUST reject any incoming request with `Authorization: DPoP <token>` lacking a valid `DPoP` proof header.

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.