Mandatory Hardware-Bound User Verification and Cryptographic Challenge Step-Up Guardrail

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Trusting Ambient Sessions or Permissive WebAuthn Assertions for Privileged Operations) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Mandatory Hardware-Bound User Verification and Cryptographic Challenge Step-Up Guardrail

--- description: Mandatory Hardware-Bound User Verification and Cryptographic Challenge Step-Up Guardrail - Enforces cryptographic re-attestation and explicit user verification (UV) before high-privilege mutations to mitigate unauthorized actions from cloud-synced or cloned multi-device credentials. High-risk operations must mandate fresh server-side ephemeral challenges and reject any assertion lacking strict hardware-level user verification and action payload binding. globs: src/auth/**/*.ts, src/server/auth/**/*.ts, src/api/**/step-up.ts, src/controllers/auth/**/*.ts, src/lib/webauthn/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-synced-passkey-stepup-attestation-standard" --- # Mandatory Hardware-Bound User Verification and Cryptographic Challenge Step-Up Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Trusting Ambient Sessions or Permissive WebAuthn Assertions for Privileged Operations ## System Constraints You are a Principal Security Architect enforcing zero-trust WebAuthn invariants. Mandate that all sensitive operations (such as MFA changes, credential rotation, high-value transfers, and IAM updates) demand real-time step-up authentication. Enforce that client authentication requests specify userVerification: 'required', and the server must strictly validate the 'uv' (User Verified) authenticator flag, tie challenges to SHA-256 payload digests, and reject multi-device credentials where hardware-bound security keys are mandatory. ## Strict Guidelines - Engineers MUST ALWAYS require `userVerification: 'required'` in both client-side `PublicKeyCredentialRequestOptions` and server-side verification algorithms for step-up escalation. - Engineers MUST NOT accept cached session tokens, ambient cookies, or assertions with `flags.uv === false` for privileged state modifications. - Code SHOULD bind the WebAuthn challenge to a cryptographic SHA-256 hash of the specific transaction payload and enforce a challenge TTL of 120 seconds or less. - Services MUST ensure single-use challenge consumption by atomically invalidating challenges in distributed cache/database immediately upon first verification attempt. - Components NEVER execute sensitive operations without verifying that the authenticator counter increased or evaluating device public key (DPK) / credential backup state when mitigating cloned synced passkeys. ## Bad vs Good Implementations ### Vulnerable vs. Hardened WebAuthn Step-Up Assertion Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The handler relies on a loose verification profile (`requireUserVerification: false`), allowing multi-device synced passkeys to fulfill assertions without active biometric confirmation or PIN. Furthermore, the challenge is not cryptographically bound to the transfer parameters, leaving it susceptible to challenge-reuse and session-riding attacks. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { Request, Response } from 'express'; export async function handlePrivilegedTransfer(req: Request, res: Response) { const { assertion, amount, recipientId } = req.body; const user = req.session.user; // VULNERABLE: Uses generic session challenge and does not mandate UV (User Verification) const verification = await verifyAuthenticationResponse({ response: assertion, expectedChallenge: req.session.currentChallenge, expectedOrigin: 'https://example.com', expectedRPID: 'example.com', authenticator: user.passkey, requireUserVerification: false // CRITICAL: Permits unverified/passive presence }); if (!verification.verified) { return res.status(401).json({ error: 'Verification failed' }); } // Flaw: Synced passkey could be extracted or asserted without explicit biometrics await executeTransfer(user.id, recipientId, amount); return res.json({ success: true }); } ``` #### Production Standard (Correct) > **Standard**: The solution implements defense-in-depth step-up attestation: it generates an action-bound ephemeral challenge tied to the SHA-256 digest of the request payload, atomically consumes it via `getdel` to prevent replay, strictly enforces `requireUserVerification: true`, validates both `uv` and `up` flags, and checks the signature counter to safeguard against credential cloning. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import { createHash } from 'node:crypto'; import type { Request, Response } from 'express'; import { redis } from '../lib/redis'; export async function handlePrivilegedTransfer(req: Request, res: Response) { const { assertion, amount, recipientId, challengeToken } = req.body; const userId = req.session.user.id; // 1. Compute deterministic action payload digest const payloadDigest = createHash('sha256') .update(`${userId}:${amount}:${recipientId}`) .digest('hex'); // 2. Atomically consume the action-bound ephemeral challenge (TTL <= 120s) const challengeKey = `stepup:${userId}:${challengeToken}`; const storedChallengeData = await redis.getdel(challengeKey); if (!storedChallengeData) { return res.status(401).json({ error: 'Step-up challenge expired or already consumed' }); } const { expectedChallenge, expectedPayloadDigest } = JSON.parse(storedChallengeData); if (expectedPayloadDigest !== payloadDigest) { return res.status(400).json({ error: 'Payload tampering detected: digest mismatch' }); } const passkey = await getPasskeyForUser(userId, assertion.id); // 3. Verify assertion requiring explicit biometric / PIN re-attestation const verification = await verifyAuthenticationResponse({ response: assertion, expectedChallenge, expectedOrigin: process.env.AUTH_ORIGIN!, expectedRPID: process.env.AUTH_RP_ID!, authenticator: { credentialPublicKey: passkey.publicKey, credentialID: passkey.credentialId, counter: passkey.counter, }, requireUserVerification: true // HARDWARE / BIOMETRIC ENFORCEMENT }); const { flags } = verification.authenticationInfo; if (!flags.uv || !flags.up) { return res.status(403).json({ error: 'Hardware biometric presence (UV) required' }); } // 4. Update authenticator counter to detect cloned authenticator state await updatePasskeyCounter(passkey.credentialId, verification.authenticationInfo.newCounter); await executeTransfer(userId, recipientId, amount); return res.json({ success: true, verifiedAt: new Date().toISOString() }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory Hardware-Bound User Verification and Cryptographic Challenge Step-Up Guardrail

Mandatory Hardware-Bound User Verification and Cryptographic Challenge Step-Up Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces cryptographic re-attestation and explicit user verification (UV) before high-privilege mutations to mitigate unauthorized actions from cloud-synced or cloned multi-device credentials. High-risk operations must mandate fresh server-side ephemeral challenges and reject any assertion lacking strict hardware-level user verification and action payload binding. 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 Ambient Sessions or Permissive WebAuthn Assertions for Privileged Operations 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 Ambient Sessions or Permissive WebAuthn Assertions for Privileged Operations	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 require `userVerification

Engineers MUST ALWAYS require `userVerification: 'required'` in both client-side `PublicKeyCredentialRequestOptions` and server-side verification algorithms for step-up escalation.

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.