FIDO2/WebAuthn L3 Device-Bound Passkey Step-Up Attestation Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Accepting Multi-Device Synced Passkeys (BE=1) Without Attestation for High-Assurance Privileged Actions) 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.

FIDO2/WebAuthn L3 Device-Bound Passkey Step-Up Attestation Standard

--- description: FIDO2/WebAuthn L3 Device-Bound Passkey Step-Up Attestation Standard - Enforces strict validation of WebAuthn Level 3 authenticator flags (BE/BS) and hardware-backed attestation during step-up re-authentication. Blocks multi-device synced passkey replay and cross-device session extraction by ensuring privileged transactions strictly require hardware-bound secure enclave authenticators. globs: src/**/*.{ts,tsx}, server/**/*.{ts,js}, api/**/*.{ts,js}, lib/auth/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fido2-webauthn-l3-device-bound-stepup-attestation" --- # FIDO2/WebAuthn L3 Device-Bound Passkey Step-Up Attestation Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Multi-Device Synced Passkeys (BE=1) Without Attestation for High-Assurance Privileged Actions ## System Constraints You are a Principal Security Architect enforcing FIDO2 / WebAuthn Level 3 Device-Bound Passkey Step-Up Attestation. Multi-device synced passkeys (e.g., Apple iCloud Keychain, Google Password Manager) expose high-privilege operations to token extraction across compromised synced client endpoints. You must enforce device-bound credential invariants (Backup Eligibility BE=0, Backup State BS=0, User Verification UV=1), require enterprise/direct attestation verification for step-up challenges, and bind step-up challenges to transaction-specific nonces. ## Strict Guidelines - Engineers MUST ALWAYS verify authenticatorData flags at the bitwise level on the server; never trust client-side claims regarding device binding or biometric verification. - Engineers MUST NOT permit credentials with Backup Eligibility (BE, bit 3) or Backup State (BS, bit 4) enabled to complete Level 3 elevated authorization flows. - Services MUST enforce 'userVerification: required' and 'authenticatorAttachment: platform' in PublicKeyCredentialRequestOptions for step-up rituals. - Services MUST cryptographically bind the step-up challenge to the specific transaction payload (e.g., SHA-256 hash of operation, amount, and recipient) to prevent authentication forwarding and replay attacks. - Components NEVER execute step-up authentication via conditional UI (autofill) alone; conditional mediation is acceptable for ambient sign-in, but step-up MUST trigger an active, modal user gesture. - Verification routines MUST assert User Present (UP, bit 0) and User Verified (UV, bit 2) are both set to 1 in the raw authenticatorData. ## Bad vs Good Implementations ### Level 3 Hardware-Bound Step-Up Attestation Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to inspect WebAuthn L3 authenticatorData flags. It accepts credentials marked as backup eligible (BE) or currently backed up (BS), allowing credentials synced to potentially compromised foreign devices to authorize critical operations. ```typescript import { Request, Response } from 'express'; export async function verifyStepUpAssertion(req: Request, res: Response) { const { credential, expectedChallenge } = req.body; // VULNERABLE: Implicitly accepts any valid WebAuthn assertion, // including multi-device synced passkeys (iCloud Keychain / Google PM) // synced across compromised consumer endpoints. if (credential.response.clientDataJSON.challenge !== expectedChallenge) { return res.status(401).json({ error: 'Invalid challenge' }); } // Naive check: Does not parse raw authenticatorData bit flags (BE, BS, UV) return res.status(200).json({ authorized: true }); } ``` #### Production Standard (Correct) > **Standard**: Extracts and parses byte 32 of authenticatorData to verify User Verification (UV) and User Presence (UP), while explicitly asserting that Backup Eligibility (BE) and Backup State (BS) are false (0). This guarantees the credential is physically bound to the local secure hardware enclave. ```typescript import crypto from 'node:crypto'; import { Request, Response } from 'express'; interface AuthenticatorFlags { up: boolean; // User Present (bit 0) uv: boolean; // User Verified (bit 2) be: boolean; // Backup Eligibility (bit 3) - WebAuthn L3 bs: boolean; // Backup State (bit 4) - WebAuthn L3 } function parseAuthDataFlags(flagsByte: number): AuthenticatorFlags { return { up: (flagsByte & 0x01) !== 0, uv: (flagsByte & 0x04) !== 0, be: (flagsByte & 0x08) !== 0, bs: (flagsByte & 0x10) !== 0, }; } export async function verifyStepUpAssertion(req: Request, res: Response) { const { rawAuthenticatorDataBase64, clientDataJSONBase64, expectedTransactionHash, storedChallenge, } = req.body; const clientDataJSON = Buffer.from(clientDataJSONBase64, 'base64url'); const clientData = JSON.parse(clientDataJSON.toString('utf-8')); // 1. Validate step-up intent and anti-replay binding if (clientData.type !== 'webauthn.get' || clientData.challenge !== storedChallenge) { return res.status(403).json({ error: 'Challenge mismatch or invalid ceremony type' }); } // 2. Validate cryptographic binding to critical transaction payload if (clientData.paymentIntentHash !== expectedTransactionHash) { return res.status(403).json({ error: 'Transaction context tampering detected' }); } const authData = Buffer.from(rawAuthenticatorDataBase64, 'base64url'); if (authData.length < 37) { return res.status(400).json({ error: 'Malformed authenticatorData structure' }); } // Flags byte is byte index 32 in the authenticatorData structure const flags = parseAuthDataFlags(authData[32]); // 3. Enforce L3 Invariants: Hardware-bound, user verified, non-synced if (!flags.up || !flags.uv) { return res.status(401).json({ error: 'Direct user verification (biometric/PIN) is mandatory' }); } // Reject multi-device synced passkeys for Level 3 Step-Up operations if (flags.be || flags.bs) { return res.status(403).json({ error: 'Elevated operation requires hardware device-bound passkey; synced passkeys are forbidden', }); } return res.status(200).json({ authorized: true, assuranceLevel: 'AAL3' }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FIDO2/WebAuthn L3 Device-Bound Passkey Step-Up Attestation Standard

FIDO2/WebAuthn L3 Device-Bound Passkey Step-Up Attestation Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict validation of WebAuthn Level 3 authenticator flags (BE/BS) and hardware-backed attestation during step-up re-authentication. Blocks multi-device synced passkey replay and cross-device session extraction by ensuring privileged transactions strictly require hardware-bound secure enclave authenticators. 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 Multi-Device Synced Passkeys (BE=1) Without Attestation for High-Assurance Privileged Actions 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 Multi-Device Synced Passkeys (BE=1) Without Attestation for High-Assurance Privileged Actions	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 authenticatorData flags at the bitwise level on the server

Engineers MUST ALWAYS verify authenticatorData flags at the bitwise level on the server; never trust client-side claims regarding device binding or biometric verification.

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.