React 19 Taint Object API Boundary Enforcement for RSC Serialization

--- description: React 19 Taint Object API Boundary Enforcement for RSC Serialization - Enforces mandatory registration of cryptographic keys, raw database records, and PII using React 19's experimental_taintObjectReference and experimental_taintUniqueValue APIs. Prevents unintentional serialization of server-side secrets across the Server-to-Client Component boundary within React Server Component (RSC) Flight streams. globs: src/**/*.server.{ts,tsx}, src/server/**/*.{ts,tsx}, src/app/**/*.{ts,tsx}, src/data/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-rsc-taint-boundary-protection" --- # React 19 Taint Object API Boundary Enforcement for RSC Serialization > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Passing Untainted Raw Records or Secrets Directly to Client Component Props Across RSC Flight Boundaries ## System Constraints You are a Principal Security Architect and React Engineer enforcing strict Server Component serialization safety via the React 19 Taint Object API (`experimental_taintObjectReference` and `experimental_taintUniqueValue`). Mandate runtime and static protection boundaries so that raw secrets, auth credentials, tokens, and untransformed database entities cannot be serialized to the browser through Client Components. ## Strict Guidelines - Engineers MUST ALWAYS invoke `experimental_taintObjectReference` on raw domain models, database rows, or internal configuration objects immediately upon hydration in data-access layers. - Engineers MUST ALWAYS invoke `experimental_taintUniqueValue` on individual scalar secrets (API keys, cryptographic hashes, private tokens) referencing a lifetime owner object. - Code MUST ALWAYS map tainted backend entities to explicitly typed, minimal Public Transfer Objects (DTOs) before passing them to Client Components. - Services MUST declare `'server-only'` at the top of data access modules that utilize taint APIs to guarantee they are never bundled into client packages. - Components NEVER pass un-projected ORM model instances or ambient environment variables containing secrets across the `'use client'` prop boundary. ## Bad vs Good Implementations ### Tainting Sensitive User Records and Cryptographic Tokens in RSC Data Layer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The entire database record is passed directly to a Client Component. Because neither the object reference nor its sensitive tokens are tainted, React's Flight protocol serializes internal secrets into the browser's JSON stream, creating a critical credential leak. ```typescript import 'server-only'; import { db } from '@/lib/db'; import { UserAvatarClient } from '@/components/UserAvatarClient'; export async function UserProfileCard({ userId }: { userId: string }) { // Anti-pattern: Raw entity with sensitive credentials fetched directly const user = await db.user.findUnique({ where: { id: userId } }); if (!user) throw new Error('Not found'); // DANGEROUS: Passing entire user entity to a Client Component. // React Flight serializes all fields into the HTML stream (including hashed_password, stripe_customer_id, api_token) return <UserAvatarClient user={user} />; } ``` #### Production Standard (Correct) > **Standard**: By registering `experimental_taintObjectReference` on the raw entity and `experimental_taintUniqueValue` on the token, React will dynamically abort serialization with an explicit error if the raw object or token is passed into a Client Component. Explicit projection produces a clean DTO containing only public fields. ```typescript import 'server-only'; import { experimental_taintObjectReference, experimental_taintUniqueValue } from 'react'; import { db } from '@/lib/db'; import { UserAvatarClient } from '@/components/UserAvatarClient'; export async function getUserSafely(userId: string) { const user = await db.user.findUnique({ where: { id: userId } }); if (!user) throw new Error('Not found'); // Invariant: Taint the entire raw database entity reference experimental_taintObjectReference( 'Do not pass raw DB user entity to client components.', user ); // Invariant: Taint individual high-value cryptographic secrets if (user.personalAccessToken) { experimental_taintUniqueValue( 'Do not leak personal access tokens to client.', user, user.personalAccessToken ); } return user; } export async function UserProfileCard({ userId }: { userId: string }) { const user = await getUserSafely(userId); // Explicit projection prevents runtime taint trap triggers const safeClientDto = { id: user.id, name: user.name, avatarUrl: user.avatarUrl }; return <UserAvatarClient user={safeClientDto} />; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Taint Object API Boundary Enforcement for RSC Serialization

React 19 Taint Object API Boundary Enforcement for RSC Serialization defines an industrial-grade behavioral standard for frontend engineering. Enforces mandatory registration of cryptographic keys, raw database records, and PII using React 19's experimental_taintObjectReference and experimental_taintUniqueValue APIs. Prevents unintentional serialization of server-side secrets across the Server-to-Client Component boundary within React Server Component (RSC) Flight streams. 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: Passing Untainted Raw Records or Secrets Directly to Client Component Props Across RSC Flight Boundaries 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	Passing Untainted Raw Records or Secrets Directly to Client Component Props Across RSC Flight Boundaries	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, database rows, or internal configuration objects immediately upon hydration in 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.