Deterministic Client-Side Symmetric Key Derivation via WebAuthn PRF Extension

--- description: Deterministic Client-Side Symmetric Key Derivation via WebAuthn PRF Extension - Enforces zero-trust deterministic client-side symmetric key derivation using the WebAuthn PRF (Pseudo-Random Function) extension. Guarantees that raw authenticator-derived entropy is domain-separated via HKDF, ingested immediately into non-extractable Web Crypto handles, memory-zeroed, and never leaked to untrusted storage or network boundaries. globs: src/**/crypto/**/*.{ts,tsx}, src/**/auth/**/*.{ts,tsx}, src/**/passkey/**/*.{ts,tsx}, src/**/vault/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-prf-client-key-derivation-guardrail-webauthn-prf-ext-767" --- # Deterministic Client-Side Symmetric Key Derivation via WebAuthn PRF Extension > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Persisting raw PRF entropy, bypassing HKDF domain separation, or generating extractable CryptoKeys in client memory. ## System Constraints You are a Principal Security Architect enforcing the WebAuthn PRF Extension Client-Side Symmetric Key Derivation Guardrail. You must ensure that PRF output is handled with defense-in-depth zero-knowledge guarantees: raw authenticator outputs must never be used directly as cipher keys, must be marked non-extractable upon Web Crypto import, must be expanded via HKDF with strict domain separation contexts, and intermediate typed arrays must be securely scrubbed from heap memory. ## Strict Guidelines - Engineers MUST ALWAYS verify the presence of `clientExtensionResults.prf` and validate that output buffers conform to expected 32-byte cryptographic entropy bounds before derivation. - Engineers MUST import raw PRF outputs directly into `crypto.subtle.importKey` as an ephemeral 'HKDF' key with `extractable: false`. - Engineers MUST use HKDF-SHA-256 with distinct, high-entropy, domain-separated `info` parameter tags (e.g., 'org.app.vault.encryption.v1') to derive operational symmetric keys (such as AES-GCM). - Engineers MUST NEVER use raw PRF output directly as a symmetric cipher key without HKDF extraction and expansion. - Code MUST scrub and zeroize intermediate `Uint8Array` memory buffers using `.fill(0)` immediately following Web Crypto ingestion to minimize GC exposure window. - Services and Components MUST NEVER persist raw PRF results, salts, or derived encryption keys to `localStorage`, `sessionStorage`, `IndexedDB`, or transmit them across API/network boundaries. ## Bad vs Good Implementations ### WebAuthn PRF Key Derivation and Zeroization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly casts the PRF buffer into an AES cipher key without HKDF domain separation, leaks the raw secret into persistent localStorage accessible by any DOM script, leaves untracked raw cryptographic entropy lingering in memory, and sets `extractable: true` exposing the key to memory dumping attacks. ```typescript export async function deriveKeyFromCredential(assertion: PublicKeyCredential): Promise<CryptoKey> { const results = assertion.getClientExtensionResults() as any; // INSECURE: Directly using raw PRF output as AES key without domain separation const rawPrf = results.prf?.results?.first; if (!rawPrf) throw new Error('PRF unsupported'); // INSECURE: Storing raw derived buffer in localStorage for offline caching localStorage.setItem('cached_prf', Array.from(new Uint8Array(rawPrf)).join(',')); // INSECURE: Setting extractable to true allows key leakage via XSS heap inspection return await crypto.subtle.importKey( 'raw', rawPrf, { name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt'] ); } ``` #### Production Standard (Correct) > **Standard**: Enforces strict domain separation using HKDF-SHA-256, marks both the root HKDF key and the resulting AES-GCM key as non-extractable within SubtleCrypto, zeroizes the raw PRF memory buffer in a `finally` block, and avoids persisting secrets into unencrypted client-side storage. ```typescript export async function deriveKeyFromCredential( assertion: PublicKeyCredential, domainSalt: Uint8Array, contextInfo: Uint8Array ): Promise<CryptoKey> { const results = assertion.getClientExtensionResults(); const prfResults = results.prf?.results; if (!prfResults?.first) { throw new Error('WebAuthn PRF extension output not available on authenticator'); } const rawSecretBuffer = new Uint8Array(prfResults.first); try { // 1. Ingest raw entropy into non-extractable HKDF master handle const hkdfKey = await crypto.subtle.importKey( 'raw', rawSecretBuffer, 'HKDF', false, // non-extractable ['deriveKey'] ); // 2. Derive operational cipher key using HKDF-SHA-256 with domain separation return await crypto.subtle.deriveKey( { name: 'HKDF', hash: 'SHA-256', salt: domainSalt, info: contextInfo }, hkdfKey, { name: 'AES-GCM', length: 256 }, false, // non-extractable handle prevents heap exfiltration ['encrypt', 'decrypt'] ); } finally { // 3. Immediately zeroize temporary heap memory holding raw authenticator secret rawSecretBuffer.fill(0); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic Client-Side Symmetric Key Derivation via WebAuthn PRF Extension

Deterministic Client-Side Symmetric Key Derivation via WebAuthn PRF Extension defines an industrial-grade behavioral standard for security engineering. Enforces zero-trust deterministic client-side symmetric key derivation using the WebAuthn PRF (Pseudo-Random Function) extension. Guarantees that raw authenticator-derived entropy is domain-separated via HKDF, ingested immediately into non-extractable Web Crypto handles, memory-zeroed, and never leaked to untrusted storage or network boundaries. 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 entropy, bypassing HKDF domain separation, or generating extractable CryptoKeys in client memory. 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 entropy, bypassing HKDF domain separation, or generating extractable CryptoKeys in client memory.	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 verify the presence of `clientExtensionResults.prf` and validate that output buffers conform to expected 32-byte cryptographic entropy bounds before derivation.

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.