WebAuthn L3 Enterprise Device-Bound Passkey Attestation and Anti-Sync Invariant

--- description: WebAuthn L3 Enterprise Device-Bound Passkey Attestation and Anti-Sync Invariant - Enforces strict hardware-bound WebAuthn Level 3 credentials for enterprise access by cryptographically verifying authenticator data flags and attestation statements. Explicitly rejects multi-device synced passkeys (iCloud Keychain, Google Password Manager) by verifying Backup Eligibility (BE=0) and Backup State (BS=0) alongside enterprise AAGUID allowlists. globs: src/auth/**/*.ts, src/security/**/*.ts, src/api/auth/**/*.ts, server/auth/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-l3-device-bound-passkey-attestation-invariant" --- # WebAuthn L3 Enterprise Device-Bound Passkey Attestation and Anti-Sync Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Synced Passkeys with Unchecked Backup Flags and Unvalidated AAGUIDs in Enterprise Workflows ## System Constraints You are a Principal Security Architect enforcing FIDO2/WebAuthn Level 3 enterprise invariants. You must mandate strict device-bound hardware credentials for all enterprise authentication surfaces. You must reject any registration flow that permits multi-device cloud credential synchronization (e.g., consumer passkeys synced via Apple iCloud Keychain, Google Password Manager, or Microsoft Cloud) by parsing raw authenticator data, asserting Backup Eligibility (BE) is 0, Backup State (BS) is 0, demanding direct or enterprise attestation, and asserting the AAGUID against the enterprise-approved hardware token allowlist. ## Strict Guidelines - Engineers MUST ALWAYS set `attestation: 'direct'` or `attestation: 'enterprise'` in registration options; `none` is strictly prohibited for enterprise identities. - Engineers MUST ALWAYS verify that Authenticator Data flags have `backupEligible === false` (BE=0) and `backedUp === false` (BS=0) during registration verification. - Engineers MUST NOT accept any credential registration whose AAGUID is zeroed out (00000000-0000-0000-0000-000000000000) or missing from the corporate hardware security token registry. - Services MUST cryptographically validate the x5c attestation certificate chain up to a trusted enterprise Root CA or FIDO Metadata Service (MDS) hardware root. - Components NEVER persist credentials with transports containing cloud-sync profiles or unverified hybrid capabilities without enforcing explicit hardware-bound validation. ## Bad vs Good Implementations ### Verifying Device-Bound Invariant and Rejecting Synced Passkeys #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code fails to inspect authenticator data flags for Backup Eligibility (BE) and Backup State (BS), accepts 'none' attestation, and ignores the AAGUID. As a result, a user can register an iCloud/Google multi-device passkey that automatically exfiltrates corporate credentials to unmanaged consumer cloud environments. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; export async function verifyPasskeyRegistration( response: RegistrationResponseJSON, expectedChallenge: string, expectedOrigin: string ) { // VULNERABLE: Default validation accepts multi-device synced passkeys // and attestation: 'none', allowing consumer cloud exfiltration. const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID: 'enterprise.internal.net', }); if (!verification.verified || !verification.registrationInfo) { throw new Error('Registration failed'); } // CRITICAL SECURITY FLAW: Ignores backup flags and hardware AAGUID. // This permits credentials to sync to personal unmanaged mobile devices. return { credentialId: verification.registrationInfo.credentialID, publicKey: verification.registrationInfo.credentialPublicKey, }; } ``` #### Production Standard (Correct) > **Standard**: The updated implementation strictly checks `flags.backupEligible` and `flags.backedUp`, immediately aborting registration if the passkey can synchronize to consumer clouds. It further enforces enterprise compliance by validating the hardware AAGUID against an approved FIDO2 inventory allowlist. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; // Enterprise-managed FIDO2 Level 3 Hardware AAGUIDs (e.g., YubiKey 5 FIPS, Titan FIDO2) const ENTERPRISE_APPROVED_AAGUIDS: ReadonlySet<string> = new Set([ 'ee88270e-540c-47db-beff-32b704c35588', 'fa2b99dc-9e39-4257-8f92-4a30d23c4118', ]); export async function verifyDeviceBoundPasskeyRegistration( response: RegistrationResponseJSON, expectedChallenge: string, expectedOrigin: string ) { const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID: 'enterprise.internal.net', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new SecurityError('Cryptographic registration verification failed'); } const { flags, aaguid, attestationObject } = verification.registrationInfo; // INVARIANT 1: Strict rejection of synced/backup-capable passkeys // Bit 3 (BE) and Bit 4 (BS) in Authenticator Data MUST be zero. if (flags.backupEligible || flags.backedUp) { throw new SecurityError( 'Rejected: Enterprise invariant violation. Multi-device synced passkeys are forbidden; device-bound hardware required.' ); } // INVARIANT 2: Authenticator Attestation GUID must match enterprise hardware registry if (!ENTERPRISE_APPROVED_AAGUIDS.has(aaguid)) { throw new SecurityError( `Rejected: Unauthorized authenticator model AAGUID: ${aaguid}. Must be enterprise-managed FIDO2 hardware.` ); } // INVARIANT 3: Ensure non-empty attestation certificate chain for cryptographic audit if (!attestationObject || attestationObject.length === 0) { throw new SecurityError('Rejected: Missing cryptographic enterprise attestation payload.'); } return { credentialId: verification.registrationInfo.credentialID, publicKey: verification.registrationInfo.credentialPublicKey, counter: verification.registrationInfo.counter, deviceBound: true, aaguid, }; } class SecurityError extends Error { constructor(message: string) { super(message); this.name = 'SecurityError'; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn L3 Enterprise Device-Bound Passkey Attestation and Anti-Sync Invariant

WebAuthn L3 Enterprise Device-Bound Passkey Attestation and Anti-Sync Invariant defines an industrial-grade behavioral standard for security engineering. Enforces strict hardware-bound WebAuthn Level 3 credentials for enterprise access by cryptographically verifying authenticator data flags and attestation statements. Explicitly rejects multi-device synced passkeys (iCloud Keychain, Google Password Manager) by verifying Backup Eligibility (BE=0) and Backup State (BS=0) alongside enterprise AAGUID allowlists. 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 with Unchecked Backup Flags and Unvalidated AAGUIDs in Enterprise Workflows 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 with Unchecked Backup Flags and Unvalidated AAGUIDs in Enterprise Workflows	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 set `attestation

Engineers MUST ALWAYS set `attestation: 'direct'` or `attestation: 'enterprise'` in registration options; `none` is strictly prohibited for enterprise identities.

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.