WebAuthn PRF Extension Deterministic Key Derivation Zero-Leakage Standard

--- description: WebAuthn PRF Extension Deterministic Key Derivation Zero-Leakage Standard - Enforces non-extractable cryptographic isolation when deriving symmetric keys from hardware-bound WebAuthn PRF (Pseudo-Random Function) authenticator outputs. Guarantees that raw PRF outputs are immediately imported into non-extractable Web Crypto handles, memory-scrubbed via zeroization, and never persisted to client storage or transmitted over transport layers. globs: src/crypto/**/*.{ts,tsx}, src/auth/**/*.{ts,tsx}, src/services/**/*.{ts,tsx}, src/lib/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-prf-deterministic-key-derivation-guardrail-webauthn-prf-ext-728" --- # WebAuthn PRF Extension Deterministic Key Derivation Zero-Leakage Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Persisting raw PRF outputs, importing derived keys as extractable, or failing to zeroize ephemeral buffers ## System Constraints You are a Principal Security Architect enforcing the WebAuthn PRF Extension Deterministic Key Derivation Zero-Leakage Standard. You must mandate that raw PRF output buffers are processed within ephemeral scopes, zeroized immediately following non-extractable key import, contextually isolated via HKDF domain separation, and never serialized or leaked to persistent client storage or remote APIs. ## Strict Guidelines - Engineers MUST ALWAYS import raw PRF outputs into Web Crypto API handles with extractable set strictly to false. - Engineers MUST ALWAYS perform in-place memory sanitization (zeroization) on ArrayBuffers holding raw PRF outputs immediately after importing into CryptoKey handles. - Engineers MUST NOT persist raw PRF outputs, intermediate master secrets, or plaintext key material to IndexedDB, localStorage, sessionStorage, cookies, or heap-retained module singletons. - Engineers MUST NOT emit raw PRF outputs or derived key material over network boundaries, logging pipelines, or telemetry payloads. - Code SHOULD use HKDF (RFC 5869) with cryptographically distinct info context strings to derive application-specific sub-keys (e.g., encryption vs. signing) from the non-extractable PRF parent key. - Services MUST verify WebAuthn client PRF extension capability flags and throw explicit operational errors when PRF results are missing from the authenticator assertion. - Components NEVER hold raw ArrayBuffer references to PRF secrets in state hooks (e.g., useState, useReducer) or reactive stores. ## Bad vs Good Implementations ### Deterministic Key Derivation from WebAuthn PRF Output #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Raw PRF output is exported to localStorage, imported as an extractable CryptoKey allowing exfiltration via XSS, and the ephemeral buffer is never sanitized, leaving key material exposed in JavaScript heap dumps. ```typescript // CRITICAL VULNERABILITY: Raw PRF output stored in state/storage, imported as extractable, never zeroized export async function deriveEncryptionKey(assertion: AuthenticationResponseJSON): Promise<CryptoKey> { // 1. Reading raw PRF buffer directly from client extension results const prfResults = (assertion as any).clientExtensionResults?.prf?.results?.first; const rawSecret = new Uint8Array(prfResults); // Flaw 1: Leaking raw entropy to persistent storage localStorage.setItem('cached_prf_secret', btoa(String.fromCharCode(...rawSecret))); // Flaw 2: extractable: true allows key extraction and memory dump extraction const cryptoKey = await window.crypto.subtle.importKey( 'raw', rawSecret, { name: 'AES-GCM' }, true, // BAD: Extractable ['encrypt', 'decrypt'] ); // Flaw 3: rawSecret remains intact in memory without zeroization return cryptoKey; } ``` #### Production Standard (Correct) > **Standard**: The raw PRF output is ingested as an unextractable HKDF parent key, domain-separated into an unextractable AES-GCM-256 key, and the underlying ArrayBuffer is explicitly zeroized in a finally block to eliminate heap remnants. ```typescript // ZERO-LEAKAGE INVARIANT: Non-extractable HKDF master import, domain-separated derivation, and immediate buffer scrub const PRF_HKDF_INFO = new TextEncoder().encode('e2ee.deterministic-storage.v1'); export async function deriveEncryptionKey(assertion: PublicKeyCredential): Promise<CryptoKey> { const extensionResults = assertion.getClientExtensionResults(); const prfResults = extensionResults.prf?.results?.first; if (!prfResults) { throw new Error('Authenticator did not return deterministic PRF derivation results.'); } // 1. Clone into isolated mutable buffer const rawBuffer = new Uint8Array(prfResults); let initialKeyHandle: CryptoKey | null = null; try { // 2. Import into WebCrypto as NON-EXTRACTABLE HKDF intermediate key initialKeyHandle = await window.crypto.subtle.importKey( 'raw', rawBuffer, { name: 'HKDF' }, false, // MUST BE NON-EXTRACTABLE ['deriveKey'] ); // 3. Derive isolated non-extractable operational key using explicit context separation const derivedKey = await window.crypto.subtle.deriveKey( { name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(32), // Authenticator salt must align with credential configuration info: PRF_HKDF_INFO, }, initialKeyHandle, { name: 'AES-GCM', length: 256 }, false, // STRICTLY NON-EXTRACTABLE ['encrypt', 'decrypt'] ); return derivedKey; } finally { // 4. Memory Scrub: Securely zeroize ephemeral byte buffer rawBuffer.fill(0); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn PRF Extension Deterministic Key Derivation Zero-Leakage Standard

WebAuthn PRF Extension Deterministic Key Derivation Zero-Leakage Standard defines an industrial-grade behavioral standard for security engineering. Enforces non-extractable cryptographic isolation when deriving symmetric keys from hardware-bound WebAuthn PRF (Pseudo-Random Function) authenticator outputs. Guarantees that raw PRF outputs are immediately imported into non-extractable Web Crypto handles, memory-scrubbed via zeroization, and never persisted to client storage or transmitted over transport layers. 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: Persisting raw PRF outputs, importing derived keys as extractable, or failing to zeroize ephemeral buffers 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	Persisting raw PRF outputs, importing derived keys as extractable, or failing to zeroize ephemeral buffers	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 import raw PRF outputs into Web Crypto API handles with extractable set strictly to false.

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.