Mandate WebAuthn Device-Bound Key Attestation with FIDO2 Enterprise Metadata Pinning

--- description: Mandate WebAuthn Device-Bound Key Attestation with FIDO2 Enterprise Metadata Pinning - Enforces hardware-backed, non-exportable passkey registration by requiring direct attestation verification against FIDO Alliance Metadata Service (MDS3) roots of trust. Rejects synced passkeys by evaluating authenticator flags (rejecting backup eligibility) and strictly pinning enterprise-approved AAGUIDs to prevent unauthorized credential export. globs: src/**/auth/**/*.{ts,tsx}, src/**/webauthn/**/*.{ts,tsx}, server/**/auth/**/*.{ts,tsx}, packages/**/auth/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-device-bound-attestation-mds-pinning" --- # Mandate WebAuthn Device-Bound Key Attestation with FIDO2 Enterprise Metadata Pinning > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting 'none' attestation, ignoring backup flags, or trusting client-supplied AAGUIDs without verifying x5c chains against FIDO MDS ## System Constraints You are a Principal Security Architect enforcing FIDO2 Enterprise Metadata Pinning and WebAuthn hardware-bound key attestation. You must ensure that enterprise registration flows mandate direct attestation, validate x5c certificate chains against trusted FIDO Alliance Metadata Service (MDS3) roots, inspect authenticator data flags to reject syncable/cloud-backed passkeys, and enforce an allowlist of enterprise-approved Authenticator Attestation GUIDs (AAGUIDs). ## Strict Guidelines - Engineers MUST configure PublicKeyCredentialCreationOptions with `attestation: 'direct'` or `'enterprise'` to force authenticators to return cryptographic attestation statements. - Engineers MUST NOT accept `'none'` attestation format during registration when enterprise hardware-bound security is mandated. - Services MUST extract the AAGUID from `authData` and assert it exists within an immutable, enterprise-approved allowlist verified against the FIDO MDS3 cache. - Services MUST parse and validate the `x5c` certificate chain in the attestation statement against pinned FIDO MDS3 root certificates, rejecting untrusted intermediates, expired certificates, or revoked status. - Services MUST inspect authenticator data flags: verify User Presence (`UP`), User Verification (`UV`), and reject credentials where Backup Eligibility (`BE`) or Backup State (`BS`) is true when multi-device synced passkeys are forbidden. - Code MUST ensure challenges are single-use, high-entropy (minimum 32 cryptographically random bytes), bound to the user session, and validated within an expiration window. ## Bad vs Good Implementations ### Enterprise WebAuthn Registration Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code allows soft-tokens or synced passkeys (iCloud Keychain, Google Password Manager) by ignoring authenticator flags (BE/BS), does not verify cryptographic attestation against FIDO MDS3 roots, and accepts unapproved AAGUIDs. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; import type { Request, Response } from 'express'; export async function verifyPasskeyRegistration(req: Request, res: Response) { const { body: credential } = req; const expectedChallenge = req.session.challenge; // VULNERABLE: Lacks attestation validation, allows multi-device synced passkeys, // and does not check AAGUID against enterprise hardware allowlist or FIDO MDS. const verification = await verifyRegistrationResponse({ response: credential as RegistrationResponseJSON, expectedChallenge, expectedOrigin: 'https://corp.example.com', expectedRPID: 'corp.example.com', requireUserVerification: false }); if (verification.verified && verification.registrationInfo) { await saveCredentialToDb(req.session.userId, verification.registrationInfo); return res.json({ success: true }); } return res.status(400).json({ error: 'Verification failed' }); } ``` #### Production Standard (Correct) > **Standard**: The implementation destroys the challenge immediately, forces user verification, checks that the key is singleDevice (rejecting multi-device sync/backup), validates the AAGUID against an approved enterprise allowlist, and verifies the attestation trust chain against FIDO MDS3 roots. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; import type { Request, Response } from 'express'; import { enterpriseMdsService } from './enterpriseMdsService'; // Pre-approved enterprise hardware tokens (e.g., YubiKey 5 Series, Feitian Bio) const APPROVED_ENTERPRISE_AAGUIDS = new Set<string>([ 'ee882879-721c-4916-ad4e-a05c708f47b9', 'fa2b99dc-9e39-4257-8f92-4a30d23c4118' ]); export async function verifyPasskeyRegistration(req: Request, res: Response) { const credential = req.body as RegistrationResponseJSON; const expectedChallenge = req.session.challenge; if (!expectedChallenge) { return res.status(400).json({ error: 'Missing or expired registration challenge' }); } // Destroy challenge immediately to prevent replay delete req.session.challenge; const verification = await verifyRegistrationResponse({ response: credential, expectedChallenge, expectedOrigin: 'https://corp.example.com', expectedRPID: 'corp.example.com', requireUserVerification: true }); if (!verification.verified || !verification.registrationInfo) { return res.status(400).json({ error: 'Attestation cryptographic verification failed' }); } const { aaguid, attestationObject, credentialBackedUp, credentialDeviceType } = verification.registrationInfo; // Invariant 1: Reject multi-device synced passkeys; enforce single-device hardware if (credentialDeviceType !== 'singleDevice' || credentialBackedUp) { return res.status(403).json({ error: 'Policy violation: Synced passkeys not permitted. Hardware-bound key required.' }); } // Invariant 2: Validate AAGUID against corporate allowlist if (!APPROVED_ENTERPRISE_AAGUIDS.has(aaguid)) { return res.status(403).json({ error: 'Authenticator model not authorized for enterprise access' }); } // Invariant 3: Verify attestation root trust chain against FIDO MDS3 metadata const isMetadataValid = await enterpriseMdsService.validateAttestationStatement({ aaguid, attestationObject }); if (!isMetadataValid) { return res.status(403).json({ error: 'Attestation root certificate validation failed against FIDO MDS3' }); } await saveCredentialToDb(req.session.userId, verification.registrationInfo); return res.json({ success: true }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandate WebAuthn Device-Bound Key Attestation with FIDO2 Enterprise Metadata Pinning

Mandate WebAuthn Device-Bound Key Attestation with FIDO2 Enterprise Metadata Pinning defines an industrial-grade behavioral standard for security engineering. Enforces hardware-backed, non-exportable passkey registration by requiring direct attestation verification against FIDO Alliance Metadata Service (MDS3) roots of trust. Rejects synced passkeys by evaluating authenticator flags (rejecting backup eligibility) and strictly pinning enterprise-approved AAGUIDs to prevent unauthorized credential export. 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, ignoring backup flags, or trusting client-supplied AAGUIDs without verifying x5c chains against FIDO MDS 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, ignoring backup flags, or trusting client-supplied AAGUIDs without verifying x5c chains against FIDO MDS	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 configure PublicKeyCredentialCreationOptions with `attestation

Engineers MUST configure PublicKeyCredentialCreationOptions with `attestation: 'direct'` or `'enterprise'` to force authenticators to return cryptographic attestation statements.

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.