WebAuthn Level 3 PRF Hardware-Bound Symmetric Key Derivation Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Persisting Raw Symmetric Keys in Browser Storage or Exposing PRF Output Directly to Application State Without HKDF Domain Separation) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

WebAuthn Level 3 PRF Hardware-Bound Symmetric Key Derivation Standard

Enforces strict implementation standards for WebAuthn Level 3 Pseudo-Random Function (PRF) extension to derive hardware-bound symmetric encryption keys directly from FIDO2/passkey authenticators. Guarantees that sensitive application data cannot be decrypted from exfiltrated memory or stolen browser tokens without active physical presence and explicit hardware token interaction. Mandates secondary key derivation via HKDF with strict domain separation before any derived secret touches application memory.

--- description: WebAuthn Level 3 PRF Hardware-Bound Symmetric Key Derivation Standard - Enforces strict implementation standards for WebAuthn Level 3 Pseudo-Random Function (PRF) extension to derive hardware-bound symmetric encryption keys directly from FIDO2/passkey authenticators. Guarantees that sensitive application data cannot be decrypted from exfiltrated memory or stolen browser tokens without active physical presence and explicit hardware token interaction. Mandates secondary key derivation via HKDF with strict domain separation before any derived secret touches application memory. globs: src/**/*.{ts,tsx,js,mjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-level3-prf-hardware-bound-key-derivation-standard" --- # WebAuthn Level 3 PRF Hardware-Bound Symmetric Key Derivation Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Persisting Raw Symmetric Keys in Browser Storage or Exposing PRF Output Directly to Application State Without HKDF Domain Separation ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Level 3 PRF Hardware-Bound Symmetric Key Derivation Standard. You must reject any authentication or encryption flow that persists long-lived master keys in browser storage (IndexedDB, localStorage, sessionStorage) or uses session bearer tokens as decryption keys. Enforce hardware-bound key derivation where the authenticator's PRF extension derives an ephemeral hardware secret, which is strictly passed to HKDF-SHA-256 with application-layer domain separation to generate short-lived, non-exportable WebCrypto CryptoKey handles. ## Strict Guidelines - Engineers MUST ALWAYS verify client support for WebAuthn PRF via `PublicKeyCredential.isConditionalMediationAvailable()` and `clientExtensionResults.prf` checks before initiating key derivation flows. - Engineers MUST NEVER use the raw PRF evaluation output buffer directly as a symmetric cipher key; it MUST be ingested as HKDF key material (`IKM`) and expanded via HKDF-SHA-256 with high-entropy salt and explicit context `info` parameters. - Code SHOULD generate derived WebCrypto `CryptoKey` objects with `extractable: false` to prevent programmatic key exfiltration via browser memory dumps or malicious scripts. - Services MUST supply a cryptographically secure, server-attested salt (minimum 32 bytes) for the PRF `eval` input to enforce domain separation and prevent precomputation attacks across distinct domains or client instances. - Components NEVER persist derived PRF evaluation buffers or intermediate cryptographic material to persistent storage (`localStorage`, `sessionStorage`, `IndexedDB`, or cookies). - Engineers MUST configure fallback strategies to gracefully downgrade to server-side authenticated re-encryption or deny access when an authenticator lacks Level 3 PRF support, rather than storing plaintext fallback keys. ## Bad vs Good Implementations ### Hardware-Bound Symmetric Key Derivation using WebAuthn Level 3 PRF and HKDF #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The bad example generates a raw symmetric key in software, stores it in plaintext inside client-side IndexedDB, and imports it with extractable: true. Any malicious script or XSS vulnerability can directly read IndexedDB and extract the key, rendering session invalidation and zero-trust guarantees completely useless. ```typescript import { openDB } from 'idb'; // VULNERABLE: Derives keys without hardware-bound PRF, persists static key to IndexedDB, // enabling session token exfiltration and permanent key theft via XSS. export async function getEncryptionKey(credentialId: string): Promise<CryptoKey> { const db = await openDB('app-secrets', 1, { upgrade(db) { db.createObjectStore('keys'); } }); let rawKey = await db.get('keys', credentialId); if (!rawKey) { rawKey = crypto.getRandomValues(new Uint8Array(32)); // Raw symmetric master key stored insecurely in client storage await db.put('keys', rawKey, credentialId); localStorage.setItem('has_key', 'true'); } return crypto.subtle.importKey( 'raw', rawKey, { name: 'AES-GCM', length: 256 }, true, // BAD: extractable is true ['encrypt', 'decrypt'] ); } ``` #### Production Standard (Correct) > **Standard**: The good example triggers an explicit hardware touch via WebAuthn Level 3 PRF extension with a 32-byte domain separation salt. The authenticator returns a hardware-derived secret, which is ingested into WebCrypto HKDF and expanded into a non-extractable AES-GCM CryptoKey. The raw PRF buffer is instantly scrubbed from memory, and the key cannot be exported or accessed across origins. ```typescript export interface HardwareKeyDerivationParams { credentialId: BufferSource; domainSalt: Uint8Array; // 32-byte server-provided domain separation salt derivationContext: string; // e.g., 'document-vault-aes-gcm-v1' } // PRODUCTION INVARIANT: Hardware-bound symmetric key derived directly via Authenticator PRF export async function deriveHardwareBoundKey({ credentialId, domainSalt, derivationContext }: HardwareKeyDerivationParams): Promise<CryptoKey> { if (domainSalt.byteLength < 32) { throw new Error('Security Violation: PRF salt must be at least 32 bytes.'); } // Request hardware authenticator evaluation via PRF Level 3 extension const credential = (await navigator.credentials.get({ publicKey: { challenge: crypto.getRandomValues(new Uint8Array(32)), allowCredentials: [{ id: credentialId, type: 'public-key' }], userVerification: 'required', extensions: { prf: { eval: { first: domainSalt } } } } })) as PublicKeyCredential | null; if (!credential) { throw new Error('Authenticator interaction failed or was cancelled.'); } const extensionResults = credential.getClientExtensionResults(); const prfResults = extensionResults.prf?.results; if (!prfResults?.first) { throw new Error('Authenticator does not support hardware PRF key derivation.'); } // Import PRF output as raw Initial Keying Material (IKM) for HKDF const prfRawBuffer = new Uint8Array(prfResults.first); const ikmKey = await crypto.subtle.importKey( 'raw', prfRawBuffer, 'HKDF', false, ['deriveKey'] ); // Zero out the raw PRF evaluation buffer in client memory immediately prfRawBuffer.fill(0); // Expand via HKDF-SHA-256 into a non-extractable AES-GCM cipher key const infoBuffer = new TextEncoder().encode(derivationContext); return crypto.subtle.deriveKey( { name: 'HKDF', hash: 'SHA-256', salt: domainSalt, info: infoBuffer }, ikmKey, { name: 'AES-GCM', length: 256 }, false, // INVARIANT: Non-extractable prevents runtime memory harvesting ['encrypt', 'decrypt'] ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Level 3 PRF Hardware-Bound Symmetric Key Derivation Standard

WebAuthn Level 3 PRF Hardware-Bound Symmetric Key Derivation Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict implementation standards for WebAuthn Level 3 Pseudo-Random Function (PRF) extension to derive hardware-bound symmetric encryption keys directly from FIDO2/passkey authenticators. Guarantees that sensitive application data cannot be decrypted from exfiltrated memory or stolen browser tokens without active physical presence and explicit hardware token interaction. Mandates secondary key derivation via HKDF with strict domain separation before any derived secret touches application memory. 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: Persisting Raw Symmetric Keys in Browser Storage or Exposing PRF Output Directly to Application State Without HKDF Domain 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	Persisting Raw Symmetric Keys in Browser Storage or Exposing PRF Output Directly to Application State Without HKDF Domain 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 support for WebAuthn PRF via `PublicKeyCredential.isConditionalMediationAvailable()` and `clientExtensionResults.prf` checks before initiating key derivation flows.

Engineers MUST ALWAYS verify client support for WebAuthn PRF via `PublicKeyCredential.isConditionalMediationAvailable()` and `clientExtensionResults.prf` checks before initiating key derivation flows.

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.