FIDO2 Hardware Attestation and Device-Bound Credential Verification

--- description: FIDO2 Hardware Attestation and Device-Bound Credential Verification - Enforces cryptographic verification of hardware-backed authenticator attachment and attestation statements during FIDO2/WebAuthn registration. Eliminates credential downgrade and unauthorized cross-platform synchronization by asserting FIDO MDS3 trust chains, validating AAGUID authentications, and auditing authenticator data backup flags. globs: src/**/auth/**/*.{ts,tsx}, src/**/webauthn/**/*.{ts,tsx}, src/**/identity/**/*.{ts,tsx}, src/server/auth/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fido2-hardware-attestation-policy-guardrail" --- # FIDO2 Hardware Attestation and Device-Bound Credential Verification > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Unverified Passkey Registration via 'attestation: none' and Ignoring Authenticator Backup Flags ## System Constraints You are a Principal Security Architect enforcing Passkey FIDO2 Hardware Attestation Policies. Mandate strict cryptographic verification of authenticator data, attestation statements, and FIDO Metadata Service (MDS3) trust anchors to prevent credential downgrade and unauthorized cloud-synced passkey usage in high-assurance environments. ## Strict Guidelines - Engineers MUST ALWAYS configure WebAuthn registration options with `attestation: 'direct'` or `'enterprise'` when hardware isolation or device-bound assurance is required. - Engineers MUST NOT trust client-reported transport, platform hints, or `authenticatorAttachment` parameters without cryptographic attestation verification. - Services MUST inspect Authenticator Data flags specifically for `backupEligibility` (BE) and `backupState` (BS) to reject multi-device synced passkeys when single-device hardware credentials are required. - Services MUST validate attestation certificate chains against the FIDO Alliance Metadata Service (MDS3) root certificates and verify that the authenticator's AAGUID corresponds to an approved hardware security level (e.g., FIPS 140-2/3, CC EAL). - Components NEVER store or trust public key credentials whose attestation statement format is 'none' or whose trust path fails validation against known authenticator certificates. ## Bad vs Good Implementations ### FIDO2 WebAuthn Registration Response Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The registration verification omits attestation certificate chain verification, permits default unvalidated attestation statements, and fails to check authenticator flags (backupEligibility/backupState) or validate AAGUID against FIDO MDS3, allowing synced software credentials to spoof dedicated hardware authenticators. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; export async function verifyPasskeyRegistration( response: RegistrationResponseJSON, expectedChallenge: string, expectedOrigin: string, expectedRPID: string ) { // VULNERABLE: No attestation validation, allowing synced software/cloud passkeys // and ignoring hardware backing proofs, enabling credential downgrade. const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID, requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new Error('Registration failed'); } const { credentialPublicKey, credentialID } = verification.registrationInfo; return { credentialID, credentialPublicKey }; } ``` #### Production Standard (Correct) > **Standard**: The hardened implementation inspects the parsed WebAuthn Authenticator Data flags (`backupEligibility` and `backupState`), verifies the AAGUID against an authoritative FIDO Metadata Service (MDS3) client, and enforces hardware-backed protection invariants before storing the credential. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; import { fidoMdsClient } from '@/server/security/fido-mds'; interface HardwareEnforcedRegistrationResult { credentialID: Uint8Array; credentialPublicKey: Uint8Array; aaguid: string; counter: number; } export async function verifyPasskeyRegistration( response: RegistrationResponseJSON, expectedChallenge: string, expectedOrigin: string, expectedRPID: string ): Promise<HardwareEnforcedRegistrationResult> { const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID, requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new SecurityError('FIDO2 registration verification failed cryptographically.'); } const { registrationInfo } = verification; const { flags, aaguid, credentialID, credentialPublicKey, counter, attestationObject } = registrationInfo; // Invariant 1: Deny synced credentials if hardware isolation is required if (flags.backupEligibility || flags.backupState) { throw new SecurityError('Policy Violation: Synchronized credentials (multi-device passkeys) are strictly forbidden.'); } // Invariant 2: Validate AAGUID and attestation via FIDO Metadata Service (MDS3) const metadata = await fidoMdsClient.getEntryByAAGUID(aaguid); if (!metadata || !metadata.statusReports.some((r) => r.status === 'FIDO_CERTIFIED')) { throw new SecurityError(`Untrusted authenticator: AAGUID ${aaguid} is not recognized or certified by MDS3.`); } const hasHardwareProtection = metadata.metadataStatement.userVerificationDetails?.some((uv) => uv.some((desc) => desc.userVerificationMethod === 'presence_internal' || desc.caProtection === 'hardware') ); if (!hasHardwareProtection) { throw new SecurityError('Policy Violation: Authenticator lacks certified hardware-backed key protection.'); } return { credentialID, credentialPublicKey, aaguid, counter, }; } class SecurityError extends Error { constructor(message: string) { super(message); this.name = 'SecurityError'; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FIDO2 Hardware Attestation and Device-Bound Credential Verification

FIDO2 Hardware Attestation and Device-Bound Credential Verification defines an industrial-grade behavioral standard for security engineering. Enforces cryptographic verification of hardware-backed authenticator attachment and attestation statements during FIDO2/WebAuthn registration. Eliminates credential downgrade and unauthorized cross-platform synchronization by asserting FIDO MDS3 trust chains, validating AAGUID authentications, and auditing authenticator data backup 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: Permitting Unverified Passkey Registration via 'attestation: none' and Ignoring Authenticator Backup Flags 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 Unverified Passkey Registration via 'attestation: none' and Ignoring Authenticator Backup Flags	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 configure WebAuthn registration options with `attestation

Engineers MUST ALWAYS configure WebAuthn registration options with `attestation: 'direct'` or `'enterprise'` when hardware isolation or device-bound assurance is required.

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.