Strict WebAuthn Backup Eligibility and Attestation Boundary Enforcement

--- description: Strict WebAuthn Backup Eligibility and Attestation Boundary Enforcement - Enforces cryptographic and authenticator data verification bounds to block synchronized (multi-device) credentials on privileged administration pathways. Mandates parsing and validating the raw authenticator data byte flags, specifically asserting that Backup Eligibility (BE) and Backup State (BS) are disabled, paired with direct attestation validation. Prevents unauthorized cloud key-sync exfiltration across consumer ecosystem boundaries in zero-trust administrative planes. globs: src/**/auth/**/*.{ts,js}, src/**/webauthn/**/*.{ts,js}, src/**/security/**/*.{ts,js}, src/**/controllers/**/*.{ts,js}, src/**/services/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-backup-eligibility-boundary-production-standard" --- # Strict WebAuthn Backup Eligibility and Attestation Boundary Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Multi-Device Synced Passkeys on High-Privilege Zero-Trust Portals Without Backup-Eligibility Assertion ## System Constraints You are a Principal Security Architect enforcing FIDO2/WebAuthn level-3 zero-trust compliance standards on privileged portals. Your core invariant is strict device-bound authentication: multi-device, cloud-synced passkeys (such as iCloud Keychain or Google Password Manager sync) MUST be systematically rejected for administrative tiers. You must mandate validation of authenticatorData flags (specifically bit 3 'BE' and bit 4 'BS'), enforce enterprise attestation verification, and reject any verification pipeline that treats passkeys as fungible single-factor strings or omits binary flag checks. ## Strict Guidelines - Engineers MUST ALWAYS inspect the raw `authenticatorData` flags byte during both registration and authentication verification on privileged pathways. - Services MUST reject registration if bit 3 (Backup Eligibility / BE) is set to 1 whenever device-bound enterprise credential policies are mandated. - Services MUST reject assertion/authentication if bit 4 (Backup State / BS) is set to 1 for high-assurance administrative sessions. - Engineers MUST configure `authenticatorSelection.authenticatorAttachment` to `'cross-platform'` or evaluate specific AAGUIDs against an enterprise hardware allowlist (e.g., FIDO2 hardware security keys) when provisioning high-privilege accounts. - Engineers MUST NOT rely solely on high-level client-reported capabilities; verification MUST occur server-side against cryptographically verified attestation objects. - Components NEVER accept user-submitted public key credentials without cryptographic signature verification across clientDataJSON and authenticatorData. - Code SHOULD enforce enterprise direct attestation (`attestation: 'direct'` or `'enterprise'`) in `generateRegistrationOptions` to validate authenticating hardware provenance. ## Bad vs Good Implementations ### WebAuthn Registration Verification Flag Invariant #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default WebAuthn verification accepts multi-device syncable passkeys. In privileged infrastructure, synced passkeys violate zero-trust boundaries because private keys leave hardware security modules and sync to third-party consumer clouds. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; export async function verifyAdminPasskeyRegistration( response: RegistrationResponseJSON, expectedChallenge: string, expectedOrigin: string ) { // VULNERABLE: Only performs default validation without inspecting backup flags. // This permits multi-device synced passkeys (iCloud, Google Password Manager) on admin consoles. const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID: 'admin.internal.net', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new Error('Registration verification failed'); } return verification.registrationInfo; } ``` #### Production Standard (Correct) > **Standard**: Explicitly extracts byte offset 32 from authenticatorData, asserts bitwise flags for Backup Eligibility (0x08) and Backup State (0x10), and validates singleDevice credential status to strictly enforce hardware-bound tokens. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; const FLAG_BACKUP_ELIGIBILITY = 0x08; // Bit 3: BE (Backup Eligibility) const FLAG_BACKUP_STATE = 0x10; // Bit 4: BS (Backup State) export async function verifyAdminPasskeyRegistration( response: RegistrationResponseJSON, expectedChallenge: string, expectedOrigin: string ) { const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID: 'admin.internal.net', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new SecurityError('Registration cryptographic verification failed'); } const { authenticatorData, credentialDeviceType } = verification.registrationInfo; // Authenticator flags byte is offset 32 in authenticatorData const flags = authenticatorData[32]; const isBackupEligible = (flags & FLAG_BACKUP_ELIGIBILITY) !== 0; const isBackedUp = (flags & FLAG_BACKUP_STATE) !== 0; // Privileged portals strictly prohibit multi-device syncable credentials if (isBackupEligible || isBackedUp || credentialDeviceType !== 'singleDevice') { throw new SecurityError( 'Compliance Violation: Synced passkeys (BE/BS set) are prohibited on privileged portals. Dedicated hardware tokens required.' ); } return verification.registrationInfo; } class SecurityError extends Error { constructor(message: string) { super(message); this.name = 'SecurityError'; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Strict WebAuthn Backup Eligibility and Attestation Boundary Enforcement

Strict WebAuthn Backup Eligibility and Attestation Boundary Enforcement defines an industrial-grade behavioral standard for security engineering. Enforces cryptographic and authenticator data verification bounds to block synchronized (multi-device) credentials on privileged administration pathways. Mandates parsing and validating the raw authenticator data byte flags, specifically asserting that Backup Eligibility (BE) and Backup State (BS) are disabled, paired with direct attestation validation. Prevents unauthorized cloud key-sync exfiltration across consumer ecosystem boundaries in zero-trust administrative planes. 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 Multi-Device Synced Passkeys on High-Privilege Zero-Trust Portals Without Backup-Eligibility Assertion 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 Multi-Device Synced Passkeys on High-Privilege Zero-Trust Portals Without Backup-Eligibility Assertion	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 byte during both registration and authentication verification on privileged pathways.

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.