WebAuthn Level 3 Hybrid Transport Relay Resistance and ClientData Validation

--- description: WebAuthn Level 3 Hybrid Transport Relay Resistance and ClientData Validation - Enforces strict RP origin validation, clientDataJSON crossOrigin verification, and authenticator data transport binding during WebAuthn Level 3 hybrid (caBLE/cross-device) ceremonies. Prevents adversary-in-the-middle (AitM) relay proxies from harvesting passkey assertions across disassociated domains or unverified hybrid channels. globs: src/**/auth/**/*.{ts,tsx}, src/**/webauthn/**/*.{ts,tsx}, src/**/fido/**/*.{ts,tsx}, src/**/api/auth/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-l3-hybrid-transport-relay-resistance" --- # WebAuthn Level 3 Hybrid Transport Relay Resistance and ClientData Validation > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Trusting unverified hybrid assertions without crossOrigin assertions or strict canonical origin and clientDataHash validation ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Level 3 Hybrid Transport Relay-Resistance Invariant. You must reject any WebAuthn assertion verification implementation that fails to validate clientDataJSON.crossOrigin, ignores authenticator transport parameters, performs naive string comparisons on origins, or delegates clientDataHash calculation to unauthenticated client payloads. ## Strict Guidelines - Engineers MUST ALWAYS verify that parsedClientData.crossOrigin is explicitly false (or strictly matches an approved, pre-registered cross-origin iframe target) during assertion and registration ceremonies. - Engineers MUST ALWAYS independently compute the SHA-256 hash of the raw clientDataJSON on the server and use this computed clientDataHash when validating the signature over authenticatorData || clientDataHash. - Engineers MUST ALWAYS enforce canonical origin matching against expected RP origin (scheme, host, port) and reject wildcard, regex-based, or substring-based origin matching to prevent reverse-proxy relay attacks. - Engineers MUST enforce that if hybrid transport ('hybrid') is indicated or requested, challenge lifetimes do not exceed 60 seconds to mitigate session-tunnelling relay windows. - Code MUST verify the userPresence (UP) and userVerification (UV) bit flags in authenticatorData according to the RP's configured userVerification policy ('required' or 'preferred'). - Services MUST NOT accept an assertion if authenticatorAttachment is inconsistent with the credential's enrolled transport metadata without explicit step-up verification. ## Bad vs Good Implementations ### Verifying WebAuthn L3 Assertion with Hybrid Relay Protection #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code uses substring matching for origins (permitting attacker domains like attacker-example.com), completely ignores the WebAuthn L3 clientData.crossOrigin flag (enabling iframe relay exploits), fails to enforce strict challenge expiry windows for hybrid transports, and fails to inspect the authenticatorData flags for User Presence (UP) and User Verification (UV). ```typescript import { Request, Response } from 'express'; interface AssertionPayload { id: string; clientDataJSON: string; authenticatorData: string; signature: string; } export async function verifyAssertion(req: Request, res: Response) { const { clientDataJSON, authenticatorData, signature } = req.body as AssertionPayload; // VULNERABLE: Naive JSON parsing without crossOrigin check or raw hash verification const clientData = JSON.parse(Buffer.from(clientDataJSON, 'base64url').toString('utf-8')); // VULNERABLE: Loose origin validation permits AitM domains if (!clientData.origin.includes('example.com')) { return res.status(401).json({ error: 'Invalid origin' }); } // VULNERABLE: Ignores challenge freshness check and transport-relay mitigations if (clientData.type !== 'webauthn.get') { return res.status(400).json({ error: 'Invalid ceremony type' }); } // Signature verified without checking UP/UV flags or crossOrigin flag res.json({ verified: true }); } ``` #### Production Standard (Correct) > **Standard**: This implementation enforces WebAuthn Level 3 hybrid transport invariants: it restricts the challenge lifecycle to 60 seconds to suppress relay windows, requires strict user verification (UP and UV bit verification), validates the canonical origin against exact expected origin, and explicitly rejects assertions containing an unexpected `crossOrigin` attribute in `clientDataJSON`. ```typescript import { createHash, timingSafeEqual } from 'crypto'; import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { AuthenticationResponseJSON } from '@simplewebauthn/types'; interface StoredChallengeSession { expectedChallenge: string; createdAt: number; expectedOrigin: string; expectedRPID: string; } const HYBRID_CHALLENGE_TTL_MS = 60_000; // 60 seconds strict window export async function verifyAssertionStrict( response: AuthenticationResponseJSON, session: StoredChallengeSession, publicKey: Uint8Array ) { // Invariant 1: Enforce challenge lifetime bound for hybrid transport relay prevention if (Date.now() - session.createdAt > HYBRID_CHALLENGE_TTL_MS) { throw new Error('WebAuthn hybrid assertion timed out; potential relay attack window exceeded.'); } // Invariant 2: WebAuthn L3 full cryptographic verification with crossOrigin enforcement const verification = await verifyAuthenticationResponse({ response, expectedChallenge: session.expectedChallenge, expectedOrigin: session.expectedOrigin, expectedRPID: session.expectedRPID, authenticator: { credentialPublicKey: publicKey, credentialID: response.id, counter: 0, }, requireUserVerification: true, }); if (!verification.verified || !verification.authenticationInfo) { throw new Error('Authentication signature verification failed.'); } // Invariant 3: Parse clientDataJSON to enforce Level 3 crossOrigin invariants const rawClientData = Buffer.from(response.response.clientDataJSON, 'base64url').toString('utf-8'); const parsedClientData = JSON.parse(rawClientData); // If present, crossOrigin must be strictly false unless deliberately permitted for verified cross-origin contexts if (parsedClientData.crossOrigin !== undefined && parsedClientData.crossOrigin !== false) { throw new Error('Security Violation: Unexpected crossOrigin flag in clientDataJSON.'); } // Invariant 4: Validate authenticator flags (User Presence and User Verification) const authDataBuffer = Buffer.from(response.response.authenticatorData, 'base64url'); const flags = authDataBuffer[32]; const userPresent = (flags & 0x01) !== 0; const userVerified = (flags & 0x04) !== 0; if (!userPresent || !userVerified) { throw new Error('Security Violation: Required UP or UV flags missing from authenticatorData.'); } return verification; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Level 3 Hybrid Transport Relay Resistance and ClientData Validation

WebAuthn Level 3 Hybrid Transport Relay Resistance and ClientData Validation defines an industrial-grade behavioral standard for security engineering. Enforces strict RP origin validation, clientDataJSON crossOrigin verification, and authenticator data transport binding during WebAuthn Level 3 hybrid (caBLE/cross-device) ceremonies. Prevents adversary-in-the-middle (AitM) relay proxies from harvesting passkey assertions across disassociated domains or unverified hybrid channels. 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 hybrid assertions without crossOrigin assertions or strict canonical origin and clientDataHash validation 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 hybrid assertions without crossOrigin assertions or strict canonical origin and clientDataHash validation	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 verify that parsedClientData.crossOrigin is explicitly false (or strictly matches an approved, pre-registered cross-origin iframe target) during assertion and registration ceremonies.

Engineers MUST ALWAYS verify that parsedClientData.crossOrigin is explicitly false (or strictly matches an approved, pre-registered cross-origin iframe target) during assertion and registration ceremonies.

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.