React 19 Server Actions Cryptographic Idempotency and Replay Guardrail

--- description: React 19 Server Actions Cryptographic Idempotency and Replay Guardrail - Enforces cryptographic replay protection and deterministic state reconciliation for React 19 Server Actions interacting with optimistic UI mutations. Prevents double-charge scenarios, orphaned side effects, and state desynchronization caused by automated browser retries, network blips, or concurrent optimistic dispatches. Mandates server-side idempotency keys backed by atomic reservation stores and signed action tokens. globs: src/actions/**/*.{ts,tsx}, src/app/**/*.{ts,tsx}, src/features/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-server-actions-cryptographic-idempotency" --- # React 19 Server Actions Cryptographic Idempotency and Replay Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Blind Server Action Dispatches Subject to Network Retries and Concurrent Duplicate Executions ## System Constraints You are a Principal Software Architect enforcing enterprise-grade idempotency and replay guardrails for React 19 Server Actions. Reject any server mutation that executes destructive side-effects without cryptographically verified client-generated idempotency keys and atomic state locking. Ensure optimistic UI rollbacks match idempotent transaction failures perfectly. ## Strict Guidelines - Engineers MUST ALWAYS pass a client-generated UUIDv4 or collision-resistant cryptographic hash as an idempotency key to mutating Server Actions. - Engineers MUST NOT rely on implicit framework-level caching, HTTP POST semantics, or transient React state to prevent duplicate server action executions during network retransmissions. - Services MUST implement atomic idempotency key reservation (e.g., Redis `SET NX EX` or database row-level locking with unique constraints) BEFORE executing any external side effects (e.g., Stripe, database mutations, emails). - Components using `useOptimistic` or `useActionState` MUST bind optimistic identifiers directly to the idempotency key so rollback state cleanly matches failed or duplicated network packets. - Server Actions MUST return the cached deterministic response payload if an idempotency key is replayed while completed, or throw a designated 409 Conflict if an operation with that key is currently in-flight. ## Bad vs Good Implementations ### Non-Idempotent Optimistic Server Action Execution vs. Atomic Token Guardrail #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Network timeouts or aggressive client-side retries during optimistic action execution will cause duplicate external payment charges and duplicate ledger rows because the action lacks replay protection and an atomic idempotency lock. ```typescript // BAD: Vulnerable to double charges and state corruption on network retries 'use server'; import { db } from '@/lib/db'; import { paymentGateway } from '@/lib/payments'; export async function processCheckoutAction(formData: FormData) { const accountId = formData.get('accountId') as string; const amount = Number(formData.get('amount')); // DANGER: Retries from network drops trigger duplicate charges const charge = await paymentGateway.charge({ accountId, amount }); await db.ledger.create({ data: { accountId, amount, transactionId: charge.id } }); return { success: true, chargeId: charge.id }; } ``` #### Production Standard (Correct) > **Standard**: The good pattern enforces input validation with a client-provided UUID idempotency key, acquires an atomic lock in Redis with 'NX' semantics to halt concurrent execution, records the transaction with downstream providers, and stores the completed state for future replay deduplication. ```typescript // GOOD: Production-grade atomic idempotency validation with replay cache 'use server'; import { db } from '@/lib/db'; import { redis } from '@/lib/redis'; import { paymentGateway } from '@/lib/payments'; import { z } from 'zod'; const ActionSchema = z.object({ idempotencyKey: z.string().uuid(), accountId: z.string().min(1), amount: z.number().positive(), }); type ActionResponse = { success: boolean; chargeId: string; replayed?: boolean }; export async function processCheckoutAction(rawInput: unknown): Promise<ActionResponse> { const parseResult = ActionSchema.safeParse(rawInput); if (!parseResult.success) { throw new Error('INVALID_INPUT: ' + parseResult.error.message); } const { idempotencyKey, accountId, amount } = parseResult.data; const lockKey = `idempotency:checkout:${idempotencyKey}`; // Step 1: Acquire atomic lock or retrieve cached outcome (TTL: 86400s) const lockAcquired = await redis.set(lockKey, 'IN_FLIGHT', 'EX', 120, 'NX'); if (!lockAcquired) { const existing = await redis.get(lockKey); if (existing && existing !== 'IN_FLIGHT') { return { ...JSON.parse(existing), replayed: true }; } throw new Error('CONCURRENT_MUTATION: Transaction is already processing.'); } try { // Step 2: Pass idempotency key to downstream PSP const charge = await paymentGateway.charge({ accountId, amount, idempotencyKey, }); await db.ledger.create({ data: { accountId, amount, transactionId: charge.id, idempotencyKey } }); const payload: ActionResponse = { success: true, chargeId: charge.id }; await redis.set(lockKey, JSON.stringify(payload), 'EX', 86400); return payload; } catch (error) { // Clean up lock if mutation failed prior to completion await redis.del(lockKey); throw error; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Actions Cryptographic Idempotency and Replay Guardrail

React 19 Server Actions Cryptographic Idempotency and Replay Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces cryptographic replay protection and deterministic state reconciliation for React 19 Server Actions interacting with optimistic UI mutations. Prevents double-charge scenarios, orphaned side effects, and state desynchronization caused by automated browser retries, network blips, or concurrent optimistic dispatches. Mandates server-side idempotency keys backed by atomic reservation stores and signed action tokens. 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: Blind Server Action Dispatches Subject to Network Retries and Concurrent Duplicate Executions 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	Blind Server Action Dispatches Subject to Network Retries and Concurrent Duplicate Executions	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 pass a client-generated UUIDv4 or collision-resistant cryptographic hash as an idempotency key to mutating Server 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.