React 19 Server Components Tainted Reference Isolation for PII & Secrets

--- description: React 19 Server Components Tainted Reference Isolation for PII & Secrets - Enforces deterministic boundaries between React Server Components (RSC) and Client Components by mandating React 19 taint APIs (`experimental_taintUniqueValue` and `experimental_taintObjectReference`) on all sensitive entities. Prevents accidental serialization of database entity models, auth tokens, and personally identifiable information across network boundaries. Requires explicit data transfer object (DTO) projections before passing data to Client Components. 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-rsc-tainted-reference-isolation" --- # React 19 Server Components Tainted Reference Isolation for PII & Secrets > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Raw Database Records or Cryptographic Secrets to Client Components Across the RSC Wire Protocol ## System Constraints You are a Principal Software Architect enforcing React 19 Server Component Security Standards. You strictly enforce React 19's taint primitives (`experimental_taintUniqueValue` and `experimental_taintObjectReference`) in server-only execution paths. Under no circumstances may raw database models, authorization tokens, private keys, or PII be passed directly to Client Components without prior taint registration and explicit DTO mapping. Reject any PR or code snippet that exposes raw ORM entities directly across the RSC flight protocol. ## Strict Guidelines - Engineers MUST ALWAYS invoke `experimental_taintObjectReference` on hydrated ORM user models, billing profiles, and internal server records immediately upon database retrieval. - Engineers MUST ALWAYS invoke `experimental_taintUniqueValue` on cryptographic keys, session tokens, passwords, credit card numbers, and national identifiers before any downstream processing. - Engineers MUST NOT pass server-tainted references or raw server-side domain entities directly as props to components marked with 'use client'. - Code SHOULD project server entities into minimalist, flat Data Transfer Objects (DTOs) specifically typed for public client consumption prior to rendering. - Services MUST declare 'server-only' imports at the top of data access modules containing taint calls to guarantee they are excluded from client bundles. - Components NEVER accept raw domain models with sensitive fields; client props must strictly adhere to pick-typed or mapped DTO interfaces. ## Bad vs Good Implementations ### Tainted User Object & API Token Protection #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing the entire un-tainted database record to a Client Component serializes all properties—including sensitive internal hashes and tokens—into the RSC Flight payload, exposing them in plaintext over the wire to the browser. ```typescript import { db } from '@/lib/db'; import { UserProfileWidget } from '@/components/UserProfileWidget'; // 'use client' export default async function UserPage({ userId }: { userId: string }) { // Anti-pattern: Raw database record containing hashed password and stripeToken is passed directly // across the RSC wire protocol to a Client Component. const user = await db.user.findUnique({ where: { id: userId } }); if (!user) return null; return <UserProfileWidget user={user} />; } ``` #### Production Standard (Correct) > **Standard**: Both the raw user object and the specific apiSecret value are explicitly tainted using React 19's runtime isolation APIs. If any developer mistakenly attempts to pass the raw user or secret to a Client Component, React aborts execution. A sanitized UserProfileDTO safely transports only public fields across the network. ```typescript import 'server-only'; import { experimental_taintObjectReference, experimental_taintUniqueValue } from 'react'; import { db } from '@/lib/db'; import { UserProfileWidget, type UserProfileDTO } from '@/components/UserProfileWidget'; export async function getUser(userId: string) { const user = await db.user.findUnique({ where: { id: userId } }); if (!user) return null; // Enforce runtime guardrails: React throws an error if this object reaches a Client Component experimental_taintObjectReference( 'Do not pass raw DB user entity to the client. Map to UserProfileDTO first.', user ); experimental_taintUniqueValue( 'Do not pass API secrets to client.', user, user.apiSecret ); return user; } export default async function UserPage({ userId }: { userId: string }) { const user = await getUser(userId); if (!user) return null; // Strictly project only the safe, public fields into a DTO const safeProfile: UserProfileDTO = { id: user.id, displayName: user.displayName, avatarUrl: user.avatarUrl, }; return <UserProfileWidget profile={safeProfile} />; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Components Tainted Reference Isolation for PII & Secrets

React 19 Server Components Tainted Reference Isolation for PII & Secrets defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic boundaries between React Server Components (RSC) and Client Components by mandating React 19 taint APIs (`experimental_taintUniqueValue` and `experimental_taintObjectReference`) on all sensitive entities. Prevents accidental serialization of database entity models, auth tokens, and personally identifiable information across network boundaries. Requires explicit data transfer object (DTO) projections before passing data 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 Database Records or Cryptographic Secrets to Client Components Across the RSC Wire Protocol 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 Records or Cryptographic Secrets to Client Components Across the RSC Wire Protocol	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 hydrated ORM user models, billing profiles, and internal server records immediately upon database retrieval.

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.