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-client-e2ee-standard

Hardware Passkey PRF Extension Client-Side E2EE and Zero-Knowledge Key Derivation

Enforces strict client-side cryptographic invariants when deriving zero-knowledge symmetric keys from WebAuthn Pseudorandom Function (PRF) authenticator extensions. Mandates secondary HKDF key expansion with domain-separated salts, prevents raw PRF output exposure, and forbids any network transmission or unencrypted persistence of derived keying material.

Prohibited Anti-Pattern: Directly Utilizing Raw PRF Outputs as Symmetric Encryption Keys or Leaking Them to Remote Relying Parties

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Hardware Passkey PRF Extension Client-Side E2EE and Zero-Knowledge Key Derivation - Enforces strict client-side cryptographic invariants when deriving zero-knowledge symmetric keys from WebAuthn Pseudorandom Function (PRF) authenticator extensions. Mandates secondary HKDF key expansion with domain-separated salts, prevents raw PRF output exposure, and forbids any network transmission or unencrypted persistence of derived keying material.
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-prf-client-e2ee-standard"
---

# Hardware Passkey PRF Extension Client-Side E2EE and Zero-Knowledge Key Derivation

> **Severity**: CRITICAL | **Category**: security
> **Anti-Pattern Warning**: Directly Utilizing Raw PRF Outputs as Symmetric Encryption Keys or Leaking Them to Remote Relying Parties

## System Constraints
You are a Principal Security Architect enforcing the WebAuthn PRF (Pseudorandom Function) Extension Client-Side End-to-End Encryption Standard. You must mandate that raw PRF outputs are treated as ephemeral high-entropy secrets and never directly used as cipher keys, persisted, or sent across the network. All symmetric encryption keys must be derived locally via standard HKDF with explicit domain separation, nonces, and Web Crypto APIs (SubtleCrypto).

## Strict Guidelines
- Engineers MUST ALWAYS verify client and authenticator support for the `prf` extension via `PublicKeyCredential.getClientExtensionResults()` before requesting encryption operations.
- Engineers MUST NEVER send the derived PRF output (`first` or `second` buffers) or raw symmetric keys to the relying party or remote server.
- Engineers MUST ALWAYS pass the raw PRF output through HKDF (RFC 5869) using `crypto.subtle.deriveKey` or `crypto.subtle.deriveBits` with an application-specific salt and an unambiguous context `info` string (domain separation).
- Engineers MUST NEVER use the raw 32-byte PRF authenticator output directly as an AES-GCM or ChaCha20-Poly1305 key.
- Engineers MUST ALWAYS initialize the PRF input evaluation with a cryptographically secure, consistent 32-byte salt (`eval.first`) stored alongside encrypted records.
- Components NEVER store derived cryptographic CryptoKey objects or raw byte keys in persistent unencrypted browser storage such as `localStorage`, `sessionStorage`, or unencrypted IndexedDB.
- Services MUST explicitly clear sensitive Uint8Array buffers containing PRF inputs or outputs using `.fill(0)` immediately after key derivation.

## Bad vs Good Implementations
### Unsafe Direct PRF Key Use and Transmission vs. Zero-Knowledge HKDF Key Derivation

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Directly uses the raw PRF output without HKDF expansion, exposes the raw PRF secret over the network to the server (breaking zero-knowledge guarantees), and uses a weak, non-32-byte string for the PRF input salt.
```typescript
export async function unlockUserVault(credentialId: Uint8Array): Promise<CryptoKey> {
  // ANTI-PATTERN: Direct PRF usage, leaking secret to server, and missing HKDF expansion
  const assertion = await navigator.credentials.get({
    publicKey: {
      challenge: crypto.getRandomValues(new Uint8Array(32)),
      allowCredentials: [{ id: credentialId, type: 'public-key' }],
      extensions: {
        prf: {
          eval: { first: new TextEncoder().encode('vault-static-salt') }
        }
      }
    }
  }) as PublicKeyCredential;

  const extensionResults = assertion.getClientExtensionResults();
  const rawPrf = extensionResults.prf?.results?.first;
  if (!rawPrf) {
    throw new Error('Authenticator did not return PRF output');
  }

  // CRITICAL: Leaking PRF secret to the relying party server!
  await fetch('/api/vault/session', {
    method: 'POST',
    body: JSON.stringify({ prfSecret: Array.from(new Uint8Array(rawPrf)) })
  });

  // CRITICAL: Directly importing raw PRF output without HKDF domain separation
  return crypto.subtle.importKey(
    'raw',
    rawPrf,
    { name: 'AES-GCM' },
    false,
    ['encrypt', 'decrypt']
  );
}
```

#### Production Standard (Correct)
> **Standard**: Validates the 32-byte PRF input, never transmits the authenticator secret to any server, derives the symmetric key using HKDF with strict domain separation, sets keys to non-extractable (`extractable: false`), and securely zeroes memory buffers.
```typescript
export async function deriveVaultKeyWithPrf(
  credentialId: Uint8Array,
  storedPrfSalt: Uint8Array,
  vaultId: string
): Promise<CryptoKey> {
  if (storedPrfSalt.byteLength !== 32) {
    throw new RangeError('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' }],
      extensions: {
        prf: {
          eval: { first: storedPrfSalt }
        }
      }
    }
  }) as PublicKeyCredential | null;

  if (!assertion) {
    throw new Error('Passkey assertion failed or was cancelled.');
  }

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

  if (!prfResult) {
    throw new Error('PRF extension evaluation unavailable or unsupported by authenticator.');
  }

  const rawPrfBuffer = new Uint8Array(prfResult);

  try {
    // Import raw PRF output into Web Crypto as an ephemeral HKDF master key
    const prfMasterKey = await crypto.subtle.importKey(
      'raw',
      rawPrfBuffer,
      { name: 'HKDF' },
      false,
      ['deriveKey']
    );

    const info = new TextEncoder().encode(`e2ee-vault-encryption-v1:${vaultId}`);
    const hkdfSalt = new Uint8Array(32); // Domain separation salt for HKDF

    // Derive a dedicated AES-GCM 256-bit key using HKDF (RFC 5869)
    return await crypto.subtle.deriveKey(
      {
        name: 'HKDF',
        hash: 'SHA-256',
        salt: hkdfSalt,
        info
      },
      prfMasterKey,
      { name: 'AES-GCM', length: 256 },
      false,
      ['encrypt', 'decrypt']
    );
  } finally {
    // Secure zeroing of transient plaintext PRF buffer
    rawPrfBuffer.fill(0);
  }
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

WebAuthn & Cryptography Inspector
Validates WebAuthn client extension payloads, authenticator data flags, and WebCrypto key configurations.
Recommended Agent Skills (askills.dev)

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

SubtleCrypto & Passkey Static Auditor
Static analysis CLI tool that flags insecure PRF key imports, unscrubbed buffers, and credential leaking.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware Passkey PRF Extension Client-Side E2EE and Zero-Knowledge Key Derivation

Hardware Passkey PRF Extension Client-Side E2EE and Zero-Knowledge Key Derivation defines an industrial-grade behavioral standard for security engineering. Enforces strict client-side cryptographic invariants when deriving zero-knowledge symmetric keys from WebAuthn Pseudorandom Function (PRF) authenticator extensions. Mandates secondary HKDF key expansion with domain-separated salts, prevents raw PRF output exposure, and forbids any network transmission or unencrypted persistence of derived keying material. 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 Utilizing Raw PRF Outputs as Symmetric Encryption Keys or Leaking Them to Remote Relying Parties 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 DriftDirectly Utilizing Raw PRF Outputs as Symmetric Encryption Keys or Leaking Them to Remote Relying PartiesCritical
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 and authenticator support for the `prf` extension via `PublicKeyCredential.getClientExtensionResults()` before requesting encryption operations.

Engineers MUST ALWAYS verify client and authenticator support for the `prf` extension via `PublicKeyCredential.getClientExtensionResults()` before requesting encryption operations.

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 send the derived PRF output (`first` or `second` buffers) or raw symmetric keys to the relying party or remote server.

Engineers MUST NEVER send the derived PRF output (`first` or `second` buffers) or raw symmetric keys to the relying party or remote server.

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 pass the raw PRF output through HKDF (RFC 5869) using `crypto.subtle.deriveKey` or `crypto.subtle.deriveBits` with an application-specific salt and an unambiguous context `info` string (domain separation).

Engineers MUST ALWAYS pass the raw PRF output through HKDF (RFC 5869) using `crypto.subtle.deriveKey` or `crypto.subtle.deriveBits` with an application-specific salt and an unambiguous context `info` string (domain separation).

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

Engineers MUST NEVER use the raw 32-byte PRF authenticator output directly as an AES-GCM or ChaCha20-Poly1305 key.

Engineers MUST NEVER use the raw 32-byte PRF authenticator output directly as an AES-GCM or ChaCha20-Poly1305 key.

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

Engineers MUST ALWAYS initialize the PRF input evaluation with a cryptographically secure, consistent 32-byte salt (`eval.first`) stored alongside encrypted records.

Engineers MUST ALWAYS initialize the PRF input evaluation with a cryptographically secure, consistent 32-byte salt (`eval.first`) stored alongside encrypted records.

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 store derived cryptographic CryptoKey objects or raw byte keys in persistent unencrypted browser storage such as `localStorage`, `sessionStorage`, or unencrypted IndexedDB.

Components NEVER store derived cryptographic CryptoKey objects or raw byte keys in persistent unencrypted browser storage such as `localStorage`, `sessionStorage`, or unencrypted IndexedDB.

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.
7

Services MUST explicitly clear sensitive Uint8Array buffers containing PRF inputs or outputs using `.fill(0)` immediately after key derivation.

Services MUST explicitly clear sensitive Uint8Array buffers containing PRF inputs or outputs using `.fill(0)` immediately after 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.
Technical Questions & Answers

Frequently Asked Technical Questions

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

Q:Why is Hardware Passkey PRF Extension Client-Side E2EE and Zero-Knowledge Key Derivation critical for AI coding assistants?

Enforces strict client-side cryptographic invariants when deriving zero-knowledge symmetric keys from WebAuthn Pseudorandom Function (PRF) authenticator extensions. Mandates secondary HKDF key expansion with domain-separated salts, prevents raw PRF output exposure, and forbids any network transmission or unencrypted persistence of derived keying material. 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 (Directly Utilizing Raw PRF Outputs as Symmetric Encryption Keys or Leaking Them to Remote Relying Parties) 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

Hardware