Mandatory Hardware-Bound Attestation and Enterprise Backup Flag Enforcement in WebAuthn Registration

Enforces strict Level 3 cryptographic hardware-bound attestation verification and authenticator data flag validation during WebAuthn passkey registration. Prohibits multi-device syncable credentials on corporate boundaries by asserting direct attestation trust roots via FIDO Metadata Service (MDS3) and strictly rejecting registrations with the Authenticator Backup Eligibility (BE) flag enabled. Guarantees non-exportable, hardware-isolated credential enrollment across zero-trust enterprise surfaces.

--- description: Mandatory Hardware-Bound Attestation and Enterprise Backup Flag Enforcement in WebAuthn Registration - Enforces strict Level 3 cryptographic hardware-bound attestation verification and authenticator data flag validation during WebAuthn passkey registration. Prohibits multi-device syncable credentials on corporate boundaries by asserting direct attestation trust roots via FIDO Metadata Service (MDS3) and strictly rejecting registrations with the Authenticator Backup Eligibility (BE) flag enabled. Guarantees non-exportable, hardware-isolated credential enrollment across zero-trust enterprise surfaces. globs: src/**/auth/**/*.{ts,js}, src/**/identity/**/*.{ts,js}, src/**/passkey/**/*.{ts,js}, src/**/webauthn/**/*.{ts,js}, src/**/controllers/**/*.{ts,js}, src/**/services/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-l3-hardware-bound-attestation-guardrail" --- # Mandatory Hardware-Bound Attestation and Enterprise Backup Flag Enforcement in WebAuthn Registration > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Synced/Multi-Device Passkeys with 'none' Attestation on Enterprise Systems ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Level 3 High-Assurance Device-Bound Passkey Attestation Standard. You must mandate strict cryptographic verification of attestation statements (direct or enterprise), rigorous validation of authenticator data flags (disallowing Backup Eligibility and Backup State flags on enterprise assets), validation against FIDO Alliance Metadata Service (MDS3), and storage of the validated AAGUID. Never allow attestationPreference: 'none' or unverified multi-device synced credentials in high-assurance environments. ## Strict Guidelines - Registration ceremony options MUST explicitly require `attestation: 'direct'` or `attestation: 'enterprise'` and set `authenticatorSelection.authenticatorAttachment: 'cross-platform'` or `'platform'` with strict `residentKey: 'required'`. - The server MUST cryptographically verify the attestation statement against trusted root certificates sourced dynamically or statically from the FIDO Alliance Metadata Service (MDS3). - The verification pipeline MUST decode the `authData` bitfield and reject any credential where the Backup Eligibility (BE) flag (bit 3, mask `0x08`) is set to 1 when enrolling enterprise-bound credentials. - The verification pipeline MUST assert that the Backup State (BS) flag (bit 4, mask `0x10`) is strictly set to 0. - The server MUST reject registration if the Authenticator Attestation GUID (AAGUID) resolves to a software keystore or an unapproved consumer-cloud syncable passkey provider (e.g., Apple iCloud Keychain, Google Password Manager) in the FIDO MDS3 cache. - The server MUST store the validated AAGUID, public key credential, non-zero sign counter (or verified zero counter strictly for known hardware profiles), and attestation certificate chain inside a tamper-resistant credential repository. - Engineers MUST NEVER use `attestation: 'none'` or rely on client-side self-assertions to verify hardware isolation. ## Bad vs Good Implementations ### Hardware-Bound Passkey Registration Verification vs. Loose Synced Passkey Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The registration accepts any authenticator without checking attestation types or authenticator data flags. Multi-device syncable passkeys (such as Apple iCloud Keychain or Google Password Manager) will be accepted because the Backup Eligibility (BE) and Backup State (BS) flags are not evaluated, and attestation format verification against trusted hardware roots (FIDO MDS3) is entirely omitted. ```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 response: RegistrationResponseJSON = req.body; const expectedChallenge = req.session.challenge; // CRITICAL VULNERABILITY: Accepts 'none' attestation and completely ignores // authenticator data flags (Backup Eligibility). Allows consumer iCloud/Google sync // credentials to persist corporate enterprise sessions across unmanaged personal devices. const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin: 'https://corp.internal.net', expectedRPID: 'corp.internal.net', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { return res.status(400).json({ error: 'Verification failed' }); } const { credentialPublicKey, credentialID, counter } = verification.registrationInfo; await saveCredentialToDb({ userId: req.session.userId, credentialID: Buffer.from(credentialID).toString('base64url'), publicKey: Buffer.from(credentialPublicKey).toString('base64url'), counter, }); return res.status(200).json({ status: 'registered' }); } ``` #### Production Standard (Correct) > **Standard**: The updated logic strictly unpacks the authenticatorData flags byte (byte index 32) and inspects the Backup Eligibility (BE, 0x08) and Backup State (BS, 0x10) bits. Any credential configured for personal cloud sync is explicitly denied. Furthermore, the AAGUID is validated against the FIDO Metadata Service (MDS3) to verify that physical hardware keys meet Level 3 requirements. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; import type { Request, Response } from 'express'; import { fidoMdsService } from './services/fidoMdsService'; const AUTH_DATA_FLAGS = { UP: 0x01, // User Present UV: 0x04, // User Verified BE: 0x08, // Backup Eligibility BS: 0x10, // Backup State AT: 0x40, // Attested Credential Data Present } as const; export async function verifyPasskeyRegistration(req: Request, res: Response) { const response: RegistrationResponseJSON = req.body; const expectedChallenge = req.session.challenge; if (!expectedChallenge) { return res.status(401).json({ error: 'Missing or expired registration challenge' }); } // 1. Mandatory direct attestation verification const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin: 'https://corp.internal.net', expectedRPID: 'corp.internal.net', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { return res.status(400).json({ error: 'Cryptographic attestation verification failed' }); } const { credentialPublicKey, credentialID, counter, aaguid, authenticatorExtensionResults, } = verification.registrationInfo; // 2. Decode raw Authenticator Data Flags const rawAuthData = Buffer.from(response.response.authenticatorData, 'base64url'); const flagsByte = rawAuthData[32]; const isUserVerified = (flagsByte & AUTH_DATA_FLAGS.UV) !== 0; const isBackupEligible = (flagsByte & AUTH_DATA_FLAGS.BE) !== 0; const isBackedUp = (flagsByte & AUTH_DATA_FLAGS.BS) !== 0; const hasAttestationData = (flagsByte & AUTH_DATA_FLAGS.AT) !== 0; if (!isUserVerified || !hasAttestationData) { return res.status(400).json({ error: 'Authenticator failed required policy: User Verification and Attested Data required' }); } // 3. HARDWARE-BOUND INVARIANT: Reject multi-device synced passkeys on corporate boundary if (isBackupEligible || isBackedUp) { return res.status(403).json({ error: 'Security Policy Violation: Synced multi-device passkeys disallowed. Device-bound hardware token required.', }); } // 4. Validate AAGUID against Enterprise FIDO MDS3 Metadata const metadataEntry = await fidoMdsService.lookupAaguid(aaguid); if (!metadataEntry || !metadataEntry.isHardwareBoundLevel3) { return res.status(403).json({ error: 'Security Policy Violation: Authenticator AAGUID not registered in approved Hardware Level 3 root list.', }); } await saveEnterpriseCredentialToDb({ userId: req.session.userId, credentialID: Buffer.from(credentialID).toString('base64url'), publicKey: Buffer.from(credentialPublicKey).toString('base64url'), counter, aaguid, isHardwareBound: true, registeredAt: new Date(), }); return res.status(200).json({ status: 'registered', hardwareBound: true }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory Hardware-Bound Attestation and Enterprise Backup Flag Enforcement in WebAuthn Registration

Mandatory Hardware-Bound Attestation and Enterprise Backup Flag Enforcement in WebAuthn Registration defines an industrial-grade behavioral standard for security engineering. Enforces strict Level 3 cryptographic hardware-bound attestation verification and authenticator data flag validation during WebAuthn passkey registration. Prohibits multi-device syncable credentials on corporate boundaries by asserting direct attestation trust roots via FIDO Metadata Service (MDS3) and strictly rejecting registrations with the Authenticator Backup Eligibility (BE) flag enabled. Guarantees non-exportable, hardware-isolated credential enrollment across zero-trust enterprise surfaces. 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 with 'none' Attestation on Enterprise Systems 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 with 'none' Attestation on Enterprise Systems	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 ceremony options MUST explicitly require `attestation

Registration ceremony options MUST explicitly require `attestation: 'direct'` or `attestation: 'enterprise'` and set `authenticatorSelection.authenticatorAttachment: 'cross-platform'` or `'platform'` with strict `residentKey: '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.