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

What a Server Action Actually Is Over the Wire

A Server Action is a function that runs on the server but can be called from the client. The "magic" isn't magic — it's a POST request to a Next.js-owned endpoint.

When you write:

ts
'use server';

export async function createProduct(formData: FormData) {
  await db.products.create({ ... });
  revalidatePath('/products');
}

Next.js at build time assigns this function a stable ID — a hash of the module path and export name. The client doesn't get the function's source code; it gets a reference that resolves to POST /next/action with a body containing the action ID and the serialised arguments.

The actual network request:

POST /_next/action
Content-Type: application/x-www-form-urlencoded
Next-Action: <action-id-hash>

0=formDataEntry1&1=formDataEntry2

Or for actions called with non-FormData arguments (e.g., from an onClick):

POST /_next/action
Content-Type: text/plain;charset=UTF-8
Next-Action: <action-id-hash>

["argument1","argument2"]

The response is a React Flight payload — the same format used for RSC navigation. After the action completes, Next.js re-renders the affected Server Components and streams the updates back to the client in the same response.

The Security Model — What's Actually Protected

Server Actions are not automatically secure. They're a transport mechanism. The misconception "Server Actions are safe because they run on the server" ignores that anything accessible via HTTP is a potential attack surface.

What Next.js provides:

1. Action ID obscurity. The action IDs are hashes — not guessable file paths. This is obfuscation, not security.

2. Built-in CSRF protection. Server Actions are called via POST. Next.js sets SameSite=Strict on its cookies by default (in Auth.js v5 and the built-in cookie handling). A cross-site form POST cannot include the session cookie if it's SameSite=Strict.

3. Origin validation. Next.js checks the Origin header on Server Action requests and rejects requests where the origin doesn't match the deployment URL.

What you must provide:

ts
'use server';

import { auth } from '@/lib/auth';

export async function deleteProduct(productId: string) {
  // ← No auth check = any authenticated (or unauthenticated!) user can call this
  
  // ✅ Always authenticate
  const session = await auth();
  if (!session) throw new Error('Unauthorized');
  
  // ✅ Always authorise — check the user owns this resource
  const product = await db.products.findUnique({
    where: { id: productId, userId: session.user.id }  // scoped to owner
  });
  if (!product) throw new Error('Not found');
  
  await db.products.delete({ where: { id: productId } });
  revalidatePath('/products');
}

Every Server Action that modifies data must:

1. Authenticate (who is calling this?)
2. Authorise (does this user have permission?)
3. Validate inputs (is the data in the expected shape?)

Treat Server Actions exactly like you'd treat an exposed API endpoint — because they are one.

Input Validation with Zod

The most common Server Action vulnerability is accepting malformed or malicious inputs without validation. TypeScript types are compile-time only — they provide no runtime protection.

ts
'use server';

import { z } from 'zod';
import { auth } from '@/lib/auth';

const CreateProductSchema = z.object({
  name: z.string().min(1).max(100),
  price: z.number().positive().max(99999),
  categoryId: z.string().cuid(),
});

export async function createProduct(
  prevState: ActionState,
  formData: FormData
): Promise<ActionState> {
  const session = await auth();
  if (!session) return { error: 'Unauthorized' };
  
  const raw = {
    name: formData.get('name'),
    price: Number(formData.get('price')),
    categoryId: formData.get('categoryId'),
  };
  
  const parsed = CreateProductSchema.safeParse(raw);
  if (!parsed.success) {
    return {
      errors: parsed.error.flatten().fieldErrors,
    };
  }
  
  await db.products.create({
    data: { ...parsed.data, userId: session.user.id }
  });
  
  revalidatePath('/products');
  return { success: true };
}

safeParse (not parse) returns a result object instead of throwing — letting you return structured validation errors to the form rather than an unhandled exception.

Progressive Enhancement — The Mechanical Reality

Progressive enhancement with Server Actions means the form works without JavaScript. This is not just a nice-to-have — it's the reason Server Actions use the same HTML <form> and action mechanism that's existed since 1993.

How it works without JS:

1. Browser submits <form action={createProduct}> as a standard POST request
2. Next.js handles the POST, executes the action, then performs a full page navigation (redirect or reload)
3. The user sees the result — no JS required

How it works with JS:

1. React intercepts the form submit event
2. Serialises the FormData
3. Sends it as an XHR/fetch POST to /_next/action
4. React re-renders the affected components from the Flight response without a page reload

tsx
// This works with AND without JavaScript
export default function CreateProductForm() {
  const [state, formAction, isPending] = useActionState(createProduct, null);
  
  return (
    <form action={formAction}>  {/* real form action for no-JS */}
      <input name="name" required />
      <input name="price" type="number" required />
      {state?.errors?.name && <p>{state.errors.name}</p>}
      <button disabled={isPending}>
        {isPending ? 'Creating...' : 'Create'}
      </button>
    </form>
  );
}

The isPending state only exists when JS is running — in the no-JS case, the button isn't disabled during submission (there's no JS to set it). This is correct progressive enhancement behaviour: core functionality works without JS, enhanced UX requires JS.

Optimistic Updates

For immediate feedback before the server responds:

tsx
'use client';

import { useOptimistic } from 'react';
import { toggleLike } from './actions';

export function LikeButton({ postId, initialLiked, initialCount }: Props) {
  const [optimisticLiked, addOptimisticLike] = useOptimistic(
    { liked: initialLiked, count: initialCount },
    (state, newLiked: boolean) => ({
      liked: newLiked,
      count: state.count + (newLiked ? 1 : -1),
    })
  );

  return (
    <form
      action={async () => {
        addOptimisticLike(!optimisticLiked.liked); // instant UI update
        await toggleLike(postId);                  // server round trip
      }}
    >
      <button type="submit">
        {optimisticLiked.liked ? '❤️' : '🤍'} {optimisticLiked.count}
      </button>
    </form>
  );
}

useOptimistic returns an optimistic state that React reverts to the real state if the action throws. The pattern: update immediately, submit to server, React reconciles after server response. If the server succeeds, the optimistic state becomes the real state. If it fails, React reverts.

Server Action Error Handling Patterns

Errors in Server Actions surface to the client differently depending on how they're thrown:

ts
'use server';

// Pattern 1: Return errors as data (preferred for user-facing errors)
export async function createProduct(
  prevState: ActionState,
  formData: FormData
): Promise<ActionState> {
  try {
    // ...
    return { success: true };
  } catch (error) {
    if (error instanceof DatabaseError) {
      return { error: 'Database unavailable. Try again.' };
    }
    return { error: 'An unexpected error occurred.' };
  }
}

// Pattern 2: Throw for unexpected errors (React Error Boundary catches these)
export async function criticalOperation() {
  const result = await db.criticalOperation();
  if (!result) {
    throw new Error('Critical operation failed'); // Bubbles to error.tsx
  }
  return result;
}

// Pattern 3: Redirect after success (throws internally — this is expected)
export async function createAndRedirect(formData: FormData) {
  const product = await createProduct(formData);
  redirect(`/products/${product.id}`); // redirect() throws a special error
  // Nothing after redirect() executes
}

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:

ts
// 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:

ts
'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.

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:

ts
'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:

bash
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:

ts
'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:

ts
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.

ts
// 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:

bash
# 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.