Next.js 15 Server Actions Origin Validation and CSRF Boundary Enforcement

--- description: Next.js 15 Server Actions Origin Validation and CSRF Boundary Enforcement - Next.js 15 Server Actions expose public HTTP POST endpoints vulnerable to cross-origin abuse, host header spoofing behind reverse proxies, and unauthorized state mutation. Architects and developers must configure explicit `serverActions.allowedOrigins` in multi-domain or proxied deployments and enforce mandatory server-side authentication, origin verification, and schema validation inside every action body. globs: next.config.{ts,js,mjs}, src/actions/**/*.{ts,tsx}, src/app/**/*.{ts,tsx}, app/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nextjs-15-server-actions-csrf-boundary" --- # Next.js 15 Server Actions Origin Validation and CSRF Boundary Enforcement > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Treating Server Actions as Protected Internal Methods Without Origin Allowlisting or In-Action Session Guards ## System Constraints You are a Principal Software Architect enforcing enterprise-grade CSRF and origin security boundaries in Next.js 15 Server Actions. Enforce strict origin configuration, zero-trust action boundaries, and mandatory in-action session validation. ## Strict Guidelines - Engineers MUST ALWAYS configure `experimental.serverActions.allowedOrigins` (or `serverActions.allowedOrigins`) in `next.config.ts` whenever the application operates behind reverse proxies, CDNs, or custom subdomains. - Engineers MUST NOT use wildcard domains (`*`) or unvalidated regex in `allowedOrigins`; explicitly specify exact fully qualified domain names (FQDNs). - Engineers MUST treat every Server Action marked with `'use server'` as an unauthenticated, publicly exposed HTTP POST endpoint regardless of parent component visibility. - Engineers MUST ALWAYS re-authenticate and authorize the requesting user session directly inside the Server Action execution context before reading inputs or performing mutations. - Engineers MUST NOT rely on client-side state, hidden inputs, or client-rendered form guards to supply tenant IDs, user IDs, or permission scopes to Server Actions. - Code MUST validate all action input payloads using strict schema parsers (such as Zod) before executing business logic to prevent prototype poisoning and injection attacks. - Actions SHOULD verify the `Origin` or `Referer` headers against trusted internal hosts explicitly if handling sensitive cryptographic operations or external webhooks. ## Bad vs Good Implementations ### Next.js 15 Allowed Origins Configuration for Reverse Proxies #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When deploying Next.js behind a reverse proxy (e.g., NGINX, Cloudflare, AWS ALB) or across subdomains, omitting `allowedOrigins` causes Next.js to reject legitimate Server Action requests due to Host/X-Forwarded-Host mismatches, or leaves multi-tenant domains exposed. ```typescript // next.config.ts import type { NextConfig } from 'next'; const nextConfig: NextConfig = { // Anti-pattern: Missing allowedOrigins while deployed behind an ingress reverse proxy // or API gateway leads to Next.js 15 host-origin mismatch rejection or open CSRF vector. reactStrictMode: true, }; export default nextConfig; ``` #### Production Standard (Correct) > **Standard**: Explicitly declaring safe domain boundaries allows Next.js 15 to perform strict cross-origin verification against the `Origin` header without failing benign proxied requests or opening untrusted origins. ```typescript // next.config.ts import type { NextConfig } from 'next'; const nextConfig: NextConfig = { reactStrictMode: true, experimental: { serverActions: { allowedOrigins: [ 'app.example.com', 'auth.example.com', process.env.NODE_ENV === 'development' ? 'localhost:3000' : 'app.example.com' ] } } }; export default nextConfig; ``` ### Zero-Trust Server Action Session & Mutation Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Anyone can trigger a raw POST request with a forged `Next-Action` ID and arbitrary `userId`, enabling account takeover without triggering frontend auth guards. ```typescript // src/actions/update-profile.ts 'use server'; import { db } from '@/lib/db'; // Anti-pattern: Blindly trusts client-supplied identifiers and assumes // invoking this server action is restricted because the UI button was hidden. export async function updateUserProfile(formData: FormData) { const userId = formData.get('userId') as string; const email = formData.get('email') as string; await db.user.update({ where: { id: userId }, data: { email } }); return { success: true }; } ``` #### Production Standard (Correct) > **Standard**: The Server Action enforces authenticated session verification directly on the server, rejects client-supplied user IDs, validates inputs via Zod, and maintains strict boundary isolation against CSRF and IDOR attacks. ```typescript // src/actions/update-profile.ts 'use server'; import { headers } from 'next/headers'; import { z } from 'zod'; import { auth } from '@/lib/auth'; import { db } from '@/lib/db'; const ProfileSchema = z.object({ email: z.string().email(), displayName: z.string().min(2).max(50) }); export type ActionState = { success: boolean; error?: string; }; export async function updateUserProfile(prevState: ActionState, formData: FormData): Promise<ActionState> { // 1. Enforce authentication at the action boundary const session = await auth(); if (!session?.user?.id) { return { success: false, error: 'Unauthorized: Valid session required.' }; } // 2. Validate input against strict schema const rawData = { email: formData.get('email'), displayName: formData.get('displayName') }; const parsed = ProfileSchema.safeParse(rawData); if (!parsed.success) { return { success: false, error: 'Invalid input data.' }; } // 3. Mutate strictly scoped to authenticated user context await db.user.update({ where: { id: session.user.id }, data: parsed.data }); return { success: true }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 Server Actions Origin Validation and CSRF Boundary Enforcement

Next.js 15 Server Actions Origin Validation and CSRF Boundary Enforcement defines an industrial-grade behavioral standard for frontend engineering. Next.js 15 Server Actions expose public HTTP POST endpoints vulnerable to cross-origin abuse, host header spoofing behind reverse proxies, and unauthorized state mutation. Architects and developers must configure explicit `serverActions.allowedOrigins` in multi-domain or proxied deployments and enforce mandatory server-side authentication, origin verification, and schema validation inside every action body. 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: Treating Server Actions as Protected Internal Methods Without Origin Allowlisting or In-Action Session Guards 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	Treating Server Actions as Protected Internal Methods Without Origin Allowlisting or In-Action Session Guards	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 configure `experimental.serverActions.allowedOrigins` (or `serverActions.allowedOrigins`) in `next.config.ts` whenever the application operates behind reverse proxies, CDNs, or custom subdomains.

Engineers MUST ALWAYS configure `experimental.serverActions.allowedOrigins` (or `serverActions.allowedOrigins`) in `next.config.ts` whenever the application operates behind reverse proxies, CDNs, or custom subdomains.

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.