Hardware Device-Bound FIDO2 Attestation & Synced Passkey Rejection Guardrail

--- description: Hardware Device-Bound FIDO2 Attestation & Synced Passkey Rejection Guardrail - Enforces hardware-backed, device-bound WebAuthn credentials for zero-trust administrative control planes by cryptographically validating attestation statement certificates and AAGUIDs against the FIDO Alliance Metadata Service. Rejects multi-device synced passkeys by validating authenticator data flags (backup eligibility and backup state) and mandating direct attestation during credential registration. globs: src/**/auth/**/*.{ts,tsx}, src/**/webauthn/**/*.{ts,tsx}, src/**/admin/**/*.{ts,tsx}, api/**/fido2/**/*.{ts,tsx}, server/src/identity/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-device-bound-attestation-enforcement" --- # Hardware Device-Bound FIDO2 Attestation & Synced Passkey Rejection Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Synced Multi-Device Passkeys and Attestation-Free Registration on Privileged Administrative Surfaces ## System Constraints You are a Principal Security Architect enforcing zero-trust WebAuthn device-bound FIDO2 attestation standards. You MUST reject any credential registration flow for administrative, privileged, or zero-trust access planes that permits multi-device synced credentials (e.g., Apple iCloud Keychain, Google Password Manager) or accepts non-verifiable 'none' attestation. Mandate strict cryptographic verification of authenticator attestation certificate chains via FIDO MDS3, validate backup eligibility (BE) and backup state (BS) flags as strictly false, and verify AAGUIDs against approved enterprise hardware tokens. ## Strict Guidelines - Engineers MUST ALWAYS specify `attestation: 'direct'` or `attestation: 'enterprise'` in `PublicKeyCredentialCreationOptions` when enrolling credentials for administrative or privileged access. - Engineers MUST inspect `authenticatorData.flags` to assert that both `backupEligibility` (BE) and `backupState` (BS) are `false`, explicitly rejecting multi-device synced credentials. - Engineers MUST NOT accept `attestation: 'none'` or skip x5c certificate chain validation for privileged administrative identity pools. - Services MUST cross-reference the extracted Authenticator Attestation GUID (AAGUID) against an enterprise-approved hardware allowlist (e.g., FIPS 140-3 validated YubiKeys or HSM-backed tokens). - Components NEVER store or trust WebAuthn credentials without validating that `userVerification` was enforced (`flags.uv === true`) during both registration and authentication ceremonies. ## Bad vs Good Implementations ### Enforcing Device-Bound Hardware FIDO2 Attestation vs Permissive Synced Registration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The registration handler does not mandate or verify direct attestation, nor does it inspect the backup eligibility (BE) or backup state (BS) flags. Consequently, users can register synchronized consumer passkeys (e.g., iCloud Keychain or 1Password synced across personal devices), breaching zero-trust isolation on privileged control planes. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; export async function handleAdminRegistration(req: Request) { const { credential, challenge } = await req.json(); // SECURITY FLAW: Accepts default 'none' attestation, permits consumer synced passkeys, // and fails to verify the authenticator hardware AAGUID or backup flags. const verification = await verifyRegistrationResponse({ response: credential, expectedChallenge: challenge, expectedOrigin: 'https://admin.enterprise.internal', expectedRPID: 'enterprise.internal', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new Error('Registration failed'); } // Saves credential without hardware isolation proof return saveAdminCredential(verification.registrationInfo); } ``` #### Production Standard (Correct) > **Standard**: The registration handler explicitly enforces direct attestation types, parses authenticator flags to guarantee both backup eligibility and backup state are false (rejecting synced credentials), validates the hardware AAGUID against an enterprise allowlist, and cryptographically verifies the certificate chain against the FIDO Alliance Metadata Service. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import { APPROVED_ADMIN_AAGUIDS, verifyFidoMdsAttestation } from './fidoMdsService'; export async function handleAdminRegistration(req: Request) { const { credential, challenge } = await req.json(); const verification = await verifyRegistrationResponse({ response: credential, expectedChallenge: challenge, expectedOrigin: 'https://admin.enterprise.internal', expectedRPID: 'enterprise.internal', requireUserVerification: true, expectedAttestationType: ['packed', 'fido-u2f', 'tpm'], }); if (!verification.verified || !verification.registrationInfo) { throw new SecurityError('Registration failed: Cryptographic attestation invalid'); } const { aaguid, attestationObject, credentialBackedUp, authenticatorData } = verification.registrationInfo; // Invariant 1: Strictly reject multi-device synced passkeys const flags = authenticatorData.flags; if (flags.backupEligibility || flags.backupState || credentialBackedUp) { throw new SecurityError('Administrative credentials MUST be hardware device-bound. Synced passkeys rejected.'); } // Invariant 2: Hardware token model validation via enterprise AAGUID allowlist if (!APPROVED_ADMIN_AAGUIDS.has(aaguid)) { throw new SecurityError(`Untrusted authenticator model (AAGUID: ${aaguid}). Hardware not permitted.`); } // Invariant 3: Cryptographic verification of attestation certificate chain via FIDO MDS3 await verifyFidoMdsAttestation(aaguid, attestationObject); return saveAdminCredential(verification.registrationInfo); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware Device-Bound FIDO2 Attestation & Synced Passkey Rejection Guardrail

Hardware Device-Bound FIDO2 Attestation & Synced Passkey Rejection Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces hardware-backed, device-bound WebAuthn credentials for zero-trust administrative control planes by cryptographically validating attestation statement certificates and AAGUIDs against the FIDO Alliance Metadata Service. Rejects multi-device synced passkeys by validating authenticator data flags (backup eligibility and backup state) and mandating direct attestation during credential registration. 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 and Attestation-Free Registration on Privileged Administrative Surfaces 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 and Attestation-Free Registration on Privileged Administrative Surfaces	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 specify `attestation

Engineers MUST ALWAYS specify `attestation: 'direct'` or `attestation: 'enterprise'` in `PublicKeyCredentialCreationOptions` when enrolling credentials for administrative or privileged access.

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.