WebAuthn Level 3 PRF Extension & Passkey Session Binding Guardrail

--- description: WebAuthn Level 3 PRF Extension & Passkey Session Binding Guardrail - Enforces strict validation of WebAuthn Level 3 pseudo-random function (prf) extension outputs and exact SHA-256 clientDataJSON hash assertions during passkey authentication. Prevents session hijacking, credential substitution, and authenticator desynchronization by deterministically binding server-side session tokens to hardware-derived PRF symmetric keys. globs: src/auth/**/*.{ts,tsx}, src/server/auth/**/*.{ts,tsx}, src/lib/webauthn/**/*.{ts,tsx}, src/services/passkey/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-prf-extension-binding-standard" --- # WebAuthn Level 3 PRF Extension & Passkey Session Binding Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Trusting unverified authenticator extension outputs and skipping raw clientDataHash cryptographic verification ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Level 3 PRF (Pseudo-Random Function) Extension and strict passkey session binding standards. You must ensure that authentication ceremonies cryptographically bind sessions using clientDataJSON hashes, verify the authenticator data flags (UP, UV, ED), and extract or evaluate PRF evaluation outputs with constant-time cryptographic primitives. Reject any implementation relying solely on unauthenticated client inputs, incomplete signature verification, or missing extension verification. ## Strict Guidelines - Engineers MUST ALWAYS compute the SHA-256 digest of raw clientDataJSON locally and verify equality against clientDataHash within the authenticator signature assertion. - Engineers MUST ALWAYS verify the authenticatorData flags, ensuring User Present (UP, bit 0) and User Verified (UV, bit 2) are set to 1 when UV is mandated by server policy. - Services MUST verify Extension Data (ED, bit 7) in authData before attempting to parse extension outputs, failing the ceremony if the PRF extension is requested but ED bit is unset. - Engineers MUST NEVER accept client-reported PRF evaluation values directly over the wire without deriving or validating against the deterministic salt passed in clientExtensionResults. - Engineers MUST ALWAYS use timing-safe comparison primitives (e.g., crypto.timingSafeEqual) when asserting challenges, expected origins, and derived session keys to prevent side-channel timing attacks. - Services MUST bind the authenticated session identifier deterministically to a HKDF expansion of the verified PRF output and ephemeral server salt to render stolen session cookies inert without the physical authenticator. ## Bad vs Good Implementations ### Verifying WebAuthn L3 PRF Extension and Authenticator Assertion #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code blindly accepts untrusted client data without computing SHA-256 clientDataHash, fails to verify authenticatorData flags (UP, UV, ED bit 7 for extension data), trusts client-supplied PRF results without cryptographic signature validation, and lacks timing-safe verification. ```typescript import { Request, Response } from 'express'; export async function verifyAssertion(req: Request, res: Response) { const { id, rawId, response } = req.body; // Flaw 1: Blindly parsing clientDataJSON without hashing or checking challenge in constant time const clientData = JSON.parse(Buffer.from(response.clientDataJSON, 'base64').toString('utf8')); if (clientData.type !== 'webauthn.get') { return res.status(400).send('Invalid type'); } // Flaw 2: Directly trusting unverified PRF output sent by client const prfResult = response.clientExtensionResults?.prf?.results?.first; if (!prfResult) { return res.status(400).send('Missing PRF'); } // Flaw 3: Session created without validating authData flags (UP/UV/ED) or binding to PRF req.session.userId = req.body.userId; return res.json({ success: true }); } ``` #### Production Standard (Correct) > **Standard**: Correctly parses authenticatorData flags using bitwise operations to assert User Presence (bit 0), User Verification (bit 2), and Extension Data presence (bit 7). Validates assertion signatures via standard WebAuthn cryptographic primitives, recomputes the SHA-256 clientDataJSON hash, and validates that PRF outputs are 32-byte cryptographically derived buffers. ```typescript import { createHash, timingSafeEqual } from 'node:crypto'; import type { AuthenticationResponseJSON } from '@simplewebauthn/types'; import { verifyAuthenticationResponse } from '@simplewebauthn/server'; interface SessionBindingInput { response: AuthenticationResponseJSON; expectedChallenge: string; expectedOrigin: string; expectedRPID: string; storedPublicKey: Uint8Array; storedSignCount: number; } export async function verifyAssertionAndBindPrf({ response, expectedChallenge, expectedOrigin, expectedRPID, storedPublicKey, storedSignCount }: SessionBindingInput) { const clientDataJSONBuffer = Buffer.from(response.response.clientDataJSON, 'base64url'); const computedClientDataHash = createHash('sha256').update(clientDataJSONBuffer).digest(); const authDataBuffer = Buffer.from(response.response.authenticatorData, 'base64url'); const flags = authDataBuffer[32]; const isUp = (flags & 0x01) !== 0; const isUv = (flags & 0x04) !== 0; const hasExtensions = (flags & 0x80) !== 0; if (!isUp || !isUv || !hasExtensions) { throw new Error('Authenticator policy violation: UP, UV, and ED flags required'); } const verification = await verifyAuthenticationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID, credential: { id: response.id, publicKey: storedPublicKey, counter: storedSignCount }, requireUserVerification: true }); if (!verification.verified || !verification.authenticationInfo) { throw new Error('WebAuthn cryptographic assertion verification failed'); } const prfExtension = response.clientExtensionResults?.prf; if (!prfExtension?.results?.first) { throw new Error('Authenticator failed to return Level 3 PRF extension output'); } const prfOutputBuffer = Buffer.from(prfExtension.results.first, 'base64url'); if (prfOutputBuffer.length !== 32) { throw new Error('Invalid PRF output length; expected 32 bytes'); } return { verified: true, newCounter: verification.authenticationInfo.newCounter, prfKeySeed: prfOutputBuffer, clientDataHash: computedClientDataHash }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Level 3 PRF Extension & Passkey Session Binding Guardrail

WebAuthn Level 3 PRF Extension & Passkey Session Binding Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces strict validation of WebAuthn Level 3 pseudo-random function (prf) extension outputs and exact SHA-256 clientDataJSON hash assertions during passkey authentication. Prevents session hijacking, credential substitution, and authenticator desynchronization by deterministically binding server-side session tokens to hardware-derived PRF symmetric keys. 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 unverified authenticator extension outputs and skipping raw clientDataHash cryptographic verification 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	Trusting unverified authenticator extension outputs and skipping raw clientDataHash cryptographic verification	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 compute the SHA-256 digest of raw clientDataJSON locally and verify equality against clientDataHash within the authenticator signature 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.