React 19 Server Actions Idempotency & CSRF Strict Origin Validation

--- description: React 19 Server Actions Idempotency & CSRF Strict Origin Validation - Enforces strict origin checking, host header verification, and cryptographic idempotency key caching for React 19 Server Actions. Guarantees cross-site POST replay resilience and prevents duplicate execution of mutating server functions in modern RSC architectures under network retry or concurrent submission conditions. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-server-actions-idempotency-csrf-validation" --- # React 19 Server Actions Idempotency & CSRF Strict Origin Validation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Executing Non-Idempotent Server Actions Without Origin Validation or Replay Protection ## System Constraints You are a Principal Engineer enforcing React 19 Server Actions Idempotency & CSRF Strict Origin Validation. Mandate strict origin/referer verification against target host headers, cryptographic idempotency-key settlement locks in atomic storage (e.g., Redis KV), and explicit defensive guards on all mutating 'use server' entry points to eliminate state-corrupting replays and CSRF bypasses. ## Strict Guidelines - Engineers MUST ALWAYS validate incoming request headers (`Origin` and `Host`) against allowed hostnames within Server Actions performing state mutations when not explicitly handled by a framework-enforced trusted origin middleware. - Engineers MUST ALWAYS require a client-generated or server-pre-signed `idempotencyKey` (UUIDv4) for any mutating action (payment, provisioning, resource updates) to guard against automatic browser/client retries and double form submissions. - Code SHOULD lock idempotency tokens atomically in a persistent cache (e.g., Redis via SET NX EX) with a minimum 60-second TTL before executing business logic, returning the cached payload upon duplicate hits. - Services MUST differentiate between transient execution failures (releasing the idempotency lock) and completed terminal mutations (storing the immutable result hash). - Components NEVER execute raw mutating Server Actions directly from unthrottled event handlers; they MUST utilize `useActionState` or `useTransition` combined with client-side disabled states during pending transitions. ## Bad vs Good Implementations ### Naive Server Action Mutation Lacking Origin Validation and Idempotency #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The Server Action accepts mutations without validating the Origin/Host headers, leaving it susceptible to cross-origin invocations when deployed in environments missing strict origin middleware. Furthermore, the absence of an idempotency key causes duplicate fund deductions if the user double-submits or if the browser automatically retries a failed socket. ```typescript 'use server'; import { db } from '@/lib/db'; interface TransferParams { recipientId: string; amountCents: number; } // ANTI-PATTERN: No CSRF/Origin check, vulnerable to replay attacks and network retries export async function transferFundsAction({ recipientId, amountCents }: TransferParams) { const session = await getSession(); if (!session) throw new Error('Unauthorized'); // Multiple concurrent clicks or connection drop retries will debit user multiple times const transfer = await db.transfers.create({ data: { senderId: session.userId, recipientId, amountCents, }, }); return { success: true, transferId: transfer.id }; } ``` #### Production Standard (Correct) > **Standard**: Validates that the Origin header precisely matches the current Host header to block cross-origin execution bypasses. Employs Redis atomic key reservation (`SET NX EX`) keyed to the caller session and an explicit `idempotencyKey`, storing results for 24 hours to guarantee that duplicates return the identical outcome without mutating the state twice. ```typescript 'use server'; import { headers } from 'next/headers'; import { db } from '@/lib/db'; import { redis } from '@/lib/redis'; import { getSession } from '@/lib/auth'; interface TransferParams { recipientId: string; amountCents: number; idempotencyKey: string; } export async function transferFundsAction(input: TransferParams) { const session = await getSession(); if (!session) throw new Error('Unauthorized'); // 1. Strict Origin & Host CSRF Validation const headerList = await headers(); const origin = headerList.get('origin'); const host = headerList.get('host'); if (!origin || new URL(origin).host !== host) { throw new Error('Forbidden: Cross-site action invocation rejected.'); } const lockKey = `idempotency:transfer:${session.userId}:${input.idempotencyKey}`; // 2. Atomic Idempotency Settlement Lock (60s TTL) const acquired = await redis.set(lockKey, 'IN_FLIGHT', 'EX', 60, 'NX'); if (!acquired) { const cachedResult = await redis.get(`${lockKey}:result`); if (cachedResult) return JSON.parse(cachedResult); throw new Error('Duplicate operation currently in flight. Please wait.'); } try { const transfer = await db.transfers.create({ data: { senderId: session.userId, recipientId: input.recipientId, amountCents: input.amountCents, clientMutationId: input.idempotencyKey, }, }); const responsePayload = { success: true, transferId: transfer.id }; await redis.set(`${lockKey}:result`, JSON.stringify(responsePayload), 'EX', 86400); return responsePayload; } catch (error) { // Release lock on runtime infrastructure error to permit subsequent legitimate retries await redis.del(lockKey); throw error; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Actions Idempotency & CSRF Strict Origin Validation

React 19 Server Actions Idempotency & CSRF Strict Origin Validation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict origin checking, host header verification, and cryptographic idempotency key caching for React 19 Server Actions. Guarantees cross-site POST replay resilience and prevents duplicate execution of mutating server functions in modern RSC architectures under network retry or concurrent submission conditions. 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 Server Actions Without Origin Validation or Replay Protection 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 Server Actions Without Origin Validation or Replay Protection	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 validate incoming request headers (`Origin` and `Host`) against allowed hostnames within Server Actions performing state mutations when not explicitly handled by a framework-enforced trusted origin middleware.

Engineers MUST ALWAYS validate incoming request headers (`Origin` and `Host`) against allowed hostnames within Server Actions performing state mutations when not explicitly handled by a framework-enforced trusted origin middleware.

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.