WebAuthn Level 3 PRF Hardware Key Derivation & Zero-Exposure Cryptographic Isolation

--- description: WebAuthn Level 3 PRF Hardware Key Derivation & Zero-Exposure Cryptographic Isolation - Enforces hardware-bound client-side key derivation via the WebAuthn Level 3 PRF (Pseudo-Random Function) extension. Requires immediate zeroization of intermediate derivation buffers, non-extractable CryptoKey constraints in SubtleCrypto, and strict isolation preventing raw symmetric secrets from leaking to auth servers or browser memory heaps. 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-l3-prf-hardware-key-derivation" --- # WebAuthn Level 3 PRF Hardware Key Derivation & Zero-Exposure Cryptographic Isolation > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Exposing Raw PRF Output to Authentication Transport or Retaining Extractable Keys in Web Application State ## System Constraints You are a Principal Security Architect enforcing WebAuthn Level 3 PRF Hardware Key Derivation standards. You must ensure all cryptographic operations utilizing navigator.credentials with the PRF extension isolate derived raw entropy, mandate non-extractable WebCrypto imports, enforce immediate memory zeroization of intermediate arrays, and strictly prohibit symmetric key transport to backend servers. ## Strict Guidelines - Engineers MUST ALWAYS import PRF outputs into WebCrypto (SubtleCrypto) with extractable: false to prevent heap exposure or script exfiltration. - Engineers MUST ALWAYS wipe intermediate derivation buffers and raw PRF outputs immediately using Uint8Array.prototype.fill(0) inside a guaranteed finally block. - Engineers MUST NEVER transmit the PRF evaluation output (results.first or results.second) or derived symmetric keys across network boundaries to Relying Party (RP) auth endpoints. - Engineers MUST ALWAYS pass the raw PRF output through HKDF (RFC 5869) with explicit domain separation (info parameter) rather than utilizing PRF output directly as a symmetric cipher key. - Components NEVER retain raw ArrayBuffer or Uint8Array symmetric key instances within persistent state, closures, module-scope variables, localStorage, sessionStorage, or IndexedDB. - Code SHOULD verify authenticator PRF capability via PublicKeyCredential.getClientCapabilities() or clientExtensionResults.prf before triggering derivation workflows. ## Bad vs Good Implementations ### Hardware Key Derivation with Secure Zeroization and Non-Extractable SubtleCrypto Import #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The PRF derived bytes are sent across the wire to the authentication server, destroying client-side zero-trust guarantees. The key is imported as extractable: true, leaving it accessible via SubtleCrypto exportKey APIs during an XSS exploit, and the rawPrfKey Uint8Array remains retained in browser memory without zeroization. ```typescript import { startAuthentication } from '@simplewebauthn/browser'; export async function decryptUserData(authOptions: any, encryptedPayload: ArrayBuffer) { // Anti-Pattern: PRF output is extracted, left dangling in memory, and sent to server const authResult = await startAuthentication(authOptions); const extensionResults = (authResult as any).clientExtensionResults; const rawPrfKey = new Uint8Array(extensionResults.prf.results.first); // CRITICAL: Leaking hardware secret to the RP server await fetch('/api/verify-and-audit', { method: 'POST', body: JSON.stringify({ rawPrfKey: Array.from(rawPrfKey) }), }); // CRITICAL: Key is extractable and not cleared from heap const cryptoKey = await window.crypto.subtle.importKey( 'raw', rawPrfKey, { name: 'AES-GCM' }, true, // extractable: true exposes key to XSS ['decrypt'] ); return cryptoKey; } ``` #### Production Standard (Correct) > **Standard**: Applies HKDF-SHA256 with explicit domain separation, marks the resulting CryptoKey as extractable: false to prevent exfiltration, strictly avoids network transmission of raw PRF material, and guarantees immediate zeroization of all intermediate ArrayBuffers in a finally block. ```typescript export async function deriveHardwareBoundKey( credentialId: Uint8Array, salt: Uint8Array, domainInfo: Uint8Array ): Promise<CryptoKey> { let rawPrfBuffer: ArrayBuffer | null = null; let intermediatePrfBytes: Uint8Array | null = null; try { const assertion = await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: credentialId, type: 'public-key' }], extensions: { prf: { eval: { first: salt }, }, }, }, }) as PublicKeyCredential | null; const prfResults = assertion?.getClientExtensionResults()?.prf; if (!prfResults?.results?.first) { throw new Error('Authenticator PRF extension failed or was not supported'); } rawPrfBuffer = prfResults.results.first; intermediatePrfBytes = new Uint8Array(rawPrfBuffer); // Import PRF output as HKDF key material const hkdfKey = await crypto.subtle.importKey( 'raw', intermediatePrfBytes, { name: 'HKDF' }, false, ['deriveKey'] ); // Derive domain-separated, non-extractable AES-GCM encryption key const derivedKey = await crypto.subtle.deriveKey( { name: 'HKDF', hash: 'SHA-256', salt: salt, info: domainInfo, }, hkdfKey, { name: 'AES-GCM', length: 256 }, false, // Invariant: extractable MUST be false ['encrypt', 'decrypt'] ); return derivedKey; } finally { // Invariant: Immediate wipe of intermediate plaintext entropy if (intermediatePrfBytes) { intermediatePrfBytes.fill(0); } if (rawPrfBuffer) { new Uint8Array(rawPrfBuffer).fill(0); } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Level 3 PRF Hardware Key Derivation & Zero-Exposure Cryptographic Isolation

WebAuthn Level 3 PRF Hardware Key Derivation & Zero-Exposure Cryptographic Isolation defines an industrial-grade behavioral standard for security engineering. Enforces hardware-bound client-side key derivation via the WebAuthn Level 3 PRF (Pseudo-Random Function) extension. Requires immediate zeroization of intermediate derivation buffers, non-extractable CryptoKey constraints in SubtleCrypto, and strict isolation preventing raw symmetric secrets from leaking to auth servers or browser memory heaps. 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: Exposing Raw PRF Output to Authentication Transport or Retaining Extractable Keys in Web Application State 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	Exposing Raw PRF Output to Authentication Transport or Retaining Extractable Keys in Web Application State	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 import PRF outputs into WebCrypto (SubtleCrypto) with extractable

Engineers MUST ALWAYS import PRF outputs into WebCrypto (SubtleCrypto) with extractable: false to prevent heap exposure or script exfiltration.

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.