Passkey FIDO2 Hybrid Transport Origin Binding & Proximity Relay Defense

--- description: Passkey FIDO2 Hybrid Transport Origin Binding & Proximity Relay Defense - Enforces strict origin binding, cryptographic proximity assertions, and client data verification on WebAuthn cross-device (hybrid/caBLE) authentication ceremonies. Prevents Man-in-the-Middle (MitM) credential relay attacks where a remote attacker tricks a victim into authorizing a malicious session using QR code or cross-device flows. Mandates verification of the clientDataJSON origin, top-origin bindings, session-bound challenges, and hybrid transport flags on the relying party backend. globs: src/**/auth/**/*.{ts,js}, src/**/webauthn/**/*.{ts,js}, src/**/identity/**/*.{ts,js}, server/**/auth/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/passkey-fido2-hybrid-transport-mitm-relay-guardrail" --- # Passkey FIDO2 Hybrid Transport Origin Binding & Proximity Relay Defense > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Blind Relying Party Authentication Accepting Unbound Challenges and Ignored Hybrid Transport State ## System Constraints You are a Principal Security Architect enforcing FIDO2/WebAuthn hybrid transport invariants. Cross-device (hybrid / caBLE) authentications must be safeguarded against remote relay and phishing attacks. Enforce cryptographic validation of clientDataJSON origin, strict ephemeral single-use challenge consumption tied directly to the initiating TLS session or WebSocket channel, and strict validation of Authenticator Data flags and extension outputs. Never permit relaxed origin validation, domain wildcards, or decoupling of registration/authentication challenges from the client session. ## Strict Guidelines - Relying Party (RP) MUST strictly validate that clientDataJSON.origin exactly matches the canonical RP ID (scheme, host, and port) with constant-time equality checks. - Relying Party MUST tie the authentication challenge cryptographically to the specific ephemeral user session or ephemeral channel (e.g., hash-bound to an encrypted channel ID) to prevent cross-session challenge relay. - Engineers MUST verify the 'authenticatorData.flags.up' (User Present) and evaluate 'authenticatorData.flags.uv' (User Verified) according to the configured UserVerificationRequirement; unverified responses MUST NOT be promoted to high-assurance tiers. - Services MUST consume challenges exactly once (single-use semantics via atomic delete-on-read in distributed key-value stores) with an expiration TTL not exceeding 120 seconds. - Relying Party MUST validate clientDataJSON.type matches 'webauthn.get' for assertion or 'webauthn.create' for attestation, and reject any unexpected type variants. - When evaluating hybrid responses containing cross-origin or topOrigin structures (WebAuthn Level 3), engineers MUST verify that topOrigin matches an explicitly configured, trusted whitelist of parent origins. - Engineers MUST NOT permit client-supplied 'rpId' overrides; the Relying Party identifier MUST be statically controlled on the server based on environment configuration. ## Bad vs Good Implementations ### WebAuthn Hybrid Assertion Verification with Origin & Session Binding #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accepts challenge directly from the request body rather than an authenticated server-side session, performs a loose substring match on the origin ('includes("example.com")') which permits attacker domains like 'attacker-example.com', and fails to atomically consume the challenge to prevent concurrent relay reuse. ```typescript import { Request, Response } from 'express'; export async function verifyAssertion(req: Request, res: Response) { const { credential, challenge } = req.body; // VULNERABLE: Challenge retrieved from client payload instead of secure session // Origin check is permissive and does not enforce canonical scheme/port matching const clientData = JSON.parse(Buffer.from(credential.response.clientDataJSON, 'base64').toString('utf8')); if (clientData.challenge !== challenge) { return res.status(400).json({ error: 'Invalid challenge' }); } if (!clientData.origin.includes('example.com')) { return res.status(400).json({ error: 'Invalid origin' }); } // No atomic challenge invalidation; vulnerable to replay across concurrent sessions return res.status(200).json({ status: 'authenticated' }); } ``` #### Production Standard (Correct) > **Standard**: Implements atomic challenge deletion upon reading (`redisClient.getDel`), validates exact canonical origin and RP ID via `@simplewebauthn/server`, enforces mandatory user verification, and protects against cloned authenticators by asserting counter monotonicity. ```typescript import { Request, Response } from 'express'; import crypto from 'node:crypto'; import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import { redisClient } from '../infrastructure/redis'; const EXPECTED_ORIGIN = process.env.AUTH_RP_ORIGIN!; // e.g. 'https://auth.example.com' const EXPECTED_RP_ID = process.env.AUTH_RP_ID!; // e.g. 'auth.example.com' export async function verifyAssertion(req: Request, res: Response) { const { credential, sessionId } = req.body; if (!sessionId || typeof sessionId !== 'string') { return res.status(400).json({ error: 'Missing session context' }); } // Atomic challenge retrieval and consumption (single-use invariant) const challengeKey = `webauthn:challenge:${sessionId}`; const expectedChallenge = await redisClient.getDel(challengeKey); if (!expectedChallenge) { return res.status(401).json({ error: 'Challenge expired or already consumed' }); } // Retrieve registered public key credential from persistence for the target user const userPasskey = await getUserPasskey(credential.id); if (!userPasskey) { return res.status(404).json({ error: 'Passkey credential not registered' }); } const verification = await verifyAuthenticationResponse({ response: credential, expectedChallenge, expectedOrigin: EXPECTED_ORIGIN, expectedRPID: EXPECTED_RP_ID, credential: { id: userPasskey.id, publicKey: userPasskey.publicKey, counter: userPasskey.counter, transports: userPasskey.transports, }, requireUserVerification: true, }); if (!verification.verified) { return res.status(401).json({ error: 'Assertion verification failed' }); } // Prevent sign-counter rollback (cloned authenticator detection) if (verification.authenticationInfo.newCounter <= userPasskey.counter && userPasskey.counter > 0) { await revokePasskey(userPasskey.id); return res.status(403).json({ error: 'Cloned authenticator detected: counter rollback' }); } await updatePasskeyCounter(userPasskey.id, verification.authenticationInfo.newCounter); return res.status(200).json({ status: 'authenticated' }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Passkey FIDO2 Hybrid Transport Origin Binding & Proximity Relay Defense

Passkey FIDO2 Hybrid Transport Origin Binding & Proximity Relay Defense defines an industrial-grade behavioral standard for security engineering. Enforces strict origin binding, cryptographic proximity assertions, and client data verification on WebAuthn cross-device (hybrid/caBLE) authentication ceremonies. Prevents Man-in-the-Middle (MitM) credential relay attacks where a remote attacker tricks a victim into authorizing a malicious session using QR code or cross-device flows. Mandates verification of the clientDataJSON origin, top-origin bindings, session-bound challenges, and hybrid transport flags on the relying party backend. 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: Blind Relying Party Authentication Accepting Unbound Challenges and Ignored Hybrid Transport State 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	Blind Relying Party Authentication Accepting Unbound Challenges and Ignored Hybrid Transport State	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:

Relying Party (RP) MUST strictly validate that clientDataJSON.origin exactly matches the canonical RP ID (scheme, host, and port) with constant-time equality checks.

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.