React 19 Server Actions Cryptographic Replay Deduplication Standard

Enforces mandatory client-generated cryptographically secure idempotency keys and server-side atomic state locking across distributed RPC boundaries for non-idempotent React 19 Server Actions. Prevents catastrophic double-execution of financial transactions, state mutations, and external API requests caused by network retry flaps, connection timeouts, or unconstrained client re-submissions. Guarantees linearizable mutation guarantees by unifying distributed atomic locks with deterministic response caching.

--- description: React 19 Server Actions Cryptographic Replay Deduplication Standard - Enforces mandatory client-generated cryptographically secure idempotency keys and server-side atomic state locking across distributed RPC boundaries for non-idempotent React 19 Server Actions. Prevents catastrophic double-execution of financial transactions, state mutations, and external API requests caused by network retry flaps, connection timeouts, or unconstrained client re-submissions. Guarantees linearizable mutation guarantees by unifying distributed atomic locks with deterministic response caching. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx}, actions/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-server-actions-cryptographic-replay-deduplication-standard" --- # React 19 Server Actions Cryptographic Replay Deduplication Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Executing Non-Idempotent React 19 Server Actions Without Distributed Locks and Replay Nonces ## System Constraints You are a Principal Software Architect enforcing enterprise-grade idempotency and replay deduplication protocols for React 19 Server Actions. You must reject any non-idempotent server action (such as balance deduction, payment capture, entity creation, or external webhooks) that lacks a client-generated cryptographic nonce validated against a distributed atomic lock (e.g., Redis Redlock or Postgres transactional reservation). Ensure that duplicate executions return cached responses or structured concurrency rejection statuses rather than executing duplicate downstream side effects. ## Strict Guidelines - Engineers MUST ALWAYS supply a client-generated UUIDv4/UUIDv7 idempotency nonce or HMAC payload signature within form data or action arguments for every non-idempotent Server Action. - Engineers MUST ALWAYS validate incoming idempotency tokens through an atomic check-and-set mechanism (e.g., Redis 'SET key val NX EX' or an equivalent transactional DB reservation) before initiating mutation logic. - Engineers MUST NOT execute external transactional mutations (e.g., Stripe API, internal payment ledgers, inventory decrement) before securing an exclusive distributed lock associated with the action's idempotency key. - Services MUST cache the terminal output of successful mutations indexed by the idempotency key with an explicit TTL to allow deterministic replay responses for subsequent duplicate requests. - Components NEVER trigger Server Actions directly inside optimistic transitions or useEffect bodies without wrapping state machines in 'useActionState' with deterministic key binding to prevent uncontrolled re-triggers across rapid UI renders. - Code SHOULD gracefully release or transition lock states from 'IN_FLIGHT' to 'FAILED' during unhandled server exceptions to prevent permanent user deadlocks. - All mutation payloads MUST be structurally validated with runtime schema validation (e.g., Zod) before acquiring idempotency locks to avoid locking invalid execution contexts. ## Bad vs Good Implementations ### Vulnerable React 19 Server Action Vulnerable to Double-Spend on Network Retry #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This server action directly executes financial charges without validating an idempotency token. When a network connection drops mid-flight or a user multi-clicks a submit button during a transient connection hiccup, React 19 or the browser re-dispatches the RPC, resulting in double-charging the customer and duplicate database records. ```typescript 'use server'; import { db } from '@/lib/db'; import { paymentGateway } from '@/lib/payment'; interface CheckoutState { success: boolean; error?: string; } // VULNERABLE: Direct execution of non-idempotent side effects inside Server Action export async function processOrderAction(prevState: CheckoutState, formData: FormData): Promise<CheckoutState> { const cartId = formData.get('cartId') as string; const amount = Number(formData.get('amount')); try { // Network latency or browser retry will execute this charge multiple times const charge = await paymentGateway.charges.create({ amount, currency: 'usd', source: 'tok_visa', }); await db.orders.create({ data: { cartId, chargeId: charge.id, amount }, }); return { success: true }; } catch (err: unknown) { const error = err instanceof Error ? err.message : 'Unknown error'; return { success: false, error }; } } ``` #### Production Standard (Correct) > **Standard**: This production pattern enforces atomic lease reservation using Redis `SET NX EX` keyed to a cryptographically unique client idempotency token. Replays during in-flight states are gracefully rejected with a 409-like conflict state, while completed transactions return deterministically cached execution payloads without re-triggering side effects. ```typescript 'use server'; import { db } from '@/lib/db'; import { redis } from '@/lib/redis'; import { paymentGateway } from '@/lib/payment'; import { z } from 'zod'; const OrderInputSchema = z.object({ cartId: z.string().uuid(), amount: z.number().int().positive(), idempotencyKey: z.string().uuid(), }); export type OrderActionState = { status: 'idle' | 'success' | 'conflict' | 'error'; orderId?: string; message?: string; }; export async function processOrderAction( prevState: OrderActionState, formData: FormData ): Promise<OrderActionState> { const parseResult = OrderInputSchema.safeParse({ cartId: formData.get('cartId'), amount: Number(formData.get('amount')), idempotencyKey: formData.get('idempotencyKey'), }); if (!parseResult.success) { return { status: 'error', message: 'Invalid transaction parameters.' }; } const { cartId, amount, idempotencyKey } = parseResult.data; const lockKey = `idempotency:order:${idempotencyKey}`; const cacheKey = `idempotency:result:${idempotencyKey}`; // Atomic lease acquisition (NX) with 60-second processing TTL const acquired = await redis.set(lockKey, 'IN_FLIGHT', 'NX', 'EX', 60); if (!acquired) { // Request is either currently processing or already committed const cachedResponse = await redis.get(cacheKey); if (cachedResponse) { return JSON.parse(cachedResponse) as OrderActionState; } return { status: 'conflict', message: 'Transaction is actively processing. Please wait.', }; } try { const charge = await paymentGateway.charges.create( { amount, currency: 'usd' }, { idempotencyKey } // Propagate to payment gateway boundary ); const order = await db.orders.create({ data: { cartId, chargeId: charge.id, amount, idempotencyKey }, }); const result: OrderActionState = { status: 'success', orderId: order.id, }; // Persist terminal success response for replay cache (24 hours TTL) await redis.set(cacheKey, JSON.stringify(result), 'EX', 86400); return result; } catch (err: unknown) { // Evict processing lock on catastrophic failure to allow legitimate client retries await redis.del(lockKey); const message = err instanceof Error ? err.message : 'Transaction failed.'; return { status: 'error', message }; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Actions Cryptographic Replay Deduplication Standard

React 19 Server Actions Cryptographic Replay Deduplication Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces mandatory client-generated cryptographically secure idempotency keys and server-side atomic state locking across distributed RPC boundaries for non-idempotent React 19 Server Actions. Prevents catastrophic double-execution of financial transactions, state mutations, and external API requests caused by network retry flaps, connection timeouts, or unconstrained client re-submissions. Guarantees linearizable mutation guarantees by unifying distributed atomic locks with deterministic response caching. 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: Executing Non-Idempotent React 19 Server Actions Without Distributed Locks and Replay Nonces 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	Executing Non-Idempotent React 19 Server Actions Without Distributed Locks and Replay Nonces	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 supply a client-generated UUIDv4/UUIDv7 idempotency nonce or HMAC payload signature within form data or action arguments for every non-idempotent Server Action.

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.