WebAuthn Device-Bound Attestation and Step-Up Escalation Guardrail

--- description: WebAuthn Device-Bound Attestation and Step-Up Escalation Guardrail - Enforces cryptographic verification of WebAuthn attestation statements, authenticator data flags (BE/BS), and AAGUIDs against the FIDO Metadata Service (MDS) during registration and step-up flows. Prevents synced multi-device passkeys from masquerading as hardware-isolated, non-exportable security keys on high-risk transaction escalation boundaries. globs: src/auth/**/*.{ts,tsx}, src/server/**/*.{ts,tsx}, src/api/**/*.{ts,tsx}, src/services/**/*.{ts,tsx}, lib/auth/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-device-bound-attestation-escalation-guardrail" --- # WebAuthn Device-Bound Attestation and Step-Up Escalation Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Synced Passkeys for Privileged Transactions Without Verifying Backup Eligibility and MDS Attestation Chains ## System Constraints You are a Principal Security Architect enforcing strict FIDO2/WebAuthn Level 3 attestation and credential tiering guardrails. Never treat synced passkeys (multi-device credentials) as equivalent to non-exportable hardware-bound security keys (e.g., FIPS 140-3 Level 3 / CC EAL6+ YubiKeys) for privileged administrative or financial escalation flows. Ensure all registration and step-up verification code inspects WebAuthn authenticatorData flags (specifically Backup Eligibility [BE] and Backup State [BS]), verifies the x5c attestation certificate chain against the FIDO Alliance Metadata Service (MDS3), and rejects unverified or synced credentials when escalated device-bound proof is required. ## Strict Guidelines - Engineers MUST ALWAYS demand 'direct' or 'enterprise' attestation conveyancePreference when registering credentials intended for privileged step-up authorization. - Engineers MUST inspect the authenticatorData flags: if a privileged operation mandates hardware-bound isolation, the credential MUST have Backup Eligibility (BE) flag set to false (0). - Engineers MUST NOT rely on client-supplied hints (such as authenticatorAttachment: 'cross-platform') to infer hardware isolation; isolation MUST be cryptographically proven via attestation statement verification. - Code MUST validate the AAGUID and attestation certificate chain against cached, signed FIDO Alliance Metadata Service (MDS3) BLOBs to verify hardware certification level. - Services MUST persist explicit credential metadata (aaguid, credentialDeviceType: 'singleDevice' | 'multiDevice', attestationType, backingStorageTier) alongside the public key to gate subsequent step-up evaluations. - Components NEVER allow fallback to 'none' attestation for elevated tiers or bypass attestation signature verification during registration. ## Bad vs Good Implementations ### Privileged Attestation and Device-Bound Flag Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The registration handler uses default verification without validating the attestation statement, ignoring the Backup Eligibility (BE) flag and AAGUID. An attacker or employee can register a synced consumer passkey (e.g., iCloud Keychain or Chrome sync), enabling the private key to be synchronized across personal untrusted devices and exported, defeating hardware step-up boundaries. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; export async function registerPrivilegedKey( userId: string, response: RegistrationResponseJSON, expectedChallenge: string ) { // VULNERABLE: Accepts any attestation, ignores backup flags, // allowing synced iCloud/Google passkeys for high-risk escalation flows const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin: 'https://vault.corp.internal', expectedRPID: 'vault.corp.internal', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new Error('Registration failed'); } const { credentialID, credentialPublicKey } = verification.registrationInfo; // Blindly saving credential without recording device-bound assurance or AAGUID await db.credentials.create({ data: { userId, credentialId: Buffer.from(credentialID).toString('base64url'), publicKey: Buffer.from(credentialPublicKey), isPrivileged: true, // Critical security bug: synced passkey granted privileged status }, }); } ``` #### Production Standard (Correct) > **Standard**: The remediation strictly enforces that `flags.backupEligibility` is false, disallows multi-device passkeys, confirms a non-zero AAGUID, and verifies that the AAGUID matches a certified hardware level in the FIDO Alliance Metadata Service before granting privileged escalation capability. ```typescript import { verifyRegistrationResponse } from '@simplewebauthn/server'; import type { RegistrationResponseJSON } from '@simplewebauthn/types'; import { fidoMdsClient } from '../crypto/fido-mds'; export async function registerPrivilegedKey( userId: string, response: RegistrationResponseJSON, expectedChallenge: string ) { const verification = await verifyRegistrationResponse({ response, expectedChallenge, expectedOrigin: 'https://vault.corp.internal', expectedRPID: 'vault.corp.internal', requireUserVerification: true, }); if (!verification.verified || !verification.registrationInfo) { throw new SecurityException('WebAuthn cryptographic verification failed'); } const { credentialID, credentialPublicKey, credentialDeviceType, flags, aaguid, attestationObject, } = verification.registrationInfo; // Invariant 1: Hardware-bound keys MUST NOT be backup-eligible if (flags.backupEligibility || credentialDeviceType === 'multiDevice') { throw new SecurityException('Privileged credential rejected: Multi-device/synced passkey detected.'); } // Invariant 2: AAGUID must not be zeroed (indicates absent attestation or non-hardware) const isZeroAaguid = /^0{8}-0{4}-0{4}-0{4}-0{12}$/.test(aaguid); if (isZeroAaguid) { throw new SecurityException('Privileged credential rejected: Missing hardware AAGUID.'); } // Invariant 3: Verify hardware assurance in FIDO Metadata Service (FIPS / CC Level >= 2) const metadata = await fidoMdsClient.getEntry(aaguid); if (!metadata || !metadata.statusReports.some(r => r.status === 'FIDO_CERTIFIED_L2' || r.status === 'FIDO_CERTIFIED_L3')) { throw new SecurityException('Privileged credential rejected: AAGUID does not meet hardware security requirements.'); } await db.credentials.create({ data: { userId, credentialId: Buffer.from(credentialID).toString('base64url'), publicKey: Buffer.from(credentialPublicKey), aaguid, deviceBoundTier: 'HARDWARE_TOKEN_SECURE_ENCLAVE', backupEligible: flags.backupEligibility, backupState: flags.backupState, }, }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Device-Bound Attestation and Step-Up Escalation Guardrail

WebAuthn Device-Bound Attestation and Step-Up Escalation Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces cryptographic verification of WebAuthn attestation statements, authenticator data flags (BE/BS), and AAGUIDs against the FIDO Metadata Service (MDS) during registration and step-up flows. Prevents synced multi-device passkeys from masquerading as hardware-isolated, non-exportable security keys on high-risk transaction escalation boundaries. 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 Synced Passkeys for Privileged Transactions Without Verifying Backup Eligibility and MDS Attestation Chains 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 Synced Passkeys for Privileged Transactions Without Verifying Backup Eligibility and MDS Attestation Chains	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 demand 'direct' or 'enterprise' attestation conveyancePreference when registering credentials intended for privileged step-up authorization.

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.