WebAuthn Passkey Cryptographic Origin & Nonce Assertion Invariant

--- description: WebAuthn Passkey Cryptographic Origin & Nonce Assertion Invariant - Defends against real-time adversary-in-the-middle (AiTM) reverse proxy phishing and replay attacks by enforcing cryptographic clientDataJSON origin validation and atomic single-use nonce consumption. WebAuthn assertions must strictly validate the fully-qualified canonical origin, rely on atomic get-and-delete challenge storage, and enforce user verification invariants. globs: src/**/auth/**/*.ts, src/**/webauthn/**/*.ts, server/**/auth/**/*.ts, packages/**/auth/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-origin-nonce-assertion-invariant" --- # WebAuthn Passkey Cryptographic Origin & Nonce Assertion Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permissive Origin Matching and Non-Atomic Challenge Consumption in WebAuthn Verification ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Passkey Cryptographic Origin & Nonce Assertion Invariant. Mandate absolute cryptographic verification of FIDO2/WebAuthn assertions. Never permit regex, suffix, or substring validation on clientDataJSON.origin. Enforce atomic, single-use challenge consumption (e.g., Redis GETDEL) to eradicate replay and concurrency race exploits. Require user verification and signature counter monotonicity. ## Strict Guidelines - Engineers MUST ALWAYS enforce exact string matching against an immutable whitelist of canonical origins including protocol, host, and port (RFC 6454). - Engineers MUST NOT use regular expressions, wildcard suffix checks (e.g., endsWith), or substring matching (e.g., includes) when validating clientDataJSON.origin. - Services MUST atomically retrieve and delete challenge nonces in a single transactional step (e.g., Redis GETDEL or SQL SELECT FOR UPDATE + DELETE) before signature verification to prevent replay races. - Code SHOULD verify that clientDataJSON.type strictly equals 'webauthn.get' for authentication ceremonies and 'webauthn.create' for registration ceremonies. - Components NEVER accept authentication assertions with clientDataJSON challenges that have zero TTL enforcement or were generated without cryptographically secure pseudorandom number generators (CSPRNG minimum 32 bytes entropy). - Services MUST verify that the SHA-256 hash of expected rpId matches the rpIdHash within the authenticatorData structure. - Engineers MUST enforce sign-count validation (authenticatorData.counter > storedCounter) to detect cloned or compromised authenticator hardware. ## Bad vs Good Implementations ### Vulnerable Origin Check and Non-Atomic Challenge Lifecycle #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using .includes('acme.corp') allows reverse-proxy phishing attackers (e.g., Evilginx) to relay credentials from attacker domains like 'https://acme.corp.attacker.dev'. Furthermore, the challenge is not atomically consumed on read, allowing replay attacks across concurrent requests. ```typescript import { Request, Response } from 'express'; export async function verifyAssertion(req: Request, res: Response) { const { credential, userId } = req.body; const session = req.session as any; // VULNERABLE: Session-based challenge check without atomic invalidation // Allows concurrent replay race conditions if (credential.response.clientDataJSON) { const clientData = JSON.parse( Buffer.from(credential.response.clientDataJSON, 'base64url').toString('utf-8') ); // CRITICAL FLAW: Substring matching permits AiTM proxy bypass (e.g., https://acme.corp.phishing.attacker.com) if (!clientData.origin.includes('acme.corp')) { return res.status(403).json({ error: 'Origin mismatch' }); } // Challenge verified but left active in session if (clientData.challenge !== session.webauthnChallenge) { return res.status(401).json({ error: 'Invalid challenge' }); } } return res.status(200).json({ success: true }); } ``` #### Production Standard (Correct) > **Standard**: Uses Redis GETDEL for zero-window atomic nonce invalidation, strictly enforces an immutable Set of canonical RFC 6454 origins, validates the RP ID cryptographic binding, and checks the signature counter for clone detection. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { AuthenticationResponseJSON } from '@simplewebauthn/types'; import Redis from 'ioredis'; const CANONICAL_ORIGINS: ReadonlySet<string> = new Set([ 'https://auth.acme.corp', 'https://login.acme.corp' ]); const EXPECTED_RP_ID = 'acme.corp'; export async function verifyAssertionSecure( response: AuthenticationResponseJSON, userId: string, redis: Redis, userAuthenticator: { credentialPublicKey: Buffer; counter: number } ) { const challengeKey = `webauthn:challenge:${userId}`; // 1. Atomic single-use nonce consumption prevents replay and concurrency races const expectedChallenge = await redis.getdel(challengeKey); if (!expectedChallenge) { throw new Error('AUTHENTICATION_CHALLENGE_EXPIRED_OR_CONSUMED'); } // 2. Cryptographic assertion verification with canonical origin set and RP ID const verification = await verifyAuthenticationResponse({ response, expectedChallenge, expectedOrigin: Array.from(CANONICAL_ORIGINS), expectedRPID: EXPECTED_RP_ID, authenticator: { credentialPublicKey: userAuthenticator.credentialPublicKey, counter: userAuthenticator.counter, credentialID: response.id, }, requireUserVerification: true, }); if (!verification.verified) { throw new Error('ASSERTION_VERIFICATION_FAILED'); } // 3. Prevent authenticator cloning via signature counter check const { newCounter } = verification.authenticationInfo; if (newCounter <= userAuthenticator.counter && userAuthenticator.counter > 0) { throw new Error('AUTHENTICATOR_CLONE_DETECTED_SIGN_COUNT_STAGNANT'); } return { success: true, newCounter }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Passkey Cryptographic Origin & Nonce Assertion Invariant

WebAuthn Passkey Cryptographic Origin & Nonce Assertion Invariant defines an industrial-grade behavioral standard for security engineering. Defends against real-time adversary-in-the-middle (AiTM) reverse proxy phishing and replay attacks by enforcing cryptographic clientDataJSON origin validation and atomic single-use nonce consumption. WebAuthn assertions must strictly validate the fully-qualified canonical origin, rely on atomic get-and-delete challenge storage, and enforce user verification invariants. 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: Permissive Origin Matching and Non-Atomic Challenge Consumption in WebAuthn 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	Permissive Origin Matching and Non-Atomic Challenge Consumption in WebAuthn 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 enforce exact string matching against an immutable whitelist of canonical origins including protocol, host, and port (RFC 6454).

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.