React 19 Taint Object API Boundary Enforcement for RSC Serialization

--- description: React 19 Taint Object API Boundary Enforcement for RSC Serialization - Enforces strict application of React 19's experimental_taintObjectReference and experimental_taintUniqueValue APIs to prevent sensitive server-side data models and cryptographic secrets from crossing the React Server Component (RSC) boundary. This guardrail ensures that server-only entities trigger deterministic build-time or runtime Flight serialization aborts if inadvertently forwarded to Client Components. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react19-taint-object-api-boundary-enforcement-production-standard" --- # React 19 Taint Object API Boundary Enforcement for RSC Serialization > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Raw Server Data Models and Sensitive Primitives Across Client Boundaries via RSC Flight Serialization ## System Constraints You are a Principal Software Architect enforcing React 19 Taint Object API Boundary Enforcement. Mandate that all server-side database records, authentication credentials, and sensitive domain models are cryptographically blocked from Flight serialization before exposure to Client Component boundaries. ## Strict Guidelines - Engineers MUST ALWAYS invoke `experimental_taintObjectReference` on raw ORM entities and sensitive server domain instances at the data-access layer before exposing them to Server Components. - Engineers MUST ALWAYS register sensitive scalar values (API tokens, private keys, password hashes) using `experimental_taintUniqueValue` bound to their owning entity or application lifetime. - Engineers MUST NOT pass whole server data structures directly to components decorated with 'use client' without constructing an explicit, field-level sanitized DTO. - Data Access Objects (DAOs) and repositories MUST enforce 'server-only' imports alongside React taint APIs to guarantee defense-in-depth against accidental client-bundle inclusion. - Components NEVER use object rest-spread (`{ ...user }`) to forward props from Server Components to Client Components without prior explicit projection. ## Bad vs Good Implementations ### Tainting Raw Server Models and Discrete Secrets #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The raw database object is passed directly to a Client Component without tainting. React's Flight protocol serializes all enumerable properties of the object, leaking internal infrastructure state, payment IDs, and password hashes over the network payload. ```typescript import 'server-only'; import { db } from '@/lib/db'; import { UserProfileCard } from '@/components/UserProfileCard'; // 'use client' export async function UserProfilePage({ userId }: { userId: string }) { // Anti-pattern: Raw ORM entity returned directly without tainting; // Client Component receives entire entity across Flight serialization boundary, // unintentionally leaking sensitive fields (e.g., hashed_password, stripe_customer_id). const user = await db.user.findUniqueOrThrow({ where: { id: userId } }); return <UserProfileCard user={user} />; } ``` #### Production Standard (Correct) > **Standard**: Both the raw user object reference and the discrete password hash are registered with React 19's taint system. Any accidental prop-drilling of `rawUser` into a Client Component will cause React's Flight serializer to throw an immediate error during serialization, completely blocking data leakage. ```typescript import 'server-only'; import { experimental_taintObjectReference, experimental_taintUniqueValue } from 'react'; import { db } from '@/lib/db'; import { UserProfileCard } from '@/components/UserProfileCard'; // 'use client' export async function getUser(userId: string) { const user = await db.user.findUniqueOrThrow({ where: { id: userId } }); // Cryptographically block the entire raw entity from Flight serialization experimental_taintObjectReference( 'Do not pass the raw User database record to Client Components. Map to PublicUserDTO instead.', user ); // Cryptographically block discrete sensitive scalar values from leakage experimental_taintUniqueValue( 'Do not expose user password hash or auth secret to the client.', user, user.passwordHash ); return user; } export async function UserProfilePage({ userId }: { userId: string }) { const rawUser = await getUser(userId); // Explicit projection prevents serialization errors and guarantees clean boundary DTO const publicUser = { id: rawUser.id, displayName: rawUser.displayName, avatarUrl: rawUser.avatarUrl }; return <UserProfileCard user={publicUser} />; } ```

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 strict application of React 19's experimental_taintObjectReference and experimental_taintUniqueValue APIs to prevent sensitive server-side data models and cryptographic secrets from crossing the React Server Component (RSC) boundary. This guardrail ensures that server-only entities trigger deterministic build-time or runtime Flight serialization aborts if inadvertently forwarded to Client Components. 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 Server Data Models and Sensitive Primitives Across Client Boundaries via RSC Flight 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 Server Data Models and Sensitive Primitives Across Client Boundaries via RSC Flight 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 ORM entities and sensitive server domain instances at the data-access layer before exposing them to Server Components.

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.