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-deterministic-key-derivation-boundary

WebAuthn PRF Extension Deterministic Cryptographic Boundary Standard

Enforces strict cryptographic domain separation and ephemeral memory isolation when deriving client-side keys via the WebAuthn Pseudo-Random Function (PRF) extension. Raw PRF outputs must strictly serve as Input Keying Material (IKM) to an authenticated HKDF pipeline and must never be used directly as symmetric ciphers or persisted to unencrypted client storage.

Prohibited Anti-Pattern: Direct Symmetric Cipher Instantiation or Persistence of Raw WebAuthn PRF Evaluator Outputs

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: WebAuthn PRF Extension Deterministic Cryptographic Boundary Standard - Enforces strict cryptographic domain separation and ephemeral memory isolation when deriving client-side keys via the WebAuthn Pseudo-Random Function (PRF) extension. Raw PRF outputs must strictly serve as Input Keying Material (IKM) to an authenticated HKDF pipeline and must never be used directly as symmetric ciphers or persisted to unencrypted client storage.
globs: src/**/*.{ts,tsx,js,jsx}, lib/**/*.{ts,tsx}, packages/**/*.{ts,tsx}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/webauthn-prf-deterministic-key-derivation-boundary"
---

# WebAuthn PRF Extension Deterministic Cryptographic Boundary Standard

> **Severity**: CRITICAL | **Category**: security
> **Anti-Pattern Warning**: Direct Symmetric Cipher Instantiation or Persistence of Raw WebAuthn PRF Evaluator Outputs

## System Constraints
You are a Principal Security Architect enforcing the WebAuthn PRF Extension Deterministic Key Derivation Boundary. You must ensure that raw PRF outputs emitted by authenticators are treated exclusively as ephemeral Input Keying Material (IKM) inside zero-knowledge architectures. Mandate strict HKDF domain separation, prohibit raw output persistence, enforce zeroization of intermediate byte buffers, and ensure that no hardware-derived master secrets or unmasked PRF evaluation results escape client-side memory or touch backend telemetry.

## Strict Guidelines
- Engineers MUST ALWAYS treat WebAuthn PRF extension results (`AuthenticationExtensionsClientOutputs.prf.results.first`) strictly as Input Keying Material (IKM) fed into HKDF (RFC 5869) or equivalent KDFs.
- Engineers MUST NOT use raw PRF evaluation outputs directly as symmetric encryption keys (e.g., raw AES-GCM or ChaCha20-Poly1305 keys) without context-specific derivation.
- Code MUST supply explicit, globally unique domain separation strings in the HKDF `info` parameter (e.g., `application-e2ee-vault-v1:user-encryption`) to prevent cross-protocol collision attacks.
- Services and client runtimes MUST NEVER serialize or persist raw PRF outputs, authenticator secrets, or derived IKM into `localStorage`, `sessionStorage`, IndexedDB, cookies, or logs.
- Components MUST explicitly zeroize (overwrite with zeros) intermediate `Uint8Array` buffers containing raw PRF evaluations immediately after key derivation completes.
- Code SHOULD verify the presence of the PRF extension capability during `navigator.credentials.create` and fail closed if the authenticator does not support hardware PRF evaluation.

## Bad vs Good Implementations
### WebAuthn PRF Key Derivation Pipeline

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Directly uses the authenticator PRF output as an AES-GCM key without HKDF domain separation, leaks the raw key to `sessionStorage`, and marks the resulting `CryptoKey` as extractable, exposing the client-side master secret.
```typescript
export async function deriveVaultKey(assertion: PublicKeyCredential): Promise<CryptoKey> {
  const results = assertion.getClientExtensionResults();
  // VULNERABILITY: Raw PRF output used directly as an AES key without HKDF expansion
  const rawPrf = results.prf?.results?.first;
  if (!rawPrf) throw new Error('PRF failed');

  // VULNERABILITY: Persisting hardware-derived secret in unencrypted storage
  sessionStorage.setItem('raw_key', Buffer.from(rawPrf).toString('hex'));

  return crypto.subtle.importKey(
    'raw',
    rawPrf,
    { name: 'AES-GCM', length: 256 },
    true, // VULNERABILITY: Key is marked extractable
    ['encrypt', 'decrypt']
  );
}
```

#### Production Standard (Correct)
> **Standard**: Treats the PRF evaluation strictly as non-extractable HKDF Input Keying Material (IKM), enforces domain separation via explicit application info strings, derives a non-extractable AES-GCM key, and wipes intermediate memory buffers via zeroization in a `finally` block.
```typescript
const PRF_DOMAIN_INFO = new TextEncoder().encode('org.zeroknowledge.vault.encryption.v1');

export async function deriveVaultKey(
  assertion: PublicKeyCredential,
  domainSalt: Uint8Array
): Promise<CryptoKey> {
  const results = assertion.getClientExtensionResults();
  const rawPrfBuffer = results.prf?.results?.first;
  if (!rawPrfBuffer) {
    throw new Error('Authenticator did not return deterministic PRF evaluation.');
  }

  const ikmView = new Uint8Array(rawPrfBuffer);
  try {
    // Import PRF output as IKM into Web Crypto HKDF boundary
    const ikmKey = await crypto.subtle.importKey(
      'raw',
      ikmView,
      'HKDF',
      false,
      ['deriveKey']
    );

    // Deterministically expand to non-extractable AES-GCM key with domain separation
    return await crypto.subtle.deriveKey(
      {
        name: 'HKDF',
        hash: 'SHA-256',
        salt: domainSalt,
        info: PRF_DOMAIN_INFO,
      },
      ikmKey,
      { name: 'AES-GCM', length: 256 },
      false,
      ['encrypt', 'decrypt']
    );
  } finally {
    // Ensure intermediate byte buffers are zeroized from memory
    ikmView.fill(0);
  }
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

Semgrep Security Analyzer MCP
Static application security testing to detect improper Web Crypto and WebAuthn extension usage.
Recommended Agent Skills (askills.dev)

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

WebAuthn PRF Security Linter
Validates client credential options and ensures PRF extension evaluations adhere to deterministic zero-knowledge boundaries.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn PRF Extension Deterministic Cryptographic Boundary Standard

WebAuthn PRF Extension Deterministic Cryptographic Boundary Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict cryptographic domain separation and ephemeral memory isolation when deriving client-side keys via the WebAuthn Pseudo-Random Function (PRF) extension. Raw PRF outputs must strictly serve as Input Keying Material (IKM) to an authenticated HKDF pipeline and must never be used directly as symmetric ciphers or persisted to unencrypted client storage. 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: Direct Symmetric Cipher Instantiation or Persistence of Raw WebAuthn PRF Evaluator Outputs 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 DriftDirect Symmetric Cipher Instantiation or Persistence of Raw WebAuthn PRF Evaluator OutputsCritical
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 treat WebAuthn PRF extension results (`AuthenticationExtensionsClientOutputs.prf.results.first`) strictly as Input Keying Material (IKM) fed into HKDF (RFC 5869) or equivalent KDFs.

Engineers MUST ALWAYS treat WebAuthn PRF extension results (`AuthenticationExtensionsClientOutputs.prf.results.first`) strictly as Input Keying Material (IKM) fed into HKDF (RFC 5869) or equivalent KDFs.

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 NOT use raw PRF evaluation outputs directly as symmetric encryption keys (e.g., raw AES-GCM or ChaCha20-Poly1305 keys) without context-specific derivation.

Engineers MUST NOT use raw PRF evaluation outputs directly as symmetric encryption keys (e.g., raw AES-GCM or ChaCha20-Poly1305 keys) without context-specific 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.
3

Code MUST supply explicit, globally unique domain separation strings in the HKDF `info` parameter (e.g., `application-e2ee-vault-v1

Code MUST supply explicit, globally unique domain separation strings in the HKDF `info` parameter (e.g., `application-e2ee-vault-v1:user-encryption`) to prevent cross-protocol collision attacks.

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 and client runtimes MUST NEVER serialize or persist raw PRF outputs, authenticator secrets, or derived IKM into `localStorage`, `sessionStorage`, IndexedDB, cookies, or logs.

Services and client runtimes MUST NEVER serialize or persist raw PRF outputs, authenticator secrets, or derived IKM into `localStorage`, `sessionStorage`, IndexedDB, cookies, or 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.
5

Components MUST explicitly zeroize (overwrite with zeros) intermediate `Uint8Array` buffers containing raw PRF evaluations immediately after key derivation completes.

Components MUST explicitly zeroize (overwrite with zeros) intermediate `Uint8Array` buffers containing raw PRF evaluations immediately after key derivation completes.

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

Code SHOULD verify the presence of the PRF extension capability during `navigator.credentials.create` and fail closed if the authenticator does not support hardware PRF evaluation.

Code SHOULD verify the presence of the PRF extension capability during `navigator.credentials.create` and fail closed if the authenticator does not support hardware PRF evaluation.

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 WebAuthn PRF Extension Deterministic Cryptographic Boundary Standard critical for AI coding assistants?

Enforces strict cryptographic domain separation and ephemeral memory isolation when deriving client-side keys via the WebAuthn Pseudo-Random Function (PRF) extension. Raw PRF outputs must strictly serve as Input Keying Material (IKM) to an authenticated HKDF pipeline and must never be used directly as symmetric ciphers or persisted to unencrypted client storage. 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 (Direct Symmetric Cipher Instantiation or Persistence of Raw WebAuthn PRF Evaluator Outputs) 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

WebAuthn