Next.js 15 Taint Object API Data-Boundary Leakage Guardrail

--- description: Next.js 15 Taint Object API Data-Boundary Leakage Guardrail - Enforces deterministic data-boundary isolation using React and Next.js 15 Taint APIs (`experimental_taintObjectReference` and `experimental_taintUniqueValue`) across all Data Access Layers (DAL). Programmatically prevents raw ORM entities, cryptographic secrets, and internal identifiers from crossing the Server Component serialization barrier into client RSC Flight payloads. globs: src/data-access/**/*.{ts,tsx}, src/lib/**/*.{ts,tsx}, src/server/**/*.{ts,tsx}, src/app/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nextjs-15-taint-object-api-guardrail" --- # Next.js 15 Taint Object API Data-Boundary Leakage Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Passing Raw Database Records or Cryptographic Secrets across Server-Client Component Boundaries ## System Constraints You are a Principal Software Architect enforcing the Next.js 15 Taint Object API Data-Boundary Leakage Guardrail. Your mandate is to prevent accidental exfiltration of raw database rows, environment credentials, and cryptographic artifacts across the Server-to-Client Component serialization barrier. Enforce `experimental_taintObjectReference` on all raw domain/ORM entities and `experimental_taintUniqueValue` on secrets inside the Data Access Layer (DAL). Require explicit Data Transfer Objects (DTOs) for all props passed into Client Components or returned from Server Actions. ## Strict Guidelines - Engineers MUST ALWAYS invoke `experimental_taintObjectReference` on raw database models, ORM records, and internal session payloads within the Data Access Layer (DAL). - Engineers MUST ALWAYS apply `experimental_taintUniqueValue` to raw cryptographic tokens, API keys, and password hashes with an explicit message explaining the security violation. - Engineers MUST NOT pass raw ORM entities or full data records directly to Client Components marked with 'use client' or return them naked from Server Actions. - Code MUST construct explicit, strictly typed Data Transfer Objects (DTOs) using allow-listed fields before transmitting data across the RSC Flight serialization boundary. - Services MUST ensure that files executing Taint APIs import 'server-only' at the root to avoid bundling server boundaries into client-executable chunks. - Components NEVER accept untyped spread objects (`{...props}`) when consuming outputs from Server Components or DAL abstractions. ## Bad vs Good Implementations ### Data Access Layer (DAL) Entity and Secret Tainting #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Returning untainted ORM models allows developers to inadvertently pass the full entity graph (including password hashes, internal IDs, and tokens) as props to Client Components. Next.js will serialize the entire graph into the HTML/RSC Flight stream, exposing sensitive backend fields. ```typescript import { db } from '@/lib/db'; // ANTI-PATTERN: Raw entity leaked without boundary protection export async function getUserAccount(userId: string) { const user = await db.user.findUnique({ where: { id: userId }, include: { sessionTokens: true, billingProfile: true } }); // Directly returning raw ORM record containing passwordHash and tokens return user; } // In Server Component: // <UserProfileCard user={user} /> // Leaks complete database record to Flight payload ``` #### Production Standard (Correct) > **Standard**: Using `experimental_taintObjectReference` halts compilation/runtime serialization if the raw `user` object is ever passed to a Client Component. `experimental_taintUniqueValue` ensures sensitive values cannot leak even if destructured. An explicit DTO safe-lists only permissible fields. ```typescript import 'server-only'; import { experimental_taintObjectReference, experimental_taintUniqueValue } from 'react'; import { db } from '@/lib/db'; export interface UserPublicDto { id: string; name: string; email: string; } export async function getUserAccount(userId: string): Promise<UserPublicDto | null> { const user = await db.user.findUnique({ where: { id: userId }, include: { sessionTokens: true, billingProfile: true } }); if (!user) return null; // Guardrail 1: Taint entire entity reference from client serialization experimental_taintObjectReference( 'Do not pass raw User entity to Client Components. Transform into a DTO.', user ); // Guardrail 2: Taint specific unique values even if extracted if (user.passwordHash) { experimental_taintUniqueValue( 'Do not pass password hashes to the client.', user, user.passwordHash ); } // Explicit DTO projection across the serialization boundary return { id: user.id, name: user.name, email: user.email }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 Taint Object API Data-Boundary Leakage Guardrail

Next.js 15 Taint Object API Data-Boundary Leakage Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic data-boundary isolation using React and Next.js 15 Taint APIs (`experimental_taintObjectReference` and `experimental_taintUniqueValue`) across all Data Access Layers (DAL). Programmatically prevents raw ORM entities, cryptographic secrets, and internal identifiers from crossing the Server Component serialization barrier into client RSC Flight payloads. 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 Raw Database Records or Cryptographic Secrets across Server-Client Component 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 Raw Database Records or Cryptographic Secrets across Server-Client Component 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 invoke `experimental_taintObjectReference` on raw database models, ORM records, and internal session payloads within the Data Access Layer (DAL).

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.