Next.js 15 Async Request Scope & Multi-Tenant Cache Isolation Guardrail

--- description: Next.js 15 Async Request Scope & Multi-Tenant Cache Isolation Guardrail - Enforces strict boundary isolation between Next.js 15 asynchronous dynamic request APIs (await cookies(), await headers(), searchParams) and shared data caching mechanisms (unstable_cache, Data Cache, shared CDN edge layers). Prevents critical cross-tenant data poisoning and authorization bypasses caused by persisting tenant-scoped or user-scoped data into shared cache partitions. globs: app/**/*.{ts,tsx}, src/app/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, src/lib/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nextjs-15-async-request-cache-isolation" --- # Next.js 15 Async Request Scope & Multi-Tenant Cache Isolation Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Persisting Tenant-Specific Data into Shared Data Caches via Dynamic Async Request Closures ## System Constraints You are a Principal Software Architect enforcing Next.js 15 Asynchronous Request Scope Cache Isolation Guardrails. In Next.js 15, dynamic request APIs (cookies(), headers(), params, searchParams) are asynchronous Promises, and fetch requests default to no-store. You must rigorously prevent cross-tenant cache contamination, ensuring that any dynamic request context is NEVER closed over or persisted into shared caching layers (unstable_cache, force-cache, or global revalidation tags) without strict cryptographic tenant partitioning or dynamic scope isolation. ## Strict Guidelines - Engineers MUST ALWAYS treat Next.js 15 request scope APIs (`cookies()`, `headers()`, `params`, `searchParams`) as asynchronous Dynamic Data Sources that opt out of static optimization. - Engineers MUST NOT invoke or close over dynamic request helpers (`await cookies()`, `await headers()`) inside the callback of `unstable_cache`, as this violates isolation boundaries and risks global data leakage across sessions. - Engineers MUST explicitly incorporate verified tenant IDs and security contexts into `keyParts` whenever `unstable_cache` is utilized in multi-tenant environments, or default strictly to React `cache()` for per-request memoization. - Code SHOULD prefer `connection()` from `next/server` before invoking dynamic APIs when explicitly opting into dynamic request handling to guarantee clean separation from static build-time paths. - Services MUST NEVER configure `fetch` with `cache: 'force-cache'` or persistent Next.js Data Cache tags when sending Authorization headers, tenant-specific cookies, or session tokens. - Components NEVER store user-personalized UI trees in shared CDN/Edge caches; layouts and components reading session state MUST render in dynamic request scopes. ## Bad vs Good Implementations ### Cross-Tenant Cache Poisoning in unstable_cache vs Isolated Multi-Tenant Scoping #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Next.js evaluates unstable_cache globally across requests and tenants. Omitting tenantId from the cache keyParts and attempting to read request headers inside the callback poisons the global cache with the first tenant's data, serving it to subsequent callers regardless of identity. ```typescript import { unstable_cache } from 'next/cache'; import { headers } from 'next/headers'; import { db } from '@/lib/db'; // CRITICAL: headers() closed inside unstable_cache or missing tenant key export async function getTenantInvoices() { return unstable_cache( async () => { // Poisoning hazard: reading async headers inside cached callback // or omitting tenantId from keyParts permits Tenant B to read Tenant A's cached invoices const headerStore = await headers(); const tenantId = headerStore.get('x-tenant-id'); return db.invoices.findMany({ where: { tenantId } }); }, ['tenant-invoices'], // Shared global cache key across ALL tenants! { revalidate: 3600, tags: ['invoices'] } )(); } ``` #### Production Standard (Correct) > **Standard**: Separates dynamic request extraction (using async headers() and React request-level cache()) from the shared caching primitive (unstable_cache). Guarantees that unstable_cache receives tenantId strictly as an external cache keyPart and isolated revalidation tag, completely eliminating cross-tenant leakage. ```typescript import { unstable_cache } from 'next/cache'; import { headers } from 'next/headers'; import { connection } from 'next/server'; import { cache } from 'react'; import { db } from '@/lib/db'; // 1. React cache() scopes memoization strictly to the current request lifecycle export const getRequestTenantId = cache(async (): Promise<string> => { await connection(); // Explicitly marks boundary as dynamic request const headerList = await headers(); const tenantId = headerList.get('x-tenant-id'); if (!tenantId || !/^[a-zA-Z0-9_-]+$/.test(tenantId)) { throw new Error('Invalid or missing tenant identifier'); } return tenantId; }); // 2. Pure data fetcher with explicit tenant key isolation const fetchCachedTenantInvoices = (tenantId: string) => unstable_cache( async () => db.invoices.findMany({ where: { tenantId } }), ['tenant-invoices', tenantId], // Strictly partitioned by verified tenantId { revalidate: 3600, tags: [`tenant:${tenantId}:invoices`] } )(); export async function getTenantInvoices() { const tenantId = await getRequestTenantId(); return fetchCachedTenantInvoices(tenantId); } ``` ### Authenticated Fetch Cache Poisoning vs Request-Bound Dynamic Fetch #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using 'force-cache' on authenticated fetches causes the Next.js Data Cache to persist the response under a global fetch hash. Another user requesting their profile may receive the poisoned cached response of the first user. ```typescript import { cookies } from 'next/headers'; export async function getUserProfile() { const cookieStore = await cookies(); const token = cookieStore.get('session_token')?.value; // VULNERABILITY: Combining authenticated bearer token with force-cache const res = await fetch('https://api.internal/user/profile', { headers: { Authorization: `Bearer ${token}` }, cache: 'force-cache', // Persists user profile into the shared Next.js Data Cache next: { tags: ['user-profile'] }, }); return res.json(); } ``` #### Production Standard (Correct) > **Standard**: Explicitly enforces 'no-store' for authenticated requests, ensuring personal user profiles are evaluated strictly per-request and never stored in the shared multi-tenant Next.js Data Cache or edge caches. ```typescript import { cookies } from 'next/headers'; import { connection } from 'next/server'; export async function getUserProfile() { await connection(); // Signals runtime dynamic execution context const cookieStore = await cookies(); const token = cookieStore.get('session_token')?.value; if (!token) { throw new Error('Unauthorized'); } // Authenticated dynamic fetches MUST NOT use persistent shared cache const res = await fetch('https://api.internal/user/profile', { headers: { Authorization: `Bearer ${token}` }, cache: 'no-store', // Next.js 15 default; explicitly enforced for auth payloads }); if (!res.ok) { throw new Error(`Profile fetch failed: ${res.status}`); } return res.json(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 Async Request Scope & Multi-Tenant Cache Isolation Guardrail

Next.js 15 Async Request Scope & Multi-Tenant Cache Isolation Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary isolation between Next.js 15 asynchronous dynamic request APIs (await cookies(), await headers(), searchParams) and shared data caching mechanisms (unstable_cache, Data Cache, shared CDN edge layers). Prevents critical cross-tenant data poisoning and authorization bypasses caused by persisting tenant-scoped or user-scoped data into shared cache partitions. 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: Persisting Tenant-Specific Data into Shared Data Caches via Dynamic Async Request Closures 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	Persisting Tenant-Specific Data into Shared Data Caches via Dynamic Async Request Closures	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 treat Next.js 15 request scope APIs (`cookies()`, `headers()`, `params`, `searchParams`) as asynchronous Dynamic Data Sources that opt out of static optimization.

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.