Passkey Conditional UI Step-Up Authentication Boundary Enforcement

--- description: Passkey Conditional UI Step-Up Authentication Boundary Enforcement - Enforces a strict cryptographic and architectural boundary between WebAuthn Conditional UI (autofill mediation) used for ambient session establishment and active, user-verified re-authentication for sensitive actions. Passive autofill ceremonies must never satisfy elevated administrative authorization states; step-up flows must mandate explicit hardware-attested user verification (UV) with fresh cryptographic challenges and short-lived, transaction-bound tokens. globs: src/auth/**/*.{ts,tsx}, src/server/auth/**/*.{ts,tsx}, src/pages/api/auth/**/*.{ts,tsx}, src/features/admin/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/passkey-conditional-ui-stepup-boundary" --- # Passkey Conditional UI Step-Up Authentication Boundary Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Conflating Passive Passkey Autofill Assertions with Explicit Step-Up User Verification ## System Constraints You are a Principal Security Architect enforcing the Passkey Conditional UI Step-Up Authentication Boundary. You must ensure that passive WebAuthn Conditional UI credentials (autocomplete="webauthn") are cryptographically segregated from high-privilege operational workflows. Any administrative or state-mutating operation requiring elevated privileges must trigger an active navigator.credentials.get() invocation with userVerification set to 'required', validate freshness against a single-use server challenge, verify the AuthenticatorData UV flag, and mint an isolated, short-lived elevation token. ## Strict Guidelines - Engineers MUST ALWAYS set `userVerification: 'required'` (never 'preferred' or 'discouraged') in PublicKeyCredentialRequestOptions for step-up authentication ceremonies. - Engineers MUST NOT reuse ambient WebAuthn session cookies or conditional UI assertion proofs to authorize destructive or administrative operations. - Services MUST verify the `uv` (User Verified) bit in the `flags` byte of the received `authenticatorData` on the backend during step-up assertion verification. - Services MUST bind step-up challenges to a specific sensitive action or transaction ID and enforce an expiration window not exceeding 120 seconds. - Components NEVER execute `navigator.credentials.get()` with `mediation: 'conditional'` within step-up modal dialogues or elevated authorization interceptors. ## Bad vs Good Implementations ### Enforcing Hardware-Attested Step-Up Verification vs Ambient Login #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using `mediation: 'conditional'` and `userVerification: 'preferred'` allows passive or non-biometric credentials to fulfill the challenge without explicit hardware-enforced user presence, failing to verify intentional physical consent for sensitive operations. ```typescript // BAD: Reusing standard conditional session verification or soft UV for sensitive operations export async function authorizeAdminAction(actionPayload: AdminActionPayload) { // Flaw 1: Implicitly relying on existing session without forcing explicit hardware UV challenge // Flaw 2: Using userVerification: 'preferred' allows PIN/Biometric bypass if platform defaults to non-UV const options: CredentialRequestOptions = { publicKey: { challenge: Buffer.from(actionPayload.storedChallenge), userVerification: 'preferred', timeout: 60000, }, mediation: 'conditional' // Incorrect: conditional mediation used in step-up flow }; const assertion = await navigator.credentials.get(options) as PublicKeyCredential; return submitAdminAction({ payload: actionPayload, assertion }); } ``` #### Production Standard (Correct) > **Standard**: Fetches a fresh server challenge bound strictly to the requested administrative action, requires active hardware user verification (`userVerification: 'required'`), avoids conditional autofill mediation, and returns an ephemeral elevation token upon cryptographic verification of the UV flag. ```typescript // GOOD: Explicit, isolated WebAuthn ceremony with mandatory User Verification and distinct challenge export async function authorizeAdminAction(actionId: string): Promise<string> { // 1. Fetch an ephemeral, transaction-bound challenge dedicated to step-up auth const challengeResponse = await fetch(`/api/auth/step-up/challenge?action=${encodeURIComponent(actionId)}`, { method: 'POST' }); const { challenge, allowCredentials } = await challengeResponse.json(); // 2. Enforce active modal ceremony with mandatory user verification const assertion = await navigator.credentials.get({ publicKey: { challenge: Uint8Array.from(atob(challenge), c => c.charCodeAt(0)), allowCredentials: allowCredentials.map((cred: { id: string }) => ({ id: Uint8Array.from(atob(cred.id), c => c.charCodeAt(0)), type: 'public-key' })), userVerification: 'required', // Mandatory biometric or hardware PIN timeout: 30000 } // Notice: mediation is omitted or set to 'optional', never 'conditional' }) as PublicKeyCredential; if (!assertion) { throw new Error('User verification failed or was aborted.'); } // 3. Exchange verified assertion for a scoped, short-lived elevation token const response = await fetch('/api/auth/step-up/verify', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ actionId, credential: assertion }) }); const { elevationToken } = await response.json(); return elevationToken; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Passkey Conditional UI Step-Up Authentication Boundary Enforcement

Passkey Conditional UI Step-Up Authentication Boundary Enforcement defines an industrial-grade behavioral standard for security engineering. Enforces a strict cryptographic and architectural boundary between WebAuthn Conditional UI (autofill mediation) used for ambient session establishment and active, user-verified re-authentication for sensitive actions. Passive autofill ceremonies must never satisfy elevated administrative authorization states; step-up flows must mandate explicit hardware-attested user verification (UV) with fresh cryptographic challenges and short-lived, transaction-bound tokens. 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: Conflating Passive Passkey Autofill Assertions with Explicit Step-Up User Verification 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	Conflating Passive Passkey Autofill Assertions with Explicit Step-Up User Verification	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 set `userVerification

Engineers MUST ALWAYS set `userVerification: 'required'` (never 'preferred' or 'discouraged') in PublicKeyCredentialRequestOptions for step-up authentication 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.