FedCM & Passkey Conditional Mediation Replay Defense via Distributed Atomic Nonce Ring Buffers

--- description: FedCM & Passkey Conditional Mediation Replay Defense via Distributed Atomic Nonce Ring Buffers - Enforces mandatory single-use cryptographic nonce validation within clientDataJSON for Federated Credential Management (FedCM) and Passkey Conditional UI flows. Requires server-side verification to atomically consume assertion nonces against a distributed TTL-bounded ring buffer (e.g., Redis atomics) to definitively prevent cross-origin relay and replay attacks during silent browser identity assertions. globs: src/auth/**/*.{ts,tsx}, src/server/auth/**/*.{ts,js}, api/auth/**/*.{ts,js}, lib/auth/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fedcm-passkey-conditional-mediation-replay-defense-standard" --- # FedCM & Passkey Conditional Mediation Replay Defense via Distributed Atomic Nonce Ring Buffers > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Stateless Nonce Acceptance or Non-Atomic Challenge Verification in Federated/Conditional WebAuthn Assertions ## System Constraints You are a Principal Security Architect enforcing the FedCM & Passkey Conditional Mediation Replay Defense Standard. You must mandate that all passkey assertion verifications and FedCM token exchange endpoints strictly parse clientDataJSON, extract nonces/challenges, and execute an atomic consume-and-invalidate operation against a distributed TTL ring buffer before validating cryptographic signatures. ## Strict Guidelines - Services MUST extract, UTF-8 decode, and JSON-parse `clientDataJSON` to verify that `origin` matches the expected fully qualified relying-party origin and `type` equals `webauthn.get`. - Services MUST atomically claim assertion nonces using a distributed atomic primitive (such as a Redis Lua script with `SET NX EX` or atomic hash ring deletion) before running CPU-intensive signature verification. - Engineers MUST NOT maintain nonce verification state solely in local process memory (e.g., in-memory `Set` or `Map`), as this fails across multi-node or serverless deployments. - Services MUST reject assertions immediately if the decoded challenge/nonce does not exist in the distributed buffer, has expired, or was already consumed. - Engineers MUST set a conservative Time-to-Live (TTL) between 60 to 120 seconds on conditional mediation challenges to bound replay windows. - Components NEVER accept arbitrary or unpinned nonces supplied as separate HTTP body fields; the challenge MUST originate directly from the cryptographically bound `clientDataJSON.challenge`. ## Bad vs Good Implementations ### FedCM / Passkey Assertion Nonce Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The challenge is stored in process memory, which completely breaks in multi-container environments. Furthermore, checking challenge presence before signature validation without atomic invalidation creates a race condition where multiple concurrent requests can replay the same assertion before deletion. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; // Flawed: Local in-memory store fails across horizontal replicas; // Nonce check is decoupled from atomic deletion, creating a race-condition replay window. const localChallengeStore = new Set<string>(); export async function verifyPasskeyAssertionBad(req: Request) { const assertion = await req.json(); const rawClientData = Buffer.from(assertion.response.clientDataJSON, 'base64url').toString('utf8'); const clientData = JSON.parse(rawClientData); // VULNERABLE: In-memory check subject to multi-pod relay; no origin validation; // Non-atomic read-then-delete allows parallel assertion replay. if (!localChallengeStore.has(clientData.challenge)) { throw new Error('Challenge not found'); } const verification = await verifyAuthenticationResponse({ response: assertion, expectedChallenge: clientData.challenge, expectedOrigin: 'https://example.com', expectedRPID: 'example.com', authenticator: { credentialPublicKey: Buffer.from([]), counter: 0 } as any }); localChallengeStore.delete(clientData.challenge); return verification; } ``` #### Production Standard (Correct) > **Standard**: Validates the challenge and origin directly within clientDataJSON, and uses a distributed Redis Lua script to atomically check-and-delete the challenge key before executing cryptographic verification, eliminating replay race conditions across distributed server clusters. ```typescript import { verifyAuthenticationResponse } from '@simplewebauthn/server'; import type { Redis } from 'ioredis'; // Atomic consumption script: returns 1 if key existed and was deleted, 0 otherwise const ATOMIC_CONSUME_LUA = ` if redis.call('EXISTS', KEYS[1]) == 1 then redis.call('DEL', KEYS[1]) return 1 else return 0 end `; export async function verifyPasskeyAssertionGood( redis: Redis, assertion: any, expectedOrigin: string, expectedRPID: string, authenticator: any ) { // 1. Decode and strictly parse clientDataJSON const rawClientData = Buffer.from(assertion.response.clientDataJSON, 'base64url').toString('utf8'); const clientData = JSON.parse(rawClientData); if (clientData.type !== 'webauthn.get') { throw new Error('Invalid assertion type'); } if (clientData.origin !== expectedOrigin) { throw new Error(`Origin mismatch: expected ${expectedOrigin}, got ${clientData.origin}`); } const challengeNonce = clientData.challenge; const cacheKey = `auth:nonce:${challengeNonce}`; // 2. Atomic consume: distributed single-use validation prevents replay across all nodes const consumed = await redis.eval(ATOMIC_CONSUME_LUA, 1, cacheKey); if (consumed !== 1) { throw new Error('Assertion nonce invalid, already consumed, or expired'); } // 3. Complete cryptographic verification once nonce ownership is secured const verification = await verifyAuthenticationResponse({ response: assertion, expectedChallenge: challengeNonce, expectedOrigin, expectedRPID, authenticator }); if (!verification.verified) { throw new Error('Cryptographic assertion verification failed'); } return verification; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FedCM & Passkey Conditional Mediation Replay Defense via Distributed Atomic Nonce Ring Buffers

FedCM & Passkey Conditional Mediation Replay Defense via Distributed Atomic Nonce Ring Buffers defines an industrial-grade behavioral standard for security engineering. Enforces mandatory single-use cryptographic nonce validation within clientDataJSON for Federated Credential Management (FedCM) and Passkey Conditional UI flows. Requires server-side verification to atomically consume assertion nonces against a distributed TTL-bounded ring buffer (e.g., Redis atomics) to definitively prevent cross-origin relay and replay attacks during silent browser identity assertions. 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: Stateless Nonce Acceptance or Non-Atomic Challenge Verification in Federated/Conditional WebAuthn Assertions 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	Stateless Nonce Acceptance or Non-Atomic Challenge Verification in Federated/Conditional WebAuthn Assertions	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:

Services MUST extract, UTF-8 decode, and JSON-parse `clientDataJSON` to verify that `origin` matches the expected fully qualified relying-party origin and `type` equals `webauthn.get`.

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.