React 19 Tainted Reference & Server Action Replay Boundary Enforcement

--- description: React 19 Tainted Reference & Server Action Replay Boundary Enforcement - Guarantees that sensitive server-side objects, environmental secrets, and raw cryptographic credentials cannot be serialized across the React Server Components (RSC) wire protocol using React 19 experimental taint primitives. Enforces strict cryptographic nonce verification, session binding, and atomic idempotency consumption across all mutating Server Actions to eradicate replay and duplicate execution vectors. 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-tainted-reference-server-action-replay-boundary" --- # React 19 Tainted Reference & Server Action Replay Boundary Enforcement > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Exposing Raw Cryptographic Secrets Across the RSC Protocol and Executing Un-fenced Mutating Server Actions ## System Constraints You are a Principal Software Architect enforcing enterprise-grade security within React 19 and React Server Components (RSC). Your primary directives are: (1) Prevent any sensitive server-side credential, token, or internal entity reference from leaking across the RSC serialization protocol via React 19 Taint APIs (experimental_taintObjectReference, experimental_taintUniqueValue). (2) Mandate that every mutating Server Action verifies a cryptographic, single-use, session-bound nonce or idempotency token before state changes occur, precluding replay attacks and unauthorized headless invocations. Never allow raw database models or credentials to pass into client boundaries. ## Strict Guidelines - Engineers MUST ALWAYS register sensitive data structures with experimental_taintObjectReference or experimental_taintUniqueValue immediately upon retrieval from storage or environment modules. - Engineers MUST NOT return raw internal database entities, session tokens, or API keys directly from Server Actions or pass them as props to Client Components ('use client'). - Mutating Server Actions MUST verify a cryptographically secure, session-bound, single-use nonce or consume an atomic idempotency key prior to executing business mutations. - Services MUST enforce atomic consumption of replay tokens (e.g., Redis SETNX or SQL transactional row locking) so that replayed POST payloads instantly fail. - Components NEVER pass server action references directly to public client forms without cryptographic anti-replay state or CSRF-resilient signed action wrappers. ## Bad vs Good Implementations ### React 19 Data Tainting: Blocking Secret Serialization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Returning un-tainted database models allows downstream developers or nested RSC trees to accidentally pass sensitive fields (e.g., passwordHash, payment IDs) as props into Client Components, serializing them into the public HTML/RSC payload. ```typescript import 'server-only'; import { db } from '@/lib/db'; export async function getUserAccount(userId: string) { const user = await db.user.findUniqueOrThrow({ where: { id: userId } }); // DANGEROUS: Returning entire user record with passwordHash and stripeCustomerId. // If passed to a Client Component prop, React serializes sensitive fields over the wire. return user; } ``` #### Production Standard (Correct) > **Standard**: Calling experimental_taintObjectReference and experimental_taintUniqueValue instructs the React 19 compiler and runtime to throw a blocking error if any tainted object or string value crosses the Client Component boundary. ```typescript import 'server-only'; import { experimental_taintObjectReference, experimental_taintUniqueValue } from 'react'; import { db } from '@/lib/db'; export interface SafeUserAccount { id: string; name: string; email: string; } export async function getUserAccount(userId: string): Promise<SafeUserAccount> { const user = await db.user.findUniqueOrThrow({ where: { id: userId } }); // INVARIANT: Block serialization of the raw model and high-risk unique tokens experimental_taintObjectReference('Do not pass raw User records to Client Components', user); experimental_taintUniqueValue('Do not pass Stripe Customer IDs to Client Components', user, user.stripeCustomerId); experimental_taintUniqueValue('Do not pass Password Hashes to Client Components', user, user.passwordHash); return { id: user.id, name: user.name, email: user.email }; } ``` ### Server Action Replay Boundary: Nonce & Idempotency Enforcement #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutating Server Actions without cryptographic nonce validation or idempotency state can be replayed by intercepted network payloads, headless automation, or rapid client double-submissions, causing multiple financial debits. ```typescript 'use server'; import { db } from '@/lib/db'; import { getSession } from '@/lib/auth'; export async function transferFunds(recipientId: string, amountCents: number) { const session = await getSession(); if (!session) throw new Error('Unauthorized'); // VULNERABLE: Direct mutation without replay verification. // A captured network request or double-click can replay this mutation multiple times. await db.account.decrementBalance(session.userId, amountCents); await db.account.incrementBalance(recipientId, amountCents); return { success: true }; } ``` #### Production Standard (Correct) > **Standard**: The Server Action enforces an atomic SETNX check on a session-bound cryptographic nonce before transaction execution, ensuring any replayed or duplicated action invocation is rejected immediately. ```typescript 'use server'; import { db } from '@/lib/db'; import { getSession } from '@/lib/auth'; import { redis } from '@/lib/redis'; import { timingSafeEqual } from 'node:crypto'; interface TransferPayload { recipientId: string; amountCents: number; actionNonce: string; } export async function transferFunds(payload: TransferPayload) { const session = await getSession(); if (!session) throw new Error('Unauthorized'); const nonceKey = `action_nonce:${session.userId}:${payload.actionNonce}`; // Atomic single-use token consumption with 60s TTL const acquired = await redis.set(nonceKey, 'CONSUMED', 'NX', 'EX', 60); if (!acquired) { throw new Error('Replay detected or action already processed. Please refresh.'); } return await db.$transaction(async (tx) => { await tx.account.decrementBalance(session.userId, payload.amountCents); await tx.account.incrementBalance(payload.recipientId, payload.amountCents); return { success: true, processedNonce: payload.actionNonce }; }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Tainted Reference & Server Action Replay Boundary Enforcement

React 19 Tainted Reference & Server Action Replay Boundary Enforcement defines an industrial-grade behavioral standard for frontend engineering. Guarantees that sensitive server-side objects, environmental secrets, and raw cryptographic credentials cannot be serialized across the React Server Components (RSC) wire protocol using React 19 experimental taint primitives. Enforces strict cryptographic nonce verification, session binding, and atomic idempotency consumption across all mutating Server Actions to eradicate replay and duplicate execution vectors. 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: Exposing Raw Cryptographic Secrets Across the RSC Protocol and Executing Un-fenced Mutating Server Actions 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	Exposing Raw Cryptographic Secrets Across the RSC Protocol and Executing Un-fenced Mutating Server Actions	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 register sensitive data structures with experimental_taintObjectReference or experimental_taintUniqueValue immediately upon retrieval from storage or environment modules.

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.