FIDO2 Enterprise Attestation and Hardware-Bound AAGUID Enforcement

Enforces strict cryptographic guarantees against multi-device cloud-synced passkeys on high-privilege IAM scopes. Mandates direct or enterprise WebAuthn attestation verification, explicit FIDO Alliance Metadata Service (MDS3) AAGUID allowlisting, and verification that credential backup eligibility (BE) and backup state (BS) flags are strictly zero. Guarantees that only physical, non-exportable hardware authenticators (e.g., YubiKey, Google Titan) can access enterprise-tier administrative operations.

--- description: FIDO2 Enterprise Attestation and Hardware-Bound AAGUID Enforcement - Enforces strict cryptographic guarantees against multi-device cloud-synced passkeys on high-privilege IAM scopes. Mandates direct or enterprise WebAuthn attestation verification, explicit FIDO Alliance Metadata Service (MDS3) AAGUID allowlisting, and verification that credential backup eligibility (BE) and backup state (BS) flags are strictly zero. Guarantees that only physical, non-exportable hardware authenticators (e.g., YubiKey, Google Titan) can access enterprise-tier administrative operations. globs: src/**/auth/**/*.ts, src/**/iam/**/*.ts, src/**/webauthn/**/*.ts, server/auth/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fido2-enterprise-attestation-aaguid-mandate" --- # FIDO2 Enterprise Attestation and Hardware-Bound AAGUID Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Synced Multi-Device Passkeys with 'none' Attestation in High-Privilege Workflows ## System Constraints You are a Principal Security Architect enforcing zero-trust FIDO2 device-bound authenticators. Multi-device synced passkeys (e.g., Apple iCloud Keychain, Google Password Manager) expose high-privilege IAM roles to account hijacking via consumer cloud compromise. You must reject any WebAuthn registration or authentication flow for privileged scopes that fails to enforce: (1) enterprise/direct attestation conveyances, (2) cryptographic validation of the AAGUID against an enterprise-approved hardware allowlist, (3) assertion of authenticatorData flags rejecting Backup Eligibility (BE=0) and Backup State (BS=0), and (4) strict userVerification='required'. ## Strict Guidelines - Engineers MUST ALWAYS set `attestation: 'enterprise'` (or `'direct'`) and `userVerification: 'required'` in WebAuthn registration options for privileged administrative roles. - Engineers MUST ALWAYS enforce `authenticatorAttachment: 'cross-platform'` in registration options to prevent binding to unmanaged platform authenticators. - Engineers MUST verify the `authenticatorData` flags on both registration and authentication, strictly rejecting credentials where `flags.backupEligibility` (BE, bit 3) is true or `flags.backupState` (BS, bit 4) is true for high-privilege roles. - Services MUST extract the 16-byte AAGUID from `authData.attestedCredentialData` during registration and validate it against a cryptographically verified enterprise hardware allowlist (e.g., FIDO MDS3 certified Level 2+ devices). - Services MUST reject the zero-value AAGUID (`00000000-0000-0000-0000-000000000000`) and unverified self-attestation formats (`packed` self, `fido-u2f` without valid x5c chain, or `none`). - Components NEVER store or trust passkey registrations for administrative scopes without persisting the attested AAGUID, attestation certificate thumbprint, and device-bound flag. ## Bad vs Good Implementations ### Registration Options Generation & Attestation Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Configuring attestationType as 'none' and requireUserVerification as false permits multi-device cloud-synced passkeys to register for administrative access. It leaves the RP blind to whether the key is hardware-bound (YubiKey) or synced across consumer devices, violating hardware-bound IAM invariants. ```typescript import { generateRegistrationOptions, verifyRegistrationResponse } from '@simplewebauthn/server'; export async function registerAdminPasskey(user: User, response: any, expectedChallenge: string) { // VULNERABLE: Accepts any passkey (including iCloud/Google sync passkeys) // Missing enterprise attestation, allows platform passkeys, ignores backup flags const options = await generateRegistrationOptions({ rpName: 'Acme Corp Admin', rpID: 'admin.acme.com', userID: user.id, userName: user.email, attestationType: 'none', // Critical vulnerability: strips hardware provenance }); const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin: 'https://admin.acme.com', expectedRPID: 'admin.acme.com', requireUserVerification: false, // Insecure }); if (verification.verified && verification.registrationInfo) { await db.savePasskey({ userId: user.id, credentialId: verification.registrationInfo.credentialID }); } } ``` #### Production Standard (Correct) > **Standard**: Forces enterprise attestation conveyance, cross-platform hardware tokens, and user verification. It verifies that flags.backupEligibility and flags.backupState are false, actively blocking synced passkeys, and enforces that the AAGUID belongs to an enterprise-approved hardware token. ```typescript import { generateRegistrationOptions, verifyRegistrationResponse, VerifiedRegistrationResponse } from '@simplewebauthn/server'; // Enterprise-approved hardware authenticators (e.g., YubiKey 5 Series FIPS / NFC) const APPROVED_ENTERPRISE_AAGUIDS = new Set<string>([ 'ee882879-721c-4916-acfe-6ef701547707', // YubiKey 5 Series 'cb69481e-8ff7-4039-93ec-0a2729a100ae', // YubiKey 5 FIPS ]); export async function getAdminRegistrationOptions(user: User): Promise<PublicKeyCredentialCreationOptionsJSON> { return generateRegistrationOptions({ rpName: 'Acme Enterprise IAM', rpID: 'iam.internal.acme.com', userID: Buffer.from(user.id, 'utf-8'), userName: user.email, attestationType: 'enterprise', authenticatorSelection: { authenticatorAttachment: 'cross-platform', residentKey: 'required', userVerification: 'required', }, }); } export async function verifyAdminPasskeyRegistration( response: RegistrationResponseJSON, expectedChallenge: string ): Promise<void> { const verification: VerifiedRegistrationResponse = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin: 'https://iam.internal.acme.com', expectedRPID: 'iam.internal.acme.com', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new SecurityException('WebAuthn cryptographic verification failed'); } const { aaguid, flags } = verification.registrationInfo; // Invariant 1: Ensure passkey is strictly device-bound (non-syncable) // BE = Backup Eligibility, BS = Backup State. Both MUST be false. if (flags.backupEligibility || flags.backupState) { throw new SecurityException('Synced/Multi-device passkeys prohibited on privileged IAM roles. Hardware-bound key required.'); } // Invariant 2: Hardware provenance verification via enterprise AAGUID allowlist if (!aaguid || !APPROVED_ENTERPRISE_AAGUIDS.has(aaguid)) { throw new SecurityException(`Authenticator AAGUID ${aaguid} is not on the enterprise-approved hardware allowlist.`); } await db.saveAdminPasskey({ userId: response.id, credentialId: verification.registrationInfo.credentialID, publicKey: verification.registrationInfo.credentialPublicKey, counter: verification.registrationInfo.counter, aaguid, isDeviceBound: true, }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FIDO2 Enterprise Attestation and Hardware-Bound AAGUID Enforcement

FIDO2 Enterprise Attestation and Hardware-Bound AAGUID Enforcement defines an industrial-grade behavioral standard for security engineering. Enforces strict cryptographic guarantees against multi-device cloud-synced passkeys on high-privilege IAM scopes. Mandates direct or enterprise WebAuthn attestation verification, explicit FIDO Alliance Metadata Service (MDS3) AAGUID allowlisting, and verification that credential backup eligibility (BE) and backup state (BS) flags are strictly zero. Guarantees that only physical, non-exportable hardware authenticators (e.g., YubiKey, Google Titan) can access enterprise-tier administrative operations. 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 Multi-Device Passkeys with 'none' Attestation in High-Privilege 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 Multi-Device Passkeys with 'none' Attestation in High-Privilege 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: 'enterprise'` (or `'direct'`) and `userVerification: 'required'` in WebAuthn registration options for privileged administrative roles.

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.