FIDO2 Passkey Conditional UI DOM Overlay Isolation and Mediation Standard

--- description: FIDO2 Passkey Conditional UI DOM Overlay Isolation and Mediation Standard - Enforces strict DOM Shadow Boundary isolation and explicit cryptographic mediation for WebAuthn Conditional Mediation (`navigator.credentials.get` with conditional mediation). Mitigates passkey autofill hijacking, credential exfiltration via third-party DOM scripts, and clickjacking overlay attacks on WebAuthn-enabled input elements. globs: src/**/*.{ts,tsx,js,jsx}, components/**/*.{ts,tsx}, auth/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fido2-passkey-conditional-ui-overlay-isolation-standard" --- # FIDO2 Passkey Conditional UI DOM Overlay Isolation and Mediation Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Exposing Passkey Conditional UI Inputs to Unbounded DOM Scripting and Unmediated Autocomplete Invocations ## System Constraints You are a Principal Security Architect enforcing the FIDO2 Passkey Conditional UI DOM Overlay Isolation Standard. You must mandate closed Shadow DOM boundaries, abort controller lifecycles, and visual z-index/opacity overlay protections for all conditional WebAuthn credentials retrieval surfaces. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate WebAuthn conditional UI `<input autocomplete='username webauthn'>` elements within a closed Shadow DOM (`mode: 'closed'`) or an isolated web component boundary to prevent DOM-sniffing scripts and keyloggers from intercepting intermediate values. - Engineers MUST ALWAYS tie every `navigator.credentials.get({ mediation: 'conditional' })` invocation to a strictly scoped `AbortController` signal, aborting active credential mediation immediately upon component unmount, navigation, or form submission. - Engineers MUST NOT invoke `navigator.credentials.get` without verifying `PublicKeyCredential.isConditionalMediationAvailable()` resolving to `true` first. - Components NEVER allow translucent, zero-opacity, or absolute-positioned elements (CSS `pointer-events: none`, invisible overlays, or negative z-indices) to overlap or mask the conditional UI input element (Clickjacking/Tapjacking mitigation). - Services MUST enforce server-side validation of the `challenge`, `origin`, and cryptographic signature (`clientDataJSON`, `authenticatorData`) against replay attacks and ensure `userVerification: 'required'` or `'preferred'` according to FIDO Alliance specifications. ## Bad vs Good Implementations ### Passkey Conditional Mediation Invocation and DOM Shadow Encapsulation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly invokes WebAuthn conditional mediation without feature verification (`isConditionalMediationAvailable`), leaks lifecycle management without an `AbortController`, renders a transparent overlay div over the input (tapjacking risk), and exposes the input to third-party scripts within the flat light DOM. ```typescript import React, { useEffect } from 'react'; export const InsecureLoginForm: React.FC = () => { useEffect(() => { // ANTI-PATTERN: Calling conditional get without feature detection or AbortSignal navigator.credentials.get({ mediation: 'conditional', publicKey: { challenge: new Uint8Array([1, 2, 3, 4]), timeout: 60000, userVerification: 'preferred' } }); }, []); // ANTI-PATTERN: Unprotected input exposed in global DOM, vulnerable to overlays & third-party scripts return ( <div className="login-container" style={{ position: 'relative' }}> <div style={{ position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', pointerEvents: 'none' }} /> <input id="username" name="username" type="text" autoComplete="username webauthn" /> </div> ); }; ``` #### Production Standard (Correct) > **Standard**: Verifies `isConditionalMediationAvailable()`, encapsulates the autofill input in a closed Shadow Root to isolate it from external DOM scripts, cleans up pending mediation using an `AbortController`, enforces strict overlay isolation (`isolation: isolate`, explicit z-index/opacity), and mandates `userVerification: 'required'`. ```typescript import React, { useEffect, useRef } from 'react'; export const SecurePasskeyInput: React.FC<{ challenge: Uint8Array; onAuthSuccess: (cred: Credential) => void }> = ({ challenge, onAuthSuccess, }) => { const containerRef = useRef<HTMLDivElement>(null); const shadowRootRef = useRef<ShadowRoot | null>(null); useEffect(() => { const abortController = new AbortController(); async function initPasskeyConditionalUI() { const isAvailable = typeof window.PublicKeyCredential !== 'undefined' && typeof window.PublicKeyCredential.isConditionalMediationAvailable === 'function' && await window.PublicKeyCredential.isConditionalMediationAvailable(); if (!isAvailable || abortController.signal.aborted) { return; } if (containerRef.current && !shadowRootRef.current) { shadowRootRef.current = containerRef.current.attachShadow({ mode: 'closed' }); const input = document.createElement('input'); input.setAttribute('type', 'text'); input.setAttribute('name', 'username'); input.setAttribute('autocomplete', 'username webauthn'); input.setAttribute('aria-label', 'Username or Passkey'); input.style.cssText = 'position: relative; z-index: 10; opacity: 1; pointer-events: auto;'; shadowRootRef.current.appendChild(input); } try { const credential = await navigator.credentials.get({ mediation: 'conditional', signal: abortController.signal, publicKey: { challenge, userVerification: 'required', rpId: window.location.hostname, }, }); if (credential) { onAuthSuccess(credential); } } catch (err: unknown) { if (err instanceof DOMException && err.name === 'AbortError') return; console.error('Passkey conditional UI failed:', err); } } initPasskeyConditionalUI(); return () => { abortController.abort(); }; }, [challenge, onAuthSuccess]); return <div ref={containerRef} style={{ isolation: 'isolate', position: 'relative' }} />; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FIDO2 Passkey Conditional UI DOM Overlay Isolation and Mediation Standard

FIDO2 Passkey Conditional UI DOM Overlay Isolation and Mediation Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict DOM Shadow Boundary isolation and explicit cryptographic mediation for WebAuthn Conditional Mediation (`navigator.credentials.get` with conditional mediation). Mitigates passkey autofill hijacking, credential exfiltration via third-party DOM scripts, and clickjacking overlay attacks on WebAuthn-enabled input elements. 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: Exposing Passkey Conditional UI Inputs to Unbounded DOM Scripting and Unmediated Autocomplete Invocations 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	Exposing Passkey Conditional UI Inputs to Unbounded DOM Scripting and Unmediated Autocomplete Invocations	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 encapsulate WebAuthn conditional UI `<input autocomplete='username webauthn'>` elements within a closed Shadow DOM (`mode

Engineers MUST ALWAYS encapsulate WebAuthn conditional UI `<input autocomplete='username webauthn'>` elements within a closed Shadow DOM (`mode: 'closed'`) or an isolated web component boundary to prevent DOM-sniffing scripts and keyloggers from intercepting intermediate values.

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.