Mandatory Step-Up Attestation for WebAuthn L3 Synced Passkeys in High-Privilege Contexts

--- description: Mandatory Step-Up Attestation for WebAuthn L3 Synced Passkeys in High-Privilege Contexts - Enforces strict server-side evaluation of WebAuthn authenticator data flags (flags.be and flags.bs) alongside enterprise attestation formats during high-privilege operations. Synced multi-device credentials (cloud-backed passkeys) must trigger immediate step-up verification or hardware-bound device-bound credential re-authentication to prevent unauthorized execution via synchronized credential compromise. globs: src/**/auth/**/*.ts, src/**/webauthn/**/*.ts, src/**/guards/**/*.ts, src/**/controllers/**/*auth*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-l3-backup-state-step-up-attestation" --- # Mandatory Step-Up Attestation for WebAuthn L3 Synced Passkeys in High-Privilege Contexts > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Multi-Device Synced Passkeys for Critical Operations Without Verifying Backup State Flags ## System Constraints You are a Principal Security Architect specializing in FIDO2 and WebAuthn Level 3 specifications. Your task is to enforce mandatory step-up challenge workflows and policy enforcement whenever WebAuthn authenticator flags indicate synchronized multi-device cloud backup (BE=1, BS=1) during high-privilege operations, disallowing bypass of hardware-bound attestation guarantees. ## Strict Guidelines - Engineers MUST ALWAYS parse and validate the Authenticator Data bit flags: specifically bit 3 (Backup Eligibility, BE) and bit 4 (Backup State, BS). - Engineers MUST NOT authorize high-privilege mutations (e.g., fund transfers, credential revocation, role elevation) using credentials where Backup State (BS) is true without executing an explicit step-up verification. - Services MUST enforce 'authenticatorAttachment: platform' with hardware-bound attestation checks when creating credentials destined for high-assurance administrative scopes. - Verification routines MUST verify that the clientDataJSON challenge matches an unexpired, cryptographically secure server nonce stored in an ephemeral, single-use session store. - Components NEVER treat a synced cloud passkey (flags.bs === true) as equivalent to a device-bound hardware token (e.g., FIDO2 Level 3 physical security key with AAGUID validation). ## Bad vs Good Implementations ### Enforcing Backup State Step-Up on High-Privilege WebAuthn Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code fails to inspect the authenticator data flags (BE and BS) returned in the verification info. If a synced passkey is compromised across multi-device iCloud Keychain or Google Password Manager sync pools, high-privilege actions are executed without secondary step-up or hardware boundary checks. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { AuthenticationResponseJSON } from '@simplewebauthn/types'; export async function verifyPrivilegedAction( response: AuthenticationResponseJSON, expectedChallenge: string, expectedOrigin: string, expectedRPID: string, credentialPublicKey: Uint8Array, currentCounter: number ) { // Anti-pattern: Blindly verifies assertion signature without evaluating backup flags const verification = await verifyAuthenticationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID, authenticator: { credentialID: response.id, credentialPublicKey, counter: currentCounter, }, }); if (!verification.verified) { throw new Error('Authentication failed'); } // Security Flaw: Permits execution even if the passkey is synced across unauthorized cloud accounts return { success: true }; } ``` #### Production Standard (Correct) > **Standard**: The corrected implementation inspects authenticationInfo.flags.backupState. If the credential is in a synced backup state and the action is privileged, it halts execution by throwing a StepUpRequiredError, safeguarding critical assets against compromised cloud sync fabrics. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { AuthenticationResponseJSON } from '@simplewebauthn/types'; export class StepUpRequiredError extends Error { constructor(message: string) { super(message); this.name = 'StepUpRequiredError'; } } export async function verifyPrivilegedAction( response: AuthenticationResponseJSON, expectedChallenge: string, expectedOrigin: string, expectedRPID: string, credentialPublicKey: Uint8Array, currentCounter: number, isHighPrivilegeContext: boolean ) { const verification = await verifyAuthenticationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID, authenticator: { credentialID: response.id, credentialPublicKey, counter: currentCounter, }, requireUserVerification: true, }); if (!verification.verified || !verification.authenticationInfo) { throw new Error('WebAuthn cryptographic verification failed'); } const { flags } = verification.authenticationInfo; const isBackedUp = flags.backupState; // Bit 4: BS flag const isBackupEligible = flags.backupEligibility; // Bit 3: BE flag if (isHighPrivilegeContext && isBackedUp) { // Invariant: Synced passkeys cannot perform zero-friction privileged operations. // Enforce step-up hardware attestation or out-of-band TOTP/mTLS challenge. throw new StepUpRequiredError( 'Operation requires hardware-bound credential; multi-device synced passkey detected.' ); } return { success: true, isDeviceBound: !isBackupEligible && !isBackedUp, counter: verification.authenticationInfo.newCounter, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory Step-Up Attestation for WebAuthn L3 Synced Passkeys in High-Privilege Contexts

Mandatory Step-Up Attestation for WebAuthn L3 Synced Passkeys in High-Privilege Contexts defines an industrial-grade behavioral standard for security engineering. Enforces strict server-side evaluation of WebAuthn authenticator data flags (flags.be and flags.bs) alongside enterprise attestation formats during high-privilege operations. Synced multi-device credentials (cloud-backed passkeys) must trigger immediate step-up verification or hardware-bound device-bound credential re-authentication to prevent unauthorized execution via synchronized credential compromise. 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 for Critical Operations Without Verifying Backup State Flags 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 for Critical Operations Without Verifying Backup State Flags	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 parse and validate the Authenticator Data bit flags

Engineers MUST ALWAYS parse and validate the Authenticator Data bit flags: specifically bit 3 (Backup Eligibility, BE) and bit 4 (Backup State, BS).

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.