WebAuthn Hardware-Backed UV and Device-Bound Attestation Step-Up Standard

--- description: WebAuthn Hardware-Backed UV and Device-Bound Attestation Step-Up Standard - Mandates cryptographic validation of WebAuthn authenticator data flags, specifically verifying User Verification (UV=1) and device-bound credential constraints (backup eligibility flags BE=0, BS=0) before authorizing high-entropy, privileged, or financial transactions. Prohibits trusting client-asserted verification status, unverified authenticator counters, or multi-device synced passkeys when strict hardware isolation and enterprise non-repudiation are required. globs: src/auth/**/*.{ts,tsx}, src/server/auth/**/*.{ts,tsx}, server/routes/**/*.{ts,tsx}, src/services/security/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-device-bound-attestation-step-up-standard" --- # WebAuthn Hardware-Backed UV and Device-Bound Attestation Step-Up Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Trusting client-reported passkey verification without validating server-side authenticatorData UV flags and device-bound attestation properties. ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Device-Bound Attestation Step-Up Verification Standard. Mandate cryptographic verification of authenticatorData bit flags (specifically UV, UP, BE, BS) and monotonic signCount validation on the server side before authorizing any high-risk state-changing operations. ## Strict Guidelines - Engineers MUST ALWAYS enforce `userVerification: 'required'` (not `'preferred'`) in server-generated `PublicKeyCredentialRequestOptions` for step-up actions. - Engineers MUST verify the `authenticatorData` flags bitwise on the server, asserting that both Bit 0 (User Present / UP) and Bit 2 (User Verified / UV) are strictly set to 1. - Engineers MUST enforce device-bound non-exportability for high-security workflows by rejecting credentials where Backup State (BS=1) or asserting that Backup Eligibility (BE=0) matches compliance constraints. - Engineers MUST validate that `signCount` strictly increases monotonically (counter check) to detect cloned authenticators, or handle authenticators with fixed 0 counters according to FIDO specifications. - Engineers MUST cryptographically tie the step-up challenge to the user session, enforce a strict TTL (maximum 120 seconds), and immediately invalidate the challenge nonce upon first use (single-use guarantee). - Services MUST NOT rely on client-side properties (e.g., `credential.response.clientDataJSON` alone or client-provided booleans) without decoding and verifying the raw `authenticatorData` binary payload. - Components NEVER store or authorize high-risk operations based solely on primary session cookies; a fresh cryptographic assertion signature must be verified within the active execution frame. ## Bad vs Good Implementations ### WebAuthn Step-Up Verification for Critical Operations #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The handler performs a superficial signature verification without decoding and inspecting `authenticatorData`. It fails to verify that User Verification (UV) occurred, ignores the clone detection counter (`signCount`), accepts non-device-bound credentials (synced passkeys) without distinction, and does not burn the step-up challenge nonce atomically. ```typescript import { Request, Response } from 'express'; import { verifySignature } from './crypto-utils'; // ANTI-PATTERN: Blindly trusting signature without verifying UV flags or credential bounds export async function handlePrivilegedTransfer(req: Request, res: Response) { const { challenge, credential, amount, recipient } = req.body; // Flaw 1: No server-side session-binding verification for challenge const isChallengeValid = await db.challenges.exists({ challenge }); if (!isChallengeValid) { return res.status(401).json({ error: 'Invalid challenge' }); } // Flaw 2: Verifying signature over clientDataJSON without validating authenticatorData flags (UV/UP) const isValidSig = verifySignature(credential.publicKey, credential.signature, credential.response); if (!isValidSig) { return res.status(401).json({ error: 'Signature invalid' }); } // Flaw 3: Does not verify whether credential is a synced passkey or device-bound hardware token // Flaw 4: Sign counter is not verified, leaving the door open to credential cloning await executeTransfer({ userId: req.user.id, amount, recipient }); return res.json({ success: true }); } ``` #### Production Standard (Correct) > **Standard**: The implementation mandates `requireUserVerification: true`, consumes a single-use session-bound challenge with an explicit TTL, verifies counter monotonicity against cloned credentials, and guarantees that the assertion originates from a hardware-backed, non-synced (`singleDevice`) passkey before authorizing the transfer. ```typescript import { Request, Response } from 'express'; import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { AuthenticationResponseJSON } from '@simplewebauthn/types'; import { getStoredCredential, consumeStepUpChallenge, recordSignCount } from './auth-service'; const STEP_UP_MAX_AGE_MS = 120_000; export async function handlePrivilegedTransfer(req: Request, res: Response) { const { assertionResponse, amount, recipient }: { assertionResponse: AuthenticationResponseJSON; amount: number; recipient: string; } = req.body; const userId = req.user.id; // 1. Atomically consume challenge tied specifically to this user and session const expectedChallenge = await consumeStepUpChallenge(userId, req.session.id, STEP_UP_MAX_AGE_MS); if (!expectedChallenge) { return res.status(401).json({ error: 'Step-up challenge expired or already consumed' }); } // 2. Fetch registered credential metadata const storedCredential = await getStoredCredential(userId, assertionResponse.id); if (!storedCredential) { return res.status(404).json({ error: 'Credential not registered' }); } // 3. Cryptographically verify authentication response with strict UV enforcement const verification = await verifyAuthenticationResponse({ response: assertionResponse, expectedChallenge, expectedOrigin: process.env.AUTH_RP_ORIGIN!, expectedRPID: process.env.AUTH_RP_ID!, authenticator: { credentialPublicKey: storedCredential.publicKey, credentialID: storedCredential.id, counter: storedCredential.signCount, }, requireUserVerification: true, // Mandates UV bit flag in authenticatorData }); if (!verification.verified || !verification.authenticationInfo) { return res.status(401).json({ error: 'Cryptographic assertion failed' }); } const { userVerified, newCounter, credentialDeviceType } = verification.authenticationInfo; // 4. Enforce hardware device-bound requirement (reject multi-device synced passkeys for privileged tier) if (!userVerified) { return res.status(403).json({ error: 'Hardware biometric or PIN user verification mandatory' }); } if (credentialDeviceType !== 'singleDevice') { return res.status(403).json({ error: 'Device-bound hardware authenticator required for this operation' }); } // 5. Update monotonic signature counter to guard against credential clones await recordSignCount(storedCredential.id, newCounter); // 6. Authorize the high-entropy operation within the attested context const transferResult = await executeTransfer({ userId, amount, recipient }); return res.json({ success: true, transactionId: transferResult.id }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Hardware-Backed UV and Device-Bound Attestation Step-Up Standard

WebAuthn Hardware-Backed UV and Device-Bound Attestation Step-Up Standard defines an industrial-grade behavioral standard for security engineering. Mandates cryptographic validation of WebAuthn authenticator data flags, specifically verifying User Verification (UV=1) and device-bound credential constraints (backup eligibility flags BE=0, BS=0) before authorizing high-entropy, privileged, or financial transactions. Prohibits trusting client-asserted verification status, unverified authenticator counters, or multi-device synced passkeys when strict hardware isolation and enterprise non-repudiation are required. 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: Trusting client-reported passkey verification without validating server-side authenticatorData UV flags and device-bound attestation properties. 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	Trusting client-reported passkey verification without validating server-side authenticatorData UV flags and device-bound attestation properties.	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 enforce `userVerification

Engineers MUST ALWAYS enforce `userVerification: 'required'` (not `'preferred'`) in server-generated `PublicKeyCredentialRequestOptions` for step-up actions.

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.