React 19 Server Data Tainting & Serialization Boundary Isolation

--- description: React 19 Server Data Tainting & Serialization Boundary Isolation - Enforces strict isolation of sensitive server-side state, user PII, and credentials using React 19 taint APIs (experimental_taintUniqueValue and experimental_taintObjectReference). Prevents accidental exposure of raw database models, cryptographic keys, and private tokens through Server-to-Client Component serialization boundaries. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx}, server/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-taint-boundary-protection" --- # React 19 Server Data Tainting & Serialization Boundary Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Raw Database Records and Environment Secrets to Client Component Props via RSC Serialization ## System Constraints You are a Principal Engineer enforcing React 19 Data Tainting Invariants. Mandate the dynamic and static prohibition of leaking database entities, tokens, and PII across React Server Component (RSC) serialization boundaries using `experimental_taintObjectReference` and `experimental_taintUniqueValue`. Enforce explicit DTO projections prior to passing data to Client Components. ## Strict Guidelines - Engineers MUST ALWAYS invoke `experimental_taintObjectReference` on raw domain models, ORM records, and authorization contexts immediately upon data hydration in server data-access layers. - Engineers MUST ALWAYS invoke `experimental_taintUniqueValue` on raw environment variables, API secret tokens, session hashes, and cryptographic materials with an explicit lifetime reference. - Engineers MUST NOT pass raw ORM entities, user database records, or configuration objects directly as props to Client Components marked with 'use client'. - Services MUST map tainted server records into explicit, minimally-scoped Data Transfer Objects (DTOs) before returning them to UI layers. - Components NEVER accept raw database entity types as props; client component props interfaces MUST strictly represent projected view models devoid of private schema fields. - Data access files containing tainting declarations MUST import `'server-only'` to guarantee static build-time failure if imported into client bundles. ## Bad vs Good Implementations ### Tainting Raw DB Entities vs. Explicit DTO Projections Across RSC Boundaries #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing the raw ORM entity directly into a Client Component serializes the entire entity into the React Server Component (RSC) wire payload. Any sensitive field (such as passwordHash, reset tokens, or private IDs) is sent over the network to the browser, even if the client component does not explicitly render it. ```typescript import { db } from '@/lib/db'; import { UserProfileCard } from '@/components/UserProfileCard'; // Client Component ('use client') export default async function UserPage({ params }: { params: { id: string } }) { // Anti-Pattern: Querying full DB entity and passing directly to Client Component const rawUser = await db.user.findUniqueOrThrow({ where: { id: params.id } }); // Leaks passwordHash, stripeCustomerId, twoFactorSecret, etc. across the flight payload return <UserProfileCard user={rawUser} />; } ``` #### Production Standard (Correct) > **Standard**: The raw database object and internal identifier are registered with React 19's runtime taint registry. If any developer attempts to pass rawUser or rawUser.stripeCustomerId across the RSC wire to a Client Component, React throws an immediate runtime error during render. The safe DTO guarantees only sanitized properties are transmitted. ```typescript import 'server-only'; import { experimental_taintObjectReference, experimental_taintUniqueValue } from 'react'; import { db } from '@/lib/db'; import { UserProfileCard } from '@/components/UserProfileCard'; import type { UserDTO } from '@/types/user'; export async function getUserSafely(userId: string): Promise<UserDTO> { const rawUser = await db.user.findUniqueOrThrow({ where: { id: userId } }); // Invariant: Dynamically taint the raw record to prevent serialization leakage experimental_taintObjectReference( 'Do not pass raw User database entities directly to Client Components. Project to UserDTO first.', rawUser ); // Invariant: Taint specific unique values that could be extracted and leaked separately if (rawUser.stripeCustomerId) { experimental_taintUniqueValue( 'Stripe customer identifiers must not be exposed to the client bundle.', rawUser, rawUser.stripeCustomerId ); } // Explicit projection to safe DTO return { id: rawUser.id, displayName: rawUser.displayName, avatarUrl: rawUser.avatarUrl, }; } export default async function UserPage({ params }: { params: { id: string } }) { const userDto = await getUserSafely(params.id); return <UserProfileCard user={userDto} />; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Data Tainting & Serialization Boundary Isolation

React 19 Server Data Tainting & Serialization Boundary Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation of sensitive server-side state, user PII, and credentials using React 19 taint APIs (experimental_taintUniqueValue and experimental_taintObjectReference). Prevents accidental exposure of raw database models, cryptographic keys, and private tokens through Server-to-Client Component serialization boundaries. 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: Leaking Raw Database Records and Environment Secrets to Client Component Props via RSC Serialization 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	Leaking Raw Database Records and Environment Secrets to Client Component Props via RSC Serialization	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 invoke `experimental_taintObjectReference` on raw domain models, ORM records, and authorization contexts immediately upon data hydration in server data-access layers.

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.