OAuth 2.1 RFC 8705 Mutual-TLS Sender-Constrained Token Verification

--- description: OAuth 2.1 RFC 8705 Mutual-TLS Sender-Constrained Token Verification - Mandates strict verification of sender-constrained access tokens bound to client X.509 certificates as specified in RFC 8705. Resource servers must extract the active mutual TLS client certificate, compute its SHA-256 DER digest (x5t#S256), and perform a constant-time comparison against the token confirmation claim (cnf). Replay attacks and exfiltrated tokens must be rejected unconditionally if the certificate thumbprint does not match the active TLS session. globs: src/**/auth/**/*.{ts,js}, src/**/middleware/**/*.{ts,js}, src/**/security/**/*.{ts,js}, src/**/gateway/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth21-rfc8705-mtls-sender-constrained-tokens" --- # OAuth 2.1 RFC 8705 Mutual-TLS Sender-Constrained Token Verification > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Bearer Tokens Without Validating Certificate Confirmation (cnf.x5t#S256) Against Active mTLS Session ## System Constraints You are a Principal Software Architect enforcing OAuth 2.1 and RFC 8705 Sender-Constrained Token standards. You must ensure all protected resource endpoints verify that access tokens containing confirmation ('cnf') claims match the client certificate presented in the mutual-TLS handshake. Never allow verification to fall back to plain bearer token semantics when certificate binding is expected. ## Strict Guidelines - Resource servers MUST extract the client certificate from the current TLS connection (or authenticated edge proxy headers) and compute its base64url-encoded SHA-256 thumbprint (x5t#S256). - Resource servers MUST reject any request with HTTP 401 Unauthorized (invalid_token) if the token contains a 'cnf' claim with 'x5t#S256' that does not match the client certificate thumbprint. - Engineers MUST perform the certificate thumbprint comparison using constant-time equality checks (e.g., crypto.timingSafeEqual) to prevent timing side-channel attacks. - If edge termination is used, reverse proxies MUST strip incoming untrusted client certificate headers and securely inject validated DER/PEM payloads over an encrypted internal network. - Services MUST NOT fall back to standard Bearer token processing when sender-constrained mTLS is configured on the client registration or route scope. ## Bad vs Good Implementations ### Validate RFC 8705 x5t#S256 Token Binding Against Client Certificate #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The middleware validates the cryptographic signature and expiration of the JWT, but completely ignores the 'cnf' confirmation claim. If an attacker exfiltrates this token, they can replay it over a regular connection without presenting the original client TLS private key/certificate. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; export function verifyToken(req: Request, res: Response, next: NextFunction) { const authHeader = req.headers.authorization; if (!authHeader?.startsWith('Bearer ')) { return res.status(401).json({ error: 'unauthorized' }); } const token = authHeader.substring(7); try { // VULNERABILITY: Verifies signature but ignores sender-constrained 'cnf' binding. // An exfiltrated token can be replayed from any client machine without certificate validation. const decoded = jwt.verify(token, process.env.JWT_PUBLIC_KEY!) as jwt.JwtPayload; req.user = decoded; next(); } catch (err) { return res.status(401).json({ error: 'invalid_token' }); } } ``` #### Production Standard (Correct) > **Standard**: Extracts the client's DER-encoded certificate from the active mutual-TLS connection, computes its SHA-256 base64url thumbprint, and compares it to the token's 'cnf.x5t#S256' claim using constant-time comparison to prevent replay attacks and timing leaks. ```typescript import { Request, Response, NextFunction } from 'express'; import jwt from 'jsonwebtoken'; import crypto from 'node:crypto'; import { TLSSocket } from 'node:tls'; interface SenderConstrainedJwtPayload extends jwt.JwtPayload { cnf?: { 'x5t#S256'?: string; }; } export function verifySenderConstrainedToken(req: Request, res: Response, next: NextFunction) { const authHeader = req.headers.authorization; if (!authHeader?.startsWith('Bearer ')) { return res.status(401).setHeader('WWW-Authenticate', 'Bearer error="invalid_request"').json({ error: 'missing_token' }); } const token = authHeader.substring(7); let payload: SenderConstrainedJwtPayload; try { payload = jwt.verify(token, process.env.JWT_PUBLIC_KEY!, { algorithms: ['RS256', 'ES256'] }) as SenderConstrainedJwtPayload; } catch { return res.status(401).setHeader('WWW-Authenticate', 'Bearer error="invalid_token"').json({ error: 'invalid_token' }); } // RFC 8705 Section 3.1: Sender-Constrained Confirmation Check const expectedThumbprint = payload.cnf?.['x5t#S256']; if (expectedThumbprint) { const tlsSocket = req.socket as TLSSocket; const peerCert = tlsSocket.getPeerCertificate?.(true); if (!peerCert || !peerCert.raw) { return res.status(401).setHeader('WWW-Authenticate', 'Bearer error="invalid_token", error_description="Client certificate required"').json({ error: 'mtls_certificate_required' }); } // Calculate SHA-256 of raw DER certificate and base64url encode it const computedThumbprint = crypto.createHash('sha256').update(peerCert.raw).digest('base64url'); const bufExpected = Buffer.from(expectedThumbprint, 'utf8'); const bufComputed = Buffer.from(computedThumbprint, 'utf8'); if (bufExpected.length !== bufComputed.length || !crypto.timingSafeEqual(bufExpected, bufComputed)) { return res.status(401).setHeader('WWW-Authenticate', 'Bearer error="invalid_token", error_description="Certificate thumbprint mismatch"').json({ error: 'invalid_token' }); } } req.user = payload; return next(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OAuth 2.1 RFC 8705 Mutual-TLS Sender-Constrained Token Verification

OAuth 2.1 RFC 8705 Mutual-TLS Sender-Constrained Token Verification defines an industrial-grade behavioral standard for security engineering. Mandates strict verification of sender-constrained access tokens bound to client X.509 certificates as specified in RFC 8705. Resource servers must extract the active mutual TLS client certificate, compute its SHA-256 DER digest (x5t#S256), and perform a constant-time comparison against the token confirmation claim (cnf). Replay attacks and exfiltrated tokens must be rejected unconditionally if the certificate thumbprint does not match the active TLS session. 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 Without Validating Certificate Confirmation (cnf.x5t#S256) Against Active mTLS Session 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 Without Validating Certificate Confirmation (cnf.x5t#S256) Against Active mTLS Session	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:

Resource servers MUST extract the client certificate from the current TLS connection (or authenticated edge proxy headers) and compute its base64url-encoded SHA-256 thumbprint (x5t#S256).

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.