React 19 RSC Taint Boundary Serialization Invariant

--- description: React 19 RSC Taint Boundary Serialization Invariant - Mandates strict object-level and cryptographic value taint tracking via React 19 Taint APIs to prevent sensitive server-only entities, database records, and secret tokens from crossing the React Server Component Flight serialization boundary. Enforces explicit DTO projection and immediate failure on inadvertent client exposure. 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-rsc-taint-boundary-serialization" --- # React 19 RSC Taint Boundary Serialization Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Raw Database Models or Cryptographic Secrets to Client Components via RSC Flight Stream Serialization ## System Constraints You are a Principal Software Architect enforcing React 19 RSC Taint Boundary Invariants. You must ensure that no server-only record, session token, or database model crosses into client component trees or Server Action wire streams without explicit taint registration and strict DTO mapping. ## Strict Guidelines - Engineers MUST ALWAYS register sensitive server data using `experimental_taintObjectReference` or `experimental_taintUniqueValue` immediately upon fetching from persistence or environment layers. - Engineers MUST NOT pass full ORM entities, Prisma models, or raw auth sessions as props to Client Components marked with 'use client'. - Code SHOULD enforce strict, explicitly typed Data Transfer Objects (DTOs) with allowlisted fields prior to passing any data payload across component boundaries. - Services MUST import 'server-only' in all backend modules handling untainted or tainted data access to prevent client bundling at the build boundary. - Components NEVER accept raw domain entities where field filtering occurs within the Client Component itself. ## Bad vs Good Implementations ### Tainted User Entity Serialization Protection #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing the full ORM entity across the RSC Flight boundary exposes hidden properties like passwordHash, stripeCustomerId, and internal telemetry metadata to the client browser in the serialized RSC wire payload. ```typescript import { db } from '@/lib/db'; import { UserProfileCard } from '@/components/UserProfileCard'; // 'use client' component export async function UserPage({ params }: { params: { id: string } }) { // Anti-Pattern: Full DB record containing passwordHash and stripeCustomerId // passed directly across the RSC Flight serialization boundary const user = await db.user.findUnique({ where: { id: params.id } }); if (!user) return null; return <UserProfileCard user={user} />; } ``` #### Production Standard (Correct) > **Standard**: Explicitly registers the raw database entity and its cryptographic credentials with React 19 Taint APIs. If any part of the tainted object is passed to a Client Component, React throws a build- or render-time boundary error. ```typescript import 'server-only'; import { experimental_taintObjectReference, experimental_taintUniqueValue } from 'react'; import { db } from '@/lib/db'; import { UserProfileCard } from '@/components/UserProfileCard'; interface UserDTO { id: string; displayName: string; avatarUrl: string; } export async function UserPage({ params }: { params: { id: string } }) { const user = await db.user.findUnique({ where: { id: params.id } }); if (!user) return null; // Invariant: Taint raw entity and sensitive tokens against Flight serialization experimental_taintObjectReference('Do not pass raw DB user entity to client', user); experimental_taintUniqueValue('Do not leak user API tokens', user, user.apiSecret); // Explicit projection to Client DTO const clientUser: UserDTO = { id: user.id, displayName: user.displayName, avatarUrl: user.avatarUrl, }; return <UserProfileCard user={clientUser} />; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 RSC Taint Boundary Serialization Invariant

React 19 RSC Taint Boundary Serialization Invariant defines an industrial-grade behavioral standard for frontend engineering. Mandates strict object-level and cryptographic value taint tracking via React 19 Taint APIs to prevent sensitive server-only entities, database records, and secret tokens from crossing the React Server Component Flight serialization boundary. Enforces explicit DTO projection and immediate failure on inadvertent client exposure. 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 Models or Cryptographic Secrets to Client Components via RSC Flight Stream 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 Models or Cryptographic Secrets to Client Components via RSC Flight Stream 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 register sensitive server data using `experimental_taintObjectReference` or `experimental_taintUniqueValue` immediately upon fetching from persistence or environment 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.