WebAuthn PRF Hardware Seed Derivation & Zero-Knowledge E2EE Storage Guardrail

--- description: WebAuthn PRF Hardware Seed Derivation & Zero-Knowledge E2EE Storage Guardrail - Standardizes deterministic client-side symmetric key derivation using WebAuthn Level 3 PRF (Pseudo-Random Function) extensions. Mandates strict HKDF domain separation, ensures hardware-bound zero-knowledge isolation, and strictly forbids raw PRF output leakage to network transports or unencrypted client state. globs: src/crypto/**/*.{ts,tsx}, src/auth/**/*.{ts,tsx}, src/security/**/*.{ts,tsx}, src/services/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-prf-zk-seed-derivation-standard" --- # WebAuthn PRF Hardware Seed Derivation & Zero-Knowledge E2EE Storage Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Leaking Raw Hardware PRF Outputs to Server Transports or Direct Slicing of PRF Bytes as Symmetric Keys Without HKDF Domain Separation ## System Constraints You are a Principal Security Architect enforcing the WebAuthn PRF Cryptographic Zero-Knowledge Seed Derivation Standard. You must ensure all cryptographic key derivation from hardware passkeys utilizes the WebAuthn PRF extension with HKDF domain separation, guarantees zero-knowledge persistence, prevents raw entropy leakage to servers, and handles authenticators lacking PRF capabilities without silent security degradation. ## Strict Guidelines - Engineers MUST ALWAYS verify authenticator PRF extension negotiation results before assuming hardware key derivation succeeded. - Engineers MUST ALWAYS pass the raw PRF output through HKDF (RFC 5869 / HKDF-SHA-256) with unique application-specific and versioned `info` strings prior to instantiating symmetric ciphers (e.g., AES-GCM-256). - Engineers MUST NEVER transmit PRF input evaluation salts, raw PRF outputs, or intermediate derived key material to backend servers or telemetry collectors. - Engineers MUST NEVER use raw 32-byte PRF output directly as a symmetric cipher key without HKDF expansion and domain separation. - Code SHOULD enforce distinct salt derivations for distinct security domains (e.g., database encryption vs. credential recovery) to prevent cross-protocol collision. - Services MUST clear sensitive typed arrays and key buffers from memory as soon as cryptographic operations complete. - Components NEVER store decrypted zero-knowledge payloads in persistent unencrypted browser storage (localStorage, sessionStorage, unencrypted IndexedDB). ## Bad vs Good Implementations ### Hardware PRF Derivation with HKDF Domain Separation vs Raw Entropy Usage #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The bad example extracts raw PRF outputs and directly imports them as an AES-GCM key without RFC 5869 HKDF expansion or domain separation info parameters. Worse, it transmits the raw hardware PRF seed to the server, completely invalidating zero-knowledge architecture and hardware non-exportability guarantees. ```typescript import { startAuthentication } from '@simplewebauthn/browser'; export async function deriveVaultKey(authResponse: any): Promise<CryptoKey> { // ANTI-PATTERN: Direct retrieval without validating PRF extension support, // directly slicing raw hardware PRF output as an AES-GCM key without HKDF domain separation, // and sending the raw PRF result to the server for 'backup'. const prfResults = authResponse.clientExtensionResults?.prf?.results?.first; if (!prfResults) { throw new Error('PRF failed'); } // CRITICAL: Leaking hardware secret to the backend await fetch('/api/user/sync-prf-seed', { method: 'POST', body: JSON.stringify({ rawPrfSeed: Array.from(new Uint8Array(prfResults)) }) }); // CRITICAL: Using raw PRF output directly without domain separation return crypto.subtle.importKey( 'raw', prfResults, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt'] ); } ``` #### Production Standard (Correct) > **Standard**: The good example correctly negotiates WebAuthn PRF evaluation with domain salt, verifies the extension result, imports the hardware PRF output as HKDF-SHA-256 key material, and derives a domain-separated AES-GCM-256 key with non-extractable flags. No PRF output or intermediate keys leave client memory. ```typescript import { startAuthentication } from '@simplewebauthn/browser'; const DOMAIN_SALT = new TextEncoder().encode('e2ee-vault-v1-client-salt-deterministic'); const HKDF_INFO_VAULT = new TextEncoder().encode('application-vault-encryption-key-v1'); export async function deriveDeterministicVaultKey( credentialRequestOptions: PublicKeyCredentialRequestOptionsJSON ): Promise<CryptoKey> { // 1. Configure WebAuthn PRF extension evaluation input const prfRequestOptions = { ...credentialRequestOptions, extensions: { ...credentialRequestOptions.extensions, prf: { eval: { first: DOMAIN_SALT } } } }; const authResponse = await startAuthentication(prfRequestOptions); // 2. Validate authenticator returned valid PRF output const prfOutput = authResponse.clientExtensionResults?.prf?.results?.first; if (!(prfOutput instanceof ArrayBuffer) || prfOutput.byteLength !== 32) { throw new Error('Authenticator does not support WebAuthn PRF or evaluation failed.'); } // 3. Import hardware PRF output as HKDF Master Key const prfKeyMaterial = await crypto.subtle.importKey( 'raw', prfOutput, { name: 'HKDF' }, false, ['deriveKey'] ); // 4. Derive isolated, domain-separated AES-GCM-256 encryption key const derivedKey = await crypto.subtle.deriveKey( { name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(32), // Salt can be static zero-bytes since PRF output is already cryptographically pseudorandom info: HKDF_INFO_VAULT }, prfKeyMaterial, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt'] ); // Zero-knowledge guarantee: Server is only sent the standard WebAuthn response verify payload, // PRF outputs and derived symmetric keys are kept strictly within client ephemeral execution. return derivedKey; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn PRF Hardware Seed Derivation & Zero-Knowledge E2EE Storage Guardrail

WebAuthn PRF Hardware Seed Derivation & Zero-Knowledge E2EE Storage Guardrail defines an industrial-grade behavioral standard for security engineering. Standardizes deterministic client-side symmetric key derivation using WebAuthn Level 3 PRF (Pseudo-Random Function) extensions. Mandates strict HKDF domain separation, ensures hardware-bound zero-knowledge isolation, and strictly forbids raw PRF output leakage to network transports or unencrypted client state. 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: Leaking Raw Hardware PRF Outputs to Server Transports or Direct Slicing of PRF Bytes as Symmetric Keys Without HKDF Domain Separation 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	Leaking Raw Hardware PRF Outputs to Server Transports or Direct Slicing of PRF Bytes as Symmetric Keys Without HKDF Domain Separation	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 authenticator PRF extension negotiation results before assuming hardware key derivation succeeded.

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.