Protecting Endpoints with Sessions

The orders page shows four rows because the component filters the API response to order.userId === me.id. A pentester opens DevTools, reads the endpoint from the network tab, calls /api/orders directly with a colleague's account cookie, and receives every row. The UI hid the data; nothing on the server ever checked it. This is the single most common authorization failure in App Router applications, and it comes from a category error: a route handler is a public URL, not a private method of your page.

Anyone who can construct the request can call it — the browser's address bar, curl, a script on another origin, or a page the user happens to have open. Hiding a button, disabling a form, or only calling the endpoint from an authenticated component changes nothing about that. The rule that follows is worth stating as an invariant: every handler verifies identity and permission itself, before reading a body or touching data. Not "most handlers" — one forgotten export is the incident.

Where should that verification live so it cannot be forgotten? Two candidates exist, and only one is reliable:

Next.js itself warns against treating middleware as the security boundary: middleware is a routing convenience that can be misconfigured, and a matcher that misses a newly added folder silently exposes it. The defensible design uses middleware for convenience (redirect a browser to /login early) and a helper inside the handler for guarantee.

Server Actions deserve the same warning, because teams apply the rule to route handlers and forget them: a "use server" function is a POST endpoint with a generated URL. React fences make accidental cross-site invocation harder, but the function must still authenticate and authorize internally — it is exactly as reachable as a route handler.

Identity is only half the check. Authentication answers "who is calling"; authorization answers "is this caller allowed to touch this resource" — and the second is where ownership bugs live. An authenticated user requesting /api/orders/ord_99 must not learn that a colleague's order id exists; the safe query constrains both conditions at once: db.orders.findFirst({ where: { id, userId: session.sub } }), returning 404 when nothing matches. The unsafe version fetches by id, compares userId in JavaScript, and forgets the comparison on the branch that updates the row three months later. Query-level constraints survive refactors; ad-hoc in-code checks do not.

The shared helper is small, and small is the point:

// lib/session.ts
export async function requireSession(): Promise<Session | NextResponse> {
  const token = (await cookies()).get('session')?.value;
  if (!token) return unauthorized('no_session');
  try {
    return (await jwtVerify(token, secret())).payload as Session;
  } catch {
    return unauthorized('invalid_session');
  }
}

// app/api/orders/route.ts
export async function GET() {
  const auth = await requireSession();
  if (auth instanceof NextResponse) return auth;   // 401 already built
  return NextResponse.json(await listOrders(auth.sub));
}

Returning the error response from the helper — instead of throwing — keeps control flow boring and auditable: every protected handler opens with the same two lines, and a grep for requireSession is a complete audit of which endpoints are protected.

Once a user logs in, something must travel with every request. Two session shapes are standard: an opaque token — a random string the server looks up in Redis or Postgres on every call — and a signed token (JWT) that carries its own claims and needs no lookup. Signed tokens are the common default in Next.js tutorials because verification is pure computation, so this chapter follows that path; the trade-off (revocation is hard) shows up in the third chapter.

Store the JWT in an httpOnly, secure, sameSite=lax cookie so client JavaScript cannot read it and simple cross-site requests do not carry it. Then verify it with a maintained library — jose is the standard choice for Node and Edge runtimes — never with hand-rolled HMAC comparisons:

import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode(process.env.SESSION_SECRET!);

export async function createSession(userId: string) {
  return new SignJWT({ sub: userId, role: 'member' })
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('7d')
    .sign(secret);
}

export async function verifySession(token: string) {
  const { payload } = await jwtVerify(token, secret, {
    algorithms: ['HS256'],   // pin the algorithm — see below
  });
  return payload;
}

Three protections are packed into those four lines, and interviewers ask about each:

Expiry is in the token. exp is checked by jwtVerify; an expired-but-signed token fails verification and yields 401, exactly like a forged one. iat lets you implement sliding sessions: when the remaining lifetime drops below a threshold, issue a fresh token in the response's Set-Cookie while the user is active.

Tampering fails the signature. Change one character of the payload — flip a role claim from member to admin — and verification rejects the token, because the signature no longer matches. Decoding without verifying (jwtDecode) gives you claims an attacker wrote; the difference between decode and verify is the entire security property.

Algorithm pinning stops confusion attacks. A JWT declares its algorithm in the header, and an attacker can rewrite that declaration to none or to HS256 while signing with a public key you never intended as an HMAC secret. Passing algorithms: ['HS256'] refuses every other value before any crypto runs.

The operational side: SESSION_SECRET comes from the environment (process.env — never a committed file, and in Next it is inlined only when prefixed NEXT_PUBLIC_, so an unprefixed secret stays server-side), and rotating it invalidates every session at once, which is the correct lever after a leak. Use at least 32 random bytes — openssl rand -base64 32 — because HMAC keys are only as strong as their entropy.

jose is deliberately the library named here: it is written against the Web Crypto API, so the same verification code runs in the Node runtime and the Edge runtime (middleware, edge route handlers) with no native dependencies. That portability is why the major Next.js auth frameworks build on it.

Where the token travels is its own decision. Browser apps put it in an httpOnly cookie and let the browser attach it to same-origin fetches automatically. Native mobile clients have no cookie jar that fits this model, so they send Authorization: Bearer <token> instead, and your helper should accept that header as a second source. One documented path per client type — the alternative is two half-implemented ones and an endpoint that only works in the browser.

Sliding sessions are a small addition with real UX value: issue a 7-day token, and on every verified request where less than a day remains, sign a fresh token and set it on the response. The user never hits an arbitrary mid-session expiry, while inactivity still ends the session after seven days. Keep the refresh inside the same helper as verification so the two can never drift apart.

A mobile client retries a failed request three times with backoff, because that is what a good client does. Your endpoint returns 401 with an empty body for a dead session, and the client dutifully retries — three more calls that will also fail, all of them logged as "server errors" in the dashboard. The status was right; the contract was missing. Designing auth failures is designing for the client's decision tree.

The two statuses mean different things and must not be interchangeable:

An authenticated non-admin hitting DELETE /api/users/9 gets 403 — retrying cannot help because the credential is fine. A user whose session expired gets 401 — retrying cannot help either, but for the opposite reason: the credential itself must be replaced. The HTTP spec pairs 401 with a WWW-Authenticate header; browsers' fetches do not auto-prompt for your cookie sessions, but including the header keeps the response honest.

The body is where you remove the ambiguity:

function unauthorized(code: string) {
  return NextResponse.json(
    { error: { code, message: 'Session expired — sign in again' } },
    { status: 401, headers: { 'www-authenticate': 'Bearer' } },
  );
}
// usage: unauthorized('session_expired') | unauthorized('no_session')

On the client, that becomes one rule at the fetch layer: a 401 clears local state and routes to /login (with a next parameter for where to return), a 403 renders a permission message, anything else follows the normal error path. Because API routes are not pages, never redirect a programmatic caller with a 307 to /login — it turns a JSON client's failure into HTML garbage; send the status and let the client decide.

The wrapper that implements it once for the whole app:

export async function api(input: string, init?: RequestInit) {
  const res = await fetch(input, { credentials: 'same-origin', ...init });
  if (res.status === 401) { redirectToLogin(); throw new AuthError(); }
  if (res.status === 403) throw new PermissionError(await res.json());
  if (!res.ok) throw new ApiError(res.status, await res.json());
  return res.status === 204 ? null : res.json();
}

Every caller inherits the reauthentication behavior; no component ever writes res.status === 401 by hand, which is how the contract stays true as the codebase grows.

Three hardening details round out the picture. Revocation: an unexpired JWT cannot be killed early without extra machinery — keep a tokenVersion (or session id) on the user row and compare it during verification, so logout and password changes bump the version and every outstanding token fails from the next request on. Brute force: rate-limit the login route per IP and per account — an in-memory counter works for one instance; Redis or an edge KV is required for a fleet, and the login handler itself must never reveal whether the email exists (uniform 401, constant behavior). Credentialed CORS: if another origin calls your API with cookies, the handler must echo that exact origin in access-control-allow-origin with access-control-allow-credentials: true — the wildcard * is rejected by browsers when credentials are on.

Get these three right and the endpoint is safe to expose; forget the verification boundary from chapter one and no amount of status-code craft matters.