WebAuthn L3 Backup State Assertion & Device-Bound Token Enforcement

--- description: WebAuthn L3 Backup State Assertion & Device-Bound Token Enforcement - Enforces strict discrimination between multi-device synced passkeys and hardware-bound passkeys using WebAuthn Level 3 AuthenticatorData Backup Eligibility (BE) and Backup State (BS) flags. Prevents privilege escalation and session exportability on high-assurance operations (e.g., step-up authentication, cryptographic key authorization, admin actions) by cryptographically guaranteeing credentials cannot leave their initial physical Secure Element or FIPS-validated enclave. globs: src/auth/**/*.{ts,tsx}, src/security/**/*.{ts,tsx}, src/server/auth/**/*.{ts,tsx}, src/services/webauthn/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-l3-backup-state-device-bound-enforcement" --- # WebAuthn L3 Backup State Assertion & Device-Bound Token Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting generic WebAuthn credentials for high-assurance actions without validating BE/BS flags, allowing synced passkeys to bypass physical hardware requirements. ## System Constraints You are a Principal Security Architect specializing in FIDO2/WebAuthn Level 3 specifications. Enforce strict cryptographic validation of AuthenticatorData flags (Backup Eligibility `BE` and Backup State `BS`). Any high-assurance action (tier-1 admin, cryptographic signing, fund transfer, elevated permission assignment) MUST mandate hardware-bound (single-device) credentials by asserting `flags.BE === false` and `flags.BS === false`. Ensure multi-device credentials (synced passkeys) are never allowed into high-assurance execution paths. ## Strict Guidelines - Engineers MUST ALWAYS inspect AuthenticatorData bit flags at byte offset 32: bit index 3 (mask 0x08) for Backup Eligibility (BE) and bit index 4 (mask 0x10) for Backup State (BS). - Engineers MUST NOT permit operations flagged with High Assurance (FIPS 140-3, step-up auth, admin console access) to succeed if the WebAuthn credential has `flags.BE === true` or `flags.BS === true`. - Services MUST record and persist `credentialDeviceType` ('singleDevice' vs 'multiDevice') at registration by checking `BE === 0` (single-device) or `BE === 1` (multi-device). - Services MUST reject authentication if `flags.BS === true` while `flags.BE === false` as this violates the WebAuthn L3 specification invariant. - Components NEVER assume `authenticatorAttachment: 'cross-platform'` guarantees a non-synced hardware token; attachment modality does not prevent multi-device ecosystem passkeys from responding over CTAP2/FIDO. ## Bad vs Good Implementations ### WebAuthn L3 AuthData Flag Verification for High-Assurance Endpoints #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code blindly verifies the cryptographic signature without checking the WebAuthn L3 BE (Backup Eligibility) or BS (Backup State) flags. A synced multi-device passkey exportable to consumer cloud backends is mistakenly accepted for an elevated action requiring physical tamper-resistant hardware. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; export async function verifyElevatedAction( response: any, expectedChallenge: string, userCredential: { publicKey: Buffer; currentCounter: number } ) { // VULNERABLE: Only checks cryptographic signature and user presence // Synced passkeys (iCloud Keychain, Google Password Manager) pass this check, // violating device-bound security requirements for high-assurance endpoints. const verification = await verifyAuthenticationResponse({ response, expectedChallenge, expectedOrigin: 'https://admin.enterprise.io', expectedRPID: 'enterprise.io', authenticator: { credentialPublicKey: userCredential.publicKey, credentialID: response.id, counter: userCredential.currentCounter, }, requireUserVerification: true, }); if (!verification.verified) { throw new Error('Authentication failed'); } return { success: true }; } ``` #### Production Standard (Correct) > **Standard**: The code extracts byte 32 of `authenticatorData` and validates the WebAuthn L3 `BE` and `BS` bitmasks. If either is set, the passkey is backed up or eligible for cloud syncing, and the request is rejected with a policy violation error before privileged operations execute. ```typescript import { verifyAuthenticationResponse, VerifiedAuthenticationResponse } from '@simplewebauthn/server'; // WebAuthn L3 AuthenticatorData Flag Masks const AUTH_DATA_FLAG_MASK = { UP: 0x01, // User Present UV: 0x04, // User Verified BE: 0x08, // Backup Eligibility (L3) BS: 0x10, // Backup State (L3) } as const; interface HighAssuranceVerificationResult { verified: boolean; isDeviceBoundHardware: boolean; newCounter: number; } export async function verifyHighAssuranceAction( response: any, expectedChallenge: string, userCredential: { publicKey: Buffer; currentCounter: number } ): Promise<HighAssuranceVerificationResult> { const verification: VerifiedAuthenticationResponse = await verifyAuthenticationResponse({ response, expectedChallenge, expectedOrigin: 'https://admin.enterprise.io', expectedRPID: 'enterprise.io', authenticator: { credentialPublicKey: userCredential.publicKey, credentialID: response.id, counter: userCredential.currentCounter, }, requireUserVerification: true, }); if (!verification.verified || !verification.authenticationInfo) { throw new Error('WebAuthn signature verification failed'); } const { authenticatorData } = verification.authenticationInfo; // Authenticator data flags byte is located at index 32 const flagsByte = authenticatorData[32]; const isBackupEligible = (flagsByte & AUTH_DATA_FLAG_MASK.BE) !== 0; const isBackedUp = (flagsByte & AUTH_DATA_FLAG_MASK.BS) !== 0; // Invariant Violation Check: A non-backup-eligible key cannot be backed up if (!isBackupEligible && isBackedUp) { throw new Error('Malformed AuthenticatorData: BS asserted without BE'); } // High-assurance policy enforcement: Reject all multi-device synced passkeys if (isBackupEligible || isBackedUp) { throw new Error( 'Security Policy Violation: High-assurance actions require a non-exportable, hardware-bound passkey (BE=0, BS=0). Synced passkeys are rejected.' ); } return { verified: true, isDeviceBoundHardware: true, newCounter: verification.authenticationInfo.newCounter, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn L3 Backup State Assertion & Device-Bound Token Enforcement

WebAuthn L3 Backup State Assertion & Device-Bound Token Enforcement defines an industrial-grade behavioral standard for security engineering. Enforces strict discrimination between multi-device synced passkeys and hardware-bound passkeys using WebAuthn Level 3 AuthenticatorData Backup Eligibility (BE) and Backup State (BS) flags. Prevents privilege escalation and session exportability on high-assurance operations (e.g., step-up authentication, cryptographic key authorization, admin actions) by cryptographically guaranteeing credentials cannot leave their initial physical Secure Element or FIPS-validated enclave. 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 generic WebAuthn credentials for high-assurance actions without validating BE/BS flags, allowing synced passkeys to bypass physical hardware requirements. 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 generic WebAuthn credentials for high-assurance actions without validating BE/BS flags, allowing synced passkeys to bypass physical hardware requirements.	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 AuthenticatorData bit flags at byte offset 32

Engineers MUST ALWAYS inspect AuthenticatorData bit flags at byte offset 32: bit index 3 (mask 0x08) for Backup Eligibility (BE) and bit index 4 (mask 0x10) for 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.