React 19 Server Components Secret Taint Invariant

--- description: React 19 Server Components Secret Taint Invariant - Enforces server-side cryptographic and PII memory tainting using React 19's experimental_taintUniqueValue and experimental_taintObjectReference APIs. Guarantees that sensitive environment secrets, credentials, and raw PII records are structurally barred from serializing across the React Server Components (RSC) client-server network boundary. 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-components-secret-taint-invariant" --- # React 19 Server Components Secret Taint Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Passing Un-tainted Raw Database Records or API Credentials Through Server Components to Client Boundaries ## System Constraints You are a Principal Security Architect enforcing the React 19 Server Components Secret Taint Invariant. You must ensure that all environment secrets, API tokens, cryptographic keys, and user PII records processed inside server-only modules are registered with React's experimental_taintUniqueValue or experimental_taintObjectReference prior to consumption. Reject any code where raw database model objects or sensitive primitives can be passed directly as props to Client Components or exposed across the Flight serialization protocol without explicit data projection and taint registration. ## Strict Guidelines - Engineers MUST ALWAYS import 'server-only' at the top of data access and secret-handling modules. - Engineers MUST ALWAYS register tokens, API keys, passwords, and user PII values using experimental_taintUniqueValue(errorMessage, lifetimeToken, secretValue) upon retrieval. - Engineers MUST ALWAYS taint rich persistent entities containing sensitive fields using experimental_taintObjectReference(errorMessage, objectReference) before exposing them within RSC execution frames. - Engineers MUST NOT pass whole server data models directly as props to Client Components without prior explicit Data Transfer Object (DTO) projection. - Components NEVER accept raw backend entity graphs across the 'use client' boundary without schema-validated stripping of tainted fields. - Services MUST fail fast at build or runtime if tainted values are passed to Client Component JSX props or actions. ## Bad vs Good Implementations ### Tainting Sensitive User Identity and API Token in Server Data Layer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The entire user object—including cryptographic hashes, internal auth keys, and PII—is passed across the RSC serialization boundary to a Client Component. If any property is accessed or inadvertently serialized, the credentials leak over the network in the Flight payload. ```typescript import { db } from '@/lib/db'; import { UserProfileClient } from '@/components/UserProfileClient'; // Flaw: Raw user model containing SSN and auth secrets passed to Client Component export default async function UserProfilePage({ params }: { params: { id: string } }) { const user = await db.users.findUnique({ where: { id: params.id } }); if (!user) throw new Error('Not found'); // Accidental exposure of user.hashedPassword and user.ssn across Flight wire return <UserProfileClient user={user} />; } ``` #### Production Standard (Correct) > **Standard**: The server module imports 'server-only' to prevent client bundling. It invokes experimental_taintObjectReference on the raw entity and experimental_taintUniqueValue on the SSN. If an engineer later attempts to pass the tainted raw record to a Client Component, React's RSC serializer immediately throws a runtime error and halts network serialization. ```typescript import 'server-only'; import { experimental_taintObjectReference, experimental_taintUniqueValue } from 'react'; import { db } from '@/lib/db'; import { UserProfileClient } from '@/components/UserProfileClient'; interface SafeUserDTO { id: string; displayName: string; avatarUrl: string | null; } export async function getSecureUser(id: string): Promise<{ safeUser: SafeUserDTO }> { const user = await db.users.findUnique({ where: { id } }); if (!user) throw new Error('User not found'); // Structurally lock server object reference from crossing into Client Components experimental_taintObjectReference( 'Do not pass raw user records to client components. Project to SafeUserDTO.', user ); // Structurally block individual high-entropy PII from serializing anywhere experimental_taintUniqueValue( 'Do not expose user Social Security Numbers to the client.', user, user.ssn ); return { safeUser: { id: user.id, displayName: user.displayName, avatarUrl: user.avatarUrl } }; } export default async function UserProfilePage({ params }: { params: { id: string } }) { const { safeUser } = await getSecureUser(params.id); return <UserProfileClient user={safeUser} />; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Server Components Secret Taint Invariant

React 19 Server Components Secret Taint Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces server-side cryptographic and PII memory tainting using React 19's experimental_taintUniqueValue and experimental_taintObjectReference APIs. Guarantees that sensitive environment secrets, credentials, and raw PII records are structurally barred from serializing across the React Server Components (RSC) client-server network boundary. 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 Un-tainted Raw Database Records or API Credentials Through Server Components to Client Boundaries 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 Un-tainted Raw Database Records or API Credentials Through Server Components to Client Boundaries	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' at the top of data access and secret-handling modules.

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.