@atelic-action/ui 0.10.0 → 0.12.0

package/dist/gate/wall.js

@@ -0,0 +1,74 @@
+/**
+ * What the access wall holds back. With the wall armed, every request needs
+ * a session except what the login page itself needs to render: the practice's
+ * FOOTPRINT.md says anything carrying a private signal is never hosted
+ * publicly, and on a private artifact that includes the owner's screenshots
+ * under /images/, the printed PDF, and the built chunks a document's content
+ * compiles into.
+ *
+ * The open paths are read from what the built /login page actually loads:
+ * its hashed CSS and JS under /assets/, the fonts its stylesheet declares,
+ * the favicon in its head, and the brand marks the header draws, which every
+ * prerendered page preloads because the router's pending page carries the
+ * header (each site's e2e/wall.spec.ts fails when the login page asks for
+ * anything else); plus the two sign in functions under /api/auth/, the login page itself,
+ * robots.txt, and the uptime monitor's health.json. /assets/doc/ is the one
+ * part of /assets/ held back: the build writes every chunk carrying a
+ * private content module there (the private chunks build plugin), so a document's
+ * copy and numbers never sit in a file the login page can load.
+ *
+ * A logo is a brand mark and is not private; a screenshot is evidence and
+ * may be. So brand marks, the sender's and the recipient's, live under
+ * public/brand/ and stay open, so the header and the login page can draw
+ * them, and the owner's screens live under public/images/ and are held. The
+ * sender's mark at /logo.svg and the favicon stay open where they are,
+ * because every cut already points at them there.
+ *
+ * The business's website build, when one is previewed, is proxied under
+ * /proto by a rewrite in the host's vercel.json. It is a public thing by design and carries no private reading, so
+ * it stays open on a private host too: a prospect reads the prototype
+ * without a sign in while the documents beside it stay behind the wall.
+ *
+ * Pure and dependency free, so the middleware imports it and the tests call
+ * it directly.
+ */
+const OPEN_EXACT = new Set([
+    "/login",
+    "/login/",
+    "/favicon.svg",
+    "/logo.svg",
+    "/robots.txt",
+    "/health.json",
+    "/proto",
+]);
+const OPEN_PREFIXES = ["/api/auth/", "/assets/", "/brand/", "/fonts/", "/proto/"];
+/** The one corner of an open prefix that stays behind the wall. */
+const HELD_PREFIXES = ["/assets/doc/"];
+/**
+ * Whether a request for this path needs a session when the wall is armed.
+ * The path is read the way a file server would read it (decoded, repeated
+ * slashes collapsed) so an encoded or doubled slash cannot walk a held file
+ * out through an open prefix; anything that will not decode, or still climbs
+ * a directory once decoded, is held. Case is folded for the held corner
+ * alone, so no spelling of it slips out, while an open path opens only as
+ * written: the host serves files by exact case, and a path that merely looks
+ * like an open one names some other file.
+ */
+export function needsSession(pathname) {
+    let path;
+    try {
+        path = decodeURIComponent(pathname);
+    }
+    catch {
+        return true;
+    }
+    path = path.replace(/\/{2,}/g, "/");
+    if (path.includes("..") || path.includes("\\"))
+        return true;
+    const folded = path.toLowerCase();
+    if (HELD_PREFIXES.some((prefix) => folded.startsWith(prefix)))
+        return true;
+    if (OPEN_EXACT.has(path))
+        return false;
+    return !OPEN_PREFIXES.some((prefix) => path.startsWith(prefix));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "0.10.0",
-	"description": "Shared UI for the Atelic templates: site chrome, base styles, and the component library they install",
+	"version": "0.12.0",
+	"description": "Shared UI for the Atelic templates: site chrome, base styles, the component library, and the access gate they install",
 	"type": "module",
 	"license": "UNLICENSED",
 	"repository": {
@@ -12,7 +12,8 @@
 		"access": "public"
 	},
 	"files": [
-		"src"
+		"src",
+		"dist"
 	],
 	"sideEffects": [
 		"**/*.css"
@@ -29,16 +30,38 @@
 		"./styles/chrome.css": "./src/styles/chrome.css",
 		"./styles/components.css": "./src/styles/components.css",
 		"./styles/star-rating.css": "./src/styles/star-rating.css",
+		"./gate": {
+			"types": "./dist/gate/index.d.ts",
+			"default": "./dist/gate/index.js"
+		},
+		"./gate/middleware": {
+			"types": "./dist/gate/middleware.d.ts",
+			"default": "./dist/gate/middleware.js"
+		},
+		"./gate/request-link": {
+			"types": "./dist/gate/request-link.d.ts",
+			"default": "./dist/gate/request-link.js"
+		},
+		"./gate/verify": {
+			"types": "./dist/gate/verify.d.ts",
+			"default": "./dist/gate/verify.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"scripts": {
+		"build": "rm -rf dist && tsc -p tsconfig.server.json",
+		"build:smoke": "node --input-type=module -e \"for (const entry of ['', '/middleware', '/request-link', '/verify']) await import('@atelic-action/ui/gate' + entry)\"",
+		"prepack": "bun run build",
 		"lint": "biome check .",
 		"lint:fix": "biome check . --write",
-		"typecheck": "tsc --noEmit && tsc --noEmit -p gallery",
+		"typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.server.json && tsc --noEmit -p gallery",
 		"test:run": "vitest run",
 		"gallery:dev": "vite gallery",
 		"gallery:build": "vite build gallery"
 	},
+	"dependencies": {
+		"jose": "^6.2.12"
+	},
 	"peerDependencies": {
 		"lucide-react": "^1.23.0",
 		"react": "^19.0.0",
@@ -48,6 +71,7 @@
 		"@biomejs/biome": "^2.5.13",
 		"@testing-library/jest-dom": "^6.6.2",
 		"@testing-library/react": "^16.0.1",
+		"@types/node": "^24.0.0",
 		"@types/react": "^19.0.0",
 		"@types/react-dom": "^19.0.0",
 		"@vitejs/plugin-react": "^6.1.1",

package/src/components/Disclosure.tsx

@@ -0,0 +1,73 @@
+import { ChevronDown } from "lucide-react";
+import { type ReactNode, useId } from "react";
+
+export interface DisclosureProps {
+	/** What the section is, and the toggle's accessible name. */
+	label: ReactNode;
+	open: boolean;
+	onToggle: () => void;
+	/**
+	 * Sits beside the label and outside the toggle's name: a count, a flag, a
+	 * small chart. A tap on it still folds the section.
+	 */
+	meta?: ReactNode;
+	/** Makes the label a real heading at this level; leave it out for none. */
+	headingLevel?: 2 | 3 | 4 | 5 | 6;
+	/** The panel's id; minted when left out. */
+	panelId?: string;
+	className?: string;
+	children: ReactNode;
+}
+
+/**
+ * A section the page opens and closes: a header row that folds a body the
+ * caller controls. Where `Collapsible` is a native details element that keeps
+ * its own state and its detail in the page, this one is for an app. The
+ * caller holds `open`, so it can remember which sections were folded, and a
+ * closed body is not rendered, so a long list costs nothing until asked for.
+ *
+ * The label is the toggle, so its name reads "Produce, collapsed" and not
+ * "Produce 10 items"; `meta` is a sibling for that reason. The toggle's
+ * `::after` stretches over the whole header row, so a tap anywhere on it,
+ * meta and chevron included, folds the section.
+ */
+export function Disclosure({
+	label,
+	open,
+	onToggle,
+	meta,
+	headingLevel,
+	panelId,
+	className,
+	children,
+}: DisclosureProps) {
+	const minted = useId();
+	const id = panelId ?? minted;
+	const Root = headingLevel ? "section" : "div";
+	const Title = headingLevel ? (`h${headingLevel}` as const) : "div";
+
+	return (
+		<Root className={["disclosure", open && "is-open", className].filter(Boolean).join(" ")}>
+			<div className="disclosure-head">
+				<Title className="disclosure-title">
+					<button
+						type="button"
+						className="disclosure-toggle"
+						onClick={onToggle}
+						aria-expanded={open}
+						aria-controls={id}
+					>
+						{label}
+					</button>
+				</Title>
+				{meta != null && meta !== false && <span className="disclosure-meta">{meta}</span>}
+				<ChevronDown className="disclosure-chevron" size={16} aria-hidden="true" />
+			</div>
+			{open && (
+				<div className="disclosure-body" id={id}>
+					{children}
+				</div>
+			)}
+		</Root>
+	);
+}

package/src/components/StatRow.tsx

@@ -22,6 +22,8 @@ export interface StatDelta {
 export interface StatItem {
 	/** The big figure, e.g. "$199", "3,948", "23%"; may embed an inline glyph. */
 	value: ReactNode;
+	/** The figure's unit, set small after it on the same baseline, e.g. "mi". */
+	unit?: ReactNode;
 	/** An arrow before the figure, when the figure is itself a change. */
 	trend?: StatDirection;
 	/** What the figure counts. */
@@ -38,6 +40,13 @@ export interface StatItem {
 
 export interface StatRowProps {
 	stats: StatItem[];
+	/**
+	 * How loud the row is. `loud`, the default, is a report's headline figures:
+	 * heavy, large, in the accent. `quiet` is a glance row for a working page:
+	 * a light figure in the text color over a small capitalized label, the
+	 * stats divided by a hairline. A tone still colors a quiet figure.
+	 */
+	variant?: "loud" | "quiet";
 	className?: string;
 }
 
@@ -50,9 +59,13 @@ const spoken = { up: "Up", down: "Down", flat: "Unchanged" } as const;
  * closes the stat, with the period it covers. The row wraps to as many
  * columns as fit, and arrows are read aloud as up or down.
  */
-export function StatRow({ stats, className }: StatRowProps) {
+export function StatRow({ stats, variant = "loud", className }: StatRowProps) {
 	return (
-		<div className={["stat-row", className].filter(Boolean).join(" ")}>
+		<div
+			className={["stat-row", variant === "quiet" && "is-quiet", className]
+				.filter(Boolean)
+				.join(" ")}
+		>
 			{stats.map((stat, i) => {
 				const Trend = stat.trend ? arrow[stat.trend] : null;
 				return (
@@ -63,6 +76,7 @@ export function StatRow({ stats, className }: StatRowProps) {
 								<Trend className="stat-trend" role="img" aria-label={spoken[stat.trend]} />
 							)}
 							{stat.value}
+							{stat.unit != null && <span className="stat-unit">{stat.unit}</span>}
 						</div>
 						{stat.deltas?.map((delta) => {
 							const Icon = arrow[delta.direction];

package/src/components/index.ts

@@ -16,6 +16,7 @@ export {
 	type DataTableValueCell,
 	type SortDirection,
 } from "./DataTable";
+export { Disclosure, type DisclosureProps } from "./Disclosure";
 export { NotFound, type NotFoundProps } from "./NotFound";
 export { StackedBar, type StackedBarProps, type StackedBarSegment } from "./StackedBar";
 export { describeStarRating, StarRating, type StarRatingProps } from "./StarRating";

package/src/gate/config.ts

@@ -0,0 +1,25 @@
+/**
+ * How the gate reads its settings from the environment. Shared by the two
+ * sign in functions and the middleware, so each reads a value the same way.
+ */
+
+/** Whether an address is on the comma separated allowlist. */
+export function isAllowed(email: string, allowlist: string | undefined): boolean {
+	const wanted = email.trim().toLowerCase();
+	if (!wanted) return false;
+	return (allowlist ?? "")
+		.split(",")
+		.map((entry) => entry.trim().toLowerCase())
+		.includes(wanted);
+}
+
+/**
+ * A setting that has to be a positive, finite number, or its default. A
+ * lifetime of zero, a negative one, or Infinity would mint a token that is
+ * already dead or that cannot be signed at all. A fraction is allowed (half
+ * a day), so a caller rounds what it derives to whole seconds.
+ */
+export function positive(value: string | undefined, fallback: number): number {
+	const parsed = Number(value);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}

package/src/gate/index.ts

@@ -0,0 +1,3 @@
+export { safeNext } from "./next.js";
+export { signToken, type TokenClaims, type TokenPurpose, verifyToken } from "./tokens.js";
+export { needsSession } from "./wall.js";

package/src/gate/middleware.ts

@@ -0,0 +1,64 @@
+/**
+ * Access gate: the routing middleware.
+ *
+ * Opt in and fail open: with no GATE_SESSION_SECRET set the gate is dormant
+ * and every request passes, so a site is fully public. Set the secret (and an
+ * allowlist) on the Vercel project and this same code starts enforcing: a
+ * request without a valid session cookie is redirected to /login. The
+ * session's address has to be on the allowlist still, so taking one off (and
+ * redeploying) ends that reader's session.
+ *
+ * A site's root `middleware.ts` exports this as its default beside its own
+ * `config`, which the platform reads from that file and nowhere else:
+ *
+ *   export { default } from "@atelic-action/ui/gate/middleware";
+ *   export const config = { matcher: ["/((?!api/auth/).*)"] };
+ *
+ * That matcher keeps only the two sign in functions away from the middleware,
+ * so any other function a host adds is held like a page. The default holds
+ * back everything `needsSession` in wall.ts does. A site
+ * whose matcher already leaves its open paths out passes its own test to
+ * `createMiddleware`.
+ */
+import { isAllowed } from "./config.js";
+import { verifyToken } from "./tokens.js";
+import { needsSession as wallNeedsSession } from "./wall.js";
+
+export interface MiddlewareOptions {
+	/** Whether a path needs a session once the gate is armed. */
+	needsSession?: (pathname: string) => boolean;
+}
+
+function readCookie(header: string, name: string): string | undefined {
+	const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]+)`));
+	if (!match) return undefined;
+	try {
+		return decodeURIComponent(match[1]);
+	} catch {
+		return undefined;
+	}
+}
+
+export function createMiddleware(options: MiddlewareOptions = {}) {
+	const needsSession = options.needsSession ?? wallNeedsSession;
+
+	return async function middleware(request: Request): Promise<Response | undefined> {
+		const secret = process.env.GATE_SESSION_SECRET;
+		if (!secret) return; // gate off, let everything through
+
+		const url = new URL(request.url);
+		if (!needsSession(url.pathname)) return; // what the login page needs to render
+
+		const cookies = request.headers.get("cookie") ?? "";
+		const claims = await verifyToken(readCookie(cookies, "gate_session"), secret);
+		if (claims?.p === "session" && isAllowed(claims.e, process.env.GATE_ALLOWLIST)) {
+			return; // valid session, continue to the site
+		}
+
+		const login = new URL("/login", url.origin);
+		login.searchParams.set("next", url.pathname + url.search);
+		return Response.redirect(login.toString(), 302);
+	};
+}
+
+export default createMiddleware();

package/src/gate/next.ts

@@ -0,0 +1,21 @@
+/**
+ * The post sign in destination, held to a path on this host. A value that
+ * starts with one slash is not enough: a browser reads `//host` as protocol
+ * relative and `/\host` the same way, and drops tabs and newlines before it
+ * parses, so `/\t/host` arrives as `//host`. The value also becomes a
+ * Location header, which throws on anything outside Latin 1, so the path is
+ * held to printable ASCII, and to a length no real path here comes near, so
+ * a request cannot grow the emailed link without bound. Anything else falls
+ * back to the root.
+ */
+const LONGEST = 512;
+
+export function safeNext(value: unknown): string {
+	if (typeof value !== "string" || !value.startsWith("/") || value.startsWith("//")) return "/";
+	if (value.length > LONGEST) return "/";
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code === 0x5c || code <= 0x20 || code >= 0x7f) return "/";
+	}
+	return value;
+}

package/src/gate/request-link.ts

@@ -0,0 +1,184 @@
+/**
+ * Access gate: request a sign in link.
+ *
+ * Emails a signed link through Resend, but only to an allowlisted address.
+ * The response is the same whether or not the email matched, in its body and
+ * in how long it takes, so the allowlist cannot be probed. A site's
+ * `api/auth/request-link.ts` re exports `POST` from here.
+ *
+ * Env (set on the Vercel project):
+ * - GATE_SESSION_SECRET   signing secret; also the gate's on and off switch
+ * - GATE_ALLOWLIST        comma separated emails allowed to receive a link
+ * - RESEND_API_KEY        sending only Resend key
+ * - GATE_FROM             sender display name (optional)
+ * - GATE_SUBJECT          email subject (optional)
+ * - GATE_LINK_TTL_MIN     link lifetime in minutes (optional, default 15)
+ * - GATE_BASE_URL         the host the link points at (optional, see linkBase)
+ */
+import { isAllowed, positive } from "./config.js";
+import { safeNext } from "./next.js";
+import { signToken } from "./tokens.js";
+
+const DEFAULT_FROM = "Atelic <forms@atelic.me>";
+
+/** How long every valid request takes to answer, whatever it did. */
+const ANSWER_AFTER_MS = 2000;
+
+/**
+ * How long a send may run before it is given up. Shorter than the answer, so
+ * a slow send can never make an allowlisted address answer later than a
+ * stranger.
+ */
+const SEND_WITHIN_MS = 1700;
+
+export interface RequestLinkOptions {
+	/** What the link opens, as the email names it. Defaults to "document". */
+	noun?: string;
+}
+
+function json(status: number, body: Record<string, unknown>): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "Content-Type": "application/json" },
+	});
+}
+
+/**
+ * Where the emailed link points. Never a forwarded header: a caller can name
+ * any host there, and the link carries a signed token. The configured base
+ * wins, read as a host (a bare one is taken as https); on production the
+ * project's own domain is next; otherwise the host the platform routed this
+ * request to, which is the deployment itself.
+ */
+export function linkBase(request: Request, env: Record<string, string | undefined>): string {
+	const configured = env.GATE_BASE_URL?.trim();
+	if (configured) {
+		try {
+			return new URL(/^https?:\/\//i.test(configured) ? configured : `https://${configured}`)
+				.origin;
+		} catch {
+			console.error("gate: GATE_BASE_URL is not a URL, falling back to the request's own host");
+		}
+	}
+	if (env.VERCEL_ENV === "production" && env.VERCEL_PROJECT_PRODUCTION_URL) {
+		return `https://${env.VERCEL_PROJECT_PRODUCTION_URL}`;
+	}
+	return new URL(request.url).origin;
+}
+
+/** Text made safe to set inside an HTML element or a quoted attribute. */
+function escapeHtml(text: string): string {
+	return text
+		.replaceAll("&", "&amp;")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;")
+		.replaceAll("'", "&#39;");
+}
+
+function linkEmailHtml(rawLink: string, rawNoun: string): string {
+	const link = escapeHtml(rawLink);
+	const noun = escapeHtml(rawNoun);
+	// Gmail renders inline styles only, no style blocks.
+	return `
+		<div style="font-family: Helvetica, Arial, sans-serif; color: #211c17; line-height: 1.6; max-width: 520px;">
+			<p style="margin: 0 0 12px; font-size: 24px; font-weight: 600;">Your private link to the ${noun}.</p>
+			<p style="margin: 0 0 24px; color: #4a4137;">Click below to open the site. The link is tied to your inbox and expires shortly. Once you are in, you stay signed in for a while.</p>
+			<a href="${link}" style="display: inline-block; background: #211c17; color: #ffffff; font-weight: 600; text-decoration: none; padding: 14px 26px; border-radius: 8px;">Open the ${noun} &rarr;</a>
+			<p style="margin: 24px 0 0; font-size: 13px; color: #4a4137;">If the button does not work, paste this link into your browser:<br><span style="color: #6b5f4f; word-break: break-all;">${link}</span></p>
+			<p style="margin: 28px 0 0; font-size: 13px; color: #8a7c68;">If you did not expect this, you can ignore it.</p>
+		</div>`;
+}
+
+/**
+ * Sends the link, and says so in the function's log when it could not. The
+ * log is the only place a failed send shows: the response never tells.
+ */
+async function sendLink(to: string, link: string, noun: string): Promise<void> {
+	const apiKey = process.env.RESEND_API_KEY;
+	if (!apiKey) {
+		console.error("gate: no RESEND_API_KEY, so no sign in link was sent");
+		return;
+	}
+	const controller = new AbortController();
+	const giveUp = setTimeout(() => controller.abort(), SEND_WITHIN_MS);
+	try {
+		const response = await fetch("https://api.resend.com/emails", {
+			method: "POST",
+			signal: controller.signal,
+			headers: {
+				Authorization: `Bearer ${apiKey}`,
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({
+				from: process.env.GATE_FROM || DEFAULT_FROM,
+				to: [to],
+				subject: process.env.GATE_SUBJECT || `Your private link to the ${noun}`,
+				html: linkEmailHtml(link, noun),
+				text: `Your private link to the ${noun}:\n\n${link}\n\nIf you did not expect this, you can ignore it.`,
+			}),
+		});
+		if (!response.ok) {
+			console.error(`gate: Resend answered ${response.status}, so no sign in link was sent`);
+		}
+	} finally {
+		clearTimeout(giveUp);
+	}
+}
+
+const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+export function createRequestLink(options: RequestLinkOptions = {}) {
+	const noun = options.noun ?? "document";
+
+	return async function POST(request: Request): Promise<Response> {
+		let data: unknown;
+		try {
+			data = await request.json();
+		} catch {
+			return json(400, { ok: false, error: "Invalid request body." });
+		}
+		if (typeof data !== "object" || data === null || Array.isArray(data)) {
+			return json(400, { ok: false, error: "Invalid request body." });
+		}
+		const fields = data as Record<string, unknown>;
+
+		const email = String(fields.email ?? "")
+			.trim()
+			.toLowerCase();
+		const next = safeNext(fields.next);
+
+		const secret = process.env.GATE_SESSION_SECRET;
+
+		// Every valid request answers after the same wait, so a send in flight
+		// reads no differently from no send at all.
+		const answered = wait(ANSWER_AFTER_MS);
+
+		if (secret && isAllowed(email, process.env.GATE_ALLOWLIST)) {
+			const ttlMinutes = positive(process.env.GATE_LINK_TTL_MIN, 15);
+			try {
+				const token = await signToken(
+					{
+						e: email,
+						x: Math.floor(Date.now() / 1000) + Math.max(1, Math.round(ttlMinutes * 60)),
+						p: "link",
+						n: next,
+					},
+					secret,
+				);
+				const link = `${linkBase(request, process.env)}/api/auth/verify?token=${encodeURIComponent(token)}`;
+				await sendLink(email, link, noun);
+			} catch (error) {
+				// The response must not reveal whether a send happened; the log may.
+				const reason = error instanceof Error ? error.name : "unknown error";
+				console.error(`gate: the sign in link was not sent (${reason})`);
+			}
+		}
+
+		await answered;
+		return json(200, { ok: true });
+	};
+}
+
+/** The handler a document host exports as is. */
+export const POST = createRequestLink();

package/src/gate/tokens.ts

@@ -0,0 +1,57 @@
+/**
+ * Signed tokens for the access gate: compact JWTs under HS256, signed and
+ * verified by jose over Web Crypto, so the same module runs in the routing
+ * middleware and in the serverless sign in functions. The secret is always
+ * passed in by the caller from the environment, so nothing here can reach a
+ * client bundle.
+ */
+import { jwtVerify, SignJWT } from "jose";
+
+export type TokenPurpose = "link" | "session";
+
+export interface TokenClaims {
+	/** Subject email. */
+	e: string;
+	/** Expiry, epoch seconds. */
+	x: number;
+	/** Purpose; keeps a short lived link token from being replayed as a session. */
+	p: TokenPurpose;
+	/** Post sign in path (link tokens only). */
+	n?: string;
+}
+
+const encoder = new TextEncoder();
+
+export async function signToken(claims: TokenClaims, secret: string): Promise<string> {
+	const body: Record<string, unknown> = { p: claims.p };
+	if (claims.n !== undefined) body.n = claims.n;
+	return new SignJWT(body)
+		.setProtectedHeader({ alg: "HS256" })
+		.setSubject(claims.e)
+		.setExpirationTime(claims.x)
+		.sign(encoder.encode(secret));
+}
+
+/**
+ * The claims of a token this secret signed and that has not expired, or null
+ * for anything else. The algorithm is pinned, so a token naming another one
+ * (or none) is refused before its signature is read.
+ */
+export async function verifyToken(
+	token: string | undefined | null,
+	secret: string,
+): Promise<TokenClaims | null> {
+	if (!token || !secret) return null;
+	try {
+		const { payload } = await jwtVerify(token, encoder.encode(secret), {
+			algorithms: ["HS256"],
+			requiredClaims: ["sub", "exp"],
+		});
+		const { sub, exp, p, n } = payload;
+		if (typeof sub !== "string" || typeof exp !== "number") return null;
+		if (p !== "link" && p !== "session") return null;
+		return { e: sub, x: exp, p, ...(typeof n === "string" ? { n } : {}) };
+	} catch {
+		return null;
+	}
+}