Enforce React 19 Experimental Taint API for Boundary Serialization Safety

--- description: Enforce React 19 Experimental Taint API for Boundary Serialization Safety - Enforces deterministic data boundary protection in React 19 Server Components using experimental_taintObjectReference and experimental_taintUniqueValue. Guarantees that raw cryptographic secrets, database tokens, and sensitive PII records cannot be serialized across the Server-to-Client Component boundary by throwing runtime errors during the React Flight serialization pass. globs: src/app/**/*.{ts,tsx}, src/features/**/*.{ts,tsx}, src/server/**/*.{ts,tsx}, src/lib/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-server-components-taint-api-standard" --- # Enforce React 19 Experimental Taint API for Boundary Serialization Safety > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Raw Sensitive Records or Operational Credentials across the Server-Client Boundary via Flight Serialization ## System Constraints You are a Principal Security and Frontend Architect enforcing React 19 Server Components Experimental Taint API Standards. Your mandate is to prevent accidental leakage of raw database entities, API tokens, cryptographic keys, and PII across the Server-to-Client component boundary. Invariants must be enforced using experimental_taintObjectReference and experimental_taintUniqueValue from the 'react' package within 'server-only' data-access layers before any DTO transformation occurs. ## Strict Guidelines - Engineers MUST ALWAYS import and invoke 'experimental_taintObjectReference' on whole data entities containing sensitive fields immediately upon instantiation or retrieval from the database layer. - Engineers MUST ALWAYS invoke 'experimental_taintUniqueValue' for standalone high-entropy secrets such as private keys, bearer tokens, or password hashes. - Engineers MUST ALWAYS isolate tainted logic within files designated with the 'server-only' package import to ensure taint registration occurs exclusively within Node.js/Edge server environments. - Engineers MUST NOT pass tainted entity references directly to Client Components (marked with 'use client'); sanitized Data Transfer Objects (DTOs) with explicit picking of safe fields MUST be created instead. - Code SHOULD provide clear, actionable taint rejection messages detailing the exact variable identity and remediation path for the serialization failure. - Services MUST instantiate tainting at the lowest possible data-access boundary (DAL/Repository) before any downstream business logic or view-layer orchestrations execute. ## Bad vs Good Implementations ### Tainting Raw Database User Records & High-Entropy Credentials #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The raw user entity contains sensitive fields (hashedPassword, ssn) and is returned without tainting. If an engineer inadvertently passes this object as a prop to a 'use client' component, React Flight will serialize the full payload to the client browser without any runtime intervention. ```typescript // server/data-access/user.ts import { db } from '@/server/db'; export async function getUserAccount(userId: string) { const user = await db.user.findUnique({ where: { id: userId }, }); // DANGEROUS: Returning raw database record containing hashedPassword, // stripeCustomerId, and ssn. If passed directly to a Client Component, // the React Flight serialization protocol will leak every field into client-side JS. return user; } ``` #### Production Standard (Correct) > **Standard**: Both the raw user object and sensitive individual values are registered with React's Taint API within a 'server-only' module. Any accidental attempt by Server Components to pass 'user' or 'user.apiToken' to a Client Component boundary will trigger an immediate runtime exception during Flight serialization. ```typescript // server/data-access/user.ts import 'server-only'; import { experimental_taintObjectReference, experimental_taintUniqueValue } from 'react'; import { db } from '@/server/db'; export interface SafeUserDTO { id: string; name: string; avatarUrl: string | null; } export async function getUserAccount(userId: string): Promise<SafeUserDTO | null> { const user = await db.user.findUnique({ where: { id: userId }, }); if (!user) return null; // INVARIANT: Taint the entire raw record against Flight serialization experimental_taintObjectReference( 'Do not pass the raw database User record to the Client. Construct a SafeUserDTO instead.', user ); // INVARIANT: Individually taint high-entropy credentials if (user.apiToken) { experimental_taintUniqueValue( 'Do not pass user API credentials to the client.', user, user.apiToken ); } // Explicit safe projection return { id: user.id, name: user.name, avatarUrl: user.avatarUrl, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Enforce React 19 Experimental Taint API for Boundary Serialization Safety

Enforce React 19 Experimental Taint API for Boundary Serialization Safety defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic data boundary protection in React 19 Server Components using experimental_taintObjectReference and experimental_taintUniqueValue. Guarantees that raw cryptographic secrets, database tokens, and sensitive PII records cannot be serialized across the Server-to-Client Component boundary by throwing runtime errors during the React Flight serialization pass. 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 Sensitive Records or Operational Credentials across the Server-Client Boundary via 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 Sensitive Records or Operational Credentials across the Server-Client Boundary via 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 import and invoke 'experimental_taintObjectReference' on whole data entities containing sensitive fields immediately upon instantiation or retrieval from the database layer.

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.