WebAuthn Device-Bound Step-Up Credential Invariant

--- description: WebAuthn Device-Bound Step-Up Credential Invariant - Enforces cryptographic and structural validation that rejects multi-device synced passkeys for high-risk transactions. Requires hardware-bound authenticators by strictly inspecting the Backup State (BS) and Backup Eligibility (BE) flags alongside explicit Authenticator Attachment requirements during WebAuthn assertion verification. globs: src/services/auth/**/*.{ts,tsx}, src/controllers/auth/**/*.{ts,tsx}, src/lib/webauthn/**/*.{ts,tsx}, src/api/transactions/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-device-bound-step-up-invariant" --- # WebAuthn Device-Bound Step-Up Credential Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Synced Passkeys for Critical Authorization and Omitting Authenticator Attachment Invariants ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Device-Bound Step-Up Credential Invariant. You must reject any authentication or authorization implementation that accepts multi-device synced credentials (e.g., iCloud Keychain, Google Password Manager) for high-risk transactions. You must strictly enforce the verification of Authenticator Data flags: specifically verifying that Backup Eligibility (BE) and Backup State (BS) are false, or that attestation/registration guarantees a non-exportable hardware-backed key (e.g., YubiKey, Secure Enclave with device-bound attestation). Ensure userVerification is strictly 'required' and challenge tokens are cryptographically bound to the transaction payload. ## Strict Guidelines - Engineers MUST ALWAYS set `userVerification: 'required'` in WebAuthn assertion options for step-up actions. - Engineers MUST ALWAYS compute the WebAuthn challenge by hashing transaction-specific context (e.g., amount, target account, nonce) via SHA-256 to prevent replay and relay attacks. - Engineers MUST NOT rely solely on default library verification; code MUST explicitly inspect the verified `authenticatorData.flags` bitmask for Backup State (`BS`, bit 2) and Backup Eligibility (`BE`, bit 3). - Services MUST reject any assertion intended for step-up authorization if `flags.backedUp` (BS) is true or `flags.backupEligible` (BE) is true, unless paired with an approved enterprise attestation statement proving non-exportable cryptographic hardware bound state. - Code MUST verify credential ID membership against an allowlist of pre-registered, hardware-bound credential IDs associated with the user profile. ## Bad vs Good Implementations ### Step-Up WebAuthn Assertion Verification for High-Risk Financial Action #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This handler accepts user-presence-only authentication (userVerification not enforced) and completely ignores the Backup Eligibility (BE) and Backup State (BS) flags in AuthenticatorData. A compromised synced cloud passkey (e.g., from an attacker syncing credentials via an iCloud/Google account compromise) can execute this high-risk transaction. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { AuthenticationResponseJSON } from '@simplewebauthn/types'; import { Request, Response } from 'express'; export async function verifyStepUpTransaction(req: Request, res: Response) { const { response, expectedChallenge, credential } = req.body as { response: AuthenticationResponseJSON; expectedChallenge: string; credential: { id: string; publicKey: Uint8Array; counter: number }; }; // VULNERABLE: Accepts any valid passkey including multi-device synced passkeys. // Fails to inspect AuthenticatorData backup flags or enforce device-bound requirements. const verification = await verifyAuthenticationResponse({ response, expectedChallenge, expectedOrigin: 'https://bank.example.com', expectedRPID: 'bank.example.com', authenticator: { credentialID: Buffer.from(credential.id, 'base64url'), credentialPublicKey: credential.publicKey, counter: credential.counter, }, requireUserVerification: false, // Insecure: Omits UV constraint }); if (!verification.verified) { return res.status(401).json({ error: 'Verification failed' }); } return res.status(200).json({ status: 'approved' }); } ``` #### Production Standard (Correct) > **Standard**: Enforces user verification (`requireUserVerification: true`), validates that the credential was marked device-bound at registration, binds the challenge directly to the transaction payload, and strictly validates that `flags.backupEligible` and `flags.backedUp` are both false, deterministically rejecting synced passkeys. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { AuthenticationResponseJSON } from '@simplewebauthn/types'; import { createHash } from 'node:crypto'; import { Request, Response } from 'express'; interface StoredCredential { id: string; publicKey: Uint8Array; counter: number; isDeviceBound: boolean; } export async function verifyStepUpTransaction( req: Request, res: Response, getStoredCredential: (id: string) => Promise<StoredCredential | null> ) { const { response, transactionPayload, expectedSessionChallenge, } = req.body; // Deterministically recompute challenge bound to transaction data and session challenge const expectedChallenge = createHash('sha256') .update(`${expectedSessionChallenge}:${JSON.stringify(transactionPayload)}`) .digest('base64url'); const credential = await getStoredCredential(response.id); if (!credential || !credential.isDeviceBound) { return res.status(403).json({ error: 'Credential must be an enrolled, hardware-bound authenticator', }); } const verification = await verifyAuthenticationResponse({ response, expectedChallenge, expectedOrigin: 'https://bank.example.com', expectedRPID: 'bank.example.com', authenticator: { credentialID: Buffer.from(credential.id, 'base64url'), credentialPublicKey: credential.publicKey, counter: credential.counter, }, requireUserVerification: true, }); if (!verification.verified || !verification.authenticationInfo) { return res.status(401).json({ error: 'Assertion validation failed' }); } const { flags } = verification.authenticationInfo.authenticatorData; // INVARIANT: Reject multi-device synced passkeys. // For strict device-bound step-up, Backup Eligibility (BE) and Backup State (BS) must be false. if (flags.backupEligible || flags.backedUp) { return res.status(403).json({ error: 'Multi-device synced credentials not permitted for high-risk operations', }); } return res.status(200).json({ status: 'approved' }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Device-Bound Step-Up Credential Invariant

WebAuthn Device-Bound Step-Up Credential Invariant defines an industrial-grade behavioral standard for security engineering. Enforces cryptographic and structural validation that rejects multi-device synced passkeys for high-risk transactions. Requires hardware-bound authenticators by strictly inspecting the Backup State (BS) and Backup Eligibility (BE) flags alongside explicit Authenticator Attachment requirements during WebAuthn assertion verification. 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 Critical Authorization and Omitting Authenticator Attachment Invariants 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 Critical Authorization and Omitting Authenticator Attachment Invariants	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 set `userVerification

Engineers MUST ALWAYS set `userVerification: 'required'` in WebAuthn assertion options 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.