@sjolystinnovation/app-kit 0.4.0 → 0.5.0

package/README.md

@@ -5,9 +5,13 @@
 
 > Building blocks for Next.js apps that sign in against a JWT API through next-auth
 
-Several apps sharing one API also share the code around it: the session plumbing, how a failed
-request becomes a message a user can read, and the form controls on the sign in page. This package
-holds that code once, so the apps install it instead of each keeping a copy.
+Several apps sharing one API also share the code around it:
+
+- the session plumbing
+- how a failed request becomes a message a user can read
+- the form controls on the sign in page
+
+This package holds that code once, and each app installs it.
 
 ## Install
 
@@ -70,15 +74,23 @@ const secret = resolveJwtSecret(sessionConfig, process.env);
 
 `(config: SessionConfig) => SessionConfig`
 
-Returns the config unchanged, so TypeScript checks its shape where it is declared rather than at
-every call site. Throws when `draftStoragePrefix` is empty or contains a colon.
+Returns the config unchanged, so TypeScript checks its shape once, where it is declared. Throws
+when `draftStoragePrefix` is empty or contains a colon.
+
+### `requireEnv(name, value)`
+
+`(name: string, value: string | undefined) => string`
+
+Returns `value`, or throws `Missing <name>.` when it is unset or empty. Pass the value read in
+place, such as `process.env.NEXT_PUBLIC_API_URL`, so Next.js can inline a public variable at build
+time.
 
 ### `resolveJwtSecret(config, env)`
 
 `(config: SessionConfig, env: Record<string, string | undefined>) => string`
 
-Reads the secret named by `config.jwtSecretEnvVar`. Throws when that variable is unset or empty, so a
-missing secret fails at startup instead of at the first token verification.
+Reads the secret named by `config.jwtSecretEnvVar`. Throws when that variable is unset or empty,
+with the variable's name in the message.
 
 ```ts
 resolveJwtSecret(sessionConfig, { API_JWT_SECRET: "s3cret" });
@@ -88,8 +100,8 @@ resolveJwtSecret(sessionConfig, {});
 // Error: Missing API_JWT_SECRET. The app verifies API session tokens with it.
 ```
 
-The environment is a parameter rather than a read of `process.env`, which keeps Node types out of a
-package that also runs in the browser.
+The environment is a parameter, so the root entry point needs no Node types and works in browser
+code. `@sjolystinnovation/app-kit/auth` is server only and does load Node types.
 
 ### `formatApiError(error, fallback, statusMessages?)`
 
@@ -110,11 +122,16 @@ body can come from a proxy, such as "Bad Gateway", so the caller's own words win
 A problem details `title` is never shown. ASP.NET Core fills it with generic text, such as "Bad
 Request" or "An error occurred while processing your request.", which says less than `fallback`.
 
-Key `0` in `statusMessages` covers a request that got no response, because of a dropped connection
-or a timeout. Only text on a single line counts as a message. Axios's own message, such as "Request
-failed with status code 500", is never shown, and a cancelled request gives `fallback`. Any other
-`Error` gives its own message. A body requested as an `arraybuffer` or a `blob`, as for a file
-download, is not read, so a failed download gets `statusMessages` or `fallback`.
+A few more rules:
+
+- Key `0` in `statusMessages` covers a request that got no response, because of a dropped
+  connection or a timeout.
+- Only text on a single line counts as a message.
+- Axios's own message, such as "Request failed with status code 500", is never shown.
+- A cancelled request gives `fallback`.
+- Any other `Error` gives its own message.
+- A body requested as an `arraybuffer` or a `blob`, as for a file download, is not read. A failed
+  download gets `statusMessages` or `fallback`.
 
 ```ts
 try {
@@ -124,13 +141,132 @@ try {
 }
 ```
 
+### `createAuthOptions(config, settings)`
+
+From `@sjolystinnovation/app-kit/auth`. Server only. Builds the next-auth options for an app that
+signs in against the API with email and password:
+
+```ts
+// src/lib/authOptions.ts
+import { requireEnv } from "@sjolystinnovation/app-kit";
+import { createAuthOptions } from "@sjolystinnovation/app-kit/auth";
+import { sessionConfig } from "@/lib/session";
+
+export const authOptions = createAuthOptions(sessionConfig, {
+  apiUrl: requireEnv("NEXT_PUBLIC_API_URL", process.env.NEXT_PUBLIC_API_URL),
+  env: process.env,
+});
+```
+
+```ts
+// src/app/api/auth/[...nextauth]/route.ts
+import NextAuth from "next-auth/next";
+import { authOptions } from "@/lib/authOptions";
+
+const handler = NextAuth(authOptions);
+
+export { handler as GET, handler as POST };
+```
+
+| Setting | Type | Description |
+| --- | --- | --- |
+| `apiUrl` | `string` | Base URL of the API. Sign-in posts to `/auth/login` and refresh to `/auth/refresh-token` under it. An empty value throws. |
+| `env` | `Record<string, string \| undefined>` | The server environment, usually `process.env`. It supplies the secret named by `jwtSecretEnvVar`. |
+| `http` | `AxiosInstance` | In place of `apiUrl`, for tests. The client for sign-in and refresh, with its own base URL. |
+
+next-auth reads `NEXTAUTH_SECRET` itself and refuses to run in production without it.
+
+What the options do:
+
+- **Sign-in** posts `{ email, password }` and expects `{ token, refreshToken }`. The access token is
+  verified with the API JWT secret, allowing 60 seconds of clock difference between the server and
+  the API. Its `sub`, `unique_name` and `role` claims become the user's `id`, `name` and `roles`.
+  The log gets the status, error code and message, never the request. A failed sign-in reports one
+  of these in next-auth's `error`:
+  - `SIGN_IN_ERRORS.unavailable` when the API does not answer, or a gateway returns 502, 503 or 504.
+  - `SIGN_IN_ERRORS.invalidCredentials` for every other failure, including an unreadable token and
+    an answer without both tokens.
+- **Refresh** runs ahead of expiry: five minutes before it, or a quarter of the token's lifetime
+  before it when that is shorter. It is never scheduled sooner than 30 seconds out, so a token that
+  lives under 30 seconds is refreshed after it expires. Parallel reads of one session in one server
+  process share a single refresh. Its answer is kept for a minute, because the API rotates the
+  refresh token on every call.
+- **Failures:** a 400 or 401 from the refresh ends the session with `RefreshTokenRejected`. Any
+  other failure keeps it and tries again a minute later. A session without a refresh token ends with
+  `NoRefreshToken` when its refresh falls due.
+- **Cap:** the session ends seven days after sign-in with `AbsoluteSessionExpired`, however recently
+  it was refreshed.
+- **Session:** it carries `user`, `accessToken`, `error`, and `absoluteExpiresAt`, the end of the
+  seven days in milliseconds.
+- **Sign-in page:** `pages.signIn` is `config.loginRoute`.
+
+Two rules keep a refresh from being lost:
+
+- Read the session on the client, through `useSession` or `getSession`. In the App Router,
+  `getServerSession(authOptions)` cannot store a cookie, in server components, route handlers and
+  server actions alike. A refresh there replaces the tokens at the API and loses the new ones. The
+  next refresh then reuses the old token, and the API revokes every session the user has. On the
+  server, read the token with `getToken` from `next-auth/jwt`, which never refreshes.
+- Run the app as one server process. Parallel session reads share one refresh only within a process.
+  Two replicas can refresh the same token at once, with the same result.
+
+The package does not declare these fields on next-auth's types. The app declares them, so its own
+code can read them:
+
+```ts
+// src/types/next-auth.d.ts
+import "next-auth";
+import "next-auth/jwt";
+
+declare module "next-auth" {
+  interface Session {
+    user: { id: string; name: string; email: string; roles: string[] };
+    accessToken: string;
+    error?: string | undefined;
+    absoluteExpiresAt?: number;
+  }
+}
+
+declare module "next-auth/jwt" {
+  interface JWT {
+    accessToken?: string;
+    refreshToken?: string;
+    refreshAt?: number;
+    loginAt?: number;
+    user?: { id: string; name: string; email: string; roles: string[] };
+    error?: string | undefined;
+  }
+}
+```
+
+### `@sjolystinnovation/app-kit/api`
+
+`createApiClient(baseURL)` returns an axios instance for the signed-in API, for code that runs in
+the browser. It reads the session through next-auth's `getSession`, which has no cookies to read on
+the server. An empty `baseURL` throws. Each request carries the session's access token. A 401
+opens the re-sign-in prompt when the session is gone or has a terminal error. It does not sign
+the user out, so the page keeps its state. The error still rejects as usual.
+
+`request(call, fallback, statusMessages?)` runs a call and returns its `data`. A failure becomes an
+`Error` with the message `formatApiError` gives it. A cancelled call rethrows the cancel unchanged:
+
+```ts
+import { requireEnv } from "@sjolystinnovation/app-kit";
+import { createApiClient, request } from "@sjolystinnovation/app-kit/api";
+
+const api = createApiClient(requireEnv("NEXT_PUBLIC_API_URL", process.env.NEXT_PUBLIC_API_URL));
+
+export const getRecipe = (id: number) =>
+  request(() => api.get<Recipe>(`/recipes/${id}`), "Could not load the recipe.");
+```
+
 ### `@sjolystinnovation/app-kit/session`
 
 Decides when a user has to sign in again. Safe to import from server code, such as the next-auth
 callbacks.
 
-The gate reads `session.error`. The app's `jwt` callback sets `token.error`, and its `session`
-callback copies it across:
+The gate reads `session.error`. `createAuthOptions` sets it already. An app with its own next-auth
+options sets `token.error` in its `jwt` callback and copies it across in its `session` callback:
 
 ```ts
 callbacks: {
@@ -162,6 +298,9 @@ declare module "next-auth/jwt" {
 }
 ```
 
+`SIGN_IN_ERRORS` holds the two codes a failed sign-in reports: `InvalidCredentials` and
+`SignInUnavailable`. Map them to the app's own messages.
+
 `SESSION_ERRORS` holds the values the jwt callback puts in `token.error` when the session cannot be
 recovered: `AbsoluteSessionExpired`, `RefreshTokenRejected` and `NoRefreshToken`. `SessionError`
 is their union type. `isTerminalSessionError(error)` is true for those three only, so a transient
@@ -178,19 +317,23 @@ The re-sign-in prompt is a flag outside React, so an axios interceptor can raise
 
 Copies of the package installed side by side share the one flag, as long as their releases use the
 same prompt state format. A release that changes the format says so in its changelog. An app's own
-copy of these functions does not, so an app moving to them moves every import at once: the
-interceptor, the prompt and every gate.
+copy of these functions does not share the flag. So the interceptor, the prompt and every gate all
+import them from this package.
 
 ### `useSessionGate()`
 
 From `@sjolystinnovation/app-kit/session/react`. Tells a protected page whether it may render. It
 reads `useSession`, so it needs a `SessionProvider` above it.
 
-A page that rendered on a healthy session stays rendered when the session gets a terminal error,
-while the session is re-read and while the prompt recovers it, so an open form keeps its values. A
-session that turns signed out with no prompt open blanks the page. A page the user opens
-on a dead session does not render. Use `mayRender` in every gate and layout on the way down, so
-none of them blanks a page that another one kept.
+A page that rendered on a healthy session stays rendered, so an open form keeps its values:
+
+- when the session gets a terminal error
+- while the session is re-read
+- while the prompt recovers it
+
+A session that turns signed out with no prompt open blanks the page. A page the user opens on a
+dead session does not render. Use `mayRender` in every gate and layout on the way down, so none of
+them blanks a page that another one kept.
 
 The hook does not navigate. The gate sends the user to the login page itself, and never while the
 prompt is open. The app passes the login URL in, so an app with a locale in the path can build it
@@ -260,10 +403,13 @@ Mount an edit form once the entity has loaded, with its values already in `value
 the values it first sees under a key as the untouched form, so values that arrive later count as an
 edit and are written over the draft being offered.
 
-It returns `pending`, the stored draft, which the page offers instead of applying. It is read when the
-owner is first known and again whenever the owner or `scope` changes, so it can appear after the form mounts. It
-also returns `dismiss()` to stop offering it, and `clear()` to drop the stored draft after a
-successful save.
+It returns:
+
+- `pending`, the stored draft. The page offers it to the user and does not apply it. It is read
+  when the owner is first known and again whenever the owner or `scope` changes, so it can appear
+  after the form mounts.
+- `dismiss()`, to stop offering it.
+- `clear()`, to drop the stored draft after a successful save.
 
 Drafts are stored under `<draftStoragePrefix>:draft:<owner>:<scope>`. The hook throws when
 `draftStoragePrefix` is empty or contains a colon. A draft older than 7 days is not offered, and is
@@ -281,7 +427,7 @@ import { Alert } from "@sjolystinnovation/app-kit/ui";
 | --- | --- | --- | --- |
 | `variant` | `"error" \| "success" \| "info" \| "warning"` | `"info"` | Colour of the box. |
 | `role` | `"alert" \| "status"` | `"alert"` | Use `status` for text that keeps changing, such as a countdown, so a screen reader does not announce every change. |
-| `className` | `string` | | Classes for placing the alert, such as a margin. Restyle it through the theme variables instead, since whether a clashing class wins depends on the order Tailwind emits them in. |
+| `className` | `string` | | Classes for placing the alert, such as a margin. Restyle it through the theme variables. A clashing class wins or loses by the order Tailwind emits them in. |
 | `children` | `ReactNode` | | Content. |
 
 ### `PasswordInput`
@@ -302,7 +448,7 @@ import { PasswordInput } from "@sjolystinnovation/app-kit/ui";
 | `error` | `string` | | Message shown under the field. It turns the border red, marks the input invalid and is read out with it by screen readers. |
 | `showPasswordLabel` | `string` | `"Show password"` | Accessible name of the toggle while the value is hidden. |
 | `hidePasswordLabel` | `string` | `"Hide password"` | Accessible name of the toggle while the value is visible. |
-| `className` | `string` | | Classes for placing the field, such as a margin. They go on the outer element around the label, input and error. Restyle the field through the theme variables instead. |
+| `className` | `string` | | Classes for placing the field, such as a margin. They go on the outer element around the label, input and error. Restyle the field through the theme variables. |
 
 Pass the two toggle labels in the app's language. The defaults are English.
 
@@ -359,15 +505,17 @@ with it and has to set the ones it uses itself.
 
 ## Requirements
 
-- Next.js 16, React 19, next-auth 4 and axios 1, as peer dependencies the app installs itself.
+- Next.js 16, React 19, next-auth 4.24 or later and axios 1.20 or later, as peer dependencies the
+  app installs itself.
+- `jsonwebtoken` comes with the package. `@sjolystinnovation/app-kit/auth` uses it on the server.
 - For `@sjolystinnovation/app-kit/ui`: Tailwind CSS 4 and `@heroicons/react` 2. The focus ring uses
   the theme's `primary` colour unless `--color-input-focus-ring` is set.
 - TypeScript with `"moduleResolution": "bundler"`. Relative imports here are extensionless, which
   `node16` and `nodenext` reject.
 
-There is no build output. Shipping source is what keeps the `"use client"` directives intact, since
-bundlers strip or relocate them. The consumer therefore compiles this source with its own
-`compilerOptions`, and `skipLibCheck` does not exempt it.
+There is no build output. Bundlers strip or relocate `"use client"` directives, and shipping source
+keeps them intact. The consumer compiles this source with its own `compilerOptions`, and
+`skipLibCheck` does not exempt it.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Building blocks for Next.js apps that sign in against a JWT API through next-auth",
   "license": "Apache-2.0",
   "author": "Sjølyst Innovation AS",
@@ -19,6 +19,8 @@
     "./session": "./src/session/index.ts",
     "./session/react": "./src/session/react/index.ts",
     "./forms": "./src/forms/index.ts",
+    "./auth": "./src/auth/index.ts",
+    "./api": "./src/api/index.ts",
     "./ui": "./src/ui/index.ts",
     "./styles.css": "./src/styles.css"
   },
@@ -35,7 +37,7 @@
   },
   "peerDependencies": {
     "@heroicons/react": "^2",
-    "axios": "^1",
+    "axios": "^1.20.0",
     "next": "^16",
     "next-auth": "^4.24",
     "react": "^19",
@@ -49,7 +51,7 @@
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "@vitejs/plugin-react": "^6.1.2",
-    "axios": "^1.19.0",
+    "axios": "^1.20.0",
     "jsdom": "^30.1.1",
     "next": "^16.3.6",
     "next-auth": "^4.24.15",
@@ -65,5 +67,9 @@
     "jwt",
     "react",
     "tailwindcss"
-  ]
+  ],
+  "dependencies": {
+    "@types/jsonwebtoken": "^9.0.8",
+    "jsonwebtoken": "^9.0.2"
+  }
 }

package/src/api/createApiClient.ts

@@ -0,0 +1,43 @@
+import axios, { type AxiosInstance } from "axios";
+import { getSession } from "next-auth/react";
+import { isTerminalSessionError, openSessionPrompt } from "../session/expiry";
+
+/**
+ * An axios instance for the signed-in API, for browser code. Each request carries the session's
+ * access token. A 401 on a dead session opens the re-sign-in prompt, so the page keeps its state.
+ */
+export function createApiClient(baseURL: string): AxiosInstance {
+  if (!baseURL) {
+    throw new Error("createApiClient needs the API base URL, and baseURL is empty.");
+  }
+  // allowAbsoluteUrls: false joins every URL onto baseURL, so the token only goes to the API.
+  const client = axios.create({ baseURL, allowAbsoluteUrls: false });
+
+  // broadcast: false, so a request does not make every other open tab refetch its session.
+  client.interceptors.request.use(async (request) => {
+    const session = await getSession({ broadcast: false });
+    const accessToken = (session as { accessToken?: string } | null)?.accessToken;
+    if (accessToken) {
+      request.headers.Authorization = `Bearer ${accessToken}`;
+    }
+    return request;
+  });
+
+  client.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      if (axios.isAxiosError(error) && error.response?.status === 401) {
+        const session = await getSession({ broadcast: false });
+        // No session also opens the prompt. The cookie is gone, or the session fetch failed. Either
+        // way there is no error field to read, and signing in again recovers both.
+        const sessionError = (session as { error?: string } | null)?.error;
+        if (!session || isTerminalSessionError(sessionError)) {
+          openSessionPrompt();
+        }
+      }
+      return Promise.reject(error);
+    },
+  );
+
+  return client;
+}

package/src/api/index.ts

@@ -0,0 +1,2 @@
+export { createApiClient } from "./createApiClient";
+export { request } from "./request";

package/src/api/request.ts

@@ -0,0 +1,22 @@
+import axios from "axios";
+import { formatApiError, type StatusMessages } from "../errors";
+
+/**
+ * Runs an API call and returns its data. A failure throws an `Error` with a message for the user,
+ * from `formatApiError`. A cancelled call rethrows the cancel as it is, so the caller can ignore it.
+ */
+export async function request<T>(
+  call: () => Promise<{ data: T }>,
+  fallback: string,
+  statusMessages?: StatusMessages,
+): Promise<T> {
+  try {
+    const response = await call();
+    return response.data;
+  } catch (error: unknown) {
+    if (axios.isCancel(error)) throw error;
+    // No cause. Errors get logged, and the axios error carries the access token and request body.
+    // eslint-disable-next-line preserve-caught-error
+    throw new Error(formatApiError(error, fallback, statusMessages));
+  }
+}

package/src/auth/createAuthOptions.ts

@@ -0,0 +1,313 @@
+import axios, { type AxiosInstance } from "axios";
+import jwt from "jsonwebtoken";
+import type { NextAuthOptions, Session, User } from "next-auth";
+import CredentialsProvider from "next-auth/providers/credentials";
+import type { JWT } from "next-auth/jwt";
+import { resolveJwtSecret, type SessionConfig } from "../config";
+import { SESSION_ERRORS, SIGN_IN_ERRORS, isTerminalSessionError } from "../session/expiry";
+
+/** The signed-in user, as the session carries it. */
+export interface SessionUser {
+  id: string;
+  name: string;
+  email: string;
+  roles: string[];
+}
+
+interface TokenPair {
+  token: string;
+  refreshToken: string;
+}
+
+interface ApiClaims {
+  sub: string;
+  unique_name: string;
+  role?: string | string[];
+  exp: number;
+  iat: number;
+}
+
+// The fields this module stores in next-auth's JWT. An intersection still compiles when the app
+// declares the same fields itself.
+type AppToken = JWT & {
+  accessToken?: string;
+  refreshToken?: string;
+  refreshAt?: number;
+  loginAt?: number;
+  user?: SessionUser;
+  error?: string;
+};
+
+interface AuthorizedUser extends User {
+  roles: string[];
+  accessToken: string;
+  refreshToken: string;
+}
+
+export type AuthOptionsSettings = {
+  /** The server environment, usually `process.env`. It holds the API JWT secret. */
+  env: Record<string, string | undefined>;
+} & (
+  | {
+      /** Base URL of the API, such as `https://api.example.com/api`. */
+      apiUrl: string;
+      http?: never;
+    }
+  | {
+      /** An HTTP client with its own base URL, for tests. */
+      http: AxiosInstance;
+      apiUrl?: never;
+    }
+);
+
+const ABSOLUTE_SESSION_MAX_AGE = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+// Refresh ahead of expiry, so the token is still fresh when the user saves.
+const MAX_REFRESH_SKEW_MS = 5 * 60 * 1000;
+
+// The soonest a refresh can be due. The floor stops a short-lived token from refreshing on every
+// session read.
+const MIN_REFRESH_GAP_MS = 30 * 1000;
+
+// How long a refresh result is remembered. It is also the wait before a failed refresh is retried.
+const REMEMBER_ROTATION_MS = 60 * 1000;
+
+// How far this server's clock may differ from the API's when a token's times are checked.
+const CLOCK_TOLERANCE_S = 60;
+
+// Sign-in and session reads wait for the API, so a hung connection must not hold them forever.
+const API_TIMEOUT_MS = 10_000;
+
+function rolesOf(claims: ApiClaims): string[] {
+  const raw = claims.role;
+  return Array.isArray(raw) ? raw : raw ? [raw] : [];
+}
+
+// The skew is capped at a quarter of the token's lifetime, so a short-lived token is not refreshed
+// on every read. A token without a lifetime gets the floor.
+function nextRefreshAt(claims: ApiClaims): number {
+  const expiresAt = claims.exp * 1000;
+  const lifetimeMs = Math.max(0, (claims.exp - claims.iat) * 1000);
+  const refreshAt = expiresAt - Math.min(MAX_REFRESH_SKEW_MS, lifetimeMs / 4);
+  if (!Number.isFinite(refreshAt)) return Date.now() + MIN_REFRESH_GAP_MS;
+  return Math.max(Date.now() + MIN_REFRESH_GAP_MS, refreshAt);
+}
+
+// No answer, or a gateway that could not reach the API. A plain 500 is left out, because the API
+// may fail after it has checked the password.
+function apiUnavailable(error: unknown): boolean {
+  if (!axios.isAxiosError(error)) return false;
+  const status = error.response?.status;
+  return status === undefined || status === 502 || status === 503 || status === 504;
+}
+
+// What a log line may contain. The error itself carries the request, which holds the password or
+// tokens.
+function failureShape(error: unknown) {
+  return {
+    status: axios.isAxiosError(error) ? error.response?.status : undefined,
+    code: axios.isAxiosError(error) ? error.code : undefined,
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+/**
+ * next-auth options for email and password sign-in against the API. The API issues a short-lived
+ * access token and a refresh token that changes on every refresh. The session refreshes ahead of
+ * expiry, rides out temporary API failures, and ends seven days after sign-in.
+ */
+export function createAuthOptions(config: SessionConfig, settings: AuthOptionsSettings): NextAuthOptions {
+  const { env } = settings;
+  if (settings.http === undefined && !settings.apiUrl) {
+    throw new Error("createAuthOptions needs the API base URL, and apiUrl is empty.");
+  }
+  const http = settings.http ?? axios.create({ baseURL: settings.apiUrl, allowAbsoluteUrls: false });
+
+  const readClaims = (token: string) =>
+    jwt.verify(token, resolveJwtSecret(config, env), {
+      clockTolerance: CLOCK_TOLERANCE_S,
+    }) as unknown as ApiClaims;
+
+  async function postTokens(path: string, body: object): Promise<TokenPair> {
+    const response = await http.post<TokenPair>(path, body, { timeout: API_TIMEOUT_MS });
+    return response.data;
+  }
+
+  // Parallel session reads carry the same refresh token. The API accepts each refresh token once.
+  // It treats a second use as replay and revokes every session the user has. So all reads of one
+  // token share one refresh. The result is kept for a while, because a slow read can arrive with
+  // the old token after the refresh is done.
+  //
+  // The map lives in one server process. Replicas do not share it.
+  const inFlight = new Map<string, Promise<AppToken>>();
+
+  function refreshOnce(token: AppToken): Promise<AppToken> {
+    const key = token.refreshToken as string;
+    const existing = inFlight.get(key);
+    if (existing) return existing;
+
+    const pending = rotate(token);
+    inFlight.set(key, pending);
+    // The minute counts from the answer, so a slow refresh is remembered as long as a fast one.
+    void pending.then(() => {
+      // unref, so the timer cannot keep a serverless invocation alive.
+      const expiry = setTimeout(() => inFlight.delete(key), REMEMBER_ROTATION_MS) as unknown as {
+        unref?: () => void;
+      };
+      expiry.unref?.();
+    });
+    return pending;
+  }
+
+  async function rotate(token: AppToken): Promise<AppToken> {
+    let refreshed: TokenPair;
+    try {
+      refreshed = await postTokens(
+        "/auth/refresh-token",
+        { token: token.accessToken, refreshToken: token.refreshToken },
+      );
+    } catch (error) {
+      // The API refused the token pair: a bad access token, or a refresh token that is unknown,
+      // expired or already used. Only this ends the session.
+      const status = axios.isAxiosError(error) ? error.response?.status : undefined;
+      if (status === 400 || status === 401) {
+        return { ...token, error: SESSION_ERRORS.refreshRejected };
+      }
+      // A network error or an API restart keeps the session. A later read tries again.
+      console.error("Refresh token request failed, keeping the session", failureShape(error));
+      return { ...token, refreshAt: Date.now() + REMEMBER_ROTATION_MS };
+    }
+
+    // A success without tokens is treated as a temporary failure, and the session keeps its own.
+    if (!refreshed?.token || !refreshed.refreshToken) {
+      console.error("Refresh token response had no tokens, keeping the session");
+      return { ...token, refreshAt: Date.now() + REMEMBER_ROTATION_MS };
+    }
+
+    // The API has already replaced the old tokens. Keep the new ones whatever happens below,
+    // because the old refresh token now counts as replay.
+    const next: AppToken = {
+      ...token,
+      accessToken: refreshed.token,
+      refreshToken: refreshed.refreshToken,
+    };
+    delete next.error;
+
+    try {
+      const claims = readClaims(refreshed.token);
+      next.refreshAt = nextRefreshAt(claims);
+      next.user = { ...(token.user as SessionUser), roles: rolesOf(claims) };
+    } catch (error) {
+      // The token is unreadable, for example after a secret change. Retry soon with the new
+      // refresh token.
+      console.error("Could not read the refreshed access token, retrying shortly", failureShape(error));
+      next.refreshAt = Date.now() + REMEMBER_ROTATION_MS;
+    }
+
+    return next;
+  }
+
+  return {
+    providers: [
+      CredentialsProvider({
+        name: "Credentials",
+        credentials: {
+          email: { label: "Email", type: "email" },
+          password: { label: "Password", type: "password" },
+        },
+        async authorize(credentials) {
+          if (!credentials) {
+            throw new Error("Credentials are missing");
+          }
+          try {
+            const tokens = await postTokens(
+              "/auth/login",
+              { email: credentials.email, password: credentials.password },
+            );
+            if (!tokens?.token || !tokens.refreshToken) {
+              throw new Error("Login response had no tokens");
+            }
+            const claims = readClaims(tokens.token);
+            const user: AuthorizedUser = {
+              id: claims.sub,
+              name: claims.unique_name,
+              email: credentials.email,
+              roles: rolesOf(claims),
+              accessToken: tokens.token,
+              refreshToken: tokens.refreshToken,
+            };
+            return user;
+          } catch (error) {
+            console.error("Sign-in failed", failureShape(error));
+            // No cause: next-auth logs this error, and the cause carries the password.
+            // eslint-disable-next-line preserve-caught-error
+            throw new Error(
+              apiUnavailable(error) ? SIGN_IN_ERRORS.unavailable : SIGN_IN_ERRORS.invalidCredentials,
+            );
+          }
+        },
+      }),
+    ],
+    pages: {
+      signIn: config.loginRoute,
+    },
+    session: {
+      maxAge: ABSOLUTE_SESSION_MAX_AGE / 1000,
+    },
+    callbacks: {
+      async jwt({ token: current, user }) {
+        let token = current as AppToken;
+        if (user) {
+          const signedIn = user as AuthorizedUser;
+          const claims = readClaims(signedIn.accessToken);
+          token = {
+            ...token,
+            accessToken: signedIn.accessToken,
+            refreshToken: signedIn.refreshToken,
+            refreshAt: nextRefreshAt(claims),
+            loginAt: Date.now(),
+            user: {
+              id: signedIn.id,
+              name: signedIn.name ?? "",
+              email: signedIn.email ?? "",
+              roles: signedIn.roles,
+            },
+          };
+          delete token.error;
+        }
+
+        // A session without a sign-in time counts as expired.
+        if (token.loginAt === undefined || Date.now() - token.loginAt > ABSOLUTE_SESSION_MAX_AGE) {
+          return { ...token, error: SESSION_ERRORS.absoluteExpiry };
+        }
+
+        // Only a new sign-in recovers a terminal session, so the API is not asked again.
+        if (isTerminalSessionError(token.error)) {
+          return token;
+        }
+
+        if (token.refreshAt && Date.now() < token.refreshAt) {
+          return token;
+        }
+
+        if (!token.refreshToken) {
+          return { ...token, error: SESSION_ERRORS.noRefreshToken };
+        }
+
+        return refreshOnce(token);
+      },
+      async session({ session, token: current }) {
+        const token = current as AppToken;
+        // Cast, so it compiles against the app's own Session declaration.
+        return {
+          ...session,
+          user: token.user,
+          accessToken: token.accessToken,
+          error: token.error,
+          // Lets the UI warn before the seven days run out.
+          absoluteExpiresAt: token.loginAt ? token.loginAt + ABSOLUTE_SESSION_MAX_AGE : undefined,
+        } as Session;
+      },
+    },
+  };
+}

package/src/auth/index.ts

@@ -0,0 +1,2 @@
+export { createAuthOptions } from "./createAuthOptions";
+export type { AuthOptionsSettings, SessionUser } from "./createAuthOptions";

package/src/config.ts

@@ -1,6 +1,6 @@
 /**
  * The values that differ between the apps using this package. Everything else in the session layer
- * is identical across them, so it stays hardcoded rather than becoming an option.
+ * is the same in every app, so it is hardcoded.
  */
 export interface SessionConfig {
   /**
@@ -10,7 +10,7 @@ export interface SessionConfig {
   jwtSecretEnvVar: string;
   /**
    * Where an expired or rejected session sends the browser. An app with a locale prefix uses
-   * something like "/en/login", one without uses "/login".
+   * something like "/en/login". An app without one uses "/login".
    */
   loginRoute: string;
   /**
@@ -23,7 +23,7 @@ export interface SessionConfig {
 
 /**
  * Declares an app's config as a typed constant. Throws when `draftStoragePrefix` is not a bare name,
- * so a bad value fails when the app starts rather than when a form first opens.
+ * so a bad value fails at app start, before any form opens.
  */
 export function defineSessionConfig(config: SessionConfig): SessionConfig {
   draftPrefix(config);
@@ -31,8 +31,8 @@ export function defineSessionConfig(config: SessionConfig): SessionConfig {
 }
 
 /**
- * The key prefix for form drafts. A colon or an empty name builds keys such as "app:draft::draft:",
- * which match none of the drafts already saved under "app:draft:".
+ * The key prefix for form drafts. Throws on a colon or an empty name. Those build keys such as
+ * "app:draft::draft:", which match no draft saved under "app:draft:".
  */
 export function draftPrefix(config: Pick<SessionConfig, "draftStoragePrefix">): string {
   const name = config.draftStoragePrefix;
@@ -43,11 +43,22 @@ export function draftPrefix(config: Pick<SessionConfig, "draftStoragePrefix">):
 }
 
 /**
- * Reads the API JWT secret named by the config. Throws rather than returning undefined, because a
- * missing secret silently breaks token verification at runtime instead of at boot.
+ * Returns `value`, or throws when it is unset or empty. Pass `process.env.NAME` directly, so Next.js
+ * can inline public variables at build time.
+ */
+export function requireEnv(name: string, value: string | undefined): string {
+  if (!value) {
+    throw new Error(`Missing ${name}.`);
+  }
+  return value;
+}
+
+/**
+ * Reads the API JWT secret named by the config. Throws when it is missing, with a message that names
+ * the variable.
  *
- * The caller passes the environment, usually `process.env`. Reading it here would put
- * `@types/node` in the type surface of a package that ends up in a browser bundle.
+ * The caller passes the environment, usually `process.env`, so this entry point needs no Node
+ * types and stays safe to import in browser code.
  */
 export function resolveJwtSecret(
   config: SessionConfig,

package/src/errors.ts

@@ -9,7 +9,7 @@ export type StatusMessages = Partial<Record<number, string>>;
 
 /**
  * Axios codes for a request that never got a response from the network. A browser reports every
- * network failure as ERR_NETWORK. On the server, Node reports the cause instead.
+ * network failure as ERR_NETWORK. On the server, Node reports the specific cause.
  */
 const NO_RESPONSE_CODES = new Set([
   "ERR_NETWORK",
@@ -26,15 +26,19 @@ const NO_RESPONSE_CODES = new Set([
 /**
  * Turns a failed request into one line a user can read.
  *
- * On a 4xx response the body's own message comes first: a text body, then `message`, the first
- * validation error and `detail` from a JSON body. After that come `statusMessages` for the status
- * and `fallback`. On a 5xx the caller's status message comes first, because the body may be a
- * proxy's "Bad Gateway" rather than the API's own words. A problem details `title` is never used:
- * ASP.NET Core fills it with generic text such as "Bad Request", which says less than `fallback`.
+ * On a 4xx response the order is:
+ * 1. The body's own message: a text body, or `message`, the first validation error or `detail` from
+ *    a JSON body.
+ * 2. `statusMessages` for the status.
+ * 3. `fallback`.
+ *
+ * On a 5xx the caller's status message comes first, because the body may come from a proxy, such
+ * as "Bad Gateway". A problem details `title` is never used. ASP.NET Core fills it with generic text
+ * such as "Bad Request", which says less than `fallback`.
  *
  * Only single line text counts as a message. Axios's own message, such as "Request failed with
- * status code 500", is never shown, and a cancelled request gives `fallback`. Any other `Error`
- * gives its message.
+ * status code 500", is never shown. A cancelled request gives `fallback`. Any other `Error` gives
+ * its message.
  */
 export function formatApiError(
   error: unknown,

package/src/forms/useFormDraft.ts

@@ -5,9 +5,8 @@ import { draftPrefix, type SessionConfig } from "../config";
 
 const WRITE_DELAY_MS = 500;
 
-// How long a draft is offered. Long enough to outlive an expired session or a closed tab, short
-// enough that week-old work is not offered as if it were current. An expired draft is removed when
-// its form next reads it.
+// How long a draft is offered. Long enough to outlive an expired session or a closed tab. Short
+// enough that stale work is not offered as current. A form removes its expired draft on next read.
 const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
 interface Envelope<T> {
@@ -35,10 +34,10 @@ function read<T>(storageKey: string): T | null {
 
 export interface FormDraftOptions<T> {
   /**
-   * The signed-in user's id. A browser profile can be shared, so the draft is stored per user.
-   * Without that, the next person to sign in is offered the previous one's work. The last known
-   * owner is kept, because a lost cookie reports nobody and that is the moment the draft matters
-   * most. Nothing is stored until an owner is known.
+   * The signed-in user's id. A browser profile can be shared, so drafts are stored per user. That
+   * way nobody is offered another user's work. The hook keeps the last known owner. A lost cookie
+   * reports nobody, and that is when the draft matters most. Nothing is stored until an owner is
+   * known.
    */
   owner: string | undefined;
   /** Identifies the form and the entity it edits, for example `recipe:new` or `recipe:42`. */
@@ -63,16 +62,15 @@ export interface FormDraft<T> {
  * Keeps a form's values in localStorage so a sign-out, reload or closed tab does not lose them.
  * Values are written half a second after the last change, so only that last half second is at risk.
  *
- * A draft found at mount is offered for restore rather than applied, so an edit form never silently
- * overwrites what the API returned. Saving starts immediately either way. The offer is held in
- * memory, so the newest work is always the thing in storage.
+ * A draft found at mount is offered for restore, not applied. So an edit form never silently
+ * overwrites what the API returned. Saving starts at once, whether or not the offer is answered.
+ * The offer is held in memory, so storage always holds the newest work.
  */
 export function useFormDraft<T>(
   config: Pick<SessionConfig, "draftStoragePrefix">,
   { owner, scope, value }: FormDraftOptions<T>,
 ): FormDraft<T> {
-  // Adjusted during render rather than in an effect, which is the supported way to derive state
-  // from changing inputs.
+  // Set during render, which is React's supported way to derive state from changing inputs.
   const [lastOwner, setLastOwner] = useState<string | undefined>(undefined);
   if (owner && owner !== lastOwner) setLastOwner(owner);
 
@@ -86,21 +84,21 @@ export function useFormDraft<T>(
   const writeTimer = useRef<number | null>(null);
 
   useEffect(() => {
-    // Re-base on a key change too. The values on screen belong to the old key, and writing them
-    // under the new one would put this form's work in another form's draft.
+    // Re-base on a key change too. The values on screen belong to the old key and must not land
+    // in the new key's draft.
     untouched.current = json;
-    // Reading the store is an external-system read, which is what an effect is for.
+    // Reading storage is an external-system read, which belongs in an effect.
     // eslint-disable-next-line react-hooks/set-state-in-effect
     setPending(key == null ? null : read<T>(key));
-    // Keyed on the draft key alone on purpose. Re-reading whenever the values change would
-    // re-offer a draft the user has already answered.
+    // Runs on a key change only. Re-reading on every value change would re-offer a draft the user
+    // has already answered.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [key]);
 
   useEffect(() => {
     if (key == null) return;
-    // Write only once the form differs from how it opened. Writing the pristine form would
-    // overwrite the draft being offered before the user has answered.
+    // Write only once the form differs from how it opened, so the pristine form never overwrites
+    // a draft that is still on offer.
     if (json === untouched.current) return;
     const timer = window.setTimeout(() => {
       try {
@@ -116,14 +114,14 @@ export function useFormDraft<T>(
 
   const clear = useCallback(() => {
     if (key == null) return;
-    // Cancel a write that is already scheduled, and treat the current values as the new baseline.
-    // Otherwise a save is followed by the draft being written back.
+    // Cancel any scheduled write and make the current values the baseline, so a save is never
+    // followed by a fresh draft write.
     if (writeTimer.current != null) window.clearTimeout(writeTimer.current);
     untouched.current = json;
     try {
       window.localStorage.removeItem(key);
     } catch {
-      // The draft is a convenience, not state anything depends on.
+      // The draft is a convenience. Nothing depends on it.
     }
   }, [key, json]);
 

package/src/index.ts

@@ -1,4 +1,4 @@
-export { defineSessionConfig, resolveJwtSecret } from "./config";
+export { defineSessionConfig, requireEnv, resolveJwtSecret } from "./config";
 export type { SessionConfig } from "./config";
 export { formatApiError } from "./errors";
 export type { StatusMessages } from "./errors";

package/src/session/expiry.ts

@@ -9,6 +9,17 @@ export const SESSION_ERRORS = {
   noRefreshToken: "NoRefreshToken",
 } as const;
 
+/**
+ * The codes a failed sign-in reports in next-auth's `error`. Wrong credentials and every API answer
+ * look the same, so the message never hints that a password was right. Only an API that does not
+ * answer, or a gateway error, reports `unavailable`. That depends on the server, never on the
+ * password.
+ */
+export const SIGN_IN_ERRORS = {
+  invalidCredentials: "InvalidCredentials",
+  unavailable: "SignInUnavailable",
+} as const;
+
 /** One of the values in `SESSION_ERRORS`. */
 export type SessionError = (typeof SESSION_ERRORS)[keyof typeof SESSION_ERRORS];
 
@@ -19,13 +30,13 @@ export function isTerminalSessionError(error: string | undefined): boolean {
   return error != null && TERMINAL.has(error);
 }
 
-// Whether the re-sign-in prompt is showing. It lives outside React because the axios interceptor
-// that raises it is a plain module, and because the page gate has to know: it must not redirect to
-// the login page while the prompt is recovering the session in place.
+// Whether the re-sign-in prompt is showing. It lives outside React for two reasons:
+// 1. The axios interceptor that raises it is a plain module.
+// 2. The page gate reads it, so it never redirects to login while the prompt recovers the session.
 //
-// Kept on globalThis under a registered symbol, so two copies of this module, such as two installed
-// versions of the package, still share one prompt. Separate state would let a prompt raised through
-// one copy go unseen by a gate reading the other, and the gate would redirect away from the form.
+// It sits on globalThis under a registered symbol, so two copies of this module share one prompt.
+// Two installed versions of the package are one example. A gate reading one copy then sees a
+// prompt raised through the other and keeps the form on screen.
 interface PromptState {
   open: boolean;
   listeners: Set<() => void>;

package/src/session/index.ts

@@ -1,5 +1,6 @@
 export {
   SESSION_ERRORS,
+  SIGN_IN_ERRORS,
   closeSessionPrompt,
   getSessionPromptOpen,
   isTerminalSessionError,

package/src/session/react/useSessionGate.ts

@@ -8,9 +8,8 @@ import { getSessionPromptOpen, isTerminalSessionError, subscribeSessionPrompt }
 /**
  * Whether a protected page may render, and whether it must stay rendered.
  *
- * Every gate on the way down should use this, so they agree. A nested layout that decides on its
- * own to blank the page undoes the in-place recovery the re-sign-in prompt exists for, and the user
- * loses the form anyway.
+ * Every gate on the way down should use this, so they all agree. A nested layout that decides on
+ * its own can blank the page. That undoes the in-place recovery the re-sign-in prompt exists for.
  */
 export function useSessionGate() {
   const { data: session, status } = useSession();
@@ -26,11 +25,10 @@ export function useSessionGate() {
   const error = (session as { error?: string } | null)?.error;
   const usable = status === "authenticated" && !isTerminalSessionError(error);
 
-  // Which page last rendered on a healthy session. Keyed by path, so each page starts the check
-  // again and a session that died on the previous page cannot carry a stale pass into a fresh form.
-  // Adjusted during render rather than in an effect, which is the supported way to derive state
-  // from changing inputs.
-  // Undefined until then rather than null, because usePathname can itself return null.
+  // The path that last rendered on a healthy session. Keyed by path, so each page checks again. A
+  // session that died on the previous page cannot pass a fresh form.
+  // Set during render, which is React's supported way to derive state from changing inputs.
+  // It starts as undefined, not null, because usePathname can return null.
   const [usableAt, setUsableAt] = useState<string | null | undefined>(undefined);
   if (usable && usableAt !== pathname) setUsableAt(pathname);
   const wasUsable = usableAt === pathname;

package/src/styles.css

@@ -2,9 +2,9 @@
 @source ".";
 
 /*
- * Design tokens for the components. Each default matches a stock Tailwind value, so an app that
- * sets none of them gets the look below. Set any of them in the app's own @theme to restyle, or in
- * a selector such as .dark for a scoped theme.
+ * Design tokens for the components. The defaults are stock Tailwind values, except the focus ring,
+ * which uses the theme's --color-primary. Set a token in the app's own @theme to restyle, or in a
+ * selector such as .dark for a scoped theme.
  */
 @theme default {
   --radius-alert: var(--radius-lg);

package/src/ui/Alert.tsx

@@ -9,9 +9,8 @@ export interface AlertProps {
    */
   role?: "alert" | "status";
   /**
-   * Classes for placing the alert, such as a margin. Restyle it through the theme variables
-   * instead: whether a class that clashes with the alert's own wins depends on the order Tailwind
-   * emits them in.
+   * Classes for placing the alert, such as a margin. Restyle it through the theme variables. A
+   * class that clashes with the alert's own wins or loses by the order Tailwind emits them in.
    */
   className?: string;
   children: ReactNode;

package/src/ui/PasswordInput.tsx

@@ -14,7 +14,7 @@ export interface PasswordInputProps extends Omit<InputHTMLAttributes<HTMLInputEl
   hidePasswordLabel?: string;
   /**
    * Classes for placing the field, such as a margin. They go on the outer element, which holds the
-   * label, the input and the error. Restyle the field through the theme variables instead.
+   * label, the input and the error. Restyle the field through the theme variables.
    */
   className?: string;
 }
@@ -30,11 +30,10 @@ export function PasswordInput({
   ...props
 }: PasswordInputProps) {
   const [visible, setVisible] = useState(false);
-  // Fall back to a generated id so the label is always tied to its own control. Not the name: two
-  // fields named "password" on one page, such as sign in next to sign up, would share an id.
+  // A generated id ties the label to its own control, even when two fields on a page share a name.
   const generated = useId();
   const inputId = id ?? generated;
-  // Built from useId rather than the name, since an id list in aria-describedby splits on spaces.
+  // From useId, which has no spaces. aria-describedby splits its ids on spaces.
   const errorId = `${generated}-error`;
 
   return (