React 19 Server Action Cryptographic Idempotency & Replay Guard

--- description: React 19 Server Action Cryptographic Idempotency & Replay Guard - Enforces cryptographically unique client-generated idempotency tokens across React 19 Server Actions and concurrent optimistic mutations. Guarantees zero duplicate distributed mutations across transient mobile/network retries and rapid multi-tap UI submissions via server-side atomic acquisition leases. globs: src/actions/**/*.{ts,tsx}, src/app/**/*.{ts,tsx}, src/components/**/*.{ts,tsx}, src/hooks/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-server-action-idempotency-guard" --- # React 19 Server Action Cryptographic Idempotency & Replay Guard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unbounded Server Action Invocations with Blind Retries and Server-Generated Request Identifiers ## System Constraints You are a Principal Software Architect enforcing zero-tolerance policies for duplicate distributed state mutations in React 19. All mutating Server Actions ('use server') exposed to optimistic UI updates or form submissions must require a client-instantiated cryptographically verifiable idempotency key. You must mandate pre-flight acquisition locking using distributed atomic primitives (e.g., Redis SET NX or ACID database reservation constraints) before processing mutations. ## Strict Guidelines - Engineers MUST ALWAYS generate idempotency tokens on the client prior to firing the Server Action or applying optimistic state. - Engineers MUST NOT generate idempotency tokens inside the body of a Server Action; tokens generated server-side cannot correlate retried network packets. - Services MUST atomically claim the idempotency token (e.g., distributed cache SET NX with TTL or an ACID reservation table) before executing write operations. - Components NEVER bind naked Server Actions directly to form action attributes without an embedded hidden idempotency key or closure-bound token. - Code SHOULD cache and return the original successful response payload when a duplicate idempotency key is detected mid-flight or post-commit. ## Bad vs Good Implementations ### Naive React 19 Server Action vs. Idempotent Atomic Guard with Optimistic Binding #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When an end-user triggers a transient network error or double-taps the transfer button, the browser or network client may retransmit the Server Action payload. Without an immutable client-provided idempotency key evaluated atomically at the server edge, the database creates duplicate financial records. ```typescript 'use server'; import { db } from '@/lib/db'; import { revalidatePath } from 'next/cache'; // VULNERABLE: Lacks client-side idempotency correlation token. // Rapid double-clicks or transient HTTP retry loops duplicate ledger mutations. export async function transferFunds(amountCents: number, targetAccount: string) { const session = await auth(); if (!session) throw new Error('Unauthorized'); // Non-idempotent mutation executes multiple times on retry const transaction = await db.ledger.create({ data: { userId: session.user.id, amount: amountCents, target: targetAccount, createdAt: new Date(), }, }); revalidatePath('/dashboard/wallet'); return { success: true, transactionId: transaction.id }; } ``` #### Production Standard (Correct) > **Standard**: The Server Action enforces a client-provided UUID token validated by Zod. A distributed atomic lock (SET NX) ensures that concurrent retries cannot execute parallel transactions. Subsequent replays return the cached original response without reprocessing mutations. ```typescript 'use server'; import { db } from '@/lib/db'; import { redis } from '@/lib/redis'; import { auth } from '@/lib/auth'; import { revalidatePath } from 'next/cache'; import { z } from 'zod'; const TransferSchema = z.object({ idempotencyKey: z.string().uuid(), amountCents: z.number().positive(), targetAccount: z.string().min(1), }); export async function transferFunds(payload: z.infer<typeof TransferSchema>) { const session = await auth(); if (!session) throw new Error('Unauthorized'); const { idempotencyKey, amountCents, targetAccount } = TransferSchema.parse(payload); const lockKey = `idempotency:transfer:${session.user.id}:${idempotencyKey}`; // Atomic acquisition: Reserve token for 120s const acquired = await redis.set(lockKey, 'IN_FLIGHT', { nx: true, ex: 120 }); if (!acquired) { const cached = await redis.get(lockKey); if (cached && cached !== 'IN_FLIGHT') { return JSON.parse(cached); } throw new Error('Concurrent operation in flight. Please wait.'); } try { const transaction = await db.$transaction(async (tx) => { return tx.ledger.create({ data: { userId: session.user.id, idempotencyKey, amount: amountCents, target: targetAccount, }, }); }); const result = { success: true, transactionId: transaction.id }; await redis.set(lockKey, JSON.stringify(result), { ex: 86400 }); revalidatePath('/dashboard/wallet'); return result; } catch (error) { await redis.del(lockKey); throw error; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Action Cryptographic Idempotency & Replay Guard

React 19 Server Action Cryptographic Idempotency & Replay Guard defines an industrial-grade behavioral standard for frontend engineering. Enforces cryptographically unique client-generated idempotency tokens across React 19 Server Actions and concurrent optimistic mutations. Guarantees zero duplicate distributed mutations across transient mobile/network retries and rapid multi-tap UI submissions via server-side atomic acquisition leases. 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: Unbounded Server Action Invocations with Blind Retries and Server-Generated Request Identifiers 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	Unbounded Server Action Invocations with Blind Retries and Server-Generated Request Identifiers	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 generate idempotency tokens on the client prior to firing the Server Action or applying optimistic state.

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.