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-step-up-cryptographic-fence

WebAuthn Level 3 PRF Extension Cryptographic Step-Up Isolation

Enforces deterministic, hardware-bound cryptographic key derivation using WebAuthn Level 3 Pseudo-Random Function (PRF) extension during step-up challenges. Guarantees client-side decryption barriers that prevent cloud-synced passkey clones from decrypting sensitive data without an interactive, hardware-verified biometric assertion.

Prohibited Anti-Pattern: Trusting Synced Passkey Signatures for Data Access Without In-Authenticator PRF Key Derivation

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: WebAuthn Level 3 PRF Extension Cryptographic Step-Up Isolation - Enforces deterministic, hardware-bound cryptographic key derivation using WebAuthn Level 3 Pseudo-Random Function (PRF) extension during step-up challenges. Guarantees client-side decryption barriers that prevent cloud-synced passkey clones from decrypting sensitive data without an interactive, hardware-verified biometric assertion.
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-step-up-cryptographic-fence"
---

# WebAuthn Level 3 PRF Extension Cryptographic Step-Up Isolation

> **Severity**: CRITICAL | **Category**: security
> **Anti-Pattern Warning**: Trusting Synced Passkey Signatures for Data Access Without In-Authenticator PRF Key Derivation

## System Constraints
You are a Principal Security Architect enforcing the WebAuthn Level 3 PRF Extension Cryptographic Step-Up Fence. Passkeys synchronized across device clouds (e.g., Apple iCloud Keychain, Google Password Manager) expose silent replication risks if authentication signatures are equated with client-side decryption rights. You must mandate that cryptographic step-ups deterministically derive encryption keys via the authenticator's internal PRF (hmac-secret) evaluation. Raw PRF outputs must never be transmitted over the wire; all derivations must be piped into client-side Web Crypto primitives (HKDF/AES-GCM), enforce userVerification='required', and ensure memory zeroization of temporary buffers.

## Strict Guidelines
- Engineers MUST ALWAYS set `userVerification: 'required'` in `PublicKeyCredentialRequestOptions` when querying the PRF extension to force an active biometric or hardware PIN assertion.
- Engineers MUST NOT transmit raw PRF evaluation outputs (`prf.results.first`) or derived key bytes to backend servers under any circumstance; derived keys must strictly remain within client-side Web Crypto isolation.
- Engineers MUST enforce cryptographic separation using HKDF (RFC 5869) on the PRF output combined with an application-specific domain separator and challenge salt before initializing AES-GCM or ChaCha20-Poly1305 ciphers.
- Code MUST verify the presence of `results.extensions?.prf?.results?.first` and gracefully abort authentication workflows if the authenticator fails to return deterministic PRF material.
- Services MUST validate during passkey registration (`navigator.credentials.create`) that the credential explicitly acknowledged the `prf` extension capability before allowing enrollment into high-security fences.
- Components NEVER store derived step-up symmetric keys in persistent browser storage (`localStorage`, `IndexedDB`, `sessionStorage`); keys must be held strictly in ephemeral execution memory and dereferenced immediately post-operation.

## Bad vs Good Implementations
### Vulnerable vs Hardened WebAuthn Step-Up Decryption

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: This implementation uses standard assertion signatures and sets userVerification to 'preferred'. In a synced passkey ecosystem, any synced machine can create valid signatures, and sending authentication metadata to a backend to receive a key breaks end-to-end zero-knowledge security guarantees.
```typescript
// BAD: Relying purely on WebAuthn signature verification to authorize
// server-side or local decryption of sensitive data. Synced passkeys on a
// compromised secondary device can sign payloads without unlocking local secrets.
export async function unlockVault(credentialId: Uint8Array, challenge: Uint8Array): Promise<ArrayBuffer> {
  const credential = (await navigator.credentials.get({
    publicKey: {
      challenge,
      allowCredentials: [{
        id: credentialId,
        type: 'public-key'
      }],
      userVerification: 'preferred'
    }
  })) as PublicKeyCredential;

  // Security Vulnerability: Sending the raw credential assertion to the server
  // to fetch the plaintext vault data or master key.
  const response = await fetch('/api/vault/decrypt', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      id: credential.id,
      clientDataJSON: Array.from(new Uint8Array(credential.response.clientDataJSON)),
      signature: Array.from(new Uint8Array((credential.response as AuthenticatorAssertionResponse).signature))
    })
  });

  return response.arrayBuffer();
}
```

#### Production Standard (Correct)
> **Standard**: Enforces `userVerification: 'required'` and passes a high-entropy salt to `extensions.prf.eval.first`. Extracts the 32-byte secret evaluated strictly within the authenticator hardware, derives an ephemeral AES-GCM key via HKDF with domain separation, and performs zero-knowledge decryption entirely within Web Crypto memory.
```typescript
// GOOD: Level 3 PRF extension directly executes HMAC-SHA-256 inside the hardware authenticator.
// Keys are derived deterministically on-client and never leave the browser sandbox.
export async function unlockVaultWithPrfFence(
  credentialId: Uint8Array,
  challenge: Uint8Array,
  salt: Uint8Array,
  encryptedVaultPayload: Uint8Array,
  iv: Uint8Array
): Promise<ArrayBuffer> {
  const assertion = (await navigator.credentials.get({
    publicKey: {
      challenge,
      allowCredentials: [{
        id: credentialId,
        type: 'public-key',
        transports: ['internal', 'hybrid']
      }],
      userVerification: 'required',
      extensions: {
        prf: {
          eval: {
            first: salt
          }
        }
      }
    }
  })) as PublicKeyCredential;

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

  if (!prfResults) {
    throw new Error('Authenticator did not return deterministic PRF output. Step-up fence failed.');
  }

  // Import PRF output as raw keying material for HKDF derivation
  const rawPrfKey = await crypto.subtle.importKey(
    'raw',
    prfResults,
    { name: 'HKDF' },
    false,
    ['deriveKey']
  );

  // Derive AES-GCM symmetric decryption key with domain separation
  const info = new TextEncoder().encode('auth-step-up-fence-v1');
  const derivedKey = await crypto.subtle.deriveKey(
    {
      name: 'HKDF',
      hash: 'SHA-256',
      salt: challenge,
      info
    },
    rawPrfKey,
    { name: 'AES-GCM', length: 256 },
    false,
    ['decrypt']
  );

  // Decrypt locally: backend never sees plaintext or derived key
  return crypto.subtle.decrypt(
    { name: 'AES-GCM', iv },
    derivedKey,
    encryptedVaultPayload
  );
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

WebAuthn & FIDO2 Protocol Inspector
Inspects and verifies WebAuthn Level 3 client/authenticator extension negotiation, CBOR structures, and registration dictionaries.
Recommended Agent Skills (askills.dev)

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

FIDO2 / PRF Conformance Checker
CLI diagnostic utility for validating PRF extension compatibility across authenticators and client runtimes.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Level 3 PRF Extension Cryptographic Step-Up Isolation

WebAuthn Level 3 PRF Extension Cryptographic Step-Up Isolation defines an industrial-grade behavioral standard for security engineering. Enforces deterministic, hardware-bound cryptographic key derivation using WebAuthn Level 3 Pseudo-Random Function (PRF) extension during step-up challenges. Guarantees client-side decryption barriers that prevent cloud-synced passkey clones from decrypting sensitive data without an interactive, hardware-verified biometric assertion. 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: Trusting Synced Passkey Signatures for Data Access Without In-Authenticator PRF Key Derivation 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 DriftTrusting Synced Passkey Signatures for Data Access Without In-Authenticator PRF Key DerivationCritical
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 set `userVerification

Engineers MUST ALWAYS set `userVerification: 'required'` in `PublicKeyCredentialRequestOptions` when querying the PRF extension to force an active biometric or hardware PIN assertion.

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 transmit raw PRF evaluation outputs (`prf.results.first`) or derived key bytes to backend servers under any circumstance

Engineers MUST NOT transmit raw PRF evaluation outputs (`prf.results.first`) or derived key bytes to backend servers under any circumstance; derived keys must strictly remain within client-side Web Crypto isolation.

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 enforce cryptographic separation using HKDF (RFC 5869) on the PRF output combined with an application-specific domain separator and challenge salt before initializing AES-GCM or ChaCha20-Poly1305 ciphers.

Engineers MUST enforce cryptographic separation using HKDF (RFC 5869) on the PRF output combined with an application-specific domain separator and challenge salt before initializing AES-GCM or ChaCha20-Poly1305 ciphers.

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

Code MUST verify the presence of `results.extensions?.prf?.results?.first` and gracefully abort authentication workflows if the authenticator fails to return deterministic PRF material.

Code MUST verify the presence of `results.extensions?.prf?.results?.first` and gracefully abort authentication workflows if the authenticator fails to return deterministic PRF material.

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

Services MUST validate during passkey registration (`navigator.credentials.create`) that the credential explicitly acknowledged the `prf` extension capability before allowing enrollment into high-security fences.

Services MUST validate during passkey registration (`navigator.credentials.create`) that the credential explicitly acknowledged the `prf` extension capability before allowing enrollment into high-security fences.

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 step-up symmetric keys in persistent browser storage (`localStorage`, `IndexedDB`, `sessionStorage`)

Components NEVER store derived step-up symmetric keys in persistent browser storage (`localStorage`, `IndexedDB`, `sessionStorage`); keys must be held strictly in ephemeral execution memory and dereferenced immediately post-operation.

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 Level 3 PRF Extension Cryptographic Step-Up Isolation critical for AI coding assistants?

Enforces deterministic, hardware-bound cryptographic key derivation using WebAuthn Level 3 Pseudo-Random Function (PRF) extension during step-up challenges. Guarantees client-side decryption barriers that prevent cloud-synced passkey clones from decrypting sensitive data without an interactive, hardware-verified biometric assertion. 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 (Trusting Synced Passkey Signatures for Data Access Without In-Authenticator PRF Key Derivation) 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