Mandatory DPoP Proof-Key Binding for Passkey Conditional UI Sessions

--- description: Mandatory DPoP Proof-Key Binding for Passkey Conditional UI Sessions - Enforces strict cryptographic binding between WebAuthn Passkey Conditional UI assertions and ephemeral, non-extractable client-side DPoP (RFC 9449) key pairs. Eliminates enterprise token theft, session hijacking, and adversary-in-the-middle (AiTM) proxying by ensuring access tokens cannot be issued as bearer tokens or replayed outside the initiating browser context. globs: src/auth/**/*.{ts,tsx}, src/lib/crypto/**/*.{ts,tsx}, src/services/api/**/*.{ts,tsx}, src/server/auth/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/passkey-conditional-ui-dpop-sender-constrained-binding" --- # Mandatory DPoP Proof-Key Binding for Passkey Conditional UI Sessions > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Issuing Unconstrained Bearer Tokens from Unbound Passkey Conditional Autofill Assertions ## System Constraints You are a Principal Security Architect enforcing Passkey Conditional UI with DPoP Sender-Constrained Token Binding. Reject any authentication architecture that returns traditional bearer tokens upon WebAuthn assertion or persists extractable private proof keys in unhardened browser storage. Mandate RFC 9449 compliance, non-extractable WebCrypto keypairs, and strict verification of proof-of-possession thumbprints bound directly to server-generated WebAuthn challenges. ## Strict Guidelines - Engineers MUST generate an ephemeral, non-extractable ECDSA (P-256) or Ed25519 CryptoKey pair via `crypto.subtle` prior to invoking Passkey Conditional UI. - Engineers MUST compute the SHA-256 JWK Thumbprint (`jkt`) of the DPoP public key and transmit it to the server during authentication challenge negotiation. - The server MUST cryptographically bind the WebAuthn challenge to the client's `jkt` thumbprint (e.g., `challenge = HMAC-SHA256(server_secret, session_id || jkt)`). - Clients MUST invoke `navigator.credentials.get` using `mediation: 'conditional'` alongside an `AbortController` signal to support autocomplete autofill safely. - Authentication and token exchange requests MUST include a valid `DPoP` proof JWT signed by the private key matching the `jkt`, containing accurate `htm`, `htu`, `iat`, and unique `jti` claims. - Engineers MUST NEVER persist DPoP private keys to `localStorage`, `sessionStorage`, or unencrypted cookies; keys MUST remain in-memory or in restricted IndexedDB contexts. - The authorization server MUST issue tokens with a `cnf.jkt` confirmation claim and verify that API requests provide fresh DPoP proofs corresponding strictly to the bound token thumbprint. ## Bad vs Good Implementations ### Passkey Conditional UI Login with Insecure Bearer Token #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This implementation retrieves a Passkey assertion via Conditional UI but exchanges it for an unbound bearer token stored in localStorage. An attacker executing an AiTM proxy or XSS attack can capture the assertion or steal the token, allowing arbitrary replay outside the original browser context. ```typescript // Anti-pattern: Authentication returns a raw bearer token with no client proof-key binding export async function initInsecureConditionalLogin(): Promise<void> { const optionsRes = await fetch('/api/auth/challenge'); const options = await optionsRes.json(); // WebAuthn conditional autofill invoked without sender constraint const credential = (await navigator.credentials.get({ mediation: 'conditional', publicKey: { challenge: Uint8Array.from(atob(options.challenge), c => c.charCodeAt(0)), rpId: window.location.hostname, userVerification: 'preferred' } })) as PublicKeyCredential; const verifyRes = await fetch('/api/auth/verify', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ credential }) }); // Bearer token vulnerable to exfiltration and replay attacks const { accessToken } = await verifyRes.json(); localStorage.setItem('access_token', accessToken); } ``` #### Production Standard (Correct) > **Standard**: The fix generates a non-extractable ECDSA keypair, binds its SHA-256 JWK thumbprint directly into the WebAuthn challenge, and requires a cryptographically signed DPoP proof header (RFC 9449) during token exchange. The issued access token is sender-constrained to the ephemeral client key, neutralizing token theft and AiTM replays. ```typescript // Production standard: Conditional UI WebAuthn assertion bound to ephemeral DPoP keypair import { calculateJwkThumbprint, createDPoPProof } from './dpop-crypto'; export async function initSecureDPoPConditionalLogin(signal: AbortSignal): Promise<void> { // 1. Generate non-extractable client DPoP keypair const dpopKeyPair = await crypto.subtle.generateKey( { name: 'ECDSA', namedCurve: 'P-256' }, false, // non-extractable ['sign'] ); const dpopJwk = await crypto.subtle.exportKey('jwk', dpopKeyPair.publicKey); const jkt = await calculateJwkThumbprint(dpopJwk); // 2. Fetch server challenge bound to the DPoP thumbprint const challengeRes = await fetch('/api/auth/challenge', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jkt }) }); const { challenge, rpId } = await challengeRes.json(); // 3. Initiate Passkey Conditional UI autofill const credential = (await navigator.credentials.get({ mediation: 'conditional', signal, publicKey: { challenge: Uint8Array.from(atob(challenge), c => c.charCodeAt(0)), rpId, userVerification: 'required' } })) as PublicKeyCredential; if (!credential) return; // 4. Generate DPoP proof binding the token request to the ephemeral key const dpopProof = await createDPoPProof({ keyPair: dpopKeyPair, htm: 'POST', htu: `${window.location.origin}/api/auth/token`, }); // 5. Exchange assertion for sender-constrained token const tokenRes = await fetch('/api/auth/token', { method: 'POST', headers: { 'Content-Type': 'application/json', 'DPoP': dpopProof }, body: JSON.stringify({ credential, jkt }) }); if (!tokenRes.ok) throw new Error('Token binding validation failed'); // Session store keeps dpopKeyPair in-memory only const tokenPayload = await tokenRes.json(); window.__SESSION_CONTEXT__ = { token: tokenPayload.accessToken, dpopKeyPair }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory DPoP Proof-Key Binding for Passkey Conditional UI Sessions

Mandatory DPoP Proof-Key Binding for Passkey Conditional UI Sessions defines an industrial-grade behavioral standard for security engineering. Enforces strict cryptographic binding between WebAuthn Passkey Conditional UI assertions and ephemeral, non-extractable client-side DPoP (RFC 9449) key pairs. Eliminates enterprise token theft, session hijacking, and adversary-in-the-middle (AiTM) proxying by ensuring access tokens cannot be issued as bearer tokens or replayed outside the initiating browser context. 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: Issuing Unconstrained Bearer Tokens from Unbound Passkey Conditional Autofill Assertions 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	Issuing Unconstrained Bearer Tokens from Unbound Passkey Conditional Autofill Assertions	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 generate an ephemeral, non-extractable ECDSA (P-256) or Ed25519 CryptoKey pair via `crypto.subtle` prior to invoking Passkey Conditional UI.

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.