WebAuthn L3 Device-Bound Attestation and Sync Guardrail

--- description: WebAuthn L3 Device-Bound Attestation and Sync Guardrail - Requires cryptographic direct or enterprise attestation verification and authenticatorData flag inspection during WebAuthn registration to separate synchronized multi-device passkeys from non-exportable hardware-bound authenticators. Enforces strict attestation certificate chain validation via the FIDO Metadata Service (MDS3) and blocks credentials with backup eligibility flags from privileged administrative workflows. globs: src/**/auth/**/*.{ts,js,py,go}, src/**/webauthn/**/*.{ts,js,py,go}, lib/auth/**/*.{ts,js,py,go}, server/routes/auth/**/*.{ts,js,py,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-l3-device-bound-attestation-sync-guardrail" --- # WebAuthn L3 Device-Bound Attestation and Sync Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Passkeys for Privileged Roles Without Cryptographic Attestation and Backup Flag Inspection ## System Constraints You are a Principal Security Architect enforcing WebAuthn Level 3 compliance and cryptographic attestation validation. Privileged workflows require non-exportable, device-bound authenticators (FIPS 140-3 / FIDO Authenticator Security Level 2+). You must mandate inspection of authenticatorData flags (Backup Eligibility and Backup State), enforce 'direct' or 'enterprise' attestation conveyance, validate certificate trust paths against the FIDO Metadata Service (MDS3), and reject multi-device synced passkeys for high-privilege access scopes. ## Strict Guidelines - Engineers MUST ALWAYS inspect the authenticatorData flags (specifically Bit 3: Backup Eligibility [BE] and Bit 4: Backup State [BS]) during registration verification for privileged roles. - Engineers MUST NOT accept credentials where `flags.backupEligibility === true` for workflows requiring non-exportable, hardware-bound credentials. - Services MUST request `attestation: 'direct'` or `attestation: 'enterprise'` in `PublicKeyCredentialCreationOptions` when provisioning privileged operator credentials. - Services MUST validate attestation statement certificates (x5c) against the official FIDO Alliance Metadata Service (MDS3) BLOB to verify AAGUID and certification status. - Engineers MUST NOT configure `attestation: 'none'` on registration ceremonies granting access to production environments, infrastructure consoles, or data mutations. - Database schemas MUST explicitly store credential provenance, including `aaguid`, `is_backed_up`, `is_backup_eligible`, `attestation_format`, and `authenticator_security_level`. - Components NEVER allow client-supplied assertions to dictate hardware-bound status without backend cryptographic attestation verification. ## Bad vs Good Implementations ### Enforcing Device-Bound Attestation and Flag Verification on WebAuthn Registration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The registration accepts any WebAuthn credential, including multi-device synced passkeys. It does not enforce direct/enterprise attestation verification, fails to inspect the BE (Backup Eligibility) and BS (Backup State) flags, and allows exportable synced keys to govern super-admin access. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; export async function registerPrivilegedUser(userId: string, credentialResponse: any, expectedChallenge: string) { // VULNERABLE: Accepts multi-device synced passkeys (iCloud Keychain, Google Password Manager) // for critical administrative operations without verifying attestation or backup flags. const verification = await verifyRegistrationResponse({ response: credentialResponse, expectedChallenge, expectedOrigin: 'https://admin.example.com', expectedRPID: 'admin.example.com', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new Error('Registration failed'); } // Blindly stores the credential without checking if it is sync-eligible or hardware-bound await db.credentials.create({ data: { userId, credentialId: verification.registrationInfo.credentialID, publicKey: verification.registrationInfo.credentialPublicKey, counter: verification.registrationInfo.counter, role: 'SUPER_ADMIN', }, }); } ``` #### Production Standard (Correct) > **Standard**: Explicitly verifies the WebAuthn Level 3 flags: rejects credentials if `backupEligibility` or `backupState` is true. Additionally validates the AAGUID against the FIDO MDS to guarantee the authenticator is a verified hardware-bound security key (FIDO Level 2/3) before persisting privileged credentials. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import { fidoMdsClient } from '../crypto/fido-mds'; export async function registerPrivilegedUser(userId: string, credentialResponse: any, expectedChallenge: string) { const verification = await verifyRegistrationResponse({ response: credentialResponse, expectedChallenge, expectedOrigin: 'https://admin.example.com', expectedRPID: 'admin.example.com', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new Error('Cryptographic registration verification failed'); } const { flags, aaguid, attestationObject } = verification.registrationInfo; // WebAuthn L3 Invariant: Enforce device-bound status for privileged accounts if (flags.backupEligibility || flags.backupState) { throw new SecurityError('Privileged roles require non-exportable hardware-bound authenticators. Synced passkeys are rejected.'); } // Validate AAGUID against FIDO MDS3 to confirm hardware certification level (Level 2 or 3) const mdsEntry = await fidoMdsClient.getMetadataEntry(aaguid); const isCertifiedHardware = mdsEntry?.statusReports.some(report => ['FIDO_CERTIFIED_L2', 'FIDO_CERTIFIED_L3'].includes(report.status) ); if (!isCertifiedHardware) { throw new SecurityError('Authenticator does not meet required FIDO L2/L3 hardware attestation level'); } await db.credentials.create({ data: { userId, credentialId: Buffer.from(verification.registrationInfo.credentialID).toString('base64url'), publicKey: Buffer.from(verification.registrationInfo.credentialPublicKey), counter: verification.registrationInfo.counter, aaguid, isBackupEligible: flags.backupEligibility, isBackedUp: flags.backupState, deviceBound: true, role: 'SUPER_ADMIN', }, }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn L3 Device-Bound Attestation and Sync Guardrail

WebAuthn L3 Device-Bound Attestation and Sync Guardrail defines an industrial-grade behavioral standard for security engineering. Requires cryptographic direct or enterprise attestation verification and authenticatorData flag inspection during WebAuthn registration to separate synchronized multi-device passkeys from non-exportable hardware-bound authenticators. Enforces strict attestation certificate chain validation via the FIDO Metadata Service (MDS3) and blocks credentials with backup eligibility flags from privileged administrative workflows. 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 Passkeys for Privileged Roles Without Cryptographic Attestation and Backup Flag Inspection 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 Passkeys for Privileged Roles Without Cryptographic Attestation and Backup Flag Inspection	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 inspect the authenticatorData flags (specifically Bit 3

Engineers MUST ALWAYS inspect the authenticatorData flags (specifically Bit 3: Backup Eligibility [BE] and Bit 4: Backup State [BS]) during registration verification for privileged roles.

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.