FAPI 2.0 Security Profile with DPoP Key-Bound Token Enforcement

--- description: FAPI 2.0 Security Profile with DPoP Key-Bound Token Enforcement - Enforces FAPI 2.0 Security Profile compliance by mandating Demonstrating Proof-of-Possession (DPoP) key-binding (RFC 9449) on all outbound client credentials and inbound resource server validations. Disallows raw Bearer token schemes across microservice perimeters to neutralize token exfiltration and replay attacks at Layer 7. globs: src/**/auth/**/*.{ts,js}, src/**/middleware/**/*.{ts,js}, src/**/clients/**/*.{ts,js}, src/**/gateway/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fapi-20-dpop-key-bound-tokens" --- # FAPI 2.0 Security Profile with DPoP Key-Bound Token Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting or Transmitting Unbound Bearer Tokens in FAPI 2.0 Perimeters ## System Constraints You are a Principal Security Architect enforcing FAPI 2.0 Security Profile compliance with strict RFC 9449 DPoP key-binding. You must prevent the use of standard Bearer tokens, enforce asymmetric proof-of-possession verification on all incoming requests, ensure strict verification of the 'jkt' (JWK Thumbprint) claim matching the bound token, and guarantee that outgoing HTTP clients generate valid, unique DPoP proofs for every request. ## Strict Guidelines - Services MUST reject inbound authorization headers prefixed with 'Bearer ' and enforce RFC 9449 'DPoP ' scheme validation. - Resource Servers MUST compute the SHA-256 JWK thumbprint ('jkt') of the public key in the DPoP proof header and assert exact equality with the 'cnf.jkt' claim embedded in the validated access token. - Resource Servers MUST validate DPoP proof claims: 'htm' MUST match the incoming HTTP method exactly, 'htu' MUST match the canonical HTTP request URI without query/fragment, and 'iat' MUST fall within a tight skew window (default: maximum 60 seconds). - Services MUST implement persistent or distributed replay caching for DPoP proof 'jti' identifiers to prevent proof replay within the validity window. - Outbound HTTP clients MUST NOT share or reuse DPoP proof JWTs across distinct HTTP requests; each request requires a distinct asymmetric signature with a unique 'jti' and freshly computed 'iat'. - Engineers MUST NOT allow non-cryptographic bypass flags in production or staging environments. ## Bad vs Good Implementations ### Inbound Token Verification: Bearer Anti-pattern vs. FAPI 2.0 DPoP Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accepts standard Bearer tokens without DPoP key-binding. If this token is captured via TLS termination compromise, logs, or intermediate proxies, an attacker can replay it against downstream microservices without proof of possession. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; export function authenticateRequest(req: Request, res: Response, next: NextFunction): void { const authHeader = req.headers.authorization; if (!authHeader?.startsWith('Bearer ')) { res.status(401).json({ error: 'Missing or invalid authorization header' }); return; } const token = authHeader.substring(7); try { // Vulnerable: Bearer token is not key-bound; exfiltrated tokens can be freely replayed const decoded = jwt.verify(token, process.env.JWT_PUBLIC_KEY!) as jwt.JwtPayload; req.user = decoded; next(); } catch (err) { res.status(401).json({ error: 'Invalid token' }); } } ``` #### Production Standard (Correct) > **Standard**: Implements RFC 9449 / FAPI 2.0 requirements: enforces the 'DPoP ' scheme, cryptographically verifies proof integrity, validates that the proof's JWK thumbprint matches the token's 'cnf.jkt' claim, asserts HTM/HTU match the request, and guards against replays using a cache. ```typescript import { Request, Response, NextFunction } from 'express'; import * as jose from 'jose'; interface ReplayCache { has(jti: string): Promise<boolean>; set(jti: string, ttlSeconds: number): Promise<void>; } declare const replayCache: ReplayCache; declare const JWKS: jose.JWTVerifyGetKey; export async function authenticateFapiDPoP(req: Request, res: Response, next: NextFunction): Promise<void> { const authHeader = req.headers.authorization; const dpopHeader = req.headers.dpop; if (!authHeader?.startsWith('DPoP ') || typeof dpopHeader !== 'string') { res.status(401).setHeader('WWW-Authenticate', 'DPoP error="invalid_token"').json({ error: 'DPoP token and proof required' }); return; } const accessToken = authHeader.substring(6); try { // 1. Verify access token signature and integrity via JWKS const { payload: tokenClaims } = await jose.jwtVerify(accessToken, JWKS, { algorithms: ['PS256', 'ES256'] }); const expectedJkt = (tokenClaims.cnf as { jkt?: string } | undefined)?.jkt; if (!expectedJkt) { res.status(401).json({ error: 'Access token is not DPoP key-bound (missing cnf.jkt)' }); return; } // 2. Decode and verify DPoP proof header and signature const { payload: proofClaims, protectedHeader } = await jose.jwtVerify(dpopHeader, async (header) => { if (!header.jwk) throw new Error('Missing ephemeral jwk in DPoP header'); return jose.importJWK(header.jwk, header.alg); }, { typ: 'dpop+jwt', algorithms: ['PS256', 'ES256'] }); // 3. Verify JWK Thumbprint matches token binding const proofThumbprint = await jose.calculateJwkThumbprint(protectedHeader.jwk!, 'sha256'); if (proofThumbprint !== expectedJkt) { res.status(401).json({ error: 'DPoP key binding mismatch' }); return; } // 4. Validate HTM, HTU, Clock Skew, and JTI replay const canonicalUrl = `${req.protocol}://${req.get('host')}${req.baseUrl}${req.path}`; if (proofClaims.htm !== req.method || proofClaims.htu !== canonicalUrl) { res.status(401).json({ error: 'DPoP proof htm/htu mismatch' }); return; } if (!proofClaims.jti || await replayCache.has(proofClaims.jti)) { res.status(401).json({ error: 'DPoP proof replayed or missing jti' }); return; } await replayCache.set(proofClaims.jti, 60); req.user = tokenClaims; next(); } catch (err) { res.status(401).setHeader('WWW-Authenticate', 'DPoP error="invalid_dpop_proof"').json({ error: 'DPoP validation failed' }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FAPI 2.0 Security Profile with DPoP Key-Bound Token Enforcement

FAPI 2.0 Security Profile with DPoP Key-Bound Token Enforcement defines an industrial-grade behavioral standard for security engineering. Enforces FAPI 2.0 Security Profile compliance by mandating Demonstrating Proof-of-Possession (DPoP) key-binding (RFC 9449) on all outbound client credentials and inbound resource server validations. Disallows raw Bearer token schemes across microservice perimeters to neutralize token exfiltration and replay attacks at Layer 7. 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 or Transmitting Unbound Bearer Tokens in FAPI 2.0 Perimeters 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 or Transmitting Unbound Bearer Tokens in FAPI 2.0 Perimeters	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 inbound authorization headers prefixed with 'Bearer ' and enforce RFC 9449 'DPoP ' scheme validation.

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.