Next.js 15 'use cache' Salt-Isolated Multi-Tenant Keying and Tagging

--- description: Next.js 15 'use cache' Salt-Isolated Multi-Tenant Keying and Tagging - Next.js 15's 'use cache' directive evaluates functions in isolated boundaries without ambient request cookies or session headers. Multi-tenant data functions must explicitly accept cryptographically salted and verified tenant identifiers in function arguments and tag calls with HMAC-derived tenant prefixes to prevent catastrophic cross-tenant cache poisoning and leakage. 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/nextjs-15-use-cache-salt-tenant-isolation" --- # Next.js 15 'use cache' Salt-Isolated Multi-Tenant Keying and Tagging > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unsalted Tenant IDs or Ambient Session Assumptions in Next.js 15 'use cache' Scopes ## System Constraints You are a Principal Software Architect enforcing data boundary security in Next.js 15 applications using the 'use cache' directive. In multi-tenant environments, 'use cache' strips dynamic headers and cookies from its internal evaluation context. You must mandate that every function decorated with 'use cache' receives an immutable, cryptographically salted tenant authorization token or HMAC hash as an explicit argument, and that all 'cacheTag' and 'revalidateTag' invocations apply this tenant HMAC prefix. Reject any code that attempts to rely on ambient async context inside 'use cache' or accepts raw, unverified string tenant IDs prone to spoofing or global collision. ## Strict Guidelines - Engineers MUST ALWAYS pass an explicit, cryptographically verified tenant token or salted HMAC hash as a positional parameter to any function declaring 'use cache'. - Engineers MUST NOT attempt to read request-bound authentication context (such as 'headers()', 'cookies()', or React 'cache()' session singletons) inside a function declaring 'use cache', as Next.js 15 will throw build or runtime errors or detach dynamic scopes. - Engineers MUST prefix all cache invalidation tags generated via 'cacheTag()' or invalidated via 'revalidateTag()' with a deterministic HMAC digest of the tenant ID salted with an application-level secret. - Code SHOULD verify the caller's authorized tenant context in the outer Server Action or Page boundary before invoking the inner 'use cache' function. - Services MUST NEVER use raw sequential, predictable, or unsalted tenant identifiers (e.g., raw UUIDs or auto-incrementing integer IDs) as cache keys or cache tag components. - Components and Server Actions NEVER pass raw client-controlled parameters directly into 'use cache' functions without structural validation and cryptographic tenant scoping. ## Bad vs Good Implementations ### Unsalted, Ambient Multi-Tenant 'use cache' Implementation (Vulnerable to Cross-Tenant Leakage) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing a raw, unvalidated string allows any caller to probe other tenants' cached data. Furthermore, using plain string interpolation for 'cacheTag' without cryptographic tenant salting makes global invalidation operations vulnerable to cross-tenant pollution and collision. ```typescript // BAD: Relies on unverified tenant ID and bare cache tags import { unstable_cacheTag as cacheTag } from 'next/cache'; import { db } from '@/lib/db'; // VULNERABILITY 1: Unverified tenantId parameter can be spoofed by any caller // VULNERABILITY 2: Bare cache tags collision risk across deployment boundaries export async function getTenantInvoices(tenantId: string) { 'use cache'; cacheTag(`tenant-${tenantId}-invoices`); return db.invoice.findMany({ where: { tenantId }, orderBy: { createdAt: 'desc' }, }); } ``` #### Production Standard (Correct) > **Standard**: The outer boundary enforces authentication and session verification. The inner cached function uses 'use cache' with an HMAC-SHA256 salted tenant cache key as an explicit argument. The cache key and 'cacheTag' are mathematically insulated, preventing both cache poisoning and cross-tenant leakage. ```typescript // GOOD: Cryptographically salted tenant isolation keying with Next.js 15 'use cache' import { unstable_cacheTag as cacheTag } from 'next/cache'; import { createHmac } from 'node:crypto'; import { db } from '@/lib/db'; import { auth } from '@/lib/auth'; const CACHE_TENANT_SALT = process.env.CACHE_TENANT_SALT!; export function computeTenantCacheKey(tenantId: string): string { return createHmac('sha256', CACHE_TENANT_SALT) .update(`tenant:${tenantId}`) .digest('hex'); } // Hermetic cached function: arguments form the deterministic cache key async function fetchCachedInvoices(tenantCacheKey: string, tenantId: string) { 'use cache'; // Cache tag is deterministically scoped using HMAC salt cacheTag(`tenant:${tenantCacheKey}:invoices`); return db.invoice.findMany({ where: { tenantId }, orderBy: { createdAt: 'desc' }, select: { id: true, amount: true, status: true, createdAt: true }, }); } // Outer boundary: verifies ambient session and binds the salted key export async function getTenantInvoices() { const session = await auth(); if (!session?.tenantId) { throw new Error('Unauthorized'); } const tenantCacheKey = computeTenantCacheKey(session.tenantId); return fetchCachedInvoices(tenantCacheKey, session.tenantId); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 'use cache' Salt-Isolated Multi-Tenant Keying and Tagging

Next.js 15 'use cache' Salt-Isolated Multi-Tenant Keying and Tagging defines an industrial-grade behavioral standard for frontend engineering. Next.js 15's 'use cache' directive evaluates functions in isolated boundaries without ambient request cookies or session headers. Multi-tenant data functions must explicitly accept cryptographically salted and verified tenant identifiers in function arguments and tag calls with HMAC-derived tenant prefixes to prevent catastrophic cross-tenant cache poisoning and leakage. 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: Unsalted Tenant IDs or Ambient Session Assumptions in Next.js 15 'use cache' Scopes 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	Unsalted Tenant IDs or Ambient Session Assumptions in Next.js 15 'use cache' Scopes	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 pass an explicit, cryptographically verified tenant token or salted HMAC hash as a positional parameter to any function declaring 'use cache'.

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.