Next.js 15 Server Actions Boundary CSRF & Origin Validation Standard

--- description: Next.js 15 Server Actions Boundary CSRF & Origin Validation Standard - Next.js 15 Server Actions enforce built-in origin checks against the Host header, but multi-domain setups, reverse proxy misconfigurations, or unauthenticated action endpoints create severe CSRF and unauthorized state mutation vectors. Production actions must assert authenticated session identity, validate strict schemas, and configure experimental.serverActions.allowedOrigins to protect critical boundaries. globs: **/next.config.{js,ts,mjs}, **/actions/**/*.{ts,tsx}, **/app/**/actions.{ts,tsx}, **/app/**/_actions/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/next-js-15-server-actions-boundary-csrf-production-standard" --- # Next.js 15 Server Actions Boundary CSRF & Origin Validation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Treating Server Actions as private client-only functions while omitting boundary session checks and reverse-proxy origin configurations. ## System Constraints You are a Next.js security and architectural authority. You must enforce authenticated boundary validation, RFC-compliant origin enforcement, and strict schema validation for all Next.js 15 Server Actions. You must never allow Server Actions to process mutations based on unverified client-provided identifiers or unauthenticated invocations. ## Strict Guidelines - Every Next.js 15 Server Action performing a mutation MUST authenticate the caller session at the boundary before executing business logic. - Projects running behind reverse proxies, multi-zone architectures, or custom domains MUST explicitly define experimental.serverActions.allowedOrigins within next.config.ts. - Server Actions MUST NEVER rely on client-supplied identifiers (such as userId) to select target records for state updates; identifiers MUST be derived from verified session credentials. - All mutation inputs passed into Server Actions MUST be validated against a strict schema using a validation library such as Zod before persistence or evaluation. - Actions SHOULD return deterministic, strongly-typed result envelopes containing explicit failure reasons instead of leaking raw unhandled database errors. ## Bad vs Good Implementations ### Securing Next.js 15 Server Action Boundary against CSRF and Unauthorized State Mutation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This Server Action is exposed via a public POST endpoint created by Next.js. Any attacker can invoke this action with an arbitrary `userId` to mutate another user's email. It does not authenticate the session, does not validate the host/origin behind a proxy, and blindly trusts user input. ```typescript // app/actions/user.ts 'use server'; interface RawUpdatePayload { userId: string; email: string; } // ANTI-PATTERN: Lacks session authentication, trusts arbitrary userId from payload, // and assumes Next.js origin check alone protects against unauthorized state mutation. export async function updateUserEmail(payload: RawUpdatePayload) { const res = await fetch(`https://api.internal.local/users/${payload.userId}`, { method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email: payload.email }), }); return res.json(); } ``` #### Production Standard (Correct) > **Standard**: The hardened action authenticates caller identity via `getSession()`, derives the target user identity strictly from the session rather than untrusted client parameters, parses input using Zod, and enforces an explicit origin-host match defense-in-depth guardrail. ```typescript // app/actions/user.ts 'use server'; import { headers } from 'next/headers'; import { z } from 'zod'; const UpdateEmailSchema = z.object({ email: z.string().trim().email().max(254), }); interface AuthSession { user: { id: string }; } declare function getSession(): Promise<AuthSession | null>; declare function updateUserInDb(userId: string, email: string): Promise<{ id: string; email: string }>; type ActionResponse<T> = | { ok: true; data: T } | { ok: false; error: string; code: 'UNAUTHORIZED' | 'FORBIDDEN' | 'VALIDATION_ERROR' | 'INTERNAL_ERROR' }; export async function updateUserEmail(input: unknown): Promise<ActionResponse<{ email: string }>> { // 1. Boundary Session Authentication: derive subject strictly from authenticated context const session = await getSession(); if (!session?.user?.id) { return { ok: false, error: 'Unauthorized request', code: 'UNAUTHORIZED' }; } // 2. Defense-in-depth Origin / Host assertion for reverse proxy environments const headerList = await headers(); const host = headerList.get('x-forwarded-host') ?? headerList.get('host'); const origin = headerList.get('origin'); if (origin && host) { const originHost = new URL(origin).host; if (originHost !== host) { return { ok: false, error: 'Origin verification failed', code: 'FORBIDDEN' }; } } // 3. Strict schema validation const parseResult = UpdateEmailSchema.safeParse(input); if (!parseResult.success) { return { ok: false, error: 'Invalid email payload', code: 'VALIDATION_ERROR' }; } try { const updated = await updateUserInDb(session.user.id, parseResult.data.email); return { ok: true, data: { email: updated.email } }; } catch { return { ok: false, error: 'Database update failed', code: 'INTERNAL_ERROR' }; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 Server Actions Boundary CSRF & Origin Validation Standard

Next.js 15 Server Actions Boundary CSRF & Origin Validation Standard defines an industrial-grade behavioral standard for frontend engineering. Next.js 15 Server Actions enforce built-in origin checks against the Host header, but multi-domain setups, reverse proxy misconfigurations, or unauthenticated action endpoints create severe CSRF and unauthorized state mutation vectors. Production actions must assert authenticated session identity, validate strict schemas, and configure experimental.serverActions.allowedOrigins to protect critical boundaries. 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 private client-only functions while omitting boundary session checks and reverse-proxy origin configurations. 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 private client-only functions while omitting boundary session checks and reverse-proxy origin configurations.	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:

Every Next.js 15 Server Action performing a mutation MUST authenticate the caller session at the boundary before executing business logic.

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.