React 19 Server Actions Cryptographic Idempotency & Stream Replay Standard

--- description: React 19 Server Actions Cryptographic Idempotency & Stream Replay Standard - Enforces deterministic cryptographic idempotency and atomic replay guards for all mutating React 19 Server Actions over progressive HTTP/3 streams. Prevents duplicate execution, financial double-spend, and corrupted state trees caused by QUIC connection migrations, network drops, and aggressive browser auto-retries during partial stream emissions. 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-cryptographic-idempotency-react-19-server--258" --- # React 19 Server Actions Cryptographic Idempotency & Stream Replay Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Blind mutating Server Actions vulnerable to HTTP/3 QUIC connection retry replays and unkeyed double-execution ## System Constraints You are a Principal Software Architect enforcing cryptographic idempotency and replay attack prevention across React 19 Server Actions. You must reject any mutating Server Action that lacks a cryptographically verifiable, single-use client-server nonce pair and atomic lease persistence. Ensure that interrupted HTTP/3 progressive response streams cannot cause duplicate side effects or orphaned transactional state. ## Strict Guidelines - Engineers MUST ALWAYS require a cryptographically bound idempotency token (signed client-generated UUIDv7 + session HMAC) as an explicit parameter in all mutating Server Actions. - Engineers MUST NOT execute business logic or persistent mutations before acquiring an atomic, time-bounded distributed lock (or database lease with state 'PROCESSING') using the idempotency key. - Services MUST return the original cached result or stream payload if a request with an identical idempotency key is received after successful execution. - Code SHOULD leverage crypto.subtle or Node.js native crypto for constant-time HMAC validation of action tokens before deserializing untrusted payloads. - Components NEVER execute mutating Server Actions directly from useEffect hooks or unkeyed optimistic transition wrappers without idempotency token orchestration. ## Bad vs Good Implementations ### Vulnerable Non-Idempotent Mutation vs. Cryptographically Keyed Atomic Server Action #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The Server Action executes without an idempotency key or atomic state reservation. If the HTTP/3 stream stalls during delivery, the browser or client runtime can retry the POST request, executing the database write and wallet deduction multiple times. ```typescript 'use server'; import { db } from '@/lib/db'; import { auth } from '@/lib/auth'; // VULNERABLE: Direct mutation without idempotency token or atomic lock. // HTTP/3 connection migrations or network packet drops trigger automatic browser retries, // causing double debit and duplicate inventory allocation. export async function processOrderAction(cartId: string, totalAmount: number) { const session = await auth(); if (!session?.userId) throw new Error('Unauthorized'); // Non-atomic: Multiple executions create multiple invoices const order = await db.orders.create({ data: { userId: session.userId, cartId, amount: totalAmount, status: 'CONFIRMED' } }); await db.wallets.decrement({ where: { userId: session.userId }, data: { balance: totalAmount } }); return { success: true, orderId: order.id }; } ``` #### Production Standard (Correct) > **Standard**: Validates a cryptographically signed client idempotency key with constant-time equality. Obtains an atomic distributed lock via Redis NX before executing mutations within a database transaction, and persists the immutable result for 24 hours to neutralize stream drop replays. ```typescript 'use server'; import { db } from '@/lib/db'; import { auth } from '@/lib/auth'; import { redis } from '@/lib/redis'; import { createHmac, timingSafeEqual } from 'node:crypto'; interface ActionPayload { cartId: string; totalAmount: number; idempotencyKey: string; signature: string; } function verifyActionToken(userId: string, key: string, signature: string): boolean { const secret = process.env.ACTION_SIGNING_SECRET!; const expected = createHmac('sha256', secret).update(`${userId}:${key}`).digest('hex'); const expectedBuf = Buffer.from(expected, 'utf8'); const actualBuf = Buffer.from(signature, 'utf8'); return expectedBuf.length === actualBuf.length && timingSafeEqual(expectedBuf, actualBuf); } export async function processOrderAction(payload: ActionPayload) { const session = await auth(); if (!session?.userId) throw new Error('Unauthorized'); const { cartId, totalAmount, idempotencyKey, signature } = payload; if (!verifyActionToken(session.userId, idempotencyKey, signature)) { throw new Error('Invalid or forged idempotency signature'); } const lockKey = `idempotency:order:${session.userId}:${idempotencyKey}`; // Acquire 60-second atomic lock with status using SET NX EX const acquired = await redis.set(lockKey, JSON.stringify({ status: 'PROCESSING' }), 'EX', 60, 'NX'); if (!acquired) { const existing = await redis.get(lockKey); if (existing) { const parsed = JSON.parse(existing); if (parsed.status === 'PROCESSING') { throw new Error('Action execution currently in-flight; retry safely deferred'); } return parsed.result; } throw new Error('Concurrent operation conflict'); } try { const order = await db.$transaction(async (tx) => { const created = await tx.orders.create({ data: { userId: session.userId, cartId, amount: totalAmount, status: 'CONFIRMED' } }); await tx.wallets.decrement({ where: { userId: session.userId }, data: { balance: totalAmount } }); return created; }); const responseData = { success: true, orderId: order.id }; // Retain completed state for 24 hours to neutralize replay attacks await redis.set(lockKey, JSON.stringify({ status: 'COMPLETED', result: responseData }), 'EX', 86400); return responseData; } catch (error) { await redis.del(lockKey); throw error; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Actions Cryptographic Idempotency & Stream Replay Standard

React 19 Server Actions Cryptographic Idempotency & Stream Replay Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic cryptographic idempotency and atomic replay guards for all mutating React 19 Server Actions over progressive HTTP/3 streams. Prevents duplicate execution, financial double-spend, and corrupted state trees caused by QUIC connection migrations, network drops, and aggressive browser auto-retries during partial stream emissions. 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 mutating Server Actions vulnerable to HTTP/3 QUIC connection retry replays and unkeyed double-execution 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 mutating Server Actions vulnerable to HTTP/3 QUIC connection retry replays and unkeyed double-execution	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 require a cryptographically bound idempotency token (signed client-generated UUIDv7 + session HMAC) as an explicit parameter in all 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.