Skip to Content

Session Management

Create, validate, rotate, and revoke secure server-side sessions with Puzzle Storage and HttpOnly cookies.

@puzzle-ui/session manages opaque server-side sessions on top of a Puzzle Storage adapter. It works independently of an authentication system, which makes it useful for anonymous carts and custom sign-in flows. For account registration, MFA, and a protected dashboard, follow the Auth tutorial instead.

Install

Add Session and choose a storage adapter for your server:

npm install @puzzle-ui/session @puzzle-ui/storage @puzzle-ui/storage-mongodb

This example uses MongoDB. Configure its connection and migrations using the Storage guide; Cloudflare Workers can use the D1 adapter instead.

Initialize the session manager

Create one manager with your server's storage adapter and initialize both the storage collections and manager before handling requests. Session management requires unique constraints, conditional writes, and atomic batches; it fails closed when the adapter cannot provide those capabilities.

import {
  createSessionCookieOptions,
  initializeSessionStorage,
  StorageSessionManager,
} from "@puzzle-ui/session";

const idleTimeoutSeconds = 60 * 60 * 24 * 7;
const sessions = new StorageSessionManager(storage, {
  lifetime: {
    idleTimeoutSeconds,
    absoluteLifetimeSeconds: 60 * 60 * 24 * 30,
  },
  maximumSessionsPerUser: 10,
});

await initializeSessionStorage(storage);
await sessions.initialize();

const cookieOptions = createSessionCookieOptions({
  production: isProduction,
});

storage is the configured adapter from the storage guide. Set isProduction from your server environment; production cookies require HTTPS and are marked Secure.

Create and deliver a session

Create an anonymous session for a visitor, or use kind: "authenticated" and a verified user ID after your sign-in flow succeeds. Only send the opaque token through an HttpOnly cookie; never return it in JSON or store it in browser-accessible storage.

import { serializeSessionCookie } from "@puzzle-ui/session";

const created = await sessions.create({
  kind: "anonymous",
  userId: null,
});

return new Response(null, {
  headers: {
    "Set-Cookie": serializeSessionCookie(
      created.token,
      cookieOptions,
      idleTimeoutSeconds,
    ),
  },
});

Validate a request

Read the token from the incoming cookie and validate it against storage on the server. A missing, expired, or revoked session is unauthenticated.

import { readSessionCookie } from "@puzzle-ui/session";

const token = readSessionCookie(
  request.headers.get("cookie"),
  cookieOptions.name,
);
const session = token ? await sessions.validate(token) : null;

if (!session) {
  return new Response("Sign in required", { status: 401 });
}

For actions that change state, also validate the request origin or use protectStateChangingRequest to apply the package's CSRF protections. Session validation alone does not protect an endpoint from cross-site requests.

Rotate a session

Rotate a session after a privilege change. Rotation atomically revokes the old session and returns a new token to put in the cookie.

import { serializeSessionCookie } from "@puzzle-ui/session";

const rotated = await sessions.rotate({ sessionId: session.id });
return new Response(null, {
  headers: {
    "Set-Cookie": serializeSessionCookie(
      rotated.token,
      cookieOptions,
      idleTimeoutSeconds,
    ),
  },
});

Sign out

Revoke the current session on sign-out, then clear the same cookie.

import { serializeClearedSessionCookie } from "@puzzle-ui/session";

await sessions.revoke(session.id);
return new Response(null, {
  headers: {
    "Set-Cookie": serializeClearedSessionCookie(cookieOptions),
  },
});

Store short-lived session data

Use SessionDataManager for small values such as a cart. Allowlist each namespace and give expiring values a time-to-live.

import { SessionDataManager } from "@puzzle-ui/session";

const data = new SessionDataManager(storage, {
  allowedNamespaces: ["cart"],
});
await data.initialize();

await data.set(
  session.id,
  "cart",
  "items",
  [{ productId: "product-1", quantity: 2 }],
  60 * 60,
);

Session data is not a replacement for durable application records. Keep authorization decisions on the server and use your storage adapter's conformance tests before deploying a custom adapter.

Next steps