React 19 Taint API & RSC Boundary Data Leakage Prevention

--- description: React 19 Taint API & RSC Boundary Data Leakage Prevention - Enforces deterministic data masking and memory-level boundary protection using React 19's experimental Taint APIs (experimental_taintObjectReference and experimental_taintUniqueValue). Prevents cryptographic secrets, authentication tokens, internal tenant identifiers, and unmasked PII from leaking across the React Server Component (RSC) serialization boundary into client bundles. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx}, lib/dal/**/*.{ts,tsx}, services/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-taint-api-serialization-guardrails" --- # React 19 Taint API & RSC Boundary Data Leakage Prevention > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Passing Raw Database Records or Unsanitized Context Containing Secrets Directly Across the RSC Flight Boundary ## System Constraints You are a Principal Security and Frontend Architect enforcing React 19 Server Component serialization guardrails. You must mandate the use of the React Taint API across all server-side data access layers (DAL). Ensure no raw database entities, API tokens, cryptographic secrets, or sensitive PII traverse the Flight protocol boundary to client components. Mandate Data Transfer Objects (DTOs) and automated taint enforcement at the ingress boundary. ## Strict Guidelines - Engineers MUST ALWAYS register experimental_taintObjectReference on raw database entity models, sensitive configuration objects, and internal session records within the Data Access Layer (DAL). - Engineers MUST ALWAYS call experimental_taintUniqueValue on individual high-entropy primitives, including JWT secrets, cryptographic keys, Stripe customer IDs, and raw PII (SSNs, password hashes). - Engineers MUST NOT pass database ORM instances (Prisma, Drizzle, TypeORM) directly to Client Components marked with 'use client'. - Services MUST project server-side entities into explicit, strictly-typed Data Transfer Objects (DTOs) before passing them as props to Client Components. - Components NEVER accept raw server context or internal tenant metadata props when client-side execution is enabled. - Code SHOULD enforce fail-closed serialization policies, ensuring that untrusted or unvalidated server data triggers a compile-time or runtime Flight protocol rejection. ## Bad vs Good Implementations ### RSC Boundary Leakage via Raw Record vs. Taint API Guardrails with Strict DTO #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing the raw database record directly across the RSC Flight serialization boundary leaks sensitive internal metadata (hashed passwords, internal tenant IDs, payment provider references) to the browser payload, easily inspectable via browser network inspect tools. ```typescript import { db } from '@/lib/db'; import { ClientUserProfile } from './ClientUserProfile'; // VULNERABLE: Direct transmission of ORM entity across RSC boundary export default async function ProfilePage({ params }: { params: { id: string } }) { const user = await db.user.findUnique({ where: { id: params.id }, include: { credentials: true, tenant: true }, }); if (!user) return null; // CRITICAL SECURITY FLAW: 'user' contains hashed passwords, tenant config, and Stripe IDs // React's flight serializer bundles these into the client payload (window.__next_f) return <ClientUserProfile user={user} />; } ``` #### Production Standard (Correct) > **Standard**: Using experimental_taintObjectReference and experimental_taintUniqueValue causes the React runtime to throw an immediate server exception if the raw user object or password hash is ever passed to a Client Component. Explicit projection to PublicUserDTO guarantees minimum necessary payload serialization. ```typescript import 'server-only'; import { experimental_taintObjectReference, experimental_taintUniqueValue } from 'react'; import { db } from '@/lib/db'; import { ClientUserProfile } from './ClientUserProfile'; export interface PublicUserDTO { id: string; displayName: string; avatarUrl: string | null; } export async function getUserSafe(id: string): Promise<PublicUserDTO | null> { const user = await db.user.findUnique({ where: { id }, include: { credentials: true, tenant: true }, }); if (!user) return null; // INVARIANT: Block serialization of the underlying raw entity and critical primitives experimental_taintObjectReference( 'Do not pass raw user entity to the client. Use PublicUserDTO instead.', user ); experimental_taintUniqueValue( 'Do not pass password hash to the client.', user, user.credentials.passwordHash ); // Explicit projection prevents implicit property leakage return { id: user.id, displayName: user.name, avatarUrl: user.avatarUrl, }; } export default async function ProfilePage({ params }: { params: { id: string } }) { const safeUser = await getUserSafe(params.id); if (!safeUser) return null; return <ClientUserProfile user={safeUser} />; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Taint API & RSC Boundary Data Leakage Prevention

React 19 Taint API & RSC Boundary Data Leakage Prevention defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic data masking and memory-level boundary protection using React 19's experimental Taint APIs (experimental_taintObjectReference and experimental_taintUniqueValue). Prevents cryptographic secrets, authentication tokens, internal tenant identifiers, and unmasked PII from leaking across the React Server Component (RSC) serialization boundary into client bundles. 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 Raw Database Records or Unsanitized Context Containing Secrets Directly Across the RSC Flight Boundary 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 Raw Database Records or Unsanitized Context Containing Secrets Directly Across the RSC Flight Boundary	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 experimental_taintObjectReference on raw database entity models, sensitive configuration objects, and internal session records within the Data Access Layer (DAL).

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.