Zero-Knowledge Hardware-Derived Cryptographic Keys via WebAuthn PRF Extension

--- description: Zero-Knowledge Hardware-Derived Cryptographic Keys via WebAuthn PRF Extension - Enforces strict client-side symmetric key derivation from hardware authenticators using the WebAuthn Pseudo-Random Function (PRF) extension (HMAC-secret). Raw derived keys, PRF evaluation outputs, and unencrypted key materials must never be transmitted to the application server or persisted in non-ephemeral storage, maintaining absolute zero-knowledge privacy. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, packages/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-prf-zk-key-derivation-standard-webauthn-prf-ext-701" --- # Zero-Knowledge Hardware-Derived Cryptographic Keys via WebAuthn PRF Extension > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Transmitting Raw PRF Outputs or Derived Master Keys to Servers and Persisting Unencrypted Key Material ## System Constraints You are a Principal Security Architect enforcing the WebAuthn PRF (Pseudo-Random Function) Extension Zero-Knowledge Key Derivation Standard. You must ensure all cryptographic key derivations execute strictly on the client hardware token, enforce WebCrypto HKDF-SHA256 post-processing with unique context-bound salts, and forbid sending raw PRF secrets, derived master keys, or unhashed evaluation results across the network or into insecure web storage. ## Strict Guidelines - Engineers MUST ALWAYS request PRF extension evaluation using client-side WebAuthn assertions with navigator.credentials.get({ publicKey: { extensions: { prf: { eval: { first: saltBuffer } } } } }). - Engineers MUST ALWAYS pass the raw PRF evaluation output ('results.first') directly into SubtleCrypto.importKey as raw keying material ('HKDF') and expand via SubtleCrypto.deriveKey using cryptographically strong, domain-separated info parameters. - Engineers MUST NOT transmit raw PRF output buffers, HMAC secrets, or derived symmetric encryption keys (AES-GCM) to the application backend or over any network interface. - Engineers MUST NOT persist derived keys or raw PRF outputs in localStorage, sessionStorage, IndexedDB, or cookies; derived CryptoKey handles must be kept strictly in ephemeral memory. - Services MUST verify WebAuthn assertion signatures (authenticatorData, clientDataJSON, signature) on the server without expecting or requiring symmetric key materials in the payload. - Code MUST explicitly check for authenticator PRF extension support during credential creation via extensions: { prf: {} } and inspect credential.getClientExtensionResults().prf?.enabled before assuming derivation capability. ## Bad vs Good Implementations ### Zero-Knowledge Symmetric Key Derivation via WebAuthn PRF and HKDF-SHA256 #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Transmits raw PRF hardware outputs directly to the backend server, entirely compromising zero-knowledge architecture. It also stores the raw secret in localStorage and lacks domain-separated key expansion via WebCrypto HKDF. ```typescript export async function unlockUserVault(credentialId: string): Promise<void> { // Flaw 1: Static salt without proper context const staticSalt = new TextEncoder().encode('global-static-salt'); const assertion = await navigator.credentials.get({ publicKey: { challenge: new Uint8Array([1, 2, 3, 4]), allowCredentials: [{ id: Buffer.from(credentialId, 'base64'), type: 'public-key' }], extensions: { prf: { eval: { first: staticSalt } } } } }) as PublicKeyCredential; const extensionResults = assertion.getClientExtensionResults(); // Flaw 2: Accessing raw PRF bytes without checking extension validity const prfOutput = new Uint8Array(extensionResults.prf?.results?.first as ArrayBuffer); // CRITICAL SECURITY FLAW: Sending raw PRF output to the backend server await fetch('/api/vault/unlock', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ credentialId, rawHardwareKey: Array.from(prfOutput) }) }); // Flaw 3: Insecure storage of raw key bytes in localStorage localStorage.setItem('cached_prf_secret', Buffer.from(prfOutput).toString('hex')); } ``` #### Production Standard (Correct) > **Standard**: Evaluates PRF with userVerification='required', immediately converts raw PRF outputs into an ephemeral HKDF IKM, derives a non-extractable client-side AES-GCM key, and only sends public assertion metadata to the server. ```typescript export interface DerivedVaultKeys { encryptionKey: CryptoKey; } export async function deriveClientZeroKnowledgeKey( credentialId: Uint8Array, challenge: Uint8Array, contextSalt: Uint8Array ): Promise<DerivedVaultKeys> { if (!window.PublicKeyCredential) { throw new Error('WebAuthn is not supported in this runtime environment'); } const assertion = (await navigator.credentials.get({ publicKey: { challenge, allowCredentials: [{ id: credentialId, type: 'public-key' }], userVerification: 'required', extensions: { prf: { eval: { first: contextSalt } } } } })) as PublicKeyCredential | null; if (!assertion) { throw new Error('WebAuthn assertion failed or was cancelled'); } const extensionResults = assertion.getClientExtensionResults(); const rawPrfBuffer = extensionResults.prf?.results?.first; if (!rawPrfBuffer || !(rawPrfBuffer instanceof ArrayBuffer)) { throw new Error('Authenticator did not return a valid PRF evaluation result'); } // Import raw PRF output as HKDF Initial Keying Material (IKM) const ikmKey = await crypto.subtle.importKey( 'raw', rawPrfBuffer, 'HKDF', false, ['deriveKey'] ); // Derive AES-GCM 256-bit key using HKDF-SHA256 with domain separation const encryptionKey = await crypto.subtle.deriveKey( { name: 'HKDF', hash: 'SHA-256', salt: contextSalt, info: new TextEncoder().encode('application-vault-encryption-v1') }, ikmKey, { name: 'AES-GCM', length: 256 }, false, // non-extractable ['encrypt', 'decrypt'] ); // Server receives ONLY the standard WebAuthn assertion signature for identity verification const base64Signature = btoa(String.fromCharCode(...new Uint8Array(assertion.response.clientDataJSON))); await fetch('/api/auth/verify-assertion', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ id: assertion.id, clientDataJSON: base64Signature }) }); // Return non-extractable CryptoKey strictly in-memory return { encryptionKey }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Zero-Knowledge Hardware-Derived Cryptographic Keys via WebAuthn PRF Extension

Zero-Knowledge Hardware-Derived Cryptographic Keys via WebAuthn PRF Extension defines an industrial-grade behavioral standard for security engineering. Enforces strict client-side symmetric key derivation from hardware authenticators using the WebAuthn Pseudo-Random Function (PRF) extension (HMAC-secret). Raw derived keys, PRF evaluation outputs, and unencrypted key materials must never be transmitted to the application server or persisted in non-ephemeral storage, maintaining absolute zero-knowledge privacy. 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: Transmitting Raw PRF Outputs or Derived Master Keys to Servers and Persisting Unencrypted Key Material 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	Transmitting Raw PRF Outputs or Derived Master Keys to Servers and Persisting Unencrypted Key Material	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 request PRF extension evaluation using client-side WebAuthn assertions with navigator.credentials.get({ publicKey

Engineers MUST ALWAYS request PRF extension evaluation using client-side WebAuthn assertions with navigator.credentials.get({ publicKey: { extensions: { prf: { eval: { first: saltBuffer } } } } }).

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.