@sjolystinnovation/app-kit 0.5.0 → 0.7.0

package/README.md

@@ -28,8 +28,8 @@ const nextConfig: NextConfig = {
 };
 ```
 
-The components in `@sjolystinnovation/app-kit/ui` are styled with Tailwind CSS. Import the
-package's stylesheet after Tailwind:
+The components in `@sjolystinnovation/app-kit/ui` and `session/react` are styled with Tailwind CSS.
+Import the package's stylesheet after Tailwind:
 
 ```css
 /* src/app/globals.css */
@@ -260,40 +260,108 @@ export const getRecipe = (id: number) =>
   request(() => api.get<Recipe>(`/recipes/${id}`), "Could not load the recipe.");
 ```
 
+`requestRevalidate(target, endpoint?)` asks the app's revalidate route to purge the pages behind
+`target`, so an edit shows at once. It posts to `/api/revalidate` unless `endpoint` says otherwise.
+It never throws. On failure the pages' own revalidate window is the fallback.
+
+### `@sjolystinnovation/app-kit/server`
+
+For server components and route handlers only. It imports `next/cache` and `next/server`.
+
+`createPublicApi(baseUrl, options?)` returns cached GETs against the API's anonymous endpoints:
+
+- `publicGet(path, { tags? })` gives the data, or null when the API answers 404. An unreachable or
+  failing API throws `PublicApiError`, so a failed fetch is never cached as an empty page in place
+  of a working one.
+- `publicGetOptional(path, { tags? })` gives null on any failure, for data a page can do without.
+- `publicGetWithMeta(path, { tags? })` also gives `lastModified`, from the `Last-Modified` header.
+
+Responses stay fresh for 60 seconds unless `options.revalidate` says otherwise. An empty `baseUrl`
+throws. Each path starts with a single `/`, or the call throws. A path with a `.` or `..` segment,
+encoded or not, gives null without a request, the same as a 404. Run a slug or other user input
+through `encodeURIComponent` before putting it in a path.
+
+```ts
+// src/lib/publicApi.ts
+import { requireEnv } from "@sjolystinnovation/app-kit";
+import { createPublicApi } from "@sjolystinnovation/app-kit/server";
+
+export const { publicGet, publicGetOptional, publicGetWithMeta } = createPublicApi(
+  requireEnv("NEXT_PUBLIC_API_URL", process.env.NEXT_PUBLIC_API_URL),
+);
+```
+
+`createRevalidateRoute({ targets, role })` returns a `POST` handler for `app/api/revalidate/route.ts`.
+Each target maps to the page paths it purges. A path with a dynamic segment, such as
+`/builds/[slug]`, purges every page of that route. The target name is purged as a cache tag too, so
+tag the fetches behind it with the same name. The handler answers 403 unless the caller has a live
+session with `role`: signed in within the last seven days, with no refused refresh and an access
+token that has not expired. It answers 415 unless the body is sent as JSON, which
+`requestRevalidate` does, and 400 for a target it does not know.
+
+```ts
+// src/app/api/revalidate/route.ts
+import { createRevalidateRoute } from "@sjolystinnovation/app-kit/server";
+
+export const POST = createRevalidateRoute({
+  role: "Admin",
+  targets: { builds: ["/builds", "/builds/[slug]", "/sitemap.xml"], legal: ["/terms", "/privacy"] },
+});
+```
+
 ### `@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`. `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:
+The gate reads `session.error`. `SessionExpiryGuard` also reads `session.absoluteExpiresAt` for its
+countdown, `session.user.id` to keep the page with the user who opened it, and `session.user.email`
+to fill in the prompt. `createAuthOptions` sets all of these. An app with its own next-auth options sets them in its
+callbacks:
 
 ```ts
+const SESSION_LIFETIME_MS = 7 * 24 * 60 * 60 * 1000;
+
 callbacks: {
+  jwt({ token, user }) {
+    if (user) token.loginAt = Date.now();
+    // A token without a sign-in time counts as expired.
+    if (!token.loginAt || Date.now() - token.loginAt > SESSION_LIFETIME_MS) {
+      token.error = SESSION_ERRORS.absoluteExpiry;
+    }
+    // Also set token.error when a refresh is refused.
+    return token;
+  },
   session({ session, token }) {
+    session.user.id = token.sub ?? "";
     session.error = token.error;
+    session.absoluteExpiresAt = token.loginAt ? token.loginAt + SESSION_LIFETIME_MS : undefined;
     return session;
   },
 },
 ```
 
-For that to compile, `error` has to be on next-auth's `Session` and `JWT` types. Add it to
+For that to compile, these fields have to be on next-auth's `Session` and `JWT` types. Add them to
 the app's existing next-auth type declarations, or create them:
 
 ```ts
 // src/types/next-auth.d.ts
 import "next-auth";
 import "next-auth/jwt";
+import type { DefaultSession } from "next-auth";
 
 declare module "next-auth" {
   interface Session {
+    user: { id: string } & DefaultSession["user"];
     error?: string | undefined;
+    absoluteExpiresAt?: number | undefined;
   }
 }
 
 declare module "next-auth/jwt" {
   interface JWT {
     error?: string | undefined;
+    loginAt?: number | undefined;
   }
 }
 ```
@@ -335,37 +403,8 @@ A session that turns signed out with no prompt open blanks the page. A page the
 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
-for the current locale:
-
-```tsx
-"use client";
-
-import { useSessionGate } from "@sjolystinnovation/app-kit/session/react";
-import { useRouter } from "next/navigation";
-import { useEffect } from "react";
-
-export function ProtectedGate({
-  loginHref,
-  children,
-}: {
-  loginHref: string;
-  children: React.ReactNode;
-}) {
-  const router = useRouter();
-  const { status, promptOpen, usable, wasUsable, mayRender } = useSessionGate();
-
-  useEffect(() => {
-    if (promptOpen) return;
-    if (status === "unauthenticated" || (status === "authenticated" && !usable && !wasUsable)) {
-      router.push(loginHref);
-    }
-  }, [status, usable, wasUsable, promptOpen, router, loginHref]);
-
-  return mayRender ? children : <p>Loading…</p>;
-}
-```
+The hook does not navigate. `ProtectedGate` below adds the redirect. Use the hook directly in a
+layout that needs its own decision, such as a role check, so it agrees with the gate.
 
 | Field | Description |
 | --- | --- |
@@ -378,6 +417,84 @@ export function ProtectedGate({
 
 `SessionGate` is the type of the result.
 
+### `AppSessionProvider`
+
+From `@sjolystinnovation/app-kit/session/react`. next-auth's `SessionProvider`, reading the session
+again every four minutes. Each read lets the jwt callback renew the access token before it expires,
+so an open tab does not find a dead session on the next save. It also keeps what `useSession`
+reports in this tab up to date. next-auth polls only once a session exists.
+
+```tsx
+<AppSessionProvider>{children}</AppSessionProvider>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `refetchInterval` | `number` | Seconds between reads. Defaults to 240. Keep it under five minutes, the time before expiry when a refresh falls due. |
+
+### `ProtectedGate`
+
+From `@sjolystinnovation/app-kit/session/react`. Wraps the protected part of the app. It renders the
+page only when `useSessionGate` allows it, and sends a signed-out visitor or a session dead on
+arrival to `loginHref`. It never redirects while the re-sign-in prompt is open.
+
+```tsx
+<ProtectedGate loginHref="/login" fallback={<p>Loading…</p>}>
+  {children}
+</ProtectedGate>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `loginHref` | `string` | Where the redirect goes. An app with a locale in the path builds it for the current locale. |
+| `fallback` | `ReactNode` | What shows while the page may not render yet. Defaults to nothing. |
+
+### `RoleGate`
+
+From `@sjolystinnovation/app-kit/session/react`. Renders its children only for a user with `role`.
+Place it inside `ProtectedGate`. While the re-sign-in prompt recovers a signed-out session there is
+no user and so no roles. The page stays up only on the path where the session last had the role.
+
+```tsx
+<RoleGate role="Admin" fallback={<p>Loading…</p>} denied={<p>You do not have access.</p>}>
+  {children}
+</RoleGate>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `role` | `string` | The role the page needs, as it appears in `session.user.roles`. |
+| `fallback` | `ReactNode` | What shows while the session or its roles are not known yet. Defaults to nothing. |
+| `denied` | `ReactNode` | What a signed-in user without the role sees. Give this or `deniedHref`. |
+| `deniedHref` | `string` | Where a signed-in user without the role is sent instead. |
+
+### `SessionExpiryGuard`
+
+From `@sjolystinnovation/app-kit/session/react`. Render it once, inside the `SessionProvider`. It
+shows:
+
+- a banner in the last 30 minutes before `session.absoluteExpiresAt`, with the minutes left. That is
+  seven days after sign-in with `createAuthOptions`.
+- a banner when the session is dead
+- the re-sign-in prompt, a dialog with `CredentialsForm`, when a request or the banner opens it
+
+A sign-in in the prompt keeps the page and its form. A sign-in in the prompt as a different user is
+signed out and sent to `loginHref`, so the prompt never hands the page to another user.
+
+```tsx
+<SessionExpiryGuard
+  loginHref="/login"
+  onRestored={() => toast.success("You are signed in again.")}
+/>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `loginHref` | `string` | Where a sign-in as a different user is sent after it is signed out. |
+| `onRestored` | `() => void` | Runs after the prompt signs the user back in, such as to show a toast. |
+| `strings` | `TextOverrides<SessionExpiryGuardStrings>` | The guard's text. `{minutes}` in `expiringSoon` becomes the minutes left. The defaults are English. |
+| `formStrings` | `TextOverrides<CredentialsFormStrings>` | The text of the form in the prompt. |
+
 ### `useFormDraft(config, options)`
 
 From `@sjolystinnovation/app-kit/forms`. Keeps a form's values in `localStorage`, so a sign-out,
@@ -415,6 +532,40 @@ Drafts are stored under `<draftStoragePrefix>:draft:<owner>:<scope>`. The hook t
 `draftStoragePrefix` is empty or contains a colon. A draft older than 7 days is not offered, and is
 removed when its form next reads it.
 
+### `CredentialsForm`
+
+From `@sjolystinnovation/app-kit/ui`. Email and password sign-in through next-auth's credentials
+provider, with `redirect: false`, so the page stays where it is. Use it on the login page and in
+the prompt.
+
+```tsx
+<CredentialsForm onSignedIn={() => router.push("/")} strings={{ signIn: "Logg inn" }} />
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `onSignedIn` | `() => void \| Promise<void>` | Runs after next-auth accepts the credentials. Throw `SignInRejected` with a message to refuse the sign-in. |
+| `initialEmail` | `string` | The email the field starts with. |
+| `children` | `ReactNode` | Extra buttons next to the submit button. |
+| `strings` | `TextOverrides<CredentialsFormStrings>` | The form's text. The defaults are English. |
+| `onPendingChange` | `(pending: boolean) => void` | Runs when a sign-in starts and ends, such as to keep a dialog open until it finishes. |
+
+A failed sign-in shows `signInUnavailable` for `SIGN_IN_ERRORS.unavailable` and
+`invalidCredentials` for any other error code. A request next-auth refuses without an error code,
+or one that throws, shows `somethingWentWrong`.
+
+`TextOverrides<T>`, from `@sjolystinnovation/app-kit/ui`, is the type of every `strings` prop. Each
+key is optional and may be `undefined`, and a missing or undefined key shows the English default.
+
+### `TextInput`
+
+From `@sjolystinnovation/app-kit/ui`. A labelled text field with the same look and props as
+`PasswordInput`, apart from the show and hide toggle. It takes the other `<input>` attributes too.
+
+```tsx
+<TextInput label="Email" name="email" type="email" required error={errors.email} />
+```
+
 ### `Alert`
 
 ```tsx
@@ -426,7 +577,7 @@ import { Alert } from "@sjolystinnovation/app-kit/ui";
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `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. |
+| `role` | `"alert" \| "status" \| "none"` | `"alert"` | A screen reader announces `status` without interrupting, on every change of its text. Use `none` when a separate live region announces the text. |
 | `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. |
 
@@ -452,6 +603,16 @@ import { PasswordInput } from "@sjolystinnovation/app-kit/ui";
 
 Pass the two toggle labels in the app's language. The defaults are English.
 
+### `toast`
+
+From `@sjolystinnovation/app-kit/toast`. sonner's `toast`, except that `toast.error` shows nothing
+while the re-sign-in prompt is open. The prompt already says why the request failed. Every other
+toast passes through, and so do the error states of `toast.promise`.
+
+```ts
+import { toast } from "@sjolystinnovation/app-kit/toast";
+```
+
 ## Theming
 
 The components draw every colour, corner radius and label size from theme variables with a light
@@ -495,10 +656,22 @@ selector such as `.dark` for a scoped theme:
 | `--input-focus-ring-width` | `2px` |
 | `--color-input-toggle` | gray 400, the show password icon |
 | `--color-input-toggle-hover` | gray 600 |
-
-A default that points at another variable, such as `--color-input-focus-ring` at `--color-primary`,
-is read once for the whole page. A scoped theme that changes `--color-primary` should set
-`--color-input-focus-ring` in the same selector.
+| `--radius-button` | `var(--radius-lg)` |
+| `--color-button-primary-bg` | `var(--color-primary)` |
+| `--color-button-primary-text` | `var(--color-primary-foreground)` |
+| `--color-button-secondary-border` | gray 300 |
+| `--color-button-secondary-text` | gray 700 |
+| `--color-button-secondary-hover-bg` | gray 50 |
+| `--radius-dialog` | `var(--radius-xl)` |
+| `--color-dialog-backdrop` | black at 40% |
+| `--color-dialog-bg` | white |
+| `--color-dialog-title` | gray 900 |
+| `--color-dialog-text` | gray 600 |
+
+A default that points at another variable is read once for the whole page. The focus ring and the
+primary button point at `--color-primary` and `--color-primary-foreground`. A scoped theme that
+changes those also sets `--color-input-focus-ring`, `--color-button-primary-bg` and
+`--color-button-primary-text` in the same selector.
 
 An app that clears a whole Tailwind namespace, such as `--color-*: initial`, clears these variables
 with it and has to set the ones it uses itself.
@@ -507,9 +680,12 @@ with it and has to set the ones it uses 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.
+- For `@sjolystinnovation/app-kit/toast`: sonner 2, as an optional peer dependency. Install a single
+  copy, because two copies keep two separate toast stores.
 - `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.
+- For `@sjolystinnovation/app-kit/ui` and the components in `session/react`: Tailwind CSS 4 and
+  `@heroicons/react` 2. The focus ring and the primary button use the theme's `primary` and
+  `primary-foreground` colours, unless their own variables are set.
 - TypeScript with `"moduleResolution": "bundler"`. Relative imports here are extensionless, which
   `node16` and `nodenext` reject.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.5.0",
+  "version": "0.7.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",
@@ -21,7 +21,9 @@
     "./forms": "./src/forms/index.ts",
     "./auth": "./src/auth/index.ts",
     "./api": "./src/api/index.ts",
+    "./server": "./src/server/index.ts",
     "./ui": "./src/ui/index.ts",
+    "./toast": "./src/toast/index.ts",
     "./styles.css": "./src/styles.css"
   },
   "files": [
@@ -41,7 +43,13 @@
     "next": "^16",
     "next-auth": "^4.24",
     "react": "^19",
-    "react-dom": "^19"
+    "react-dom": "^19",
+    "sonner": "^2"
+  },
+  "peerDependenciesMeta": {
+    "sonner": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@heroicons/react": "^2.2.0",
@@ -57,6 +65,7 @@
     "next-auth": "^4.24.15",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
+    "sonner": "^2.0.8",
     "typescript": "^6.0.3",
     "vitest": "^5.0.3"
   },

package/src/api/index.ts

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

package/src/api/requestRevalidate.ts

@@ -0,0 +1,15 @@
+/**
+ * Asks the app's revalidate route to purge the pages behind `target`, so an admin edit shows at
+ * once. Best effort: on failure the pages' revalidate window is the fallback.
+ */
+export async function requestRevalidate(target: string, endpoint = "/api/revalidate"): Promise<void> {
+  try {
+    await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ target }),
+    });
+  } catch {
+    // Best effort, see above.
+  }
+}

package/src/auth/createAuthOptions.ts

@@ -4,7 +4,7 @@ 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";
+import { ABSOLUTE_SESSION_MAX_AGE, CLOCK_TOLERANCE_S, SESSION_ERRORS, SIGN_IN_ERRORS, isTerminalSessionError } from "../session/expiry";
 
 /** The signed-in user, as the session carries it. */
 export interface SessionUser {
@@ -60,8 +60,6 @@ export type AuthOptionsSettings = {
     }
 );
 
-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;
 
@@ -72,9 +70,6 @@ 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;
 

package/src/server/index.ts

@@ -0,0 +1,4 @@
+export { createPublicApi, PublicApiError } from "./publicApi";
+export type { PublicApiOptions, PublicGetOptions, PublicResponse } from "./publicApi";
+export { createRevalidateRoute } from "./revalidateRoute";
+export type { RevalidateRouteOptions } from "./revalidateRoute";

package/src/server/publicApi.ts

@@ -0,0 +1,104 @@
+export interface PublicResponse<T> {
+  data: T;
+  /** From the `Last-Modified` header, when the endpoint reports one. */
+  lastModified: Date | null;
+}
+
+export interface PublicGetOptions {
+  /** Cache tags, so a revalidate route can purge this fetch by tag. */
+  tags?: string[] | undefined;
+}
+
+export interface PublicApiOptions {
+  /** Seconds a cached response stays fresh. Defaults to 60. */
+  revalidate?: number | undefined;
+}
+
+/** The API could not be reached, or answered with no usable content. */
+export class PublicApiError extends Error {
+  readonly path: string;
+  readonly status: number | null;
+
+  constructor(path: string, status: number | null, options?: { cause?: unknown }) {
+    super(`GET ${path} failed${status == null ? "" : ` with ${status}`}`, options);
+    this.name = "PublicApiError";
+    this.path = path;
+    this.status = status;
+  }
+}
+
+/** Reads `Last-Modified`, ignoring a header that is missing or not a date. */
+function lastModifiedOf(response: Response): Date | null {
+  const header = response.headers.get("last-modified");
+  if (!header) return null;
+  const date = new Date(header);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+/**
+ * Cached GETs against the API's anonymous endpoints, for server components and route handlers.
+ *
+ * A 404 gives null. An unreachable or failing API throws `PublicApiError`, so a failed fetch is
+ * never cached as an empty page in place of a working one.
+ */
+export function createPublicApi(baseUrl: string, options: PublicApiOptions = {}) {
+  if (!baseUrl) {
+    throw new Error("createPublicApi needs the API base URL, and baseUrl is empty.");
+  }
+  const revalidate = options.revalidate ?? 60;
+  const base = new URL(baseUrl);
+  const basePath = base.pathname.replace(/\/$/, "");
+
+  // The path is joined onto the base URL. A path that does not start with a single "/" is a bug in
+  // the caller, so it throws. A path with a dot segment, often a slug from the URL, names no resource,
+  // so it gives null, the same as a 404. A slug goes through encodeURIComponent first.
+  function urlFor(path: string): string | null {
+    if (!path.startsWith("/") || path.startsWith("//")) {
+      throw new Error(`Public API path must start with a single "/" under the base URL: ${path}`);
+    }
+    const segments = path.split(/[?#]/, 1)[0]!.replace(/%2e/gi, ".").split("/");
+    if (segments.some((segment) => segment === "." || segment === "..")) return null;
+    const url = new URL(`${baseUrl.replace(/\/$/, "")}${path}`);
+    if (url.origin !== base.origin || !url.pathname.startsWith(`${basePath}/`)) return null;
+    return url.toString();
+  }
+
+  async function publicGetWithMeta<T>(path: string, opts: PublicGetOptions = {}): Promise<PublicResponse<T> | null> {
+    const url = urlFor(path);
+    if (url == null) return null;
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        next: opts.tags ? { revalidate, tags: opts.tags } : { revalidate },
+      });
+    } catch (cause) {
+      throw new PublicApiError(path, null, { cause });
+    }
+
+    if (response.status === 404) return null;
+    if (!response.ok) throw new PublicApiError(path, response.status);
+
+    try {
+      return { data: (await response.json()) as T, lastModified: lastModifiedOf(response) };
+    } catch (cause) {
+      throw new PublicApiError(path, response.status, { cause });
+    }
+  }
+
+  /** The data alone. Null when the resource does not exist. */
+  async function publicGet<T>(path: string, opts: PublicGetOptions = {}): Promise<T | null> {
+    return (await publicGetWithMeta<T>(path, opts))?.data ?? null;
+  }
+
+  /** For data a page can do without. Null on any failure, so the page still renders. */
+  async function publicGetOptional<T>(path: string, opts: PublicGetOptions = {}): Promise<T | null> {
+    try {
+      return await publicGet<T>(path, opts);
+    } catch (error) {
+      if (error instanceof PublicApiError) return null;
+      throw error;
+    }
+  }
+
+  return { publicGet, publicGetOptional, publicGetWithMeta };
+}

package/src/server/revalidateRoute.ts

@@ -0,0 +1,77 @@
+import { revalidatePath, revalidateTag } from "next/cache";
+import { NextResponse, type NextRequest } from "next/server";
+import jwt from "jsonwebtoken";
+import { getToken, type JWT } from "next-auth/jwt";
+import { ABSOLUTE_SESSION_MAX_AGE, CLOCK_TOLERANCE_S, isTerminalSessionError } from "../session/expiry";
+
+export interface RevalidateRouteOptions {
+  /**
+   * Each target the client may send, with the page paths it purges. A path with a dynamic segment,
+   * such as `/builds/[slug]`, purges every page of that route. The target name is also purged as a
+   * cache tag, so tag fetches with it.
+   */
+  targets: Record<string, readonly string[]>;
+  /** The role allowed to purge, as it appears in the session user's roles. */
+  role: string;
+}
+
+type Token = JWT | null;
+
+const rolesOf = (token: Token): string[] => (token?.user as { roles?: string[] } | undefined)?.roles ?? [];
+
+// getToken only decrypts the cookie, without the jwt callback. So the checks that callback makes are
+// made here: a refused refresh still carries its roles, and the cookie outlives the seven days. The
+// roles must also come from an access token that has not expired, so a copied cookie of a user who
+// lost the role stops working within the token's lifetime.
+function isLive(token: Token): boolean {
+  if (!token || isTerminalSessionError(token.error as string | undefined)) return false;
+  const loginAt = token.loginAt;
+  if (typeof loginAt !== "number" || Date.now() - loginAt > ABSOLUTE_SESSION_MAX_AGE) return false;
+  return accessTokenValid(token.accessToken);
+}
+
+// The cookie is encrypted and authenticated with NEXTAUTH_SECRET, so the access token in it is the
+// one the API issued, and its expiry can be read without verifying the signature again.
+function accessTokenValid(accessToken: unknown): boolean {
+  if (typeof accessToken !== "string") return false;
+  const claims = jwt.decode(accessToken);
+  const exp = claims && typeof claims === "object" ? claims.exp : undefined;
+  return typeof exp === "number" && exp * 1000 + CLOCK_TOLERANCE_S * 1000 > Date.now();
+}
+
+/**
+ * A `POST` route handler that purges cached pages after an edit, for `app/api/revalidate/route.ts`.
+ * It answers 403 unless the caller has a live session with `role`, 415 unless the body is JSON, and
+ * 400 for a target it does not know.
+ */
+export function createRevalidateRoute({ targets, role }: RevalidateRouteOptions) {
+  return async function POST(req: NextRequest): Promise<NextResponse> {
+    // getToken reads NEXTAUTH_SECRET itself, the same way next-auth does. It is asked for both cookie
+    // names, because behind a TLS proxy next-auth can sign in with the secure cookie while getToken
+    // would look for the plain one.
+    const token = (await getToken({ req, secureCookie: true })) ?? (await getToken({ req, secureCookie: false }));
+    if (!isLive(token) || !rolesOf(token).includes(role)) {
+      return NextResponse.json({ message: "Forbidden" }, { status: 403 });
+    }
+
+    // JSON only, so a plain form on a sibling subdomain cannot post here with the session cookie.
+    if (!req.headers.get("content-type")?.toLowerCase().startsWith("application/json")) {
+      return NextResponse.json({ message: "Expected JSON" }, { status: 415 });
+    }
+
+    const body: unknown = await req.json().catch(() => null);
+    const target = (body as { target?: unknown } | null)?.target;
+    if (typeof target !== "string" || !Object.hasOwn(targets, target)) {
+      return NextResponse.json({ message: "Unknown target" }, { status: 400 });
+    }
+
+    for (const path of targets[target] ?? []) {
+      if (path.includes("[")) revalidatePath(path, "page");
+      else revalidatePath(path);
+    }
+    // By tag as well, because a path purge misses fetches that another route rendered. expire 0
+    // makes them stale at once.
+    revalidateTag(target, { expire: 0 });
+    return NextResponse.json({ revalidated: true, target });
+  };
+}

package/src/session/expiry.ts

@@ -1,3 +1,9 @@
+/** How long a session lasts after sign-in, however often it is refreshed. Seven days. */
+export const ABSOLUTE_SESSION_MAX_AGE = 7 * 24 * 60 * 60 * 1000;
+
+/** How far this server's clock may differ from the API's when a token's times are checked. */
+export const CLOCK_TOLERANCE_S = 60;
+
 /**
  * Errors the jwt callback sets when the session cannot be recovered without a new sign-in. A
  * transient refresh failure, such as a network error or an API restart, sets no error, so the

package/src/session/react/AppSessionProvider.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { SessionProvider } from "next-auth/react";
+import type { ReactNode } from "react";
+
+/** Four minutes, shorter than the five minutes before expiry when a refresh falls due. */
+const SESSION_POLL_SECONDS = 4 * 60;
+
+export interface AppSessionProviderProps {
+  /** Seconds between session reads. Defaults to four minutes. */
+  refetchInterval?: number | undefined;
+  children: ReactNode;
+}
+
+/**
+ * next-auth's `SessionProvider`, reading the session again on a timer. Each read lets the jwt
+ * callback renew the access token ahead of expiry, so an open tab stays usable and does not find a
+ * dead session on the next save. It also keeps what `useSession` reports in this tab up to date.
+ * next-auth polls only once a session exists, so signed-out visitors cost nothing.
+ */
+export function AppSessionProvider({ refetchInterval = SESSION_POLL_SECONDS, children }: AppSessionProviderProps) {
+  return <SessionProvider refetchInterval={refetchInterval}>{children}</SessionProvider>;
+}