A-6 — Server Actions at Scale: Internals and Security

Returning errors as data (Pattern 1) gives you the most control over user-facing error messages. Throwing unhandled errors (Pattern 2) is appropriate for genuinely exceptional cases — the error boundary provides a recovery UI. redirect() uses a throw internally; always put it outside try/catch blocks.

---

Organising Server Actions at Scale

In a large codebase, scattering Server Actions across component files creates a maintenance problem. The architectural pattern that scales:

src/
  actions/
    products.ts    ← all product mutations
    users.ts       ← all user mutations
    orders.ts      ← all order mutations
  lib/
    validations/
      product.ts   ← Zod schemas reused by both actions and API routes

Each actions file:

// src/actions/products.ts
'use server';
 
import { auth } from '@/lib/auth';
import { CreateProductSchema, UpdateProductSchema } from '@/lib/validations/product';
 
export async function createProduct(prevState: ActionState, formData: FormData) {
  // ...
}
 
export async function updateProduct(id: string, prevState: ActionState, formData: FormData) {
  // ...
}
 
export async function deleteProduct(id: string) {
  // ...
}

This structure means:

• One file per domain — easy to find all mutations for a feature
• Validation schemas live in /lib/validations — shared with API routes and server-side queries
• Auth checks at the top of every action — impossible to accidentally skip
• Easy to audit — a security review reads one file per domain

---

The after() API and Side Effects

after() is the correct way to run side effects (analytics, audit logging, cache warming) after a Server Action completes — without blocking the response:

'use server';
 
import { after } from 'next/server';
import { auth } from '@/lib/auth';
 
export async function purchaseProduct(productId: string) {
  const session = await auth();
  const order = await db.orders.create({ ... });
 
  // Response sent immediately after this line
  // The after() callback runs after the response is sent
  after(async () => {
    await analytics.track('purchase', {
      userId: session.user.id,
      productId,
      orderId: order.id,
    });
    await auditLog.write({
      action: 'purchase',
      userId: session.user.id,
      resourceId: order.id,
    });
  });
 
  revalidatePath('/orders');
  return order;
}

Without after(), you'd either block the response waiting for analytics (bad UX) or fire-and-forget with a floating promise (data loss risk if the function exits before the promise resolves). after() gives you the correct semantics: the callback completes before the serverless function exits, but after the response is sent.

---

Encrypted Closures — Protecting Bound Arguments

The "action ID obscurity" point above is about the action's identifier — the hash that tells Next.js which function to invoke. That hash is not a secret; it's a routing key. But there's a separate, more interesting mechanism that protects a different piece of data: values you close over with bind().

Consider a pattern you'll see constantly — binding a server-side value into an action before passing it to a Client Component:

// app/products/[id]/page.tsx (Server Component)
import { deleteProduct } from '@/actions/products';
 
export default async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const product = await db.products.findUnique({ where: { id } });
 
  // internalCostBasis never appears in the form, never appears in the DOM —
  // but it IS closed over in the bound action
  const deleteWithContext = deleteProduct.bind(null, {
    productId: id,
    internalCostBasis: product.costBasis,
  });
 
  return <DeleteButton action={deleteWithContext} />;
}

When you bind() arguments onto a Server Action, those bound values have to travel to the client somehow — the client needs to send them back when it calls the action, and the client-side reference to deleteWithContext has to encode them. Next.js does this by serialising the closed-over values, encrypting them, and embedding the ciphertext in the reference sent to the client. The client round-trips that ciphertext back on invocation; it can't read it, and it can't tamper with it without invalidating it (decryption fails and the request is rejected).

This is a real, distinct security feature — not the same claim as "action IDs are hashes." The action ID being an unguessable hash is obfuscation of which function is being called. Closure encryption is actual encryption of the values bound into that function — a client genuinely cannot read internalCostBasis out of the wire payload, and genuinely cannot substitute a different value and have it be accepted.

A few things worth knowing about the mechanism:

• The encryption key is generated per build by default. This means the encrypted reference from one deployment is not valid against a different build's key — encrypted closures don't survive a redeploy, which is correct behaviour (you don't want a stale client tab replaying a bound value against new server code).
• In a multi-instance deployment (multiple serverless functions or containers running the same build), all instances need to agree on the same key for encrypted actions to work across requests that don't hit the same instance. Next.js supports pinning this via an environment variable so the key is consistent across instances of the same build — verify the exact environment variable name (NEXT_SERVER_ACTIONS_ENCRYPTION_KEY in recent versions) against your installed version's docs before relying on it in a multi-instance setup.
• This does not mean you should bind secrets you wouldn't otherwise want on the server carelessly — encryption protects the value in transit and at rest in the client reference, but the value still needs to be something the server is fine reconstructing on the next call. Treat it as "safe from client tampering," not "safe to bind anything, however sensitive, without thought."

The practical takeaway: action ID obfuscation and closure encryption solve two different problems. One makes the endpoint hard to guess (weak, cosmetic). The other makes bound arguments unreadable and untamperable (real, cryptographic). Don't rely on either as a substitute for the auth and authorisation checks covered above — they protect different things, and neither one authenticates the caller.

---

Configuring Server Actions — bodySizeLimit and allowedOrigins

Two configuration options live under experimental.serverActions in next.config.ts. Both exist because a Server Action is, mechanically, a POST endpoint — and POST endpoints need the same guardrails you'd put on any API route.

// next.config.ts
import type { NextConfig } from 'next';
 
const nextConfig: NextConfig = {
  experimental: {
    serverActions: {
      bodySizeLimit: '2mb',
      allowedOrigins: ['my-app.com', '*.my-app.com'],
    },
  },
};
 
export default nextConfig;

(These options have lived under experimental across recent Next.js major versions — verify against your installed version whether they've graduated out of the experimental key by the time you read this.)

bodySizeLimit caps the size of the request body a Server Action will accept (default is 1MB). Without it, a Server Action that accepts a FormData upload — or that naively accepts an arbitrary JSON blob — will happily start processing a body far larger than your UI ever intends to send. That's an easy resource-exhaustion vector: an attacker doesn't need to find a bug, just a form field they can stuff with megabytes of payload to burn server memory and CPU on every submission. Setting an explicit, deliberately small limit for actions that don't need large payloads means oversized requests get rejected before your action code even runs.

allowedOrigins restricts which origins are allowed to invoke your Server Actions. Recall from the security section above that Next.js already validates the Origin header against the deployment URL — allowedOrigins extends that allowlist for cases where legitimate requests do come from a different origin than the deployment itself: a reverse proxy or CDN in front of your app that terminates on a different hostname, a staging domain that proxies to production, or a multi-domain setup where the same app is served under several hostnames. Without this configured correctly for a proxied setup, you'd either have to disable origin checking entirely (bad) or watch legitimate proxied requests get rejected (broken). List every origin that's actually allowed to front your app — this is an allowlist, not a wildcard-everything escape hatch.

---

Server Action vs. Route Handler — The Architectural Decision

Both are ways to run server code in response to a client request. They are not interchangeable, and choosing wrong shows up later as a painful migration. The decision comes down to who's calling, and what contract you owe them.

The short version: if the caller is a <form> or a client-side function call from your own React tree, and the interaction is a mutation, reach for a Server Action first — you get progressive enhancement and revalidation almost for free. The moment you need a GET, a versioned contract, a webhook receiver, or a response shape you control precisely (status codes, custom headers, a specific JSON schema for a non-React consumer), that's a sign that what you actually need is a Route Handler, not a Server Action wearing a Route Handler's job.

---

Where We Go From Here

A-7 goes into the advanced routing internals that architects need to build complex UI layouts — parallel routes (multiple slots in a single layout), intercepting routes (modal patterns without losing the underlying page), and route groups and templates. With A-6's understanding of mutations, A-7 explains the routing structures that make multi-panel and overlay UIs possible.

---

Mass Assignment via FormData — The Silent Privilege Escalation

This is one of the most common Server Action security vulnerabilities, and it's actively shipped in production codebases. It looks harmless. It's a complete authentication bypass.

The pattern starts innocuously. You have a Server Action for a profile update form:

'use server';
 
export async function updateProfile(formData: FormData) {
  const session = await auth();
  if (!session) redirect('/login');
 
  // 🚨 DANGEROUS — DO NOT DO THIS
  const updates = Object.fromEntries(formData);
  await db.users.update({
    where: { id: session.user.id },
    data: updates, // passes ALL formData fields to the database
  });
}

The form in your UI has fields for name and bio. But the formData object is constructed from the HTTP request body — an attacker doesn't send your form. They send whatever they want:

curl -X POST https://yourapp.com/_next/action \
  -H "Next-Action: abc123def456" \
  -F "name=Alice" \
  -F "bio=Hello" \
  -F "role=admin" \           # 🚨 not in your form
  -F "emailVerified=true" \   # 🚨 not in your form
  -F "plan=enterprise"        # 🚨 not in your form

Object.fromEntries(formData) produces { name, bio, role, emailVerified, plan }. All of it goes to db.users.update. The attacker is now an admin.

This is a mass assignment attack — the same class of vulnerability that caused the GitHub Rails incident in 2012. The vector is different (FormData instead of JSON body), but the exploit is identical.

The Fix: Explicit Allowlisting with Zod

Never pass Object.fromEntries(formData) directly to a database call. Always extract exactly the fields you intend to update:

'use server';
 
import { z } from 'zod';
import { auth } from '@/lib/auth';
import { db } from '@/lib/db';
 
const updateProfileSchema = z.object({
  name: z.string().min(1).max(100).trim(),
  bio: z.string().max(500).trim().optional(),
});
 
export async function updateProfile(formData: FormData) {
  const session = await auth();
  if (!session) return { error: 'Unauthenticated' };
 
  // Parse ONLY the fields you intend to update
  const result = updateProfileSchema.safeParse({
    name: formData.get('name'),
    bio: formData.get('bio'),
    // role is NOT here — cannot be set through this action
  });
 
  if (!result.success) {
    return { error: result.error.flatten().fieldErrors };
  }
 
  // Only the validated, allowlisted fields reach the database
  await db.users.update({
    where: { id: session.user.id },
    data: result.data, // { name, bio } only
  });
 
  return { success: true };
}

Zod's safeParse does two things simultaneously: validates the values (type, length, format) and acts as an allowlist — only the fields declared in the schema can exist in result.data. Extra fields in formData are silently dropped.

Discriminated Unions for Multi-Step Forms

When a single action handles multiple form types (a wizard form, tabbed settings), the allowlist schema changes based on the form step. Use a discriminated union:

const settingsSchema = z.discriminatedUnion('tab', [
  z.object({
    tab: z.literal('profile'),
    name: z.string().min(1).max(100),
    bio: z.string().max(500).optional(),
  }),
  z.object({
    tab: z.literal('notifications'),
    emailNotifications: z.coerce.boolean(),
    pushNotifications: z.coerce.boolean(),
  }),
  z.object({
    tab: z.literal('security'),
    currentPassword: z.string().min(8),
    newPassword: z.string().min(8),
  }),
]);
 
export async function updateSettings(formData: FormData) {
  const session = await auth();
  if (!session) return { error: 'Unauthenticated' };
 
  const result = settingsSchema.safeParse(Object.fromEntries(formData));
  if (!result.success) return { error: result.error.flatten() };
 
  // result.data is narrowed to the specific tab's schema
  // An attacker sending tab=profile with newPassword=... 
  // gets a validation error — newPassword is not in the profile schema
 
  switch (result.data.tab) {
    case 'profile':
      await updateUserProfile(session.user.id, result.data);
      break;
    case 'notifications':
      await updateNotificationPrefs(session.user.id, result.data);
      break;
    case 'security':
      await updatePassword(session.user.id, result.data);
      break;
  }
}

The discriminated union means you can never accidentally process newPassword in the profile update path — the schema won't include it.

bind() Does Not Protect Against This

A common misconception: using bind() to pass server-side values to an action makes it secure.

// This does NOT prevent mass assignment
const updateProfileWithId = updateProfile.bind(null, session.user.id);

bind() prepends arguments to the action's parameter list. It does not prevent the FormData argument (which comes after the bound arguments) from containing arbitrary fields. The mass assignment vulnerability exists in the FormData, regardless of what was bound.

The only protection is schema-based allowlisting. There is no shortcut.

The Security Audit Pattern

Add this to your code review checklist for every Server Action:

# Find actions that use Object.fromEntries without schema validation
grep -r "Object.fromEntries(formData)" src/actions/
grep -r "Object.fromEntries(prevState" src/actions/
 
# Any match needs a Zod schema between the fromEntries call and the db call

A Server Action that calls db.anything.update(Object.fromEntries(formData)) is a mass assignment vulnerability. No exceptions.

---