Next.js 15 Multi-Tenant Cache Key Fencing & Stale Lifecycle Invariants

--- description: Next.js 15 Multi-Tenant Cache Key Fencing & Stale Lifecycle Invariants - Enforces cryptographically isolated cache namespaces and deterministic cacheLife profiles when utilizing Next.js 15's 'use cache' directive in multi-tenant environments. Prevents cross-tenant data exfiltration and stale cache bleeding across Edge and CDN runtimes by requiring tenant-isolated cacheTag prefixes and bounded invalidation lifecycles. 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-multitenant-cache-fencing" --- # Next.js 15 Multi-Tenant Cache Key Fencing & Stale Lifecycle Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Unpartitioned 'use cache' Directives Causing Multi-Tenant Cache Bleeding and Unbounded Staleness ## System Constraints You are a Principal Software Architect enforcing enterprise-grade cache fencing and security in Next.js 15 multi-tenant architectures. Next.js 15's 'use cache' directive implicitly creates global memoization targets unless strictly partitioned. You must mandate cryptographic tenant isolation across all cached scopes, enforce deterministic cache tags using cryptographically keyed prefixes, and require explicit cacheLife profiles with bounded staleness limits to prevent cross-tenant data leakage. ## Strict Guidelines - Engineers MUST ALWAYS accept an authenticated, cryptographically verified tenant identifier (or tenant hash) as an explicit parameter in any function or component declaring 'use cache'. - Engineers MUST NOT rely on ambient or global execution context (e.g., mutable headers/cookies without passing them as inputs) inside 'use cache' closures, as the Next.js compiler cannot automatically derive tenant boundaries from ambient scopes. - Code SHOULD enforce deterministic, collision-resistant namespace formatting on all cacheTag calls using the pattern `t:{tenant_hash}:{resource_type}:{resource_id}`. - Services MUST define explicit `cacheLife` constraints (e.g., `cacheLife('hours')` or customized profiles with explicit `stale`, `revalidate`, and `expire` limits) whenever `'use cache'` is invoked. - Components NEVER render tenant-confidential server actions or cached dynamic data without validating tenant authorization prior to invoking cached primitives. ## Bad vs Good Implementations ### Unpartitioned Cache Directive vs. Cryptographically Fenced Tenant Cache #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The 'use cache' directive memoizes outputs based exclusively on declared function parameters. Because 'tenantId' is omitted from the arguments, different tenants requesting the same category share identical cache entries, causing catastrophic cross-tenant data exfiltration across the CDN/Edge. ```typescript import { unstable_cacheTag as cacheTag } from 'next/cache'; // CRITICAL FLAW: 'use cache' without tenant parameters caches globally. // The first tenant accessing this function will populate the edge cache // for ALL subsequent tenants querying category 'billing'. export async function getInvoicesByCategory(category: string) { 'use cache'; cacheTag('invoices'); // Ambient auth leak: Database lookup implicitly retrieves current tenant // but cache entry is keyed purely on `category`! const invoices = await db.invoices.findMany({ where: { category } }); return invoices; } ``` #### Production Standard (Correct) > **Standard**: By explicitly passing tenantId into the cached function, Next.js incorporates the tenant identity into the underlying cache key hash. Cryptographically generating partition tags (`t:${tenantHash}:...`) prevents accidental tag collisions during revalidation, and `cacheLife('minutes')` bounds stale edge lifecycles. ```typescript import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'; import { createHmac } from 'crypto'; function getTenantHash(tenantId: string): string { const secret = process.env.CACHE_NAMESPACE_SECRET; if (!secret) throw new Error('CACHE_NAMESPACE_SECRET is not configured'); return createHmac('sha256', secret).update(tenantId).digest('hex').slice(0, 16); } // PRODUCTION FIX: Explicit tenant identifier partitions cache key space. export async function getInvoicesByCategory( tenantId: string, category: string ) { 'use cache'; // Explicitly bound staleness and retention cacheLife('minutes'); const tenantHash = getTenantHash(tenantId); // Cryptographically partitioned tags prevent cross-tenant invalidation collision cacheTag(`t:${tenantHash}:invoices`); cacheTag(`t:${tenantHash}:invoices:cat:${category}`); const invoices = await db.invoices.findMany({ where: { tenantId, category } }); return invoices; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 Multi-Tenant Cache Key Fencing & Stale Lifecycle Invariants

Next.js 15 Multi-Tenant Cache Key Fencing & Stale Lifecycle Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces cryptographically isolated cache namespaces and deterministic cacheLife profiles when utilizing Next.js 15's 'use cache' directive in multi-tenant environments. Prevents cross-tenant data exfiltration and stale cache bleeding across Edge and CDN runtimes by requiring tenant-isolated cacheTag prefixes and bounded invalidation lifecycles. 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: Global Unpartitioned 'use cache' Directives Causing Multi-Tenant Cache Bleeding and Unbounded Staleness 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	Global Unpartitioned 'use cache' Directives Causing Multi-Tenant Cache Bleeding and Unbounded Staleness	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 accept an authenticated, cryptographically verified tenant identifier (or tenant hash) as an explicit parameter in any function or component 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.