WebAuthn Passkey PRF Cryptographic Seed Invariants for Zero-Knowledge Vaults

--- description: WebAuthn Passkey PRF Cryptographic Seed Invariants for Zero-Knowledge Vaults - Enforces strict cryptographic handling and memory safety invariants when deriving client-side Zero-Knowledge encryption keys via WebAuthn Pseudo-Random Function (PRF) extensions. Mandates domain-separated key derivation (HKDF), strict buffer zeroization of raw PRF outputs, and explicit assertions against authenticator extension omission. globs: src/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, services/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-passkey-prf-cryptographic-seed-invariants" --- # WebAuthn Passkey PRF Cryptographic Seed Invariants for Zero-Knowledge Vaults > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Directly consuming raw WebAuthn PRF output as symmetric cipher keys and leaking un-zeroized raw seeds across client state or network boundaries. ## System Constraints You are a Principal Security Architect and Cryptographer enforcing WebAuthn Passkey PRF (Pseudo-Random Function) Cryptographic Seed Invariants for Zero-Knowledge Vaults. You must enforce that raw PRF outputs are treated as volatile high-entropy entropy inputs, never used directly as cipher keys, always passed through domain-separated HKDF, explicitly checked for authenticator support without silent fallback to insecure defaults, and zeroized immediately after derivation. ## Strict Guidelines - Engineers MUST ALWAYS pass the raw WebAuthn PRF output (`results.first`) through a standardized Key Derivation Function (HKDF-SHA256) with distinct domain-separation `info` parameters (e.g., 'vault-kek:v1') before using it in any cryptographic primitive. - Engineers MUST NEVER use raw WebAuthn PRF evaluation buffers directly as symmetric keys (e.g., AES-GCM or ChaCha20-Poly1305) without cryptographic expansion and context binding. - Engineers MUST ALWAYS explicitly check `assertion.getClientExtensionResults().prf?.results` for null or undefined values; if the PRF extension result is missing, the application MUST fail securely and MUST NOT fall back to weak client-side key generation or unauthenticated fallbacks. - Code MUST explicitly zeroize ephemeral Uint8Array buffers containing raw PRF evaluations immediately after HKDF derivation within a `finally` block using `buffer.fill(0)` or `crypto.getRandomValues(buffer)` followed by `buffer.fill(0)`. - Services MUST NEVER transmit raw PRF output buffers, PRF input salts, or derived root vault keys to any server, logging infrastructure, telemetry payload, or persistent storage (localStorage/IndexedDB). - Authenticators MUST be challenged with a cryptographically secure, fixed-length (32-byte) salt for PRF input (`eval: { first: salt }`), and this salt MUST be stored with vault metadata, cryptographically bound to the vault ID. ## Bad vs Good Implementations ### WebAuthn PRF Key Derivation and Buffer Zeroization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly imports raw PRF output as an AES key without HKDF domain separation, lacks assertion that the authenticator actually executed the PRF extension (leading to unhandled crashes or undefined behavior), and fails to scrub/zeroize the raw PRF entropy buffer from ephemeral memory. ```typescript export async function unlockVaultWithPasskey(credentialId: Uint8Array, prfSalt: Uint8Array) { const assertion = await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: credentialId, type: 'public-key' }], extensions: { prf: { eval: { first: prfSalt } } } } }) as PublicKeyCredential; // VULNERABILITY 1: Direct unsafe property access without validating PRF extension support const results = assertion.getClientExtensionResults() as any; const rawPrf = results.prf.results.first; // Runtime panic if PRF unsupported, or undefined // VULNERABILITY 2: Using raw PRF output directly as AES-GCM key (no domain separation/HKDF) const vaultKey = await crypto.subtle.importKey( 'raw', rawPrf, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt'] ); // VULNERABILITY 3: rawPrf is left hanging in memory without zeroization return vaultKey; } ``` #### Production Standard (Correct) > **Standard**: Validates PRF extension presence, wraps the raw PRF evaluation buffer in a try-finally block to enforce complete memory zeroization, and passes the high-entropy PRF output through HKDF-SHA256 with explicit domain separation ('zero-knowledge-vault:kek:v1') before producing the AES-GCM Key Encryption Key. ```typescript export async function unlockVaultWithPasskey( credentialId: Uint8Array, prfSalt: Uint8Array ): Promise<CryptoKey> { if (prfSalt.byteLength !== 32) { throw new Error('PRF salt must be exactly 32 bytes.'); } 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: prfSalt } } } } })) as PublicKeyCredential | null; if (!assertion) { throw new Error('Passkey authentication cancelled or unavailable.'); } const extensionResults = assertion.getClientExtensionResults(); const prfResult = extensionResults.prf?.results?.first; if (!prfResult) { throw new Error( 'Authenticator does not support WebAuthn PRF extension. Zero-knowledge key derivation failed.' ); } // Copy output to a local buffer for guaranteed explicit zeroization const rawPrfBuffer = new Uint8Array(prfResult.slice(0)); try { // Import PRF output as raw HKDF Initial Keying Material (IKM) const ikm = await crypto.subtle.importKey( 'raw', rawPrfBuffer, 'HKDF', false, ['deriveKey'] ); const info = new TextEncoder().encode('zero-knowledge-vault:kek:v1'); const salt = new Uint8Array(32); // Standardized context salt // Derive the final Key Encryption Key (KEK) using domain-separated HKDF-SHA256 return await crypto.subtle.deriveKey( { name: 'HKDF', hash: 'SHA-256', salt, info }, ikm, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt'] ); } finally { // Invariant: Scrub raw PRF keying material from ephemeral memory immediately crypto.getRandomValues(rawPrfBuffer); rawPrfBuffer.fill(0); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Passkey PRF Cryptographic Seed Invariants for Zero-Knowledge Vaults

WebAuthn Passkey PRF Cryptographic Seed Invariants for Zero-Knowledge Vaults defines an industrial-grade behavioral standard for security engineering. Enforces strict cryptographic handling and memory safety invariants when deriving client-side Zero-Knowledge encryption keys via WebAuthn Pseudo-Random Function (PRF) extensions. Mandates domain-separated key derivation (HKDF), strict buffer zeroization of raw PRF outputs, and explicit assertions against authenticator extension omission. 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: Directly consuming raw WebAuthn PRF output as symmetric cipher keys and leaking un-zeroized raw seeds across client state or network boundaries. 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	Directly consuming raw WebAuthn PRF output as symmetric cipher keys and leaking un-zeroized raw seeds across client state or network boundaries.	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 pass the raw WebAuthn PRF output (`results.first`) through a standardized Key Derivation Function (HKDF-SHA256) with distinct domain-separation `info` parameters (e.g., 'vault-kek

Engineers MUST ALWAYS pass the raw WebAuthn PRF output (`results.first`) through a standardized Key Derivation Function (HKDF-SHA256) with distinct domain-separation `info` parameters (e.g., 'vault-kek:v1') before using it in any cryptographic primitive.

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.