Enforce WebAuthn Device-Bound Enterprise Attestation & Sync Segregation

--- description: Enforce WebAuthn Device-Bound Enterprise Attestation & Sync Segregation - Enforces strict segregation between multi-device synced passkeys and device-bound hardware credentials for Tier-0 administrative operations. Mandates verification of the WebAuthn authenticatorData backup flags (BE/BS), explicit AAGUID enterprise allowlisting, and cryptographic attestation signature validation to prevent synched credentials from satisfying high-privilege access tiers. globs: src/auth/**/*.{ts,tsx}, src/services/webauthn/**/*.{ts,tsx}, src/server/security/**/*.{ts,tsx}, lib/auth/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-device-bound-enterprise-attestation-sync-segregation" --- # Enforce WebAuthn Device-Bound Enterprise Attestation & Sync Segregation > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Multi-Device Synced Passkeys to Register or Authorize Tier-0 Privileged Actions Without Attestation Flag Validation ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Device-Bound Enterprise Attestation & Passkey Sync Segregation Invariant. Multi-device synced passkeys (such as iCloud Keychain or Google Password Manager) must never be permitted to satisfy Tier-0 administrative thresholds. You must enforce strict inspection of authenticatorData flags (Backup Eligibility 'BE' bit 3, Backup State 'BS' bit 4), validate direct/enterprise x5c attestation certificate chains against FIDO MDS or corporate enterprise roots, and reject any credential with BE=1 or non-allowlisted AAGUIDs for high-assurance security tiers. ## Strict Guidelines - Engineers MUST ALWAYS inspect the raw `authenticatorData` bitfield to verify bit 3 (BE - Backup Eligibility) is strictly 0 and bit 4 (BS - Backup State) is strictly 0 for all Tier-0 credential registrations. - Engineers MUST ALWAYS demand 'direct' or 'enterprise' attestation conveyance (`attestation: 'enterprise' | 'direct'`) when generating registration options for Tier-0 credentials. - Engineers MUST NOT accept self-attestation ('none') or multi-device passkeys (`flags.backupEligible === true`) for privileged operational scopes, root-level administration, or break-glass workflows. - Services MUST validate the AAGUID extracted from the authData payload against an authoritative hardware allowlist (e.g., FIPS 140-3 Level 3 YubiKeys) before recording credential metadata. - Services MUST verify the X.509 attestation certificate chain (`x5c`) against trusted FIDO Alliance Metadata Service (MDS3) root anchors or enterprise internal PKI trust roots. - Components NEVER store or authorize Tier-0 credentials in unified user tables without a cryptographically attested, immutable `authenticatorAttachment: 'cross-platform'` and `isDeviceBound: true` constraint. ## Bad vs Good Implementations ### Tier-0 WebAuthn Registration Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The implementation ignores attestation type and fails to evaluate the authenticatorData flags. Synced multi-device passkeys (BE=1, BS=1) and soft-tokens are accepted into Tier-0 credential storage, violating hardware-bound segregation and exposing administrative surfaces to multi-device sync compromise. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; export async function registerTier0Credential(body: any, expectedChallenge: string) { // VULNERABLE: Accepts any authenticator without checking backup flags or attestation const verification = await verifyRegistrationResponse({ response: body, expectedChallenge, expectedOrigin: 'https://admin.enterprise.internal', expectedRPID: 'enterprise.internal', }); if (!verification.verified || !verification.registrationInfo) { throw new Error('Registration failed'); } // Multi-device synced passkey (iCloud, Google) can be registered as Tier-0 await db.credentials.create({ data: { credentialId: verification.registrationInfo.credentialID, publicKey: verification.registrationInfo.credentialPublicKey, tier: 'TIER_0', }, }); } ``` #### Production Standard (Correct) > **Standard**: Cryptographically enforces hardware segregation by validating that `flags.backupEligible` and `flags.backupState` are false (BE=0, BS=0), ensuring the token is physically bound to the hardware device. Rejects 'none' attestation and mandates strict membership within an enterprise-controlled AAGUID allowlist. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; // Enterprise-approved hardware AAGUIDs (e.g., YubiKey 5 Series / FIPS) const APPROVED_TIER0_AAGUIDS = new Set<string>([ 'ee882879-721c-4916-ad4e-a05c7082fbab', // YubiKey 5 NFC FIPS '2fc0579f-8113-47ea-b116-e82db9354044', // YubiKey 5C NFC FIPS ]); export async function registerTier0Credential(body: any, expectedChallenge: string) { const verification = await verifyRegistrationResponse({ response: body, expectedChallenge, expectedOrigin: 'https://admin.enterprise.internal', expectedRPID: 'enterprise.internal', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new SecurityError('WebAuthn verification failed'); } const { flags, aaguid, attestationObject } = verification.registrationInfo; // INVARIANT 1: Must NOT be eligible for cloud synchronization (BE bit MUST be 0) if (flags.backupEligible || flags.backupState) { throw new SecurityError('Tier-0 credentials MUST be device-bound. Multi-device synced passkeys are prohibited.'); } // INVARIANT 2: Authenticator must match enterprise-approved hardware token AAGUIDs if (!APPROVED_TIER0_AAGUIDS.has(aaguid)) { throw new SecurityError(`AAGUID ${aaguid} is not authorized for Tier-0 hardware binding.`); } // INVARIANT 3: Attestation statement must be direct/enterprise, not 'none' if (verification.registrationInfo.attestationObjectFormat === 'none') { throw new SecurityError('Cryptographic attestation required for Tier-0; self-attestation rejected.'); } await db.credentials.create({ data: { credentialId: verification.registrationInfo.credentialID, publicKey: verification.registrationInfo.credentialPublicKey, counter: verification.registrationInfo.counter, aaguid, isDeviceBound: true, tier: 'TIER_0', }, }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Enforce WebAuthn Device-Bound Enterprise Attestation & Sync Segregation

Enforce WebAuthn Device-Bound Enterprise Attestation & Sync Segregation defines an industrial-grade behavioral standard for security engineering. Enforces strict segregation between multi-device synced passkeys and device-bound hardware credentials for Tier-0 administrative operations. Mandates verification of the WebAuthn authenticatorData backup flags (BE/BS), explicit AAGUID enterprise allowlisting, and cryptographic attestation signature validation to prevent synched credentials from satisfying high-privilege access tiers. 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 to Register or Authorize Tier-0 Privileged Actions Without Attestation Flag Validation 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 to Register or Authorize Tier-0 Privileged Actions Without Attestation Flag Validation	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` bitfield to verify bit 3 (BE - Backup Eligibility) is strictly 0 and bit 4 (BS - Backup State) is strictly 0 for all Tier-0 credential registrations.

Engineers MUST ALWAYS inspect the raw `authenticatorData` bitfield to verify bit 3 (BE - Backup Eligibility) is strictly 0 and bit 4 (BS - Backup State) is strictly 0 for all Tier-0 credential registrations.

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.