React 19 RSC Taint Boundary & Cryptographic Secret Protection

--- description: React 19 RSC Taint Boundary & Cryptographic Secret Protection - Enforces compiler- and runtime-level data tainting via React 19 experimental_taintUniqueValue and experimental_taintObjectReference across the Data Access Layer (DAL). Guarantees that cryptographic keys, authentication tokens, and raw entity models containing sensitive fields cannot be serialized into React Server Component (RSC) flight payloads or leaked to client bundles. 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-data-taint-boundary" --- # React 19 RSC Taint Boundary & Cryptographic Secret Protection > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Passing Untainted Raw Database Entities or Cryptographic Secrets Through RSC Boundaries to Client Components ## System Constraints You are a Principal Security Architect enforcing React 19 Server Components Data Taint Boundaries. You must mandate strict isolation between server-side data access, cryptographic operations, and serialized client boundaries. Every secret, API key, token, and raw database record must be proactively tainted at ingestion using experimental_taintUniqueValue or experimental_taintObjectReference, and all client-facing data must be transformed into explicit, minimal Data Transfer Objects (DTOs). ## Strict Guidelines - Engineers MUST ALWAYS import 'server-only' in any module that reads environment secrets or queries persistent datastores. - Engineers MUST invoke experimental_taintUniqueValue(errorMessage, lifetime, value) immediately upon loading any secret, API token, private key, or sensitive credential. - Engineers MUST invoke experimental_taintObjectReference(errorMessage, object) on raw database entity models containing sensitive or internal attributes before passing them across layer boundaries. - Engineers MUST NOT pass database query results directly to Client Components without an explicit projection into an un-tainted Data Transfer Object (DTO). - Components and Server Actions MUST NEVER return tainted primitives or objects across the Flight RPC serialization boundary; violations must fail hard during build or SSR evaluation. - Data Access Layer (DAL) modules MUST centralize data retrieval and taint enforcement so downstream consumers cannot bypass protection. ## Bad vs Good Implementations ### Data Access Layer Secret & Entity Taint Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to import 'server-only', does not invoke React 19 taint APIs, and returns raw entity records and secrets directly. Inadvertent usage in Client Component props will silently serialize sensitive data to the client's network tab. ```typescript import db from '@/lib/db'; // ANTI-PATTERN: Raw database record and decrypted API token exposed directly. // If this object or its properties are passed as props to a Client Component, // React will serialize them into the RSC JSON payload sent to the browser. export async function getUserProfile(userId: string) { const user = await db.users.findUnique({ where: { id: userId } }); const stripeApiKey = process.env.STRIPE_SECRET_KEY; return { user, // Contains passwordHash, ssn, stripeCustomerId, etc. stripeApiKey, }; } ``` #### Production Standard (Correct) > **Standard**: Marks module as 'server-only', taints the Stripe API secret string with experimental_taintUniqueValue, taints the raw user entity with experimental_taintObjectReference, and projects safe fields into an explicit DTO, throwing fatal runtime errors if tainted values attempt serialization. ```typescript import 'server-only'; import { experimental_taintUniqueValue, experimental_taintObjectReference } from 'react'; import db from '@/lib/db'; // Production Invariant: Taint secrets globally upon module evaluation if (process.env.STRIPE_SECRET_KEY) { experimental_taintUniqueValue( 'CRITICAL: Stripe secret keys must never be exposed to the client bundle.', process, process.env.STRIPE_SECRET_KEY ); } export interface PublicUserDto { id: string; displayName: string; avatarUrl: string | null; } export async function getUserProfile(userId: string): Promise<PublicUserDto> { const user = await db.users.findUnique({ where: { id: userId } }); if (!user) throw new Error('User not found'); // Production Invariant: Taint raw database record reference experimental_taintObjectReference( 'CRITICAL: Raw User entity contains sensitive attributes and must not cross RSC boundary.', user ); // Explicit projection: only pass safe, explicitly mapped DTOs to components return { id: user.id, displayName: user.displayName, avatarUrl: user.avatarUrl, }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 RSC Taint Boundary & Cryptographic Secret Protection

React 19 RSC Taint Boundary & Cryptographic Secret Protection defines an industrial-grade behavioral standard for frontend engineering. Enforces compiler- and runtime-level data tainting via React 19 experimental_taintUniqueValue and experimental_taintObjectReference across the Data Access Layer (DAL). Guarantees that cryptographic keys, authentication tokens, and raw entity models containing sensitive fields cannot be serialized into React Server Component (RSC) flight payloads or leaked to 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 Untainted Raw Database Entities or Cryptographic Secrets Through RSC Boundaries to Client Components 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 Untainted Raw Database Entities or Cryptographic Secrets Through RSC Boundaries to Client Components	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 any module that reads environment secrets or queries persistent datastores.

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.