WebAuthn PRF Extension Zero-Knowledge Key Derivation Standard

--- description: WebAuthn PRF Extension Zero-Knowledge Key Derivation Standard - Enforces hardware-bound cryptographic key derivation using the WebAuthn Pseudo-Random Function (PRF) extension (hmac-secret) for zero-knowledge client-side encryption. Mandates strict salt uniqueness per domain context, HKDF sub-key expansion, deterministic client-side credential verification, and explicit rejection of insecure fallbacks when hardware-backed PRF fails or is unsupported. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, crypto/**/*.{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-422" --- # WebAuthn PRF Extension Zero-Knowledge Key Derivation Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Deriving E2EE encryption keys directly from raw WebAuthn signatures, predictable salts, or unverified PRF inputs without HKDF separation ## System Constraints You are a Principal Security Architect enforcing the WebAuthn PRF (Pseudo-Random Function) Extension Zero-Knowledge Key Derivation Standard. You must ensure that all client-side encryption keys derived from passkeys utilize hardware-bound HMAC-SHA-256 secrets via the WebAuthn PRF extension, processed through HKDF with contextual domain separation. Prohibit raw signature hashing, ephemeral fallback leaks, and persistent plaintext storage of derived master keys in memory or Web Storage. ## Strict Guidelines - Engineers MUST ALWAYS verify client and authenticator support for the 'prf' extension during registration and authentication before attempting zero-knowledge operations. - Engineers MUST ALWAYS feed the PRF output into HKDF (RFC 5869) using HMAC-SHA-256 with distinct, cryptographically random salts and explicit 'info' context parameters (e.g., 'e2ee-storage-encryption-v1') to achieve sub-key separation. - Engineers MUST NOT use non-deterministic outputs such as raw ECDSA signatures (authenticatorData + clientDataJSON) as key material, as ECDSA signatures produce variable values per assertion. - Engineers MUST NOT fallback to software-derived or server-escrowed master keys silently when the hardware authenticator fails to return PRF outputs. - Engineers MUST IMMEDIATELY wipe derived symmetric keys and intermediate PRF buffers from JavaScript memory structures once cryptographic operations complete, avoiding long-lived heap references. - Services MUST NEVER transmit the PRF evaluation input salt, evaluation output, or derived encryption keys to the server under any circumstance. - Components NEVER store derived master keys in localStorage, sessionStorage, IndexedDB, or standard unencrypted state containers. ## Bad vs Good Implementations ### Hardware-Bound PRF Key Derivation with HKDF Separation vs Raw Signature Hashing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Raw WebAuthn signatures are non-deterministic for standard ECDSA algorithms (P-256), meaning the derived key changes every time the user authenticates, permanently corrupting zero-knowledge access. Furthermore, the signature is accessible to the relying party server, violating zero-knowledge isolation. ```typescript // ANTI-PATTERN: Attempting to derive an encryption key from raw assertion signature // ECDSA signatures use random nonces (k), yielding non-deterministic outputs // that break zero-knowledge decryption across sessions. export async function deriveKeyFromAssertion(credentialId: string): Promise<CryptoKey> { const assertion = await navigator.credentials.get({ publicKey: { challenge: new Uint8Array(32), allowCredentials: [{ id: Uint8Array.from(atob(credentialId), c => c.charCodeAt(0)), type: 'public-key' }], userVerification: 'required' } }) as PublicKeyCredential; const response = assertion.response as AuthenticatorAssertionResponse; // Flaw 1: Insecure, non-deterministic raw signature used as secret // Flaw 2: No context separation, no HKDF, no PRF extension used const rawKeyMaterial = await crypto.subtle.digest('SHA-256', response.signature); return crypto.subtle.importKey( 'raw', rawKeyMaterial, { name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt'] ); } ``` #### Production Standard (Correct) > **Standard**: Leverages the official WebAuthn PRF extension to retrieve a deterministic, hardware-bound 32-byte symmetric secret unknown to the server. Expands the raw secret using HKDF with isolated context strings, preventing key reuse attacks, and marks derived keys as non-extractable (extractable: false). ```typescript // PRODUCTION STANDARD: Hardware-bound PRF extension with HKDF domain separation export interface DerivedVaultKeys { encryptionKey: CryptoKey; authKey: CryptoKey; } export async function deriveZeroKnowledgeKeys( credentialId: Uint8Array, staticPrfSalt: Uint8Array // 32-byte domain-bound salt stored locally/publicly ): Promise<DerivedVaultKeys> { if (!window.PublicKeyCredential || !PublicKeyCredential.isConditionalMediationAvailable) { throw new Error('WebAuthn PRF unsupported on this platform'); } const assertion = await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: credentialId, type: 'public-key' }], userVerification: 'required', extensions: { prf: { eval: { first: staticPrfSalt } } } } }) as PublicKeyCredential; const extensionResults = assertion.getClientExtensionResults(); const prfResult = extensionResults.prf?.results?.first; if (!prfResult || !(prfResult instanceof ArrayBuffer)) { throw new Error('Authenticator did not return hardware-bound PRF output'); } // Step 1: Import raw PRF output (32 bytes) as HKDF base key material const baseHkdfKey = await crypto.subtle.importKey( 'raw', prfResult, { name: 'HKDF' }, false, ['deriveKey'] ); const textEncoder = new TextEncoder(); const hkdfParams = (info: string): HkdfParams => ({ name: 'HKDF', hash: 'SHA-256', salt: staticPrfSalt, info: textEncoder.encode(info) }); // Step 2: Contextual Sub-key Derivation via HKDF const encryptionKey = await crypto.subtle.deriveKey( hkdfParams('zk-storage-encryption-v1'), baseHkdfKey, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt'] ); const authKey = await crypto.subtle.deriveKey( hkdfParams('zk-storage-authentication-v1'), baseHkdfKey, { name: 'HMAC', hash: 'SHA-256', length: 256 }, false, ['sign', 'verify'] ); return { encryptionKey, authKey }; } ```

Architectural Specification & Invariant Rationale

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

WebAuthn PRF Extension Zero-Knowledge Key Derivation Standard defines an industrial-grade behavioral standard for security engineering. Enforces hardware-bound cryptographic key derivation using the WebAuthn Pseudo-Random Function (PRF) extension (hmac-secret) for zero-knowledge client-side encryption. Mandates strict salt uniqueness per domain context, HKDF sub-key expansion, deterministic client-side credential verification, and explicit rejection of insecure fallbacks when hardware-backed PRF fails or is unsupported. 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: Deriving E2EE encryption keys directly from raw WebAuthn signatures, predictable salts, or unverified PRF inputs without HKDF 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	Deriving E2EE encryption keys directly from raw WebAuthn signatures, predictable salts, or unverified PRF inputs without HKDF 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 client and authenticator support for the 'prf' extension during registration and authentication before attempting zero-knowledge operations.

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.