AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
securitycritical PriorityID: webauthn-prf-zk-e2ee-key-derivation-standard-webauthn-prf-ext-890

Zero-Knowledge Hardware-Bound Key Derivation via WebAuthn PRF Extension

Enforces cryptographically isolated, client-side encryption key derivation directly from hardware authenticators using the WebAuthn Pseudo-Random Function (PRF) extension (HMAC-secret). Guarantees zero-knowledge end-to-end encryption by ensuring symmetric key material is derived via HKDF from PRF outputs using application-scoped salts and never leaves client volatile memory unencrypted.

Prohibited Anti-Pattern: Deriving E2EE Keys from WebAuthn Signatures, Raw Challenge Hashes, or Storing Unwrapped Master Keys Server-Side

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Zero-Knowledge Hardware-Bound Key Derivation via WebAuthn PRF Extension - Enforces cryptographically isolated, client-side encryption key derivation directly from hardware authenticators using the WebAuthn Pseudo-Random Function (PRF) extension (HMAC-secret). Guarantees zero-knowledge end-to-end encryption by ensuring symmetric key material is derived via HKDF from PRF outputs using application-scoped salts and never leaves client volatile memory unencrypted.
globs: src/lib/crypto/**/*.{ts,tsx}, src/features/auth/**/*.{ts,tsx}, src/services/vault/**/*.{ts,tsx}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/webauthn-prf-zk-e2ee-key-derivation-standard-webauthn-prf-ext-890"
---

# Zero-Knowledge Hardware-Bound Key Derivation via WebAuthn PRF Extension

> **Severity**: CRITICAL | **Category**: security
> **Anti-Pattern Warning**: Deriving E2EE Keys from WebAuthn Signatures, Raw Challenge Hashes, or Storing Unwrapped Master Keys Server-Side

## System Constraints
You are a Principal Security Architect enforcing zero-knowledge hardware-backed key derivation standards. You must ensure developers use the W3C WebAuthn PRF (HMAC-Secret) extension strictly within Web Crypto API contexts, isolating symmetric master keys from network transmission and ensuring deterministic derivation across platforms using RFC 5869 HKDF.

## Strict Guidelines
- Engineers MUST ALWAYS verify client support for WebAuthn PRF extension via `PublicKeyCredential.getClientCapabilities()` or evaluation of `credential.getClientExtensionResults().prf` before executing key derivation.
- Engineers MUST NEVER use authenticator signatures (`authenticatorData` + `clientDataJSON` ECDSA/Ed25519 signatures) as key derivation material, as digital signatures lack non-deterministic secrecy and may leak keying material through signature malleability or audit logs.
- Engineers MUST ALWAYS feed the 32-byte WebAuthn PRF raw output (`results.prf.results.first`) into RFC 5869 HKDF-Expand (or HKDF-Extract-and-Expand) using a cryptographically random, versioned, application-specific `info` string and distinct salt.
- Services MUST NEVER transmit or store the raw PRF evaluation inputs (when static), derived symmetric keys (e.g., AES-256-GCM), or unwrapped data encryption keys (DEKs) to the server or any non-volatile client storage without encryption.
- Code MUST strictly encapsulate PRF outputs in non-exportable `CryptoKey` structures using the Web Crypto API (`window.crypto.subtle.importKey`) with `extractable: false` whenever supported by the runtime target.
- Components NEVER execute PRF key derivation on the main thread without handling user cancellation (`NotAllowedError`) and authenticator fallback degradation pathways securely.

## Bad vs Good Implementations
### Deriving AES-GCM-256 Vault Encryption Key via WebAuthn PRF Extension

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Derives encryption keys from an authenticator signature rather than the PRF extension. Signatures are transmitted across the wire, verifiable by third parties, non-secret, and malleable, nullifying all zero-knowledge guarantees.
```typescript
export async function deriveVaultKey(credentialId: string): Promise<CryptoKey> {
  // Anti-Pattern: Using authentication signature as keying material
  const assertion = await navigator.credentials.get({
    publicKey: {
      challenge: new Uint8Array([1, 2, 3, 4]),
      allowCredentials: [{ id: Uint8Array.from(atob(credentialId), c => c.charCodeAt(0)), type: 'public-key' }]
    }
  }) as PublicKeyCredential;

  const response = assertion.response as AuthenticatorAssertionResponse;
  // Flaw: Signature is public, verifiable by the server, and malleable. Zero-knowledge is completely broken.
  const rawKeyMaterial = new Uint8Array(response.signature);
  
  return window.crypto.subtle.importKey(
    'raw',
    rawKeyMaterial.slice(0, 32),
    { name: 'AES-GCM' },
    true, // Flaw: extractable
    ['encrypt', 'decrypt']
  );
}
```

#### Production Standard (Correct)
> **Standard**: Correctly invokes the WebAuthn PRF extension, checks client extension execution, and feeds the resulting high-entropy hardware secret through WebCrypto HKDF to derive an unextractable AES-GCM-256 key without disclosing secret material to the server.
```typescript
export async function deriveHardwareBoundVaultKey(
  credentialId: Uint8Array,
  salt: Uint8Array,
  contextInfo: string
): Promise<CryptoKey> {
  if (salt.byteLength < 32) {
    throw new Error('Salt must be at least 32 bytes of cryptographically secure random entropy');
  }

  const assertion = await navigator.credentials.get({
    publicKey: {
      challenge: window.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('WebAuthn assertion failed or was aborted');
  }

  const extensionResults = assertion.getClientExtensionResults();
  const prfOutput = extensionResults.prf?.results?.first;

  if (!prfOutput) {
    throw new Error('Hardware authenticator does not support or grant PRF extension capability');
  }

  // Import PRF output as raw IKM into WebCrypto
  const prfKeyMaterial = await window.crypto.subtle.importKey(
    'raw',
    prfOutput,
    { name: 'HKDF' },
    false,
    ['deriveKey']
  );

  // Derive isolated AES-GCM-256 Vault Encryption Key via HKDF-Expand
  const encoder = new TextEncoder();
  return window.crypto.subtle.deriveKey(
    {
      name: 'HKDF',
      hash: 'SHA-256',
      salt: new Uint8Array(32), // Salt already injected into PRF evaluation
      info: encoder.encode(contextInfo)
    },
    prfKeyMaterial,
    { name: 'AES-GCM', length: 256 },
    false,
    ['encrypt', 'decrypt']
  );
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

WebAuthn & Cryptography Inspector MCP
Validates CBOR extensions, PRF outputs, and client capability assertions in end-to-end WebAuthn test suites.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Cryptographic Protocol Auditor
Verifies HKDF expansions, entropy distributions, and RFC compliance for zero-knowledge key derivations.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Zero-Knowledge Hardware-Bound Key Derivation via WebAuthn PRF Extension

Zero-Knowledge Hardware-Bound Key Derivation via WebAuthn PRF Extension defines an industrial-grade behavioral standard for security engineering. Enforces cryptographically isolated, client-side encryption key derivation directly from hardware authenticators using the WebAuthn Pseudo-Random Function (PRF) extension (HMAC-secret). Guarantees zero-knowledge end-to-end encryption by ensuring symmetric key material is derived via HKDF from PRF outputs using application-scoped salts and never leaves client volatile memory unencrypted. 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 Keys from WebAuthn Signatures, Raw Challenge Hashes, or Storing Unwrapped Master Keys Server-Side 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftDeriving E2EE Keys from WebAuthn Signatures, Raw Challenge Hashes, or Storing Unwrapped Master Keys Server-SideCritical
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 InconsistencyAI 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:

1

Engineers MUST ALWAYS verify client support for WebAuthn PRF extension via `PublicKeyCredential.getClientCapabilities()` or evaluation of `credential.getClientExtensionResults().prf` before executing key derivation.

Engineers MUST ALWAYS verify client support for WebAuthn PRF extension via `PublicKeyCredential.getClientCapabilities()` or evaluation of `credential.getClientExtensionResults().prf` before executing key derivation.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST NEVER use authenticator signatures (`authenticatorData` + `clientDataJSON` ECDSA/Ed25519 signatures) as key derivation material, as digital signatures lack non-deterministic secrecy and may leak keying material through signature malleability or audit logs.

Engineers MUST NEVER use authenticator signatures (`authenticatorData` + `clientDataJSON` ECDSA/Ed25519 signatures) as key derivation material, as digital signatures lack non-deterministic secrecy and may leak keying material through signature malleability or audit logs.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Engineers MUST ALWAYS feed the 32-byte WebAuthn PRF raw output (`results.prf.results.first`) into RFC 5869 HKDF-Expand (or HKDF-Extract-and-Expand) using a cryptographically random, versioned, application-specific `info` string and distinct salt.

Engineers MUST ALWAYS feed the 32-byte WebAuthn PRF raw output (`results.prf.results.first`) into RFC 5869 HKDF-Expand (or HKDF-Extract-and-Expand) using a cryptographically random, versioned, application-specific `info` string and distinct salt.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Services MUST NEVER transmit or store the raw PRF evaluation inputs (when static), derived symmetric keys (e.g., AES-256-GCM), or unwrapped data encryption keys (DEKs) to the server or any non-volatile client storage without encryption.

Services MUST NEVER transmit or store the raw PRF evaluation inputs (when static), derived symmetric keys (e.g., AES-256-GCM), or unwrapped data encryption keys (DEKs) to the server or any non-volatile client storage without encryption.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Code MUST strictly encapsulate PRF outputs in non-exportable `CryptoKey` structures using the Web Crypto API (`window.crypto.subtle.importKey`) with `extractable

Code MUST strictly encapsulate PRF outputs in non-exportable `CryptoKey` structures using the Web Crypto API (`window.crypto.subtle.importKey`) with `extractable: false` whenever supported by the runtime target.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
6

Components NEVER execute PRF key derivation on the main thread without handling user cancellation (`NotAllowedError`) and authenticator fallback degradation pathways securely.

Components NEVER execute PRF key derivation on the main thread without handling user cancellation (`NotAllowedError`) and authenticator fallback degradation pathways securely.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Zero-Knowledge Hardware-Bound Key Derivation via WebAuthn PRF Extension critical for AI coding assistants?

Enforces cryptographically isolated, client-side encryption key derivation directly from hardware authenticators using the WebAuthn Pseudo-Random Function (PRF) extension (HMAC-secret). Guarantees zero-knowledge end-to-end encryption by ensuring symmetric key material is derived via HKDF from PRF outputs using application-scoped salts and never leaves client volatile memory unencrypted. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Deriving E2EE Keys from WebAuthn Signatures, Raw Challenge Hashes, or Storing Unwrapped Master Keys Server-Side) 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.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related SECURITY Rules

View all rules →
security
105

OpenFGA Graph Invariants: Cyclic Relation Prevention & Contextual Tuple Hardening

Enforces strict directed acyclic graph (DAG) topology validation during relationship mutation writes and mandates strict server-side schema verification for ephemeral contextual tuples in OpenFGA evaluations. Prohibits persistent storage of ephemeral request attributes and guards against recursive relation loops causing graph expansion denial-of-service.

security
81

WebAuthn Conditional UI Mediation, Nonce Atomicity, and Assertion Cryptographic Verification

Enforces zero-trust cryptographic validation for FIDO2/WebAuthn Passkey authentication with Conditional UI autofill. Requires atomic single-use challenge consumption to eliminate replay attacks, strict RP ID hash and origin binding, authenticatorData flag verification (User Presence and User Verification), and monotonic signature counter enforcement to detect authenticator cloning.

security
111

Enforce Sigstore Keyless OIDC Attestation and Admission Controller Verification

Enforces immutable supply-chain security using Sigstore Cosign keyless signing via ephemeral OIDC tokens issued by Fulcio and verified against the Rekor transparency log. Container workloads must be signed and attested at build time by digest, and admission controllers (such as Kyverno or Sigstore Policy Controller) must strictly validate the OIDC issuer and subject identity before allowing image execution.

1 Rule in Stack

Zero-Knowledge