WebAuthn Level 3 PRF Extension Zero-Knowledge Vault Standard

Mandates client-side symmetric key derivation directly from passkey hardware authenticators via the WebAuthn Level 3 PRF extension to achieve end-to-end zero-knowledge encryption. Master secret keys, raw PRF evaluation buffers, and decrypted payloads must never be transmitted across network boundaries or persisted in client-side storage. Cryptographic vaults must enforce HKDF-SHA-256 derivation over the PRF output before performing authenticated symmetric encryption (AES-256-GCM or ChaCha20-Poly1305).

--- description: WebAuthn Level 3 PRF Extension Zero-Knowledge Vault Standard - Mandates client-side symmetric key derivation directly from passkey hardware authenticators via the WebAuthn Level 3 PRF extension to achieve end-to-end zero-knowledge encryption. Master secret keys, raw PRF evaluation buffers, and decrypted payloads must never be transmitted across network boundaries or persisted in client-side storage. Cryptographic vaults must enforce HKDF-SHA-256 derivation over the PRF output before performing authenticated symmetric encryption (AES-256-GCM or ChaCha20-Poly1305). globs: src/**/{auth,crypto,vault,passkey}/**/*.{ts,tsx,js,mjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-prf-zk-vault-standard" --- # WebAuthn Level 3 PRF Extension Zero-Knowledge Vault Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Transmitting Raw PRF Outputs or Derived Vault Keys to Backend Services for Server-Side Decryption ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Level 3 PRF (Pseudo-Random Function) Extension Zero-Knowledge Vault Standard. Ensure that all master symmetric keys are derived strictly on the client using hardware-evaluated PRF outputs piped into HKDF-SHA-256. Prohibit sending raw PRF secrets, key derivation seeds, or unencrypted vault credentials to any remote API. Mandate proper WebCrypto memory hygiene, ephemeral state isolation, and validation of client extension outputs. ## Strict Guidelines - Engineers MUST ALWAYS evaluate the WebAuthn PRF extension client-side and pipe the resulting authenticator output buffer directly into HKDF-SHA-256 to derive distinct symmetric encryption and integrity keys. - Engineers MUST NOT transmit raw PRF output buffers (`results.prf.results.first`), derivation inputs, or unencrypted vault payloads across HTTP, WebSocket, or RPC boundaries under any circumstance. - Code SHOULD verify authenticator PRF support via `clientExtensionResults.prf.enabled` during registration and fail closed if hardware PRF capability is not confirmed. - Services MUST only ingest and persist ciphertext envelopes containing initialization vectors (IVs/nonces), encrypted payloads, authentication tags, and public salt parameters with zero knowledge of plaintext secrets. - Components NEVER store derived master symmetric keys or decrypted records in persistent browser storage (`localStorage`, `IndexedDB`, session cookies) and MUST zero-fill sensitive `ArrayBuffer` allocations immediately after cryptographic use. ## Bad vs Good Implementations ### Client-Side PRF Key Derivation and Zero-Knowledge Decryption #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Transmits raw PRF authenticator output over the wire to a backend server, completely violating zero-knowledge guarantees. Backend compromise exposes all user secrets. Furthermore, caches unencrypted vault data in persistent localStorage. ```typescript import axios from 'axios'; export async function unlockVaultInsecurely(credentialId: string): Promise<void> { // Anti-pattern: Evaluating PRF and transmitting the raw authenticator output to server const assertion = await navigator.credentials.get({ publicKey: { challenge: new Uint8Array(32), allowCredentials: [{ id: Buffer.from(credentialId, 'base64'), type: 'public-key' }], extensions: { prf: { eval: { first: new TextEncoder().encode('vault-salt-constant-001') } } } } }) as PublicKeyCredential; const extensionResults = assertion.getClientExtensionResults(); const rawPrfSecret = (extensionResults as any).prf?.results?.first; // CRITICAL SECURITY FLAW: Sending PRF output to the backend server const response = await axios.post('/api/vault/decrypt', { credentialId, prfKey: Buffer.from(rawPrfSecret).toString('base64') }); // Insecure storage in localStorage localStorage.setItem('decrypted_vault', JSON.stringify(response.data.vault)); } ``` #### Production Standard (Correct) > **Standard**: Executes cryptographic operations client-side using the WebCrypto API. PRF outputs are consumed locally, expanded using HKDF-SHA-256 into a non-extractable AES-GCM key, and the raw buffer is explicitly wiped with zeros in a finally block. ```typescript export async function unlockVaultZeroKnowledge( credentialId: Uint8Array, salt: Uint8Array, encryptedVault: { iv: Uint8Array; ciphertext: Uint8Array } ): Promise<ArrayBuffer> { 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: salt } } } } }) as PublicKeyCredential | null; if (!assertion) { throw new Error('Authentication cancelled by user'); } const extensionResults = assertion.getClientExtensionResults(); const prfOutput = (extensionResults as unknown as { prf?: { results?: { first?: ArrayBuffer } } }).prf?.results?.first; if (!prfOutput) { throw new Error('Authenticator does not support or return PRF evaluation results'); } let prfBuffer: Uint8Array | null = new Uint8Array(prfOutput); try { // Import raw PRF output as initial key material for HKDF const baseKey = await crypto.subtle.importKey( 'raw', prfBuffer, 'HKDF', false, ['deriveKey'] ); // Derive symmetric encryption key strictly in client memory const vaultKey = await crypto.subtle.deriveKey( { name: 'HKDF', salt: salt, info: new TextEncoder().encode('webauthn-zk-vault-aes-gcm-256'), hash: 'SHA-256' }, baseKey, { name: 'AES-GCM', length: 256 }, false, ['decrypt'] ); // Decrypt vault ciphertext client-side return await crypto.subtle.decrypt( { name: 'AES-GCM', iv: encryptedVault.iv }, vaultKey, encryptedVault.ciphertext ); } finally { // Scrub sensitive raw PRF buffer from memory if (prfBuffer) { prfBuffer.fill(0); prfBuffer = null; } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Level 3 PRF Extension Zero-Knowledge Vault Standard

WebAuthn Level 3 PRF Extension Zero-Knowledge Vault Standard defines an industrial-grade behavioral standard for security engineering. Mandates client-side symmetric key derivation directly from passkey hardware authenticators via the WebAuthn Level 3 PRF extension to achieve end-to-end zero-knowledge encryption. Master secret keys, raw PRF evaluation buffers, and decrypted payloads must never be transmitted across network boundaries or persisted in client-side storage. Cryptographic vaults must enforce HKDF-SHA-256 derivation over the PRF output before performing authenticated symmetric encryption (AES-256-GCM or ChaCha20-Poly1305). 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 Vault Keys to Backend Services for Server-Side Decryption 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 Vault Keys to Backend Services for Server-Side Decryption	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 evaluate the WebAuthn PRF extension client-side and pipe the resulting authenticator output buffer directly into HKDF-SHA-256 to derive distinct symmetric encryption and integrity keys.

Engineers MUST ALWAYS evaluate the WebAuthn PRF extension client-side and pipe the resulting authenticator output buffer directly into HKDF-SHA-256 to derive distinct symmetric encryption and integrity keys.

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.