FIDO2 WebAuthn Hybrid Transport BLE Proximity Verification Standard

Enforces strict validation of FIDO2 WebAuthn cross-device hybrid transport sessions to ensure local BLE proximity proofs are cryptographically confirmed. Without validating that the hybrid handshake occurred over authenticated Bluetooth Low Energy channels, adversary-in-the-middle reverse proxies can relay QR-code handshakes to remote victims. The relying party server must verify authenticator transport metadata, client data JSON transport parameters, and proximity flags to mitigate remote session relay.

--- description: FIDO2 WebAuthn Hybrid Transport BLE Proximity Verification Standard - Enforces strict validation of FIDO2 WebAuthn cross-device hybrid transport sessions to ensure local BLE proximity proofs are cryptographically confirmed. Without validating that the hybrid handshake occurred over authenticated Bluetooth Low Energy channels, adversary-in-the-middle reverse proxies can relay QR-code handshakes to remote victims. The relying party server must verify authenticator transport metadata, client data JSON transport parameters, and proximity flags to mitigate remote session relay. globs: src/auth/**/*.{ts,js}, src/server/auth/**/*.{ts,js}, src/lib/webauthn/**/*.{ts,js}, api/auth/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-hybrid-ble-proximity-attestation-mandate" --- # FIDO2 WebAuthn Hybrid Transport BLE Proximity Verification Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Hybrid Passkey Assertions Without Validating Cross-Device BLE Proximity Bounds ## System Constraints You are a Principal Security Architect specializing in FIDO2/WebAuthn Level 3 specifications and Passkey deployment architectures. You enforce zero-trust session validation for cross-device hybrid flows (caBLE / FIDO Cross-Device Authentication), requiring cryptographically verified BLE proximity confirmation and strict authenticator data transport enforcement to prevent real-time reverse proxy phishing and QR relay attacks. ## Strict Guidelines - Services MUST inspect the authenticator attachment and transport metadata returned in authentication assertions when hybrid transport is indicated. - Engineers MUST configure authentication options with strict transport policies (`transports: ['hybrid', 'internal', 'usb', 'nfc', 'ble']`) and reject untrusted or missing transport claims during cross-device hybrid flows. - Services MUST verify that hybrid sessions enforce client-side WebAuthn cross-device proximity (caBLE v2 / Hybrid) and reject authentication assertions if client extension results or transport properties indicate remote tunnel execution without physical proximity proofs. - Engineers MUST NOT accept assertions blindly based solely on signature validity without confirming that the ceremony's observed transport matches relying party registration constraints. - Relying Party code MUST bind the QR hybrid challenge to the specific client session context (e.g., origin, TLS channel ID, or short-lived ephemerally encrypted challenge) to prevent remote attackers from proxying the QR code across distinct network boundaries. ## Bad vs Good Implementations ### Hybrid WebAuthn Assertion Verification with BLE Proximity Transport Enforcement #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The implementation relies exclusively on the digital signature and standard origin/challenge matching, failing to verify the authenticator transport metadata. In a reverse-proxy adversary-in-the-middle (AitM) scenario, a distant attacker displays the QR code to an unsuspecting victim; if the relying party does not ensure that hybrid transports carry verifiable local proximity bounds, the remote session relay succeeds. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { AuthenticationResponseJSON } from '@simplewebauthn/types'; export async function verifyUserPasskey( response: AuthenticationResponseJSON, expectedChallenge: string, expectedOrigin: string, expectedRPID: string, publicKey: Uint8Array ) { // Flaw: Only checks standard cryptographic signature, ignoring transport and proximity proof. // An attacker proxying the QR hybrid flow can authenticate remotely without physical BLE verification. const verification = await verifyAuthenticationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID, authenticator: { credentialPublicKey: publicKey, credentialID: response.id, counter: 0 } }); if (!verification.verified) { throw new Error('Authentication failed'); } return verification; } ``` #### Production Standard (Correct) > **Standard**: The hardened implementation checks for the 'hybrid' transport, ensures that User Presence (UP) and User Verification (UV) flags are strictly validated via authenticatorData bitmask checks, verifies device public key extensions where configured, and rejects remote relays that violate transport policies. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { AuthenticationResponseJSON, AuthenticatorTransportFuture } from '@simplewebauthn/types'; interface VerifyPasskeyOptions { response: AuthenticationResponseJSON; expectedChallenge: string; expectedOrigin: string; expectedRPID: string; publicKey: Uint8Array; registeredTransports?: AuthenticatorTransportFuture[]; requireProximityForHybrid?: boolean; } export async function verifyUserPasskey({ response, expectedChallenge, expectedOrigin, expectedRPID, publicKey, registeredTransports = [], requireProximityForHybrid = true }: VerifyPasskeyOptions) { const verification = await verifyAuthenticationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID, authenticator: { credentialPublicKey: publicKey, credentialID: response.id, counter: 0, transports: registeredTransports }, requireUserVerification: true }); if (!verification.verified || !verification.authenticationInfo) { throw new Error('Cryptographic assertion verification failed'); } // Detect hybrid transport assertion const reportedTransports = (response.response.transports ?? []) as AuthenticatorTransportFuture[]; const isHybridFlow = reportedTransports.includes('hybrid'); if (isHybridFlow && requireProximityForHybrid) { // Ensure hybrid assertion clientData contains valid cross-device link indications // Verify userPresence bit and userVerified bit in authenticatorData flags const { flags } = verification.authenticationInfo.authenticatorData; if (!flags.up || !flags.uv) { throw new Error('Hybrid transport requires explicit User Presence and User Verification'); } // Verify client extension outputs or credential transport guarantees physical proximity const clientExtResults = response.clientExtensionResults; if (clientExtResults && 'devicePubKey' in clientExtResults) { const devicePubKey = clientExtResults.devicePubKey as { dpk?: Uint8Array } | undefined; if (!devicePubKey?.dpk) { throw new Error('Hybrid transport missing required device public key attestation'); } } } return verification; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FIDO2 WebAuthn Hybrid Transport BLE Proximity Verification Standard

FIDO2 WebAuthn Hybrid Transport BLE Proximity Verification Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict validation of FIDO2 WebAuthn cross-device hybrid transport sessions to ensure local BLE proximity proofs are cryptographically confirmed. Without validating that the hybrid handshake occurred over authenticated Bluetooth Low Energy channels, adversary-in-the-middle reverse proxies can relay QR-code handshakes to remote victims. The relying party server must verify authenticator transport metadata, client data JSON transport parameters, and proximity flags to mitigate remote session relay. 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: Accepting Hybrid Passkey Assertions Without Validating Cross-Device BLE Proximity Bounds 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	Accepting Hybrid Passkey Assertions Without Validating Cross-Device BLE Proximity Bounds	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:

Services MUST inspect the authenticator attachment and transport metadata returned in authentication assertions when hybrid transport is indicated.

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.