caracms 0.0.0-stage → 0.2.0

package/src/live/auth/links.ts

@@ -0,0 +1,101 @@
+/**
+ * What sign-in keeps in Redis: one-time link tokens and the rate-limit counters (M4
+ * Decision 14; the template's `server/login-store.mjs`, over our RedisClient).
+ *
+ * Every key starts with `caracms:auth:` and has an expiry, so nothing here outlives
+ * 15 minutes.
+ *
+ * **Link tokens:** 32 random bytes, base64url (43 characters) in the link. **Only the
+ * token's SHA-256 is stored**, `caracms:auth:link:<hash>` → `{ email, next }`, for 15
+ * minutes, so a leaked Redis yields no usable link. `peek` is a plain GET: loading the
+ * confirm page never spends a token (mail scanners load every link). **`spend` is
+ * GETDEL**: atomic, so two presses can't both sign in.
+ *
+ * **Rate limits:** a fixed 15-minute window per key, started by the first hit and never
+ * extended. Link requests: **3 per address and 10 per IP**. Backup sign-in: 5 attempts
+ * per IP, counting every attempt (the template's `BACKUP_LIMIT`). The address and the IP
+ * are SHA-256'd in the key names, so no address sits in Redis in the clear and a header
+ * can't put arbitrary text into a key.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import type { RedisClient } from '../redis.ts';
+
+export const LINK_TTL_MS = 15 * 60 * 1000;
+export const RATE_WINDOW_MS = 15 * 60 * 1000;
+export const LINK_LIMITS = { perAddress: 3, perIp: 10 } as const;
+export const BACKUP_LIMIT = 5;
+const PREFIX = 'caracms:auth:';
+
+export const sha256Hex = (value: string) => createHash('sha256').update(value, 'utf8').digest('hex');
+export const newLinkToken = () => randomBytes(32).toString('base64url');
+/** Only tokens this module could have minted reach Redis. */
+export const isTokenShape = (token: unknown): token is string => typeof token === 'string' && /^[A-Za-z0-9_-]{43}$/.test(token);
+export const linkKey = (token: string) => `${PREFIX}link:${sha256Hex(token)}`;
+
+export interface LinkRecord {
+	email: string;
+	next: string;
+}
+
+function parse(raw: string | null): LinkRecord | null {
+	if (raw === null) return null;
+	try {
+		const record = JSON.parse(raw) as Partial<LinkRecord>;
+		return typeof record?.email === 'string' ? { email: record.email, next: typeof record.next === 'string' ? record.next : '' } : null;
+	} catch {
+		return null;
+	}
+}
+
+export interface LinkStore {
+	/** Store a new token for this (normalised) address; returns the token for the link. */
+	issue(email: string, next: string): Promise<string>;
+	/** Read without spending (the confirm page). Null for missing, expired, used or malformed. */
+	peek(token: unknown): Promise<LinkRecord | null>;
+	/** Read and delete in one step (the press). Null if it was already gone. */
+	spend(token: unknown): Promise<LinkRecord | null>;
+}
+
+export function createLinkStore(redis: RedisClient): LinkStore {
+	return {
+		async issue(email, next) {
+			const token = newLinkToken();
+			await redis.set(linkKey(token), JSON.stringify({ email, next }), { px: LINK_TTL_MS });
+			return token;
+		},
+		async peek(token) {
+			return isTokenShape(token) ? parse(await redis.get(linkKey(token))) : null;
+		},
+		async spend(token) {
+			return isTokenShape(token) ? parse(await redis.getdel(linkKey(token))) : null;
+		},
+	};
+}
+
+export interface RateLimits {
+	/** One link request: counts against both the address and the IP; whether either is now over. */
+	linkRequestOver(email: string, ip: string): Promise<boolean>;
+	/** One backup sign-in attempt from this IP: whether it's over. */
+	backupAttemptOver(ip: string): Promise<boolean>;
+}
+
+export function createRateLimits(redis: RedisClient): RateLimits {
+	/** Count one hit; the window starts with the first and isn't extended by later ones. */
+	const hit = async (name: string) => {
+		const key = `${PREFIX}rl:${name}`;
+		const count = await redis.incr(key);
+		// The first hit starts the window. A key left with no expiry (a crash between the
+		// two calls) is given one on its next hit, so a counter can never stick.
+		if (count === 1 || (await redis.pttl(key)) === -1) await redis.pexpire(key, RATE_WINDOW_MS);
+		return count;
+	};
+	return {
+		async linkRequestOver(email, ip) {
+			const [byAddress, byIp] = await Promise.all([hit(`link-address:${sha256Hex(email)}`), hit(`link-ip:${sha256Hex(ip)}`)]);
+			return byAddress > LINK_LIMITS.perAddress || byIp > LINK_LIMITS.perIp;
+		},
+		async backupAttemptOver(ip) {
+			return (await hit(`backup-ip:${sha256Hex(ip)}`)) > BACKUP_LIMIT;
+		},
+	};
+}

package/src/live/auth/login.ts

@@ -0,0 +1,245 @@
+/**
+ * The sign-in pages under `/admin/login` (M4 Decision 14; the template's
+ * `server/admin-login.mjs`, without Auth.js). A Request in, a Response out.
+ *
+ *   GET  /admin/login[?next=][&backup=1][&signedout=1]
+ *        The email form. `?backup=1` swaps in the backup form (only while the backup
+ *        account is on); `?signedout=1` adds "You're signed out".
+ *   POST /admin/login                (form: email, next[, again])
+ *        **Request a link: a plain form POST.** Rate limits (3 per address, 10 per IP,
+ *        per 15 minutes), then the whitelist; the link is issued and emailed (or
+ *        logged) AFTER the response, so **every path answers the same "Check your
+ *        email" page** in about the same time. A malformed address is the one other
+ *        answer (400, the form's own error), which says nothing about the whitelist.
+ *   POST /admin/login?backup=1       Script off: shows the backup form again. Reads nothing.
+ *   GET  /admin/login/confirm?token=…
+ *        Where the emailed link lands. **Read-only** (GET, never GETDEL: mail scanners
+ *        open links): "Sign in as …"; "Switch to …?" when this browser is signed in as
+ *        someone else; straight to `next` with the token left unspent when it's
+ *        already signed in as that address; or the one dead-link page (410).
+ *   POST /admin/login/confirm        Script off: 303 back to the GET. Spends nothing.
+ *   POST /admin/login/signin         (JSON: `{ kind: 'link', token }` or
+ *        `{ kind: 'backup', username, password, next }`) The press. **The token is
+ *        spent here only**, with GETDEL, and the address checked against the whitelist
+ *        again. Answers `{ location }` with the session cookie, or `{ error, reason }`
+ *        (`dead-link` 410, `wrong` 401, `limited` 429, `failed`).
+ *   POST /admin/login/signout        Clears the cookie; 303 to `?signedout=1`, or
+ *        `{ ok, location }` to a JSON request.
+ *   GET  /admin/login/signed-in?next=
+ *        After signing in on a narrow window (M2 Decision 8): signed in, open the
+ *        editor on a larger screen, with Sign out.
+ *
+ * Every POST requires the same origin (403 otherwise): the guard lets these paths
+ * through, so they check it themselves. Responses are `Cache-Control: private,
+ * no-store`, `X-Robots-Tag: noindex, nofollow`, `nosniff`, `Referrer-Policy:
+ * same-origin` (not `no-referrer`, under which browsers send `Origin: null` on the
+ * form POSTs) and a CSP with only the page's own style and script, by hash.
+ */
+import type { Auth } from './auth.ts';
+import { normaliseEmail } from './allow.ts';
+import { clientIp, isRead, isSameOrigin } from './request.ts';
+import { backupPerson, cleanNext, DEFAULT_NEXT, LOGIN_PATH, loginHref, safeEqual } from './session.ts';
+import {
+	backupView,
+	confirmView,
+	deadLinkView,
+	emailView,
+	layout,
+	messageView,
+	sentView,
+	signedInNarrowView,
+	SIGNED_IN_PATH,
+	SIGNIN_PATH,
+	type Brand,
+	type PageAssets,
+	type SafeHtml,
+} from './views.ts';
+
+export const CONFIRM_PATH = `${LOGIN_PATH}/confirm`;
+export const SIGNOUT_PATH = `${LOGIN_PATH}/signout`;
+export { SIGNIN_PATH, SIGNED_IN_PATH };
+
+/** Largest form or JSON body read. An address and a password are tiny. */
+const MAX_BODY_BYTES = 8 * 1024;
+
+export interface LoginContext {
+	auth: Auth;
+	brand: Brand;
+	assets: PageAssets;
+	/** The adapter's socket address (Astro's `clientAddress`), read lazily: it can throw. */
+	clientAddress: () => string | undefined;
+}
+
+const BASE_HEADERS = {
+	'Cache-Control': 'private, no-store',
+	'X-Robots-Tag': 'noindex, nofollow',
+	'X-Content-Type-Options': 'nosniff',
+	'Referrer-Policy': 'same-origin',
+};
+
+class BodyTooLarge extends Error {}
+
+async function readBody(request: Request): Promise<string> {
+	if (Number(request.headers.get('content-length') ?? 0) > MAX_BODY_BYTES) throw new BodyTooLarge();
+	const text = await request.text();
+	if (Buffer.byteLength(text) > MAX_BODY_BYTES) throw new BodyTooLarge();
+	return text;
+}
+
+export async function handleLogin(request: Request, ctx: LoginContext): Promise<Response> {
+	const { auth, brand, assets } = ctx;
+	const url = new URL(request.url);
+	const pathname = url.pathname.replace(/\/+$/, '') || '/';
+	const method = request.method;
+	const query = url.searchParams;
+	const extra: Record<string, string> = {};
+
+	const page = (status: number, title: string, body: SafeHtml, opts: { script?: boolean; quiet?: boolean; bare?: boolean } = {}) => {
+		const { html, csp } = layout({ title, brand, assets, body, home: url.host, ...opts });
+		return new Response(method === 'HEAD' ? null : html, {
+			status,
+			headers: { ...BASE_HEADERS, ...extra, 'Content-Type': 'text/html; charset=utf-8', 'Content-Security-Policy': csp },
+		});
+	};
+	const redirect = (location: string, cookie?: string) => {
+		const headers = new Headers({ ...BASE_HEADERS, Location: location });
+		if (cookie) headers.append('Set-Cookie', cookie);
+		return new Response(null, { status: 303, headers });
+	};
+	const json = (status: number, body: unknown, cookie?: string) => {
+		const headers = new Headers({ ...BASE_HEADERS, 'Content-Type': 'application/json; charset=utf-8' });
+		if (cookie) headers.append('Set-Cookie', cookie);
+		return new Response(JSON.stringify(body), { status, headers });
+	};
+	const notAllowed = (allow: string) => {
+		extra.Allow = allow;
+		return page(405, 'Not allowed', messageView('Not allowed', 'Use the form on the sign-in page.'));
+	};
+	const crossOrigin = () => page(403, 'Not allowed', messageView('Not allowed', 'Send the form from the sign-in page.'));
+	const wantsJson = (request.headers.get('accept') ?? '').includes('application/json');
+
+	try {
+		// ────────────────────────────────────────────────────────────── confirm
+		if (pathname === CONFIRM_PATH) {
+			if (method === 'POST') return redirect(`${CONFIRM_PATH}${url.search}`);
+			if (!isRead(method)) return notAllowed('GET, HEAD, POST');
+			const record = await auth.links.peek(query.get('token'));
+			if (!record) return page(410, 'Link expired', deadLinkView());
+			const next = cleanNext(record.next);
+			const who = auth.identify(request.headers.get('cookie'));
+			if (who.state === 'in' && who.payload.kind === 'link' && who.person.email === record.email) {
+				// Already in as this address: go on, and leave the token unspent.
+				return redirect(next);
+			}
+			const current = who.state !== 'in' ? null : who.payload.kind === 'backup' ? 'the backup account' : who.person.email;
+			return page(200, 'Sign in', confirmView({ email: record.email, next, siteName: auth.siteName, current }), { script: true, quiet: true });
+		}
+
+		// ─────────────────────────────────────────────────────────────── signin
+		if (pathname === SIGNIN_PATH) {
+			if (method !== 'POST') return notAllowed('POST');
+			if (!isSameOrigin(request)) return json(403, { error: 'Sign in from the sign-in page.', reason: 'failed' });
+			let body: Record<string, unknown>;
+			try {
+				const parsed: unknown = JSON.parse(await readBody(request));
+				if (!parsed || typeof parsed !== 'object') throw new Error('not an object');
+				body = parsed as Record<string, unknown>;
+			} catch {
+				return json(400, { error: 'Send { kind, … } as JSON.', reason: 'failed' });
+			}
+			if (body.kind === 'link') {
+				const record = await auth.links.spend(body.token);
+				const email = normaliseEmail(record?.email);
+				// Spent, and the address still on the whitelist (it may have been removed since).
+				if (!record || !email || !auth.whitelist.allows(email)) return json(410, { error: 'This link has expired or was already used.', reason: 'dead-link' });
+				auth.log(`signed in: ${email}`);
+				return json(200, { location: cleanNext(record.next) }, auth.startSession({ kind: 'link', email }));
+			}
+			if (body.kind === 'backup') {
+				const { backup } = auth;
+				if (!backup.enabled) return json(404, { error: 'There is no backup account on this site.', reason: 'failed' });
+				// Every attempt counts, the right password included, so the limit can't confirm a guess.
+				let over = true;
+				try {
+					over = await auth.limits.backupAttemptOver(clientIp(request, ctx.clientAddress));
+				} catch (error) {
+					auth.log(`could not count a backup sign-in attempt, so it was refused: ${error instanceof Error ? error.message : String(error)}`);
+				}
+				if (over) return json(429, { error: 'Too many attempts. Try again in 15 minutes.', reason: 'limited' });
+				// Both compared every time: no early exit on a wrong username.
+				const userOk = safeEqual(body.username, backup.user);
+				const passwordOk = safeEqual(body.password, backup.password);
+				if (!(userOk && passwordOk)) return json(401, { error: "That username and password didn't work.", reason: 'wrong' });
+				auth.log(`signed in: the backup account (${backupPerson(backup.user).name})`);
+				return json(200, { location: cleanNext(body.next) }, auth.startSession({ kind: 'backup' }));
+			}
+			return json(400, { error: 'Unknown kind of sign-in.', reason: 'failed' });
+		}
+
+		// ────────────────────────────────────────────────────────────── signout
+		if (pathname === SIGNOUT_PATH) {
+			if (method !== 'POST') return notAllowed('POST');
+			if (!isSameOrigin(request)) return wantsJson ? json(403, { error: 'Sign out from the editor.', reason: 'cross-origin' }) : crossOrigin();
+			const location = loginHref({ signedout: '1' });
+			return wantsJson ? json(200, { ok: true, location }, auth.clearCookie()) : redirect(location, auth.clearCookie());
+		}
+
+		// ──────────────────────────────────────────────────────────── signed-in
+		if (pathname === SIGNED_IN_PATH) {
+			if (!isRead(method)) return notAllowed('GET, HEAD');
+			const who = auth.identify(request.headers.get('cookie'));
+			if (who.state !== 'in') return redirect(LOGIN_PATH);
+			const shown = who.payload.kind === 'backup' ? 'the backup account' : who.person.email;
+			return page(200, 'Signed in', signedInNarrowView({ brand, who: shown, host: url.host }), { script: true, bare: true });
+		}
+
+		if (pathname !== LOGIN_PATH) return page(404, 'Not found', messageView('Not found', 'There is no page at this address.'));
+
+		// ──────────────────────────────────────────────────────────────── login
+		const showBackup = query.get('backup') === '1' && auth.backup.enabled;
+		if (isRead(method)) {
+			const next = cleanNext(query.get('next'));
+			if (showBackup) return page(200, 'Backup account', backupView({ next }), { script: true });
+			return page(200, 'Sign in', emailView({ next, signedOut: query.get('signedout') === '1', backupEnabled: auth.backup.enabled }));
+		}
+		if (method !== 'POST') return notAllowed('GET, HEAD, POST');
+		if (!isSameOrigin(request)) return crossOrigin();
+		if (showBackup) return page(200, 'Backup account', backupView({ next: cleanNext(query.get('next')) }), { script: true });
+
+		let form: URLSearchParams;
+		try {
+			form = new URLSearchParams(await readBody(request));
+		} catch {
+			return page(400, 'Sign in', emailView({ next: DEFAULT_NEXT, invalid: 'Enter your email address.', backupEnabled: auth.backup.enabled }));
+		}
+		const next = cleanNext(form.get('next'));
+		const typed = (form.get('email') ?? '').trim().slice(0, 320);
+		const email = normaliseEmail(typed);
+		if (!email) {
+			const invalid = typed ? 'Enter a full email address.' : 'Enter your email address.';
+			return page(400, 'Sign in', emailView({ next, value: typed, invalid, backupEnabled: auth.backup.enabled }));
+		}
+
+		// Every address counts against the limits, allowed or not, so the time taken is the same.
+		const ip = clientIp(request, ctx.clientAddress);
+		let over = true;
+		try {
+			over = await auth.limits.linkRequestOver(email, ip);
+		} catch (error) {
+			// No counters, no link: fail closed.
+			auth.log(`could not check the rate limits, so no link was sent: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (over) auth.log(`link request refused by the rate limit (ip ${ip})`);
+		else if (auth.whitelist.allows(email)) void auth.sendLink(email, next, url.origin);
+		else auth.log(`no link sent: ${email} isn't on the whitelist`);
+		return page(200, 'Check your email', sentView({ email, next, again: form.get('again') === '1', backupEnabled: auth.backup.enabled }));
+	} catch (error) {
+		auth.log(`sign-in page failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+		return page(500, 'Something went wrong', messageView('Something went wrong', "Couldn't finish that. Try again in a moment."));
+	}
+}
+
+/** Local mode has no sign-in (Decision 1): every sign-in page goes to the editor. */
+export function localLoginRedirect(): Response {
+	return new Response(null, { status: 303, headers: { Location: DEFAULT_NEXT, 'Cache-Control': 'private, no-store' } });
+}

package/src/live/auth/middleware.ts

@@ -0,0 +1,53 @@
+/**
+ * The guard as Astro middleware (M4 Decision 14), registered by the integration with
+ * `addMiddleware({ order: 'pre' })` after Phase 2's 503 middleware for an
+ * unconfigured server. The check itself is guard.ts.
+ *
+ * - **Local mode: it does nothing** (M3's behaviour, no sign-in; Decision 1).
+ * - **Live mode**: a path outside `/admin` and `/_caracms/` goes straight on, without
+ *   even building the runtime, so the public site never waits on GitHub or Redis.
+ *   A guarded path that passes records the person (`setPerson`) for the route.
+ * - **Unconfigured** never reaches here in a correct setup (Phase 2's middleware
+ *   answers first); if it does, a guarded path gets a 503 rather than through.
+ *
+ * The mode is Phase 2's `editorMode()`, so the two agree on live and local.
+ */
+import type { MiddlewareHandler } from 'astro';
+import { site } from 'virtual:caracms/config';
+import { editorMode } from '../../editor/server/mode.ts';
+import { setPerson } from '../locals.ts';
+import { guard, isGuardedPath } from './guard.ts';
+import { authFor } from './index.ts';
+
+const unavailable = (text: string) => new Response(text, { status: 503, headers: { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'private, no-store' } });
+
+export const onRequest: MiddlewareHandler = async (context, next) => {
+	if (!isGuardedPath(context.url.pathname)) return next();
+	const mode = editorMode();
+	if (mode.kind === 'local') return next();
+	if (mode.kind !== 'live') return unavailable("The editor isn't set up on this server yet.");
+
+	let auth;
+	try {
+		auth = await authFor(site, mode.settings, context.site);
+	} catch (error) {
+		console.error('[caracms] sign-in: the live runtime could not start:', error);
+		return unavailable("The editor couldn't start. Try again in a moment.");
+	}
+	const result = guard(context.request, auth);
+	if (result.kind === 'respond') return result.response;
+	if (result.kind === 'skip') return next();
+
+	setPerson(context.locals, result.person);
+	const response = await next();
+	if (!result.setCookie) return response;
+	try {
+		response.headers.append('Set-Cookie', result.setCookie);
+		return response;
+	} catch {
+		// Immutable headers (a Response.redirect): copy it.
+		const copy = new Response(response.body, response);
+		copy.headers.append('Set-Cookie', result.setCookie);
+		return copy;
+	}
+};

package/src/live/auth/request.ts

@@ -0,0 +1,56 @@
+/**
+ * Two things read off a request: the client's IP (for rate limits) and whether a write
+ * came from this site.
+ */
+
+const first = (value: string | null) => (value ?? '').split(',')[0]!.trim();
+
+/**
+ * The client's IP, which keys the per-IP rate limits (the template's `clientIp()`,
+ * `docs/admin-login.md` → Rate limits and the client IP). In order:
+ *
+ * 1. **`X-Real-IP`.** Railway's edge overwrites it with the address that connected, so
+ *    behind Railway it's the one value the client can't choose.
+ * 2. The socket's address as the adapter gives it (`clientAddress`).
+ * 3. The first `X-Forwarded-For` hop, only when there's nothing else. Never ahead of
+ *    the socket: the client writes the leftmost hop, so keyed on it an attacker could
+ *    rotate past every per-IP limit.
+ *
+ * Off Railway (dev, tests) nothing proxies, so a spoofed `X-Real-IP` only rate-limits
+ * the spoofer's own requests: accepted, as in the template.
+ */
+export function clientIp(request: Request, clientAddress: () => string | undefined): string {
+	const real = first(request.headers.get('x-real-ip'));
+	if (real) return real.slice(0, 64);
+	let socket: string | undefined;
+	try {
+		socket = clientAddress();
+	} catch {
+		/* not available here */
+	}
+	if (socket) return socket.slice(0, 64);
+	return first(request.headers.get('x-forwarded-for')).slice(0, 64) || 'unknown';
+}
+
+/**
+ * Whether a write (any non-GET/HEAD) came from this site: **an `Origin` whose host is
+ * the request's own host**, and no `Sec-Fetch-Site` saying otherwise. A missing
+ * `Origin`, or the opaque `null` (a sandboxed frame, `Referrer-Policy: no-referrer`
+ * form posts), is refused: every current browser sends `Origin` on a POST.
+ *
+ * Host only, not the scheme, as M3's write route does: behind Railway's edge the
+ * server itself sees plain http while the page is https.
+ */
+export function isSameOrigin(request: Request): boolean {
+	const fetchSite = request.headers.get('sec-fetch-site');
+	if (fetchSite && fetchSite !== 'same-origin') return false;
+	const origin = request.headers.get('origin');
+	if (!origin || origin === 'null') return false;
+	try {
+		return new URL(origin).host === new URL(request.url).host;
+	} catch {
+		return false;
+	}
+}
+
+export const isRead = (method: string) => method === 'GET' || method === 'HEAD';

package/src/live/auth/routes.ts

@@ -0,0 +1,9 @@
+/**
+ * Sign-in's routes and middleware, for the integration (src/index.ts), which injects
+ * them beside the editor's. One route serves every `/admin/login…` page (login.ts);
+ * Astro ranks it above `/admin/[...path]`.
+ */
+export const LOGIN_ROUTES = [{ pattern: '/admin/login/[...path]', entrypoint: 'editor/routes/login/login.ts' }] as const;
+
+/** The guard, relative to src/ (index.ts resolves it against its own URL). */
+export const GUARD_MIDDLEWARE = 'live/auth/middleware.ts';

package/src/live/auth/session.ts

@@ -0,0 +1,181 @@
+/**
+ * The session, the backup account and `next` (M4 Decision 14; the template's
+ * `server/auth-options.mjs`, without Auth.js).
+ *
+ * **The session is a cookie the site signs itself**: `<payload>.<mac>`, the payload
+ * base64url JSON, the mac HMAC-SHA256 over it under a key derived from
+ * `CARACMS_SECRET`, compared in constant time. `HttpOnly`, `Secure` in production,
+ * `SameSite=Lax`, `Path=/`, no `Domain`. It lasts **30 days from last use**: the guard
+ * renews it (a new `renewed` and `expires`) when it's more than an hour old, so a
+ * poll every 5 s doesn't set a cookie every 5 s. In production the name has the
+ * `__Host-` prefix, so no other host can plant one. Changing `CARACMS_SECRET` signs
+ * everyone out.
+ *
+ * Two kinds:
+ * - `link`: an address that spent a link. **The whitelist is checked again on every
+ *   request** (guard.ts), so removing an address signs that person out on their next one.
+ * - `backup`: the backup account. It carries a fingerprint of the password it signed
+ *   in with (an HMAC under the secret, never the password), so **changing the password
+ *   signs backup sessions out**.
+ */
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import type { Person } from '../messages.ts';
+
+export const LOGIN_PATH = '/admin/login';
+export const DEFAULT_NEXT = '/admin';
+export const SESSION_MAX_AGE_S = 30 * 24 * 60 * 60;
+/** Renew the cookie once it's this old, so it stays 30 days from last use. */
+export const SESSION_RENEW_MS = 60 * 60 * 1000;
+/** Shorter means no backup sign-in, and no link to it. */
+export const BACKUP_MIN_PASSWORD = 24;
+
+/** The cookie's name: `__Host-` prefixed when it's `Secure` (production). */
+export const sessionCookieName = (secure: boolean) => (secure ? '__Host-caracms_session' : 'caracms_session');
+
+export type SessionPayload =
+	| { v: 1; kind: 'link'; email: string; renewed: number; expires: number }
+	| { v: 1; kind: 'backup'; user: string; fingerprint: string; renewed: number; expires: number };
+
+const macKey = (secret: string) => createHmac('sha256', secret).update('caracms session v1').digest();
+
+/** Constant-time string comparison: both sides hashed first, so lengths never leak. */
+export function safeEqual(a: unknown, b: string): boolean {
+	const digest = (s: string) => createHash('sha256').update(s, 'utf8').digest();
+	return timingSafeEqual(digest(typeof a === 'string' ? a : ''), digest(b));
+}
+
+export function signSession(payload: SessionPayload, secret: string): string {
+	const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+	const mac = createHmac('sha256', macKey(secret)).update(body).digest('base64url');
+	return `${body}.${mac}`;
+}
+
+/** The payload, if the cookie is ours, intact and not expired; else null. */
+export function verifySession(value: string | undefined | null, secret: string, now: number): SessionPayload | null {
+	if (!value || value.length > 4096) return null;
+	const dot = value.indexOf('.');
+	if (dot <= 0 || dot !== value.lastIndexOf('.')) return null;
+	const body = value.slice(0, dot);
+	const given = Buffer.from(value.slice(dot + 1), 'base64url');
+	const expected = createHmac('sha256', macKey(secret)).update(body).digest();
+	if (given.length !== expected.length || !timingSafeEqual(given, expected)) return null;
+	let payload: unknown;
+	try {
+		payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+	} catch {
+		return null;
+	}
+	const p = payload as Partial<SessionPayload> & Record<string, unknown>;
+	if (!p || p.v !== 1 || typeof p.expires !== 'number' || typeof p.renewed !== 'number' || !(p.expires > now)) return null;
+	if (p.kind === 'link' && typeof p.email === 'string') return p as SessionPayload;
+	if (p.kind === 'backup' && typeof p.user === 'string' && typeof p.fingerprint === 'string') return p as SessionPayload;
+	return null;
+}
+
+/** A fresh payload for a sign-in, or a renewal of an existing one. */
+export function freshPayload(
+	identity: { kind: 'link'; email: string } | { kind: 'backup'; user: string; fingerprint: string },
+	now: number,
+): SessionPayload {
+	return { v: 1, ...identity, renewed: now, expires: now + SESSION_MAX_AGE_S * 1000 } as SessionPayload;
+}
+
+export interface CookieOptions {
+	secure: boolean;
+}
+
+/** The Set-Cookie value for a session. */
+export function sessionCookie(value: string, { secure }: CookieOptions): string {
+	return `${sessionCookieName(secure)}=${value}; Path=/; Max-Age=${SESSION_MAX_AGE_S}; HttpOnly; SameSite=Lax${secure ? '; Secure' : ''}`;
+}
+
+/** The Set-Cookie value that clears it (sign out). */
+export function clearedSessionCookie({ secure }: CookieOptions): string {
+	return `${sessionCookieName(secure)}=; Path=/; Max-Age=0; HttpOnly; SameSite=Lax${secure ? '; Secure' : ''}`;
+}
+
+/** One cookie's value out of a Cookie header. */
+export function readCookie(header: string | null, name: string): string | null {
+	if (!header) return null;
+	for (const part of header.split(';')) {
+		const eq = part.indexOf('=');
+		if (eq < 0) continue;
+		if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();
+	}
+	return null;
+}
+
+// ── The backup account ────────────────────────────────────────────────────────
+
+export type BackupConfig = { enabled: true; user: string; password: string; fingerprint: string } | { enabled: false };
+
+/**
+ * The backup account as configured: both variables, and a password of at least 24
+ * characters. **Under 24 characters means no backup sign-in and no link to it**, with
+ * one line in the log. Neither set: off, silently.
+ */
+export function backupConfig(backup: { user: string; password: string } | null, secret: string, log: (line: string) => void): BackupConfig {
+	if (!backup) return { enabled: false };
+	if (backup.password.length < BACKUP_MIN_PASSWORD) {
+		log(`CARACMS_BACKUP_PASSWORD is shorter than ${BACKUP_MIN_PASSWORD} characters: the backup account is off.`);
+		return { enabled: false };
+	}
+	return { enabled: true, user: backup.user, password: backup.password, fingerprint: passwordFingerprint(backup.user, backup.password, secret) };
+}
+
+/** The backup password's fingerprint for the session: an HMAC under the secret, never the password. */
+export function passwordFingerprint(user: string, password: string, secret: string): string {
+	return createHmac('sha256', secret).update(`caracms backup\u0000${user}\u0000${password}`, 'utf8').digest('base64url').slice(0, 22);
+}
+
+/** The backup account as a person: an address that can't be anyone's (`.invalid`), named by its username. */
+export function backupPerson(user: string): Person {
+	return { email: `${user.toLowerCase().replace(/[^a-z0-9._-]/g, '-')}@backup.invalid`, name: user };
+}
+
+// ── `next` ────────────────────────────────────────────────────────────────────
+
+/**
+ * **`next` must be a same-origin path under `/admin`**, else `/admin`. Refused:
+ * protocol-relative (`//evil.com`, `/\evil.com`), absolute URLs (`https://evil.com/admin`),
+ * paths outside `/admin` (`/x`), backslashes and control characters anywhere,
+ * percent-encoded slashes or backslashes (`%2f`, `%5c`), dot segments that leave
+ * `/admin` once resolved, and the sign-in pages themselves.
+ */
+export function cleanNext(value: unknown): string {
+	if (typeof value !== 'string') return DEFAULT_NEXT;
+	const raw = value.trim();
+	if (!raw || raw.length > 2048) return DEFAULT_NEXT;
+	if (/[\\\u0000-\u001f\u007f]/.test(raw)) return DEFAULT_NEXT;
+	if (/%(?:2f|5c|00)/i.test(raw)) return DEFAULT_NEXT;
+	if (!raw.startsWith('/') || raw.startsWith('//')) return DEFAULT_NEXT;
+	const base = 'http://next.invalid';
+	let url: URL;
+	try {
+		url = new URL(raw, base);
+	} catch {
+		return DEFAULT_NEXT;
+	}
+	if (url.origin !== base) return DEFAULT_NEXT;
+	const { pathname } = url;
+	if (pathname !== '/admin' && !pathname.startsWith('/admin/')) return DEFAULT_NEXT;
+	if (pathname === LOGIN_PATH || pathname.startsWith(`${LOGIN_PATH}/`)) return DEFAULT_NEXT;
+	return `${pathname}${url.search}${url.hash}`;
+}
+
+/** `/admin/login?next=…`, with `next` left off when it's the default. */
+export function loginHref(params: Record<string, string> = {}, next = DEFAULT_NEXT): string {
+	const search = new URLSearchParams(params);
+	if (next && next !== DEFAULT_NEXT) search.set('next', next);
+	const query = search.toString();
+	return query ? `${LOGIN_PATH}?${query}` : LOGIN_PATH;
+}
+
+/**
+ * A `Cookie` header value for a link session as this person (tests, and Phase 2's
+ * route tests over HTTP). The address must also be on the whitelist to pass the guard.
+ */
+export function sessionCookieFor(person: Pick<Person, 'email'>, secret: string, options: { secure?: boolean; now?: number } = {}): string {
+	const value = signSession(freshPayload({ kind: 'link', email: person.email.trim().toLowerCase() }, options.now ?? Date.now()), secret);
+	return `${sessionCookieName(options.secure ?? false)}=${value}`;
+}