Mandatory React 19 RSC Server Taint Boundary and Secret Isolation

--- description: Mandatory React 19 RSC Server Taint Boundary and Secret Isolation - Enforces strict isolation of server-only secrets, cryptographic material, and raw database models using React 19's Server Taint APIs (taintObjectReference, taintUniqueValue) alongside explicit Data Transfer Object (DTO) projection. Prevents accidental serialization of sensitive backend credentials and internal domain models into React Server Component (RSC) streaming Flight protocol payloads sent to the client browser. 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-server-taint-boundary" --- # Mandatory React 19 RSC Server Taint Boundary and Secret Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Raw Database Entities and Environment Secrets Through RSC Flight Wire Payloads ## System Constraints You are a Principal Security Architect and React 19 Core Specialist. You must rigorously prevent server-side credential leaks in React Server Components. Mandate the use of 'server-only', React 19's experimental_taintObjectReference and experimental_taintUniqueValue, and strict projection layers. Reject any code where raw database records, sensitive tokens, or cryptographic primitives are passed across server-to-client component boundaries. ## Strict Guidelines - Engineers MUST ALWAYS import 'server-only' in modules handling database models, external service secrets, or cryptographic operations. - Engineers MUST call 'experimental_taintObjectReference' on all raw database entities, authentication sessions, and proprietary domain objects immediately upon instantiation or retrieval. - Engineers MUST call 'experimental_taintUniqueValue' on discrete secret strings, including API tokens, session cookies, private hashes, and cryptographic keys. - Engineers MUST NOT pass raw server-tainted objects directly as props to Client Components ('use client') or return them from Server Actions without explicit DTO sanitization. - Code SHOULD implement explicit view-model mapping functions (e.g., toSafeUserDTO) that construct new plain objects containing only allowlisted public fields before rendering Client Components. - Services MUST ensure that environment configuration variables containing sensitive credentials (e.g., process.env.API_SECRET) are tagged with taintUniqueValue during application bootstrap. ## Bad vs Good Implementations ### Tainting Raw DB Entities and Passing Safe DTOs #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing the raw database record directly to a Client Component causes React to serialize every field in the object into the streaming RSC payload, exposing password hashes, internal roles, and multi-factor secrets over the network wire. ```typescript import db from '@/lib/db'; import { UserProfileCard } from '@/components/UserProfileCard'; // Client Component export async function UserPage({ userId }: { userId: string }) { // Anti-Pattern: Raw DB record with passwordHash and internal metadata is passed directly // into a Client Component, causing React to serialize sensitive fields over RSC Flight stream. const rawUser = await db.user.findUnique({ where: { id: userId } }); if (!rawUser) return null; return <UserProfileCard user={rawUser} />; } ``` #### Production Standard (Correct) > **Standard**: By registering the entity with React's Taint API, any attempt to serialize the tainted reference or unique value in a client prop throws an immediate runtime error on the server before data leaves the boundary. Safe projection ensures minimal, sanitized data transfer. ```typescript import 'server-only'; import { experimental_taintObjectReference, experimental_taintUniqueValue } from 'react'; import db from '@/lib/db'; import { UserProfileCard, type SafeUserDTO } from '@/components/UserProfileCard'; export async function UserPage({ userId }: { userId: string }) { const rawUser = await db.user.findUnique({ where: { id: userId } }); if (!rawUser) return null; // Invariant: Cryptographically taint the raw database record and discrete secrets experimental_taintObjectReference( 'Do not pass raw User records directly to Client Components. Project to SafeUserDTO.', rawUser ); experimental_taintUniqueValue( 'Do not expose user password hash or salt to client payloads.', rawUser, rawUser.passwordHash ); // Explicit projection: only allowlisted fields cross the RSC boundary const safeUser: SafeUserDTO = { id: rawUser.id, displayName: rawUser.displayName, avatarUrl: rawUser.avatarUrl }; return <UserProfileCard user={safeUser} />; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory React 19 RSC Server Taint Boundary and Secret Isolation

Mandatory React 19 RSC Server Taint Boundary and Secret Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation of server-only secrets, cryptographic material, and raw database models using React 19's Server Taint APIs (taintObjectReference, taintUniqueValue) alongside explicit Data Transfer Object (DTO) projection. Prevents accidental serialization of sensitive backend credentials and internal domain models into React Server Component (RSC) streaming Flight protocol payloads sent to the client browser. 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 Entities and Environment Secrets Through RSC Flight Wire Payloads 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 Entities and Environment Secrets Through RSC Flight Wire Payloads	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 import 'server-only' in modules handling database models, external service secrets, or cryptographic operations.

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.