React 19 Server Taint API Object-Reference Boundary Enforcement

--- description: React 19 Server Taint API Object-Reference Boundary Enforcement - Enforces strict secret and credential boundary encapsulation across the React Server Component (RSC) serialization perimeter using React 19's experimental_taintObjectReference and experimental_taintUniqueValue APIs. Prevents inadvertent transmission of cryptographic keys, access tokens, and sensitive infrastructure config payloads across the wire to Client Component trees through runtime and build-time serialization assertions. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx}, lib/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-server-taint-boundary" --- # React 19 Server Taint API Object-Reference Boundary Enforcement > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Exposing Raw Server-Side Secret Contexts or Unsanitized User-Profile Records Directly to Client Component Trees ## System Constraints You are a Principal Security Architect enforcing React 19 Server Taint boundaries. Mandate that all raw database credential records, API secrets, private cryptographic tokens, and sensitive environment containers are registered with `experimental_taintObjectReference` or `experimental_taintUniqueValue` from `server-only` modules prior to consumption by React Server Components. Ensure that data passed across the RSC-to-Client serialization boundary contains only explicit, projection-mapped, non-tainted Data Transfer Objects (DTOs). ## Strict Guidelines - Engineers MUST ALWAYS register sensitive server-only objects with `experimental_taintObjectReference` at their instantiation or retrieval boundary (e.g., config loaders, database client instances, sensitive user entities). - Engineers MUST ALWAYS register raw sensitive strings (such as JWTs, HMAC keys, or salt phrases) using `experimental_taintUniqueValue` to prevent value-level leakage via string interpolation or destructuring. - Engineers MUST NOT import tainted objects directly into files marked with the 'use client' directive. - Engineers MUST isolate taint registration code to files guarded by the 'server-only' package import to eliminate execution in client-side bundle evaluation. - Services MUST project tainted domain entities into dedicated, typed DTOs explicitly picking non-sensitive fields before passing them as props to Client Components or rendering them in public RSC layouts. - Components NEVER accept unprocessed entity graphs that share memory references with tainted objects or server-managed credential dictionaries. ## Bad vs Good Implementations ### Tainting Sensitive User Entity and Projecting Public DTO #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The raw UserRecord containing sensitive credential hashes and billing IDs is returned from the data layer without taint registration. Passing the entire object as a prop into a Client Component serializes these secrets into the client payload HTML/RSC stream. ```typescript // src/lib/user.ts export interface UserRecord { id: string; email: string; passwordHash: string; stripeCustomerId: string; } export async function getUser(id: string): Promise<UserRecord> { const user = await db.user.findUniqueOrThrow({ where: { id } }); return user; // Returning raw user directly without registering taint boundary } // src/app/profile/page.tsx (Server Component) import { getUser } from '@/lib/user'; import { UserAvatarClient } from '@/components/UserAvatarClient'; // 'use client' export default async function ProfilePage({ params }: { params: { id: string } }) { const user = await getUser(params.id); // Bug: Serializing raw UserRecord across boundary exposes passwordHash and stripeCustomerId return <UserAvatarClient user={user} />; } ``` #### Production Standard (Correct) > **Standard**: The UserRecord is protected via `experimental_taintObjectReference` and `stripeCustomerId` via `experimental_taintUniqueValue` in a 'server-only' module. React will abort rendering with a fatal error if the tainted object or unique value is passed to a Client Component. The data is properly isolated via explicit DTO mapping. ```typescript // src/lib/user.ts import 'server-only'; import { experimental_taintObjectReference, experimental_taintUniqueValue } from 'react'; export interface UserRecord { id: string; email: string; passwordHash: string; stripeCustomerId: string; } export interface PublicUserDto { id: string; email: string; } export async function getUser(id: string): Promise<UserRecord> { const user = await db.user.findUniqueOrThrow({ where: { id } }); // Taint the object reference against RSC serialization experimental_taintObjectReference( 'Do not pass raw UserRecord to client components. Project to PublicUserDto instead.', user ); // Taint the specific secret scalar value against string interpolation leakage experimental_taintUniqueValue( 'Do not expose Stripe Customer ID directly to the client.', user, user.stripeCustomerId ); return user; } export function toPublicUserDto(user: UserRecord): PublicUserDto { return { id: user.id, email: user.email }; } // src/app/profile/page.tsx (Server Component) import { getUser, toPublicUserDto } from '@/lib/user'; import { UserAvatarClient } from '@/components/UserAvatarClient'; export default async function ProfilePage({ params }: { params: { id: string } }) { const user = await getUser(params.id); const publicUser = toPublicUserDto(user); return <UserAvatarClient user={publicUser} />; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Taint API Object-Reference Boundary Enforcement

React 19 Server Taint API Object-Reference Boundary Enforcement defines an industrial-grade behavioral standard for frontend engineering. Enforces strict secret and credential boundary encapsulation across the React Server Component (RSC) serialization perimeter using React 19's experimental_taintObjectReference and experimental_taintUniqueValue APIs. Prevents inadvertent transmission of cryptographic keys, access tokens, and sensitive infrastructure config payloads across the wire to Client Component trees through runtime and build-time serialization assertions. 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 Server-Side Secret Contexts or Unsanitized User-Profile Records Directly to Client Component Trees 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 Server-Side Secret Contexts or Unsanitized User-Profile Records Directly to Client Component Trees	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-only objects with `experimental_taintObjectReference` at their instantiation or retrieval boundary (e.g., config loaders, database client instances, sensitive user entities).

Engineers MUST ALWAYS register sensitive server-only objects with `experimental_taintObjectReference` at their instantiation or retrieval boundary (e.g., config loaders, database client instances, sensitive user entities).

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.