WebAuthn Level 3 Device-Bound Attestation Step-Up Enforcement

--- description: WebAuthn Level 3 Device-Bound Attestation Step-Up Enforcement - Mandates cryptographic verification of hardware-bound security keys during privileged tenant operations to mitigate account takeover via compromised cloud-synced passkey ecosystems. Step-up verification for administrative actions must strictly enforce non-backupable authenticator flags (BE=0, BS=0) and validate hardware attestation certificates. globs: src/auth/**/*.{ts,tsx}, src/server/auth/**/*.{ts,tsx}, src/security/**/*.{ts,tsx}, src/api/admin/**/*.{ts,tsx}, src/middleware/stepUp/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-l3-device-bound-attestation-step-up" --- # WebAuthn Level 3 Device-Bound Attestation Step-Up Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Synced Multi-Device Passkeys to Authorize Privileged Tenant Mutations ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Level 3 Synced-Passkey Step-Up Attestation Standard. Multi-device synced passkeys (e.g., Apple iCloud Keychain, Google Password Manager) expose high-privilege tenant operations to blast radius expansion if a user's consumer cloud identity is compromised. You must mandate that privileged administrative endpoints verify cryptographic proofs showing authenticators are physical, device-bound security keys with enterprise/direct attestation and non-backup flags. ## Strict Guidelines - Services MUST inspect authenticatorData flags to assert backupEligible (BE) is false and backupState (BS) is false during privileged step-up authentication. - Engineers MUST configure WebAuthn challenge creation with `authenticatorAttachment: 'cross-platform'` or explicit device-bound credential IDs during administrative step-up flows. - Verification handlers MUST NOT accept assertions signed by multi-device credentials (BE=1) when escalating tenant privileges or modifying root security policies. - Services MUST cryptographically bind the challenge to the specific privileged operation payload and user session ID via clientDataJSON hash verification. - Authentication responses MUST validate direct or enterprise attestation statements against an allowed hardware root certificate authority or FIDO Metadata Service (MDS) registry. - Privileged step-up tokens MUST be single-use, cryptographically signed, and have a maximum lifetime of 300 seconds. ## Bad vs Good Implementations ### Privileged Step-Up Authentication Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The handler verifies cryptographic validity but completely ignores authenticatorData flags (backupEligible and backupState). A compromised iCloud or Google account allows an attacker to sync the passkey to an unmanaged personal device and execute privileged tenant actions without possessing a physical, enterprise-managed hardware token. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { AuthenticationResponseJSON } from '@simplewebauthn/types'; import { Request, Response } from 'express'; export async function handlePrivilegedStepUp(req: Request, res: Response) { const { credential, expectedChallenge, userCredential } = req.body; // CRITICAL FLAW: Accepts any valid passkey signature, including cloud-synced passkeys // synced from compromised consumer iCloud or Google accounts. const verification = await verifyAuthenticationResponse({ response: credential as AuthenticationResponseJSON, expectedChallenge, expectedOrigin: 'https://admin.tenant.enterprise.com', expectedRPID: 'tenant.enterprise.com', authenticator: { credentialPublicKey: userCredential.publicKey, credentialID: userCredential.id, counter: userCredential.counter, }, }); if (!verification.verified) { return res.status(401).json({ error: 'Authentication failed' }); } // Authorizes destructive action without asserting device-bound hardware backing await executePrivilegedTenantAction(req.body.actionPayload); return res.json({ success: true }); } ``` #### Production Standard (Correct) > **Standard**: The corrected implementation enforces WebAuthn Level 3 invariants: it cryptographically binds the challenge to the specific operation payload, requires user verification, and parses authenticatorData flags at byte offset 32 to ensure the authenticator is non-backup eligible (BE=0) and not synced (BS=0), guaranteeing that only physically bound hardware keys can complete the step-up. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { AuthenticationResponseJSON } from '@simplewebauthn/types'; import { Request, Response } from 'express'; import crypto from 'node:crypto'; interface PrivilegedStepUpSession { stepUpChallenge: string; userId: string; sessionNonce: string; } export async function handlePrivilegedStepUp( req: Request & { session: PrivilegedStepUpSession }, res: Response ) { const credential = req.body.credential as AuthenticationResponseJSON; const { actionPayload, userCredential } = req.body; // Cryptographically bind payload to expected challenge const payloadHash = crypto.createHash('sha256').update(JSON.stringify(actionPayload)).digest('hex'); const expectedChallenge = `${req.session.stepUpChallenge}:${payloadHash}`; const verification = await verifyAuthenticationResponse({ response: credential, expectedChallenge, expectedOrigin: 'https://admin.tenant.enterprise.com', expectedRPID: 'tenant.enterprise.com', authenticator: { credentialPublicKey: userCredential.publicKey, credentialID: userCredential.id, counter: userCredential.counter, }, requireUserVerification: true, }); const authData = verification.authenticationInfo; const flags = authData.authenticatorData; // WebAuthn L3 Device-Bound Invariant: Reject backup-eligible/synced credentials const isBackupEligible = (flags[32] & 0x08) !== 0; const isCurrentlyBackedUp = (flags[32] & 0x10) !== 0; if (isBackupEligible || isCurrentlyBackedUp) { return res.status(403).json({ error: 'SECURITY_VIOLATION_DEVICE_BOUND_KEY_REQUIRED', message: 'Privileged operations strictly require a physical, non-synced hardware security key.', }); } if (!verification.verified || !authData.userVerified) { return res.status(401).json({ error: 'MFA verification failed' }); } // Invalidate challenge to guarantee single-use execution req.session.stepUpChallenge = ''; await executePrivilegedTenantAction(actionPayload); return res.json({ success: true, verifiedAt: new Date().toISOString() }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Level 3 Device-Bound Attestation Step-Up Enforcement

WebAuthn Level 3 Device-Bound Attestation Step-Up Enforcement defines an industrial-grade behavioral standard for security engineering. Mandates cryptographic verification of hardware-bound security keys during privileged tenant operations to mitigate account takeover via compromised cloud-synced passkey ecosystems. Step-up verification for administrative actions must strictly enforce non-backupable authenticator flags (BE=0, BS=0) and validate hardware attestation certificates. 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 to Authorize Privileged Tenant Mutations 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 to Authorize Privileged Tenant Mutations	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:

Services MUST inspect authenticatorData flags to assert backupEligible (BE) is false and backupState (BS) is false during privileged step-up authentication.

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.