WebAuthn Synced Passkey Step-Up Verification and Hardware Attestation Guardrail

--- description: WebAuthn Synced Passkey Step-Up Verification and Hardware Attestation Guardrail - Enforces cryptographic step-up verification and high-assurance hardware attestation for privileged tenant operations when passkeys are synchronized across consumer clouds. Distinguishes multi-device credentials (synced passkeys with BE=1, BS=1) from device-bound security keys (single-device credentials) by inspecting authenticator data flags and attestation roots. globs: src/auth/**/*.{ts,tsx}, src/security/**/*.{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-stepup-attestation-guardrail" --- # WebAuthn Synced Passkey Step-Up Verification and Hardware Attestation Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Multi-Device Synced Consumer Passkeys for Tier-0 Privileged Tenant Operations Without Hardware Attestation ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Synced-Passkey Step-Up Device Attestation Guardrail. You must ensure that high-risk, privileged, or destructive tenant operations cannot be executed using cloud-synced passkeys (such as consumer iCloud Keychain or Google Password Manager) without explicit cryptographic step-up verification against enterprise hardware-bound authenticators. Enforce explicit inspection of authenticatorData bit flags (Backup Eligibility and Backup State), require direct attestation checks, and reject unverified or synced credential types for privileged execution paths. ## Strict Guidelines - Engineers MUST ALWAYS inspect the raw `authenticatorData` flags for Backup Eligibility (`BE`, bit 3: `0x08`) and Backup State (`BS`, bit 4: `0x10`) during authentication verification for privileged operations. - Engineers MUST NOT authorize Tier-0 operations (e.g., cryptographic key rotation, tenant deletion, IAM policy modification, federation changes) using credentials marked with `isBackupEligible = true` or `isBackedUp = true`. - Services MUST require `userVerification: 'required'` across all WebAuthn registration and authentication challenges associated with administrative escalation. - Services MUST validate and store `credentialDeviceType` ('singleDevice' vs 'multiDevice'), the credential's AAGUID, and the registration attestation statement (`packed`, `tpm`, `apple`, etc.) during enrollment. - Components NEVER accept boolean `verified === true` from WebAuthn verification libraries without asserting that the specific credential fulfills the tenant-configured assurance level (AAL3/FIDO2 hardware-bound). - Step-up challenge flows MUST regenerate a fresh cryptographic challenge (minimum 32 cryptographically secure random bytes), enforce a maximum TTL of 120 seconds, and bind the challenge directly to the user session and specific action payload. ## Bad vs Good Implementations ### Enforcing Hardware Attestation and Rejecting Synced Passkeys for Privileged Operations #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The implementation relies solely on `verification.verified`, ignoring whether the authenticator is a synced consumer passkey (iCloud Keychain, Google Password Manager) or a device-bound hardware security key. If the user's personal Apple ID or Google account is compromised, the attacker can execute irreversible tenant-level destructive operations without physical device custody. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; export async function authorizeKeyRotation(req: Request, user: any) { const { body } = req; // Flaw: Considers any valid passkey response as sufficient for Tier-0 privilege const verification = await verifyAuthenticationResponse({ response: body.assertion, expectedChallenge: user.currentChallenge, expectedOrigin: 'https://admin.enterprise.io', expectedRPID: 'enterprise.io', authenticator: user.credentials.find((c: any) => c.credentialID === body.assertion.id), }); if (verification.verified) { await rotateTenantRootKmsKeys(body.tenantId); } } ``` #### Production Standard (Correct) > **Standard**: The invariant strictly inspects the WebAuthn `authenticatorData.flags` bitmask to ensure that `BE` (0x08) and `BS` (0x10) are falsy. It verifies that the credential was verified with `userVerification: 'required'`, matches a pre-enrolled `'singleDevice'` credential, and rejects all synced consumer cloud credentials for privileged actions. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { AuthenticatorDevice } from '@simplewebauthn/types'; interface StoredEnterpriseCredential extends AuthenticatorDevice { deviceType: 'singleDevice' | 'multiDevice'; attestationFormat: string; aaguid: string; } export async function authorizeKeyRotation(req: Request, user: any) { const { body } = req; const credential = user.credentials.find( (c: StoredEnterpriseCredential) => c.credentialID === body.assertion.id ); if (!credential) { throw new SecurityError('Credential not registered for user'); } // Enforce step-up with required biometric/PIN verification const verification = await verifyAuthenticationResponse({ response: body.assertion, expectedChallenge: user.activeStepUpChallenge, expectedOrigin: 'https://admin.enterprise.io', expectedRPID: 'enterprise.io', authenticator: credential, requireUserVerification: true, }); if (!verification.verified || !verification.authenticationInfo) { throw new SecurityError('Cryptographic assertion verification failed'); } const { authenticatorData } = verification.authenticationInfo; const flags = authenticatorData.flags; // Bit 3 (0x08): Backup Eligibility (BE), Bit 4 (0x10): Backup State (BS) const isBackupEligible = Boolean(flags & 0x08); const isBackedUp = Boolean(flags & 0x10); // Guardrail: Privileged tenant operations mandate non-syncable, hardware-bound credentials if (credential.deviceType !== 'singleDevice' || isBackupEligible || isBackedUp) { throw new SecurityError( 'Privilege Escalation Blocked: Tier-0 tenant actions mandate device-bound hardware security keys.' ); } await rotateTenantRootKmsKeys(body.tenantId); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Synced Passkey Step-Up Verification and Hardware Attestation Guardrail

WebAuthn Synced Passkey Step-Up Verification and Hardware Attestation Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces cryptographic step-up verification and high-assurance hardware attestation for privileged tenant operations when passkeys are synchronized across consumer clouds. Distinguishes multi-device credentials (synced passkeys with BE=1, BS=1) from device-bound security keys (single-device credentials) by inspecting authenticator data flags and attestation roots. 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 Consumer Passkeys for Tier-0 Privileged Tenant Operations Without Hardware Attestation 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 Consumer Passkeys for Tier-0 Privileged Tenant Operations Without Hardware Attestation	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 inspect the raw `authenticatorData` flags for Backup Eligibility (`BE`, bit 3

Engineers MUST ALWAYS inspect the raw `authenticatorData` flags for Backup Eligibility (`BE`, bit 3: `0x08`) and Backup State (`BS`, bit 4: `0x10`) during authentication verification for privileged 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.