WebAuthn Synced Passkey Hardware Attestation Step-Up Standard

--- description: WebAuthn Synced Passkey Hardware Attestation Step-Up Standard - Enforces mandatory hardware-bound FIDO2 token verification invariants for high-risk operations when multi-device synced passkeys are detected. Inspects authenticatorData flags (Backup Eligibility and Backup State) and requires step-up authentication using FIDO Alliance MDS-certified, non-exportable hardware security keys. globs: src/auth/**/*.{ts,tsx}, src/server/auth/**/*.{ts,tsx}, src/services/auth/**/*.{ts,tsx}, src/api/auth/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-synced-passkey-hardware-stepup" --- # WebAuthn Synced Passkey Hardware Attestation Step-Up Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Synced Passkeys (BE=1, BS=1) to Authorize Irreversible High-Risk Operations Without Hardware Attestation Step-Up ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Synced Passkey Hardware Attestation Step-Up Standard. Mandate that all high-risk mutations (cryptographic key rotation, payment authorization, privileged IAM modifications) evaluate authenticatorData flags (Backup Eligibility 'BE' and Backup State 'BS') and reject multi-device synced credentials in favor of explicit, device-bound, hardware-attested FIDO2 tokens validated against the FIDO Alliance Metadata Service (MDS3). ## Strict Guidelines - Engineers MUST ALWAYS verify the authenticatorData flags 'backupEligible' (BE) and 'backupState' (BS) on WebAuthn assertion responses for high-risk operations. - Engineers MUST NOT allow credentials with 'flags.backupEligible === true' or 'flags.backupState === true' to authorize high-risk, irreversible operations without step-up authentication. - Code SHOULD enforce 'userVerification: required' and evaluate the 'UV' flag during both registration and assertion verification. - Services MUST query the FIDO Alliance Metadata Service (MDS3) by AAGUID to confirm physical authenticator certification (FIPS 140-2/3 or CC EAL4+) for step-up security keys. - Components NEVER accept default or none attestation ('none') when enrolling hardware security keys intended for high-risk step-up tiers. ## Bad vs Good Implementations ### Bypassing Hardware Invariants vs. Enforcing Hardware Step-Up #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The handler relies solely on verification.verified without inspecting authenticatorData flags or credential bounds. Synced passkeys (iCloud Keychain, Google Password Manager) with BE=1/BS=1 can be exported across compromised end-user ecosystems, failing to satisfy hardware-isolation invariants required for critical transactions. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; // ANTI-PATTERN: High-risk wire transfer blindly relies on any verified passkey, // ignoring whether the credential is synced (multi-device) or hardware-bound. export async function authorizeHighRiskAction( session: UserSession, authResponse: any ): Promise<void> { const verification = await verifyAuthenticationResponse({ response: authResponse, expectedChallenge: session.currentChallenge, expectedOrigin: process.env.AUTH_ORIGIN!, expectedRPID: process.env.AUTH_RPID!, authenticator: session.activeCredential, }); if (verification.verified) { await executePrivilegedWireTransfer(session.userId); } } ``` #### Production Standard (Correct) > **Standard**: Validates the UV (User Verified) flag, asserts that neither Backup Eligible (BE) nor Backup State (BS) flags are set, and verifies the AAGUID against the FIDO Metadata Service to enforce hardware-backed cryptographic isolation. ```typescript import { verifyAuthenticationResponse, VerifiedAuthenticationResponse } from '@simplewebauthn/server'; import { FidoMetadataService } from '../security/fido-mds'; import { SecurityException } from '../errors'; // PRODUCTION FIX: Enforces explicit hardware-bound validation rejecting synced passkeys. export async function authorizeHighRiskAction( session: UserSession, authResponse: any, fidoMds: FidoMetadataService ): Promise<void> { const verification: VerifiedAuthenticationResponse = await verifyAuthenticationResponse({ response: authResponse, expectedChallenge: session.stepUpChallenge, expectedOrigin: process.env.AUTH_ORIGIN!, expectedRPID: process.env.AUTH_RPID!, authenticator: session.hardwareStepUpCredential, requireUserVerification: true, }); if (!verification.verified || !verification.authenticationInfo) { throw new SecurityException('Step-up authentication failed signature verification.'); } const { flags, aaguid } = verification.authenticationInfo; // Invariant 1: Ensure User Verification (UV) was enforced by the authenticator if (!flags.userVerified) { throw new SecurityException('User Verification (UV flag) is mandatory for step-up operations.'); } // Invariant 2: Explicitly reject multi-device / synced credentials if (flags.backupEligible || flags.backupState) { throw new SecurityException('Hardware-bound invariant violated: Synced passkeys (BE/BS) cannot authorize high-risk actions.'); } // Invariant 3: Verify hardware token certification via FIDO MDS const metadata = await fidoMds.getEntryByAAGUID(aaguid); const isHardwareBound = metadata?.metadataStatement?.attestationTypes?.some( (type: string) => ['basic_full', 'attca'].includes(type) ) && metadata?.statusReports?.some((s: any) => s.status === 'FIDO_CERTIFIED_L2' || s.status === 'FIDO_CERTIFIED_L3'); if (!isHardwareBound) { throw new SecurityException(`AAGUID ${aaguid} does not meet required hardware security certification level.`); } await executePrivilegedWireTransfer(session.userId); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Synced Passkey Hardware Attestation Step-Up Standard

WebAuthn Synced Passkey Hardware Attestation Step-Up Standard defines an industrial-grade behavioral standard for security engineering. Enforces mandatory hardware-bound FIDO2 token verification invariants for high-risk operations when multi-device synced passkeys are detected. Inspects authenticatorData flags (Backup Eligibility and Backup State) and requires step-up authentication using FIDO Alliance MDS-certified, non-exportable hardware security keys. 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: Permitting Synced Passkeys (BE=1, BS=1) to Authorize Irreversible High-Risk Operations Without Hardware Attestation Step-Up 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	Permitting Synced Passkeys (BE=1, BS=1) to Authorize Irreversible High-Risk Operations Without Hardware Attestation Step-Up	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 the authenticatorData flags 'backupEligible' (BE) and 'backupState' (BS) on WebAuthn assertion responses for high-risk operations.

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.