Mandate Strict FIDO2 MDS3 Root-of-Trust Attestation for Device-Bound Enterprise Passkeys

--- description: Mandate Strict FIDO2 MDS3 Root-of-Trust Attestation for Device-Bound Enterprise Passkeys - Enforces cryptographic authenticator attestation certificate chain validation against trusted FIDO Alliance Metadata Service (MDS) roots during WebAuthn enrollment. Rejects unvalidated attestation formats, software-backed credentials, and untrusted AAGUIDs to prevent unauthorized multi-device passkeys in zero-trust architectures. globs: src/**/auth/**/*.{ts,tsx}, src/**/webauthn/**/*.{ts,tsx}, src/**/identity/**/*.{ts,tsx}, api/**/registration/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-device-bound-attestation-verification-boundary" --- # Mandate Strict FIDO2 MDS3 Root-of-Trust Attestation for Device-Bound Enterprise Passkeys > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting 'none' attestation or bypassing x5c trust anchor validation during credential registration ## System Constraints You are a Principal Security Architect and Cryptographic Systems Engineer. Mandate strict FIDO2 MDS3 attestation root-of-trust verification for enterprise Passkey registration. Reject any registration pipeline that trusts client-declared attestation without cryptographically validating the x5c certificate chain to an authoritative root certificate, verifying AAGUID hardware policy conformance, and asserting enterprise device-bound flag status (disallowing backup-eligible credentials when hardware isolation is required). ## Strict Guidelines - Registration options MUST explicitly demand attestation: 'direct' or 'enterprise' for enterprise boundary endpoints; 'none' is STRICTLY FORBIDDEN. - Verification routines MUST validate the complete X.509 certificate chain (x5c) up to a pre-distributed FIDO Alliance MDS3 Root CA or enterprise PKI trust anchor. - The server MUST enforce that the AAGUID embedded within the Authenticator Data matches the leaf certificate Subject Alternative Name (SAN) extension (OID 1.3.6.1.4.1.45724.1.1.4). - Services MUST cross-reference the verified AAGUID against an explicit hardware model allowlist verified via MDS metadata statements (asserting FIPS 140-2/3 or Common Criteria EAL4+ certifications). - Enrollment handlers MUST assert Authenticator Data flags: User Present (UP=1), User Verified (UV=1 if PIN/Biometric required), and Backup Eligibility (BE=0 when enforcing non-exportable hardware-bound credentials). ## Bad vs Good Implementations ### Enforcing Hardware-Bound MDS Attestation vs Blind Trust #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The implementation allows default or 'none' attestation, fails to supply MDS3 root certificates, does not inspect the AAGUID against an approved enterprise hardware registry, and ignores backup flags (allowing synced/exportable cloud passkeys). ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; export async function registerPasskeyNaive( response: RegistrationResponseJSON, expectedChallenge: string, expectedOrigin: string ) { // VULNERABLE: Accepting 'none' or unverified attestation chains. // Permitted soft-tokens, synced passkeys, and spoofed AAGUIDs. const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID: 'enterprise.internal', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new Error('Registration verification failed'); } // Blindly saving credential without verifying attestation root or AAGUID return { credentialID: verification.registrationInfo.credential.id, publicKey: verification.registrationInfo.credential.publicKey, counter: verification.registrationInfo.credential.counter, }; } ``` #### Production Standard (Correct) > **Standard**: Validates the full X.509 attestation certificate chain against cached FIDO MDS3 roots, verifies the AAGUID against a strict corporate hardware allowlist, and explicitly inspects flags to prevent backup-eligible (synced) passkeys from enrolling in a zero-trust perimeter. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; import { fidoMdsClient } from './services/fidoMdsClient'; const APPROVED_ENTERPRISE_AAGUIDS = new Set([ 'cbfe0a44-9730-40e1-8e14-53c4ee469da7', // YubiKey 5 Series '2fc0579f-8113-47ea-b116-bb5a8db9202a', // SoloKeys V2 ]); export async function registerPasskeyHardwareBound( response: RegistrationResponseJSON, expectedChallenge: string, expectedOrigin: string ) { const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin, expectedRPID: 'enterprise.internal', requireUserVerification: true, // Mandate root verification using cached authoritative FIDO MDS3 roots getCertificateInfo: async ({ aaguid }) => { const metadata = await fidoMdsClient.getMetadataStatement(aaguid); if (!metadata) { throw new Error(`AAGUID ${aaguid} is not recognized by FIDO MDS3`); } return { rootCertificates: metadata.attestationRootCertificates, }; }, }); const { verified, registrationInfo } = verification; if (!verified || !registrationInfo) { throw new Error('Registration verification failed'); } const { aaguid, flags, credential, attestationObject } = registrationInfo; // Invariant 1: Deny multi-device/syncable passkeys for hardware-bound boundary if (flags.backupEligible || flags.backupState) { throw new SecurityError('Syncable multi-device passkeys are prohibited; hardware key required'); } // Invariant 2: Deny self or anonymous attestation when enterprise direct is mandated if (registrationInfo.attestationFormat === 'none') { throw new SecurityError('Attestation format "none" rejected; cryptographic proof required'); } // Invariant 3: Verify hardware AAGUID against approved enterprise fleet if (!APPROVED_ENTERPRISE_AAGUIDS.has(aaguid)) { throw new SecurityError(`Hardware token AAGUID ${aaguid} not in enterprise allowlist`); } return { credentialID: credential.id, publicKey: credential.publicKey, counter: credential.counter, deviceAaguid: aaguid, attestationType: registrationInfo.attestationFormat, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandate Strict FIDO2 MDS3 Root-of-Trust Attestation for Device-Bound Enterprise Passkeys

Mandate Strict FIDO2 MDS3 Root-of-Trust Attestation for Device-Bound Enterprise Passkeys defines an industrial-grade behavioral standard for security engineering. Enforces cryptographic authenticator attestation certificate chain validation against trusted FIDO Alliance Metadata Service (MDS) roots during WebAuthn enrollment. Rejects unvalidated attestation formats, software-backed credentials, and untrusted AAGUIDs to prevent unauthorized multi-device passkeys in zero-trust architectures. 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 bypassing x5c trust anchor validation during credential registration 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 bypassing x5c trust anchor validation during credential registration	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 explicitly demand attestation

Registration options MUST explicitly demand attestation: 'direct' or 'enterprise' for enterprise boundary endpoints; 'none' is STRICTLY FORBIDDEN.

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.