WebAuthn Level 3 Synced Passkey Attestation & Step-Up Transaction Binding

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Trusting Bearer Session Tokens for High-Privilege Actions Without Cryptographic Challenge-Response Binding and Backup State Verification) 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.

WebAuthn Level 3 Synced Passkey Attestation & Step-Up Transaction Binding

--- description: WebAuthn Level 3 Synced Passkey Attestation & Step-Up Transaction Binding - Enforces strict W3C WebAuthn Level 3 cryptographic verification, distinguishing hardware-bound FIDO2 devices from multi-device synced passkeys via credential backup state checks. Mandates short-lived, transaction-bound cryptographic challenges during step-up re-authentication to prevent session hijacking and adversary-in-the-middle (AiTM) proxy replay attacks. globs: src/auth/**/*.{ts,tsx}, src/server/auth/**/*.{ts,tsx}, src/services/security/**/*.{ts,tsx}, src/api/v1/auth/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-l3-passkey-attestation-step-up-binding" --- # WebAuthn Level 3 Synced Passkey Attestation & Step-Up Transaction Binding > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Trusting Bearer Session Tokens for High-Privilege Actions Without Cryptographic Challenge-Response Binding and Backup State Verification ## System Constraints You are a Principal Security Architect enforcing W3C WebAuthn Level 3 specifications and zero-trust step-up authorization. You must ensure that authentication challenges cannot be intercepted or replayed by AiTM reverse proxies. Mandate strict cryptographic validation of AuthenticatorData flags (UP, UV, BE, BS), verify clientDataJSON against expected origins and nonces, and enforce cryptographically bound step-up challenges for high-risk operations. ## Strict Guidelines - Engineers MUST ALWAYS verify both User Presence (UP) and User Verification (UV) flags in authenticatorData for every authentication and step-up response. - Engineers MUST ALWAYS cryptographically bind sensitive step-up payloads by deriving the challenge as SHA-256(nonce + session_id + action_payload_hash) and storing it in transient cache with a TTL <= 120 seconds. - Engineers MUST NOT rely on standard bearer session cookies or JWTs alone for privileged actions; high-risk endpoints MUST require a completed step-up assertion signature. - Services MUST inspect Backup Eligibility (BE) and Backup State (BS) flags in authenticatorData to determine if the credential is a synced passkey or device-bound hardware authenticator. - Services MUST validate that clientDataJSON.origin strictly matches the expected fully qualified domain (and scheme) without accepting wildcard domains or dynamic origins from request headers. - Components NEVER store or reuse challenges across different operations or sessions; every challenge MUST be single-use and invalidated immediately upon verification attempt. ## Bad vs Good Implementations ### Step-Up Re-Authentication Challenge Verification & Authenticator Flags Check #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accepts origin directly from the client request header (vulnerable to AiTM spoofing), sets requireUserVerification to false, fails to bind the challenge cryptographically to the transaction payload, and does not verify credential backup status (BE/BS flags) or invalidate the challenge on use. ```typescript import { Request, Response } from 'express'; import { verifyAuthenticationResponse } from '@simplewebauthn/server'; export async function handleStepUpTransfer(req: Request, res: Response) { const { authenticationResponse, amount, recipientId } = req.body; // BAD: Challenge not bound to the transaction payload; accepting challenge directly from session const expectedChallenge = req.session.currentChallenge; const verification = await verifyAuthenticationResponse({ response: authenticationResponse, expectedChallenge, expectedOrigin: req.headers.origin as string, // VULNERABILITY: Trusting header origin allows AiTM bypass expectedRPID: 'example.com', requireUserVerification: false, // VULNERABILITY: UV not strictly enforced }); if (verification.verified) { await executeTransfer(recipientId, amount); return res.json({ success: true }); } return res.status(401).json({ error: 'Failed step-up' }); } ``` #### Production Standard (Correct) > **Standard**: Validates single-use transient challenges bound to session and transaction payload, hardcodes expected origin, mandates User Verification (UV) and User Presence (UP), updates authenticator counter, and inspects Level 3 backup flags to restrict high-risk transactions. ```typescript import { Request, Response } from 'express'; import { createHash } from 'node:crypto'; import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import { getTransientChallenge, invalidateChallenge } from '../services/challengeStore'; import { getPasskeyCredential } from '../services/credentialStore'; export async function handleStepUpTransfer(req: Request, res: Response) { const { authenticationResponse, amount, recipientId, challengeToken } = req.body; const sessionId = req.session.id; // 1. Retrieve and invalidate single-use transaction-bound challenge const storedChallengeData = await getTransientChallenge(challengeToken); if (!storedChallengeData || storedChallengeData.sessionId !== sessionId) { return res.status(401).json({ error: 'Invalid or expired challenge context' }); } await invalidateChallenge(challengeToken); // 2. Recompute expected challenge: SHA-256(sessionId + actionPayload) const actionHash = createHash('sha256').update(`${recipientId}:${amount}`).digest('hex'); const expectedChallenge = createHash('sha256') .update(`${storedChallengeData.nonce}:${sessionId}:${actionHash}`) .digest('base64url'); const credential = await getPasskeyCredential(authenticationResponse.id); if (!credential) { return res.status(404).json({ error: 'Credential not registered' }); } // 3. Strict verification with hardcoded RP ID and Origin const verification = await verifyAuthenticationResponse({ response: authenticationResponse, expectedChallenge, expectedOrigin: 'https://app.example.com', expectedRPID: 'example.com', authenticator: { credentialPublicKey: credential.publicKey, credentialID: credential.id, counter: credential.counter, }, requireUserVerification: true, }); const { flags } = verification.authenticationInfo; // 4. Level 3 Invariant: Enforce UP and UV; evaluate backup status if (!verification.verified || !flags.userPresent || !flags.userVerified) { return res.status(403).json({ error: 'Biometric verification or presence confirmation failed' }); } const isSyncedPasskey = flags.backupEligible && flags.backupState; if (amount > 100000 && isSyncedPasskey) { return res.status(403).json({ error: 'High-value transactions require a hardware-bound authenticator' }); } await executeTransfer(recipientId, amount); return res.json({ success: true, verifiedAt: new Date().toISOString() }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Level 3 Synced Passkey Attestation & Step-Up Transaction Binding

WebAuthn Level 3 Synced Passkey Attestation & Step-Up Transaction Binding defines an industrial-grade behavioral standard for security engineering. Enforces strict W3C WebAuthn Level 3 cryptographic verification, distinguishing hardware-bound FIDO2 devices from multi-device synced passkeys via credential backup state checks. Mandates short-lived, transaction-bound cryptographic challenges during step-up re-authentication to prevent session hijacking and adversary-in-the-middle (AiTM) proxy replay attacks. 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 Bearer Session Tokens for High-Privilege Actions Without Cryptographic Challenge-Response Binding and Backup State Verification 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 Bearer Session Tokens for High-Privilege Actions Without Cryptographic Challenge-Response Binding and Backup State Verification	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 verify both User Presence (UP) and User Verification (UV) flags in authenticatorData for every authentication and step-up response.

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.