WebAuthn Level 3 PRF Salted Client Assertion & Device-Bound Token Invariant

--- description: WebAuthn Level 3 PRF Salted Client Assertion & Device-Bound Token Invariant - Enforces hardware-backed session binding using WebAuthn Level 3 Pseudo-Random Function (PRF) extension outputs to derive symmetric cryptographic keys directly on the client. Prevents session hijacking, stolen cookie replay, and token exfiltration by requiring all authenticated application requests to carry an ephemeral assertion signed by keys derived from authenticator-evaluated salts. globs: src/**/*.{ts,tsx}, lib/auth/**/*.{ts,js}, services/auth/**/*.{ts,js}, middleware/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-l3-prf-device-bound-tokens" --- # WebAuthn Level 3 PRF Salted Client Assertion & Device-Bound Token Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Bearer Token Decoupling from Hardware PRF Roots and Unsalted Client Assertion Generation ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Level 3 Pseudo-Random Function (PRF) Device-Bound Token Invariant. All authentication contexts in zero-trust surfaces must strictly derive client-side symmetric keys from hardware authenticator PRF outputs using cryptographically secure, server-provided salts and ephemeral nonces. Bearer tokens must never exist in a state decoupled from hardware possession proof; any request lacking a valid Proof-of-Possession (PoP) signature generated from the PRF-derived ephemeral key must be rejected at the boundary. ## Strict Guidelines - Engineers MUST ALWAYS supply a cryptographically random, server-originated salt (minimum 32 bytes) when evaluating the `navigator.credentials.get` PRF extension. - Engineers MUST derive symmetric signing keys using standard Key Derivation Functions (e.g., HKDF-SHA-256) over the raw authenticator PRF output combined with an ephemeral session context. - Engineers MUST NOT persist raw PRF outputs or derived master symmetric keys in non-ephemeral client storage (`localStorage`, `IndexedDB`, or cookies). - Services MUST verify both the WebAuthn assertion signature and the PRF-derived proof-of-possession (PoP) signature over the HTTP method, URI, timestamp, and payload hash. - Components NEVER accept static or unsigned session bearer tokens for privileged operations once the client has negotiated a PRF-capable authenticator credential. ## Bad vs Good Implementations ### Hardware PRF Derivation vs Static Session Bearer Authentication #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Stores a static bearer token in localStorage without hardware binding. If an attacker extracts this token via XSS, malware, or network inspection, the token can be replayed from any environment without proof of authenticator possession. ```typescript import axios from 'axios'; // Anti-pattern: Exporting and storing naked bearer tokens decoupled from authenticator hardware. export async function requestSensitiveAction(actionPayload: Record<string, unknown>): Promise<void> { const token = localStorage.getItem('access_token'); if (!token) throw new Error('Unauthenticated'); // Token can be exfiltrated via XSS and replayed from any device await axios.post('/api/v1/transfer', actionPayload, { headers: { Authorization: `Bearer ${token}` }, }); } ``` #### Production Standard (Correct) > **Standard**: Leverages the WebAuthn Level 3 PRF extension to calculate a symmetric key directly within the security boundary of the client's passkey hardware. The derived HMAC-SHA256 key signs the outgoing payload and timestamp, guaranteeing that stolen session headers cannot be executed on an adversary's machine without the physical authenticator. ```typescript import { subtle } from 'node:crypto'; interface PrfAssertionRequest { credentialId: Uint8Array; serverSalt: Uint8Array; actionPayload: Record<string, unknown>; } export async function requestBoundAction({ credentialId, serverSalt, actionPayload, }: PrfAssertionRequest): Promise<Response> { // 1. Evaluate PRF extension on the WebAuthn Authenticator const assertion = (await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: credentialId, type: 'public-key' }], extensions: { prf: { eval: { first: serverSalt }, }, }, }, })) as PublicKeyCredential; const prfResults = assertion.getClientExtensionResults().prf; if (!prfResults?.results?.first) { throw new Error('Authenticator did not return PRF output; device binding failed.'); } // 2. Import PRF output as master keying material const rawPrfKey = new Uint8Array(prfResults.results.first); const importedPrf = await crypto.subtle.importKey( 'raw', rawPrfKey, 'HKDF', false, ['deriveKey'] ); // 3. Derive an ephemeral HMAC-SHA256 signing key bound to epoch and salt const signingKey = await crypto.subtle.deriveKey( { name: 'HKDF', salt: serverSalt, info: new TextEncoder().encode('webauthn-l3-prf-pop-binding-v1'), hash: 'SHA-256', }, importedPrf, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'] ); const timestamp = Date.now().toString(); const bodyText = JSON.stringify(actionPayload); const signaturePayload = new TextEncoder().encode(`${timestamp}:${bodyText}`); const signature = await crypto.subtle.sign('HMAC', signingKey, signaturePayload); const hexSignature = Array.from(new Uint8Array(signature)) .map((b) => b.toString(16).padStart(2, '0')) .join(''); // 4. Send request with hardware-bound Proof-of-Possession (PoP) assertion headers return fetch('/api/v1/transfer', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Device-Timestamp': timestamp, 'X-Device-PoP-Signature': hexSignature, 'X-Credential-ID': btoa(String.fromCharCode(...new Uint8Array(credentialId))), }, body: bodyText, }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Level 3 PRF Salted Client Assertion & Device-Bound Token Invariant

WebAuthn Level 3 PRF Salted Client Assertion & Device-Bound Token Invariant defines an industrial-grade behavioral standard for security engineering. Enforces hardware-backed session binding using WebAuthn Level 3 Pseudo-Random Function (PRF) extension outputs to derive symmetric cryptographic keys directly on the client. Prevents session hijacking, stolen cookie replay, and token exfiltration by requiring all authenticated application requests to carry an ephemeral assertion signed by keys derived from authenticator-evaluated salts. 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: Bearer Token Decoupling from Hardware PRF Roots and Unsalted Client Assertion Generation 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	Bearer Token Decoupling from Hardware PRF Roots and Unsalted Client Assertion Generation	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 supply a cryptographically random, server-originated salt (minimum 32 bytes) when evaluating the `navigator.credentials.get` PRF extension.

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.