FIDO2 MDS3 AAGUID Hardware-Class Whitelist Enforcement Guardrail

--- description: FIDO2 MDS3 AAGUID Hardware-Class Whitelist Enforcement Guardrail - Enterprise authentication workflows must enforce direct attestation and validate the Authenticator Attestation GUID (AAGUID) against FIDO Alliance Metadata Service v3 (MDS3). The registration pipeline must cryptographically reject synced multi-device passkeys (all-zero AAGUIDs or uncertified software authenticators) and require certified hardware security keys matching an enterprise trust list with acceptable FIDO certification levels (e.g., FIDO_CERTIFIED_L2 or higher). globs: src/auth/**/*.ts, src/security/**/*.ts, src/services/webauthn/**/*.ts, src/api/auth/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-mds3-aaguid-hardware-class-whitelist-invariant" --- # FIDO2 MDS3 AAGUID Hardware-Class Whitelist Enforcement Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Acceptance of Synced Multi-Device Passkeys or Unverified AAGUIDs in Enterprise-Bound Hardware Workflows ## System Constraints You are a Principal Security Architect enforcing the WebAuthn FIDO2 MDS3 AAGUID Hardware-Class Whitelist Invariant. You must reject any registration flow that accepts 'none' attestation, fails to extract and verify the authentic AAGUID, allows the zero-UUID (00000000-0000-0000-0000-000000000000), or skips cryptographically validated FIDO MDS3 metadata verification for authenticator hardware-backed assurance. ## Strict Guidelines - Registration options MUST ALWAYS mandate `attestation: 'direct'` (or 'enterprise' where supported) and `authenticatorSelection: { authenticatorAttachment: 'cross-platform', userVerification: 'required' }`. - Engineers MUST NEVER permit the zero-GUID ('00000000-0000-0000-0000-000000000000') in enterprise hardware-bound policies, as it explicitly designates multi-device synced passkeys or software authenticators. - Services MUST download, verify the digital signature chain against the FIDO MDS3 Root CA, and cache the FIDO Alliance MDS3 BLOB to perform offline or low-latency authenticated lookups. - The server-side verification pipeline MUST verify that the authenticator's AAGUID extracted from `authData` is present in the enterprise-approved whitelist of AAGUIDs sourced from verified MDS3 entries. - Authentication metadata queries MUST verify the `certificationStatus` field in MDS3 metadata entries (e.g., ensuring `FIDO_CERTIFIED_L2`, `FIDO_CERTIFIED_L3` status) and verify absence of `statusReports` indicating key compromise ('USER_VERIFICATION_BYPASS', 'ATTESTATION_KEY_COMPROMISE'). - Attestation certificates (x5c) extracted from the attestation object MUST be cryptographically verified against the attestation root certificates declared in the authenticator's MDS3 metadata statement. ## Bad vs Good Implementations ### AAGUID and MDS3 Hardware-Class Whitelist Attestation Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This implementation fails to verify attestation authenticity, accepts multi-device synced passkeys (like Apple/Google passkeys that leak hardware boundaries), does not extract the AAGUID, and completely omits FIDO MDS3 validation, allowing unvetted software authenticators into a high-security zone. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; export async function registerDevice(userId: string, response: RegistrationResponseJSON, expectedChallenge: string) { // ANTI-PATTERN: None/Indirect attestation accepted, AAGUID ignored, no MDS3 validation const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin: 'https://vault.enterprise.internal', expectedRPID: 'vault.enterprise.internal', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new Error('Registration failed'); } // Storing credential without checking if it is a synced iCloud/Google passkey or hardware key const { credentialID, credentialPublicKey } = verification.registrationInfo; return await db.credentials.create({ data: { userId, credentialID, credentialPublicKey } }); } ``` #### Production Standard (Correct) > **Standard**: The good implementation strictly bans the zero-AAGUID multi-device passkey indicator, verifies the device AAGUID against an authenticated FIDO MDS3 metadata cache, checks for enterprise-grade FIDO certification (L2+), and validates that no security revocations or compromise reports affect the device model. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; import { FidoMds3Service } from './fidoMds3Service'; const ZERO_AAGUID = '00000000-0000-0000-0000-000000000000'; const MINIMUM_CERTIFICATION_LEVELS = new Set(['FIDO_CERTIFIED_L2', 'FIDO_CERTIFIED_L3', 'FIDO_CERTIFIED_L3plus']); export async function registerHardwareKey( userId: string, response: RegistrationResponseJSON, expectedChallenge: string, mds3Service: FidoMds3Service ) { const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin: 'https://vault.enterprise.internal', expectedRPID: 'vault.enterprise.internal', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new SecurityViolationError('Cryptographic registration verification failed.'); } const { aaguid, credentialID, credentialPublicKey, attestationObject } = verification.registrationInfo; // Reject multi-device synced passkeys and missing AAGUIDs if (!aaguid || aaguid === ZERO_AAGUID) { throw new SecurityViolationError('Synced multi-device passkeys prohibited. Enterprise hardware key required.'); } // Verify device against FIDO MDS3 authenticated metadata statement const metadata = await mds3Service.getEntryByAAGUID(aaguid); if (!metadata) { throw new SecurityViolationError(`AAGUID ${aaguid} is not recognized by FIDO MDS3.`); } // Ensure hardware-class certification and absence of revocations/compromise const certLevel = metadata.metadataStatement.authenticatorGetInfo?.certificationLevel; if (!certLevel || !MINIMUM_CERTIFICATION_LEVELS.has(certLevel)) { throw new SecurityViolationError(`Hardware assurance level insufficient: ${certLevel}`); } const hasCompromise = metadata.statusReports.some(report => ['ATTESTATION_KEY_COMPROMISE', 'USER_VERIFICATION_BYPASS'].includes(report.status) ); if (hasCompromise) { throw new SecurityViolationError('Hardware token model has active MDS3 compromise status reports.'); } return await db.credentials.create({ data: { userId, credentialID: Buffer.from(credentialID).toString('base64url'), credentialPublicKey: Buffer.from(credentialPublicKey).toString('base64url'), aaguid, hardwareModel: metadata.metadataStatement.description, }, }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FIDO2 MDS3 AAGUID Hardware-Class Whitelist Enforcement Guardrail

FIDO2 MDS3 AAGUID Hardware-Class Whitelist Enforcement Guardrail defines an industrial-grade behavioral standard for security engineering. Enterprise authentication workflows must enforce direct attestation and validate the Authenticator Attestation GUID (AAGUID) against FIDO Alliance Metadata Service v3 (MDS3). The registration pipeline must cryptographically reject synced multi-device passkeys (all-zero AAGUIDs or uncertified software authenticators) and require certified hardware security keys matching an enterprise trust list with acceptable FIDO certification levels (e.g., FIDO_CERTIFIED_L2 or higher). 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: Acceptance of Synced Multi-Device Passkeys or Unverified AAGUIDs in Enterprise-Bound Hardware 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	Acceptance of Synced Multi-Device Passkeys or Unverified AAGUIDs in Enterprise-Bound Hardware 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:

Registration options MUST ALWAYS mandate `attestation

Registration options MUST ALWAYS mandate `attestation: 'direct'` (or 'enterprise' where supported) and `authenticatorSelection: { authenticatorAttachment: 'cross-platform', userVerification: '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.