WebAuthn Hybrid Transport Cross-Device BLE Proximity and Channel-Binding Guardrail

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Accepting Relayed Hybrid QR Assertions Without Strict Origin Pinning and Ephemeral Channel Binding) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

WebAuthn Hybrid Transport Cross-Device BLE Proximity and Channel-Binding Guardrail

--- description: WebAuthn Hybrid Transport Cross-Device BLE Proximity and Channel-Binding Guardrail - Enforces strict proximity and cryptographic channel-binding verification for WebAuthn hybrid transport (caBLE / QR code cross-device flows). Defeats hybrid Adversary-in-the-Middle (AitM) phishing proxies by validating authenticator data flags, immutable RP ID hashes, ephemeral session key bindings, and transport-layer attestation boundaries. globs: src/**/auth/**/*.{ts,tsx,js}, src/**/webauthn/**/*.{ts,tsx,js}, src/**/passkeys/**/*.{ts,tsx,js}, packages/**/auth/**/*.{ts,tsx,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-hybrid-transport-ble-proximity-boundary" --- # WebAuthn Hybrid Transport Cross-Device BLE Proximity and Channel-Binding Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Relayed Hybrid QR Assertions Without Strict Origin Pinning and Ephemeral Channel Binding ## System Constraints You are a Principal Security Architect and Rules Author enforcing FIDO2/WebAuthn Level 3 compliance and hybrid transport isolation. You must ensure that cross-device authentication sessions cannot be relayed by Adversary-in-the-Middle (AitM) proxies. Enforce strict RP ID hash validation, origin immutability, ephemeral single-use session nonces, and Bluetooth Low Energy (BLE) proximity attestation boundaries across all WebAuthn verification pipelines. ## Strict Guidelines - Engineers MUST ALWAYS verify that 'clientDataJSON.origin' matches the immutable, statically configured Relying Party origin rather than dynamic 'Host' or 'X-Forwarded-Host' headers. - Engineers MUST compute the SHA-256 hash of the configured rpId and verify byte-for-byte equivalence against 'authData.rpIdHash' before processing signatures. - Engineers MUST invalidate ephemeral session tokens and QR-rendezvous nonces immediately upon consumption (single-use semantics with a TTL <= 60 seconds). - Services MUST cryptographically bind the initiation session to the hybrid authentication challenge using an ephemeral channel-binding hash (e.g., linking the TLS client certificate or local initiator session nonce). - Verification routines MUST verify User Presence (UP) and User Verification (UV) flags in authenticatorData: (flags & 0x01) !== 0 and (flags & 0x04) !== 0. - Engineers MUST NOT allow cross-origin iframe framing or unauthenticated relaying of the WebAuthn rendezvous endpoint. - Components NEVER accept hybrid credential responses where the authenticator transport metadata diverges from declared client session capabilities. ## Bad vs Good Implementations ### WebAuthn Hybrid Assertion Verification Guardrail #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Derives expectedOrigin and expectedRPID dynamically from request headers, which an AitM phishing proxy (e.g., Evilginx) can manipulate. Furthermore, it lacks ephemeral session binding, allowing an attacker to proxy the QR code and relay the assertion to the victim. ```typescript import { Request, Response } from 'express'; import { verifyAuthenticationResponse } from '@simplewebauthn/server'; export async function verifyHybridAuth(req: Request, res: Response) { const { response, sessionChallenge } = req.body; // VULNERABLE: Uses untrusted host header for origin check, enabling AitM proxying const clientOrigin = `${req.protocol}://${req.get('host')}`; const expectedRPID = req.hostname; // VULNERABLE: Does not check transport type or verify ephemeral rendezvous token const verification = await verifyAuthenticationResponse({ response, expectedChallenge: sessionChallenge, expectedOrigin: clientOrigin, expectedRPID, }); if (verification.verified) { return res.json({ success: true }); } return res.status(400).json({ error: 'Failed' }); } ``` #### Production Standard (Correct) > **Standard**: Pins RP Origin and RP ID to immutable environment constants, performs atomic single-use nonce consumption within a 60-second window, validates User Verification, and executes a timing-safe byte comparison on the raw authData rpIdHash to block AitM relaying. ```typescript import { Request, Response } from 'express'; import crypto from 'node:crypto'; import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import { consumeEphemeralSessionNonce, getPinnedAuthenticator } from './auth-store'; const IMMUTABLE_RP_ORIGIN = process.env.TRUSTED_RP_ORIGIN!; // e.g., 'https://auth.company.internal' const IMMUTABLE_RP_ID = process.env.TRUSTED_RP_ID!; // e.g., 'company.internal' const EXPECTED_RP_ID_HASH = crypto.createHash('sha256').update(IMMUTABLE_RP_ID).digest(); export async function verifyHybridAuth(req: Request, res: Response) { const { response, sessionToken } = req.body; // 1. Atomic single-use consumption of ephemeral QR rendezvous session const session = await consumeEphemeralSessionNonce(sessionToken); if (!session || Date.now() - session.createdAt > 60_000) { return res.status(401).json({ error: 'Session expired or replay detected' }); } // 2. Fetch public key credential securely bound to the user session const authenticator = await getPinnedAuthenticator(response.id); if (!authenticator) { return res.status(404).json({ error: 'Unrecognized credential' }); } // 3. Strict verification against statically pinned RP identity const verification = await verifyAuthenticationResponse({ response, expectedChallenge: session.challenge, expectedOrigin: IMMUTABLE_RP_ORIGIN, expectedRPID: IMMUTABLE_RP_ID, authenticator: { credentialPublicKey: authenticator.publicKey, credentialID: authenticator.id, counter: authenticator.counter, transports: authenticator.transports, }, requireUserVerification: true, }); if (!verification.verified || !verification.authenticationInfo) { return res.status(403).json({ error: 'Cryptographic attestation failed' }); } // 4. Invariant: Raw rpIdHash byte comparison ensuring strict boundary const rawAuthData = Buffer.from(response.response.authenticatorData, 'base64url'); const claimedRpIdHash = rawAuthData.subarray(0, 32); if (!crypto.timingSafeEqual(claimedRpIdHash, EXPECTED_RP_ID_HASH)) { return res.status(403).json({ error: 'RP ID Hash mismatch across boundary' }); } return res.json({ success: true }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Hybrid Transport Cross-Device BLE Proximity and Channel-Binding Guardrail

WebAuthn Hybrid Transport Cross-Device BLE Proximity and Channel-Binding Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces strict proximity and cryptographic channel-binding verification for WebAuthn hybrid transport (caBLE / QR code cross-device flows). Defeats hybrid Adversary-in-the-Middle (AitM) phishing proxies by validating authenticator data flags, immutable RP ID hashes, ephemeral session key bindings, and transport-layer attestation boundaries. 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 Relayed Hybrid QR Assertions Without Strict Origin Pinning and Ephemeral Channel Binding 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 Relayed Hybrid QR Assertions Without Strict Origin Pinning and Ephemeral Channel Binding	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 'clientDataJSON.origin' matches the immutable, statically configured Relying Party origin rather than dynamic 'Host' or 'X-Forwarded-Host' headers.

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.