Mandatory Hardware-Bound Attestation and Authenticator Attachment Validation for Enterprise Passkeys

Enforces strict FIDO2/WebAuthn Level 3 enterprise attestation verification, requiring direct or enterprise attestation statements and hardware authenticator flags. Prevents the enrollment and assertion of multi-device synchronized passkeys (e.g., iCloud Keychain, Google Password Manager) for administrative and zero-trust tiers by cryptographically validating AAGUID against an approved enterprise hardware registry and verifying the backup eligibility (BE) and backup state (BS) credential flags.

--- description: Mandatory Hardware-Bound Attestation and Authenticator Attachment Validation for Enterprise Passkeys - Enforces strict FIDO2/WebAuthn Level 3 enterprise attestation verification, requiring direct or enterprise attestation statements and hardware authenticator flags. Prevents the enrollment and assertion of multi-device synchronized passkeys (e.g., iCloud Keychain, Google Password Manager) for administrative and zero-trust tiers by cryptographically validating AAGUID against an approved enterprise hardware registry and verifying the backup eligibility (BE) and backup state (BS) credential flags. globs: src/auth/**/*.{ts,tsx}, src/server/auth/**/*.{ts,tsx}, src/services/webauthn/**/*.{ts,tsx}, src/api/auth/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-l3-passkey-enterprise-attestation-boundary" --- # Mandatory Hardware-Bound Attestation and Authenticator Attachment Validation for Enterprise Passkeys > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting 'none' attestation or missing flags allows soft/synced passkeys on high-privilege enterprise boundary endpoints ## System Constraints You are a Principal Security Architect enforcing FIDO Alliance WebAuthn Level 3 Passkey Enterprise Attestation Boundaries. You must mandate strict cryptographic attestation parsing, verify authenticator attachment guarantees, and strictly forbid fallback to unauthenticated or synchronized passkeys for privileged roles. Reject any registration pipeline that accepts 'none' attestation, permits backup eligibility (BE=1), or bypasses AAGUID enterprise allowlist checks. ## Strict Guidelines - Engineers MUST ALWAYS enforce 'attestation: direct' or 'attestation: enterprise' in PublicKeyCredentialCreationOptions for privileged access levels. - Engineers MUST NEVER accept 'attestation: none' during administrative credential registration or permit attestation format fallback to unverified self-attestation. - Services MUST inspect authenticator data flags to verify the credential is bound to a single hardware token by asserting Backup Eligibility (BE flag bit 3) is 0 and Backup State (BS flag bit 4) is 0. - Services MUST extract the Authenticator Attestation GUID (AAGUID) from authData and validate it against an immutable enterprise allowlist of FIDO L3 certified hardware authenticators (e.g., YubiKey 5 Series). - Components NEVER store or trust passkey public keys without validating the entire attestation certificate chain back to an embedded or FIDO Metadata Service (MDS) trusted root certificate. ## Bad vs Good Implementations ### Registration Options and Attestation Verification Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The registration options request 'none' attestation instead of 'direct' or 'enterprise'. The verification handler omits AAGUID validation against a trusted hardware registry and fails to check the BE (Backup Eligibility) and BS (Backup State) flags, permitting extractable or cloud-synced passkeys into a zero-trust administrative tier. ```typescript import { generateRegistrationOptions, verifyRegistrationResponse } from '@simplewebauthn/server'; import type { Request, Response } from 'express'; export async function getAdminRegistrationOptions(req: Request, res: Response) { const user = req.user; // Flaw: Accepts 'none' attestation, no authenticatorAttachment enforcement, // allowing synced passkeys (iCloud/Google) for enterprise admin access. const options = await generateRegistrationOptions({ rpName: 'Enterprise Admin Portal', rpID: 'admin.enterprise.internal', userID: Buffer.from(user.id), userName: user.email, attestationType: 'none', }); res.json(options); } export async function verifyAdminRegistration(req: Request, res: Response) { const { credential, expectedChallenge } = req.body; const verification = await verifyRegistrationResponse({ response: credential, expectedChallenge, expectedOrigin: 'https://admin.enterprise.internal', expectedRPID: 'admin.enterprise.internal', requireUserVerification: true, }); // Flaw: Ignores AAGUID allowlisting and flags (BE/BS), allowing soft/synced passkeys. if (!verification.verified || !verification.registrationInfo) { return res.status(400).json({ error: 'Verification failed' }); } return res.json({ status: 'ok' }); } ``` #### Production Standard (Correct) > **Standard**: Explicitly requests 'direct' attestation and 'cross-platform' authenticator attachment. During verification, it strictly enforces that Backup Eligibility (flags.backupEligibility) and Backup State (flags.backupState) are false, and ensures the AAGUID is registered in an enterprise-approved hardware allowlist. ```typescript import { generateRegistrationOptions, verifyRegistrationResponse } from '@simplewebauthn/server'; import type { Request, Response } from 'express'; const ENTERPRISE_APPROVED_AAGUIDS: ReadonlySet<string> = new Set([ 'ee882879-721c-4913-9775-3dfcce97072a', // YubiKey 5 Series NFC (FIPS) 'cb94e2b3-a439-4507-beab-61cd94364299', // YubiKey 5 Series Lightning ]); export async function getAdminRegistrationOptions(req: Request, res: Response) { const user = req.user; const options = await generateRegistrationOptions({ rpName: 'Enterprise Admin Portal', rpID: 'admin.enterprise.internal', userID: Buffer.from(user.id), userName: user.email, attestationType: 'direct', authenticatorSelection: { authenticatorAttachment: 'cross-platform', residentKey: 'required', userVerification: 'required', }, }); res.json(options); } export async function verifyAdminRegistration(req: Request, res: Response) { const { credential, expectedChallenge } = req.body; const verification = await verifyRegistrationResponse({ response: credential, expectedChallenge, expectedOrigin: 'https://admin.enterprise.internal', expectedRPID: 'admin.enterprise.internal', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { return res.status(401).json({ error: 'Cryptographic attestation failed' }); } const { aaguid, flags } = verification.registrationInfo; // Invariant 1: Reject multi-device synced passkeys via Backup Eligibility (BE) and Backup State (BS) if (flags.backupEligibility || flags.backupState) { return res.status(403).json({ error: 'Multi-device synced passkeys prohibited. Hardware-bound security key required.', }); } // Invariant 2: Hardware AAGUID must match the enterprise-approved inventory const normalizedAaguid = aaguid.toLowerCase(); if (!ENTERPRISE_APPROVED_AAGUIDS.has(normalizedAaguid)) { return res.status(403).json({ error: 'Unapproved hardware authenticator. AAGUID not registered in enterprise allowlist.', }); } return res.json({ status: 'ok', credentialId: verification.registrationInfo.credentialID }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory Hardware-Bound Attestation and Authenticator Attachment Validation for Enterprise Passkeys

Mandatory Hardware-Bound Attestation and Authenticator Attachment Validation for Enterprise Passkeys defines an industrial-grade behavioral standard for security engineering. Enforces strict FIDO2/WebAuthn Level 3 enterprise attestation verification, requiring direct or enterprise attestation statements and hardware authenticator flags. Prevents the enrollment and assertion of multi-device synchronized passkeys (e.g., iCloud Keychain, Google Password Manager) for administrative and zero-trust tiers by cryptographically validating AAGUID against an approved enterprise hardware registry and verifying the backup eligibility (BE) and backup state (BS) credential flags. 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 'none' attestation or missing flags allows soft/synced passkeys on high-privilege enterprise boundary endpoints 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 'none' attestation or missing flags allows soft/synced passkeys on high-privilege enterprise boundary endpoints	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 enforce 'attestation

Engineers MUST ALWAYS enforce 'attestation: direct' or 'attestation: enterprise' in PublicKeyCredentialCreationOptions for privileged access levels.

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.