nextjs-server-action-safety

Files (1)

• SKILL.md

SKILL.md (first lines)

# Next.js Server Action Safety

> Defends against **OWASP ASI02 (Tool Misuse)** -- a Server Action invoked
> from a wrong client context (logged-out tab, different user's session, an
> attacker's CSRF-shaped payload) re-invokes the server-side mutation with
> the agent's logged-in privileges -- AND **OWASP ASI03 (Identity & Privilege
> Abuse)** -- authn drift where a token-bound mutation runs with stale or
> elevated identity because the action implicitly trusts client-passed
> context instead of re-deriving identity from the server-side session.

**Tradeoff:** Server Actions are a powerful ergonomic for mutations -- they
collapse the form-POST + route-handler + revalidation triad into one
function declaration. The cost: the function is exposed at a public URL
(Next.js compiles each action to a callable endpoint), so it must be
treated like any other public mutation entry point. Without the patterns
below, the convenience leaks into the security model.

---

## Why this matters

Server Actions look like local function calls (`await myAction(formData)`)
but they're actually HTTP POST endpoints generated at build time. Any
authenticated tab can invoke them. Any unauthenticated client can probe
the endpoint URL. Any code in the same Next.js app can import and call
them. The "server-only" annotation (`'use server'`) marks the boundary --
it does NOT add authentication, authorization, validation, or rate
limiting.

A handler that doesn't explicitly re-verify identity, validate input, and
guard against replay is structurally identical to an unauthenticated POST
endpoint. The familiar function-call surface hides this fact from authors
who haven't shipped Next.js mutations in production.

---

## Pattern 1 -- Re-derive identity from server-side session inside every action

Inside the action, ALWAYS read the session from a server-side source
(cookie-backed session store, `auth()` helper, JWT verified against your
own signing secret). Never trust an `actorId` / `userId` / `tenantId`
passed as a form field or function argument -- it's attacker-controllable.

```ts
'use server';

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

const UpdateProfileInput = z.object({
  displayName: z.string().min(1).max(120),
  bio: z.string().max(2000).optional(),
});

export async function updateProfile(formData: FormData) {
  // 1. Re-derive identity. session.userId is the server-side truth.
  const session = await auth();
  if (!session?.userId) {
    throw new Error('unauthenticated');
  }

  // 2. Validate input at the boundary -- the function signature accepts
  //    FormData (any shape); Zod is the runtime contract.
  const parsed = UpdateProfileInput.safeParse({
    displayName: formData.get('displayName'),
    bio: formData.get('bio'),
  });
  if (!parsed.success) {
    throw new Error('invalid input');
  }

  // 3. Scope the mutation to the session-derived identity, not any
  //    client-passed identifier. db.user.update WHERE id = session.userId.
  await db.user.update({
    where: { id: session.userId },
    data: parsed.data,
  });
}
```

A defender reviewing this action can answer in one minute: "Who is this
mutation acting on?" The answer is "the server-derived session user, not
whoever the client says they are."

---

## Pattern 2 -- Validate input with a runtime schema at the action boundary

TypeScript types are compile-time only. The `FormData` argument is the
real runtime contract -- it's whatever the client posted, which may be
arbitrary strings, arrays, or absent fields.

Use Zod / Valibot / a similar runtime validator. Validate at the first
line of the action body. Reject invalid input with a generic error
message (don't echo the invalid value back -- it's potentially attacker-
controlled and may be reflected somewhere).

The validator's schema is also documentation: a defender can read it and
know exactly which fields the action accepts and what the bounds are.

---

## Pattern 3 -- Idempotency for mutations that the client may retry

Server Actions are invoked from forms and from optimistic-UI patterns,
both of which can retry on transient failure (network blip, slow render,
user double-clicks Submit). A mutation that books a flight, charges a
card, or sends a message has to handle the retry without producing two
side effects.

The universal pattern: an idempotency key passed through the action and
checked against a dedupe store. The Stripe-style approach works here too:

```ts
'use server';

export async function chargeOrder(formData: FormData) {
  const session = await auth();

From MILTONADINA/DevOPs, MIT.

More from MILTONADINA/DevOPs