WebAuthn Passkey Conditional Mediation Rate-Fencing & Assertion Isolation

--- description: WebAuthn Passkey Conditional Mediation Rate-Fencing & Assertion Isolation - Enforces strict server-side rate-fencing, atomic challenge invalidation, and origin-bound assertion validation for WebAuthn autofill/conditional UI requests. Mitigates automated cross-device credential enumeration, passkey credential stuffing, and replay attacks on ambient authentication flows. Guarantees that ephemeral conditional challenges cannot be recycled across sessions or elevated into modal authentication contexts. globs: src/auth/**/*.{ts,tsx}, src/server/auth/**/*.ts, src/pages/api/auth/**/*.ts, src/routes/auth/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/webauthn-conditional-mediation-rate-fencing-standard" --- # WebAuthn Passkey Conditional Mediation Rate-Fencing & Assertion Isolation > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unmetered Conditional WebAuthn Verification with Reusable or Shared Challenges ## System Constraints You are a Principal Security Architect enforcing the WebAuthn Passkey Conditional Mediation Rate-Fencing Standard. You must mandate strict cryptographic binding, single-use atomic challenge consumption, and sliding-window rate limiting on all conditional WebAuthn verification endpoints. ## Strict Guidelines - Engineers MUST ALWAYS isolate conditional mediation authentication challenges into a dedicated Redis/datastore namespace with a strict maximum TTL of 60 seconds. - Engineers MUST atomically consume challenges (e.g., using Redis GETDEL or atomic Lua scripts) upon the first verification attempt regardless of whether the assertion signature succeeds or fails. - Services MUST enforce token-bucket or sliding-window rate-limiting scoped to IP, client session ID, and target Relying Party (RP) ID prior to executing expensive cryptographic signature verifications. - Engineers MUST NOT allow a challenge generated for conditional UI (`mediation: 'conditional'`) to be validated in a modal or registration WebAuthn transaction. - Verification routines MUST explicitly validate expected RP ID, expected Origin (enforcing exact scheme, hostname, and port), and enforce user verification policies (`userVerification: 'preferred'` or `'required'`). - Services MUST reject authentication attempts if the authenticator clone detection triggers an anomaly on counter progression for hardware authenticators, while safely accommodating multi-device sync passkeys with counter-bypass flags. ## Bad vs Good Implementations ### Vulnerable vs Secure Conditional WebAuthn Assertion Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The session challenge is checked non-atomically and only removed upon success, leaving it vulnerable to automated replay attacks, parallel race conditions, and denial of service via CPU-heavy cryptographic operations without rate limiting. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { Request, Response } from 'express'; export async function verifyPasskeyBad(req: Request, res: Response) { const { credential, email } = req.body; // Flaw 1: Session challenge is read without atomic invalidation (race condition / replay) const expectedChallenge = req.session.currentChallenge; if (!expectedChallenge) { return res.status(400).json({ error: 'No challenge in session' }); } // Flaw 2: No rate-limiting before CPU-intensive cryptographic signature verification // Flaw 3: Does not enforce mediation context isolation const verification = await verifyAuthenticationResponse({ response: credential, expectedChallenge, expectedOrigin: 'https://example.com', expectedRPID: 'example.com', requireUserVerification: false }); if (verification.verified) { // Flaw 4: Challenge deleted only after success; failed attempts can be replayed delete req.session.currentChallenge; return res.json({ status: 'ok' }); } return res.status(401).json({ error: 'Authentication failed' }); } ``` #### Production Standard (Correct) > **Standard**: Implements an atomic Redis GETDEL challenge retrieval, preventing challenge reuse across parallel attempts or re-entrant calls. Applies a pre-signature verification rate-limiting fence and confirms the challenge was issued specifically for conditional mediation. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { Request, Response } from 'express'; import { redis } from '../lib/redis'; import { rateLimiter } from '../lib/rate-limiter'; const CHALLENGE_PREFIX = 'webauthn:conditional:challenge:'; const RATE_LIMIT_PREFIX = 'rate-fence:conditional-passkey:'; export async function verifyPasskeyGood(req: Request, res: Response) { const clientIp = req.ip || req.socket.remoteAddress || 'unknown'; const sessionId = req.cookies?.auth_session_id; const { credential } = req.body; if (!sessionId || !credential?.id) { return res.status(400).json({ error: 'Malformed assertion payload' }); } // Invariant 1: Multi-tiered rate fence per IP and session before crypto execution const isAllowed = await rateLimiter.checkLimit(`${RATE_LIMIT_PREFIX}${clientIp}:${sessionId}`, { maxRequests: 5, windowSeconds: 60 }); if (!isAllowed) { return res.status(429).json({ error: 'Too many conditional authentication attempts' }); } // Invariant 2: Atomic consumption of single-use challenge via Redis GETDEL const challengeKey = `${CHALLENGE_PREFIX}${sessionId}`; const challengeMetadataRaw = await redis.getdel(challengeKey); if (!challengeMetadataRaw) { return res.status(401).json({ error: 'Authentication challenge expired or already consumed' }); } const challengeMetadata = JSON.parse(challengeMetadataRaw) as { challenge: string; mediationType: 'conditional' | 'modal'; issuedAt: number; }; // Invariant 3: Enforce strict mediation context binding if (challengeMetadata.mediationType !== 'conditional') { return res.status(403).json({ error: 'Challenge context mismatch' }); } const verification = await verifyAuthenticationResponse({ response: credential, expectedChallenge: challengeMetadata.challenge, expectedOrigin: process.env.AUTH_EXPECTED_ORIGIN!, expectedRPID: process.env.AUTH_RP_ID!, requireUserVerification: true }); if (!verification.verified) { return res.status(401).json({ error: 'Verification signature rejected' }); } return res.json({ status: 'ok', userId: verification.authenticationInfo.userId }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAuthn Passkey Conditional Mediation Rate-Fencing & Assertion Isolation

WebAuthn Passkey Conditional Mediation Rate-Fencing & Assertion Isolation defines an industrial-grade behavioral standard for security engineering. Enforces strict server-side rate-fencing, atomic challenge invalidation, and origin-bound assertion validation for WebAuthn autofill/conditional UI requests. Mitigates automated cross-device credential enumeration, passkey credential stuffing, and replay attacks on ambient authentication flows. Guarantees that ephemeral conditional challenges cannot be recycled across sessions or elevated into modal authentication contexts. 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: Unmetered Conditional WebAuthn Verification with Reusable or Shared Challenges 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	Unmetered Conditional WebAuthn Verification with Reusable or Shared Challenges	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 isolate conditional mediation authentication challenges into a dedicated Redis/datastore namespace with a strict maximum TTL of 60 seconds.

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.