caracms 0.0.0-stage → 0.2.0

package/src/live/README.md

@@ -0,0 +1,43 @@
+# Live mode (`src/live/`)
+
+M4's server side: git, Redis and the mode. Spec: `notes/2026-10-14-m4-drafts-publish.md`
+(Decisions 1–3, 5–8, 10, 12, 14, 16, 17). Phase 1 built this folder with no UI; Phase 2's
+live drafts store, sweep, locks and status route, and Phase 3's sign-in, sit on top.
+
+| File | What |
+|---|---|
+| `mode.ts` | `readMode(env, production)` → `local`, `live` (with `LiveSettings`) or `unconfigured` (`missing`, `problems`); `unconfiguredMessage()` for the 503 |
+| `runtime.ts` | `liveRuntime(site, settings)`: one per process, lazy. `createLiveRuntime({...})` for tests (inject backend, Redis, clock). `CARACMS_GITHUB=memory`: a MemoryBackend seeded from disk (`siteFiles`), refused in production |
+| `git.ts` | `LiveGit`: the `drafts` copy (`files()`, `read()`, `contentSource()`), `commitDrafts()`, `check()`, `publish()` and its `commitPending` hook, `waiting()`, `publishStatus()`, `history()`, `tryAgain()`. M5a: a draft entry with `text` null removes the file; "Contact (deleted)" in the headlines; `mainHas`, `changeOf` (new, deleted or changed), `titleFor` |
+| `timings.ts` | `LiveTimings` and `DEFAULT_TIMINGS`: every timing, Phase 2's sweep and lock ones included |
+| `merge.ts` | `mergeFile({ base, draft, other })`: the per-key three-way merge, pure and byte-preserving |
+| `messages.ts` | The commit-message contract (`draftMessage`, `mergeMessage`, `publishMessage`, `parseMessage`), `Person`, `displayName` |
+| `status.ts` | Pure: `waitingFromCommits()`, `publishState()`, `PublishRecord` |
+| `redis.ts` | `RedisClient`; `connectRedis(url)` (ioredis with M1 → R2's retry and idle close) and `memoryRedis()` (the stand-in, with `calls` and `flush()`) |
+| `backend.ts` | `GitBackend`; `GitHubBackend`, `MemoryBackend` (test helpers: `seed`, `push`, `file`, `deployments`, `beforeRequest`); `StaleHeadError` |
+| `branches.ts` | `Branch` (a role: `main` or `drafts`), `BranchNames` (the refs behind them), `DEFAULT_BRANCHES`. `CARACMS_MAIN_BRANCH` and `CARACMS_DRAFTS_BRANCH` (read by `mode.ts`, M9 Decision 6) name the branch Publish commits to and the one autosaves land on; unset, `main` and `drafts`. They're set together or not at all: one alone is a problem, so the mode is unconfigured (`/admin` answers 503 saying both must be set; the public site still serves). Only the backends turn a role into a ref name, so with both set a branch called `main` is never read or moved. `MemoryBackend.refs` is keyed by name |
+| `github.ts` | The App's JWT, the installation token (one repo, refreshed early), `Tracker` (request counts) |
+| `webhook.ts` | `handleGithubWebhook()`, behind `POST /_caracms/github` (`../editor/routes/github.ts`) |
+| `autosaves.ts` | Phase 2. Autosaves in Redis (`caracms:autosave:<file>`, a week; stored compare-and-set, ordered per tab by `X-Caracms-Seq`), the session's last commit (the merge's ancestor) and who last changed a document (Decision 11; no expiry, and `known: false` when neither Redis nor git can say). M5a: a new document's autosave carries `created: { over }` (its ancestor until committed), a deletion is a "gone" autosave (`text` and `document` null, `gone: { title }`) |
+| `locks.ts` | Phase 2. `Locks`: taken by the first write, heartbeat on the poll, lapse only once committed, releasing, Edit here; presence |
+| `sweep.ts` | Phase 2. `Sweep`: one commit per tick for everything ready; ticks only while something is pending (no Redis call otherwise); `commitAll` fills `git.commitPending` |
+| `drafts-store.ts` | Phase 2. The live `DraftsStore`: the copy with autosaves on top (a gone one leaves the file out); `write` takes the lock and stores the autosave. M5a Phase 3: `create` (the lock, then the new document as an autosave) and `delete` (the lock, then a gone autosave, the lock released to drop once committed), with `editor/server/create.ts`'s rules. M5a: any kind of document; Site Settings' autosave is marked `sweepAtOnce` (the sweep commits it on its next tick, no idle wait); `source()` is the copy with every autosave on top (a preview's reads) |
+| `editor.ts` | Phase 2. `createLiveEditor(runtime)` / `liveEditor(site, settings)`: the store, sweep and locks, and the handlers for write, status, lock, publish, history, try-again, notice |
+| `locals.ts` | The hand-off from the sign-in guard to the routes: `setPerson` / `personOf` on Astro's `locals` |
+| `auth/` | Phase 3. Sign-in: the whitelist, the session cookie, links and rate limits, email, the guard and the `/admin/login` pages (map: `auth/index.ts`'s header) |
+
+Rules that hold everywhere here:
+
+- **Two servers run at once during a deploy.** Ref moves are compare-and-swap; after any
+  failed move both heads are re-read and the copy refreshed before a retry. The newest
+  publish lives in Redis (`caracms:publish:last`), not in memory.
+- **Status reads never ask GitHub**, except `check()`'s once-a-minute ref read (started,
+  never awaited: the poll answers with what's known) and the deployment reads while a
+  publish is in flight (at most every 10 s). Every GitHub request times out after 20 s.
+- **The startup check runs in `createLiveEditor`**, once `commitPending` is filled, so a
+  merge from `main` at startup commits pending autosaves first (Decision 8).
+- **Nothing polls Redis.** The client connects on the first command and closes after 30 s idle.
+- **Paths:** the copy and every message use paths relative to the site's folder
+  (`content/pages/index.json`); `repoPath` is joined only at the git boundary.
+
+The throwaway repo's scripts are in `../../scripts/throwaway/` (`seed.ts`, `run.ts`).

package/src/live/auth/allow-rules.ts

@@ -0,0 +1,70 @@
+/**
+ * The whitelist's rules for one entry (M4 Decision 15), browser-safe (no imports), so
+ * the editor's Site Settings form checks an entry as it's typed by exactly the rules
+ * the server applies (M5a Decision 10). allow.ts re-exports these; nothing here changed
+ * when they moved.
+ */
+/** Public mail domains: never a domain entry. The template's list, as is. */
+export const PUBLIC_MAIL_DOMAINS: ReadonlySet<string> = new Set([
+	'gmail.com',
+	'googlemail.com',
+	'outlook.com',
+	'hotmail.com',
+	'live.com',
+	'msn.com',
+	'icloud.com',
+	'me.com',
+	'mac.com',
+	'yahoo.com',
+	'yahoo.co.nz',
+	'aol.com',
+	'proton.me',
+	'protonmail.com',
+	'gmx.com',
+	'xtra.co.nz',
+	// Regional versions and NZ internet providers.
+	'hotmail.co.nz',
+	'hotmail.co.uk',
+	'hotmail.com.au',
+	'outlook.co.nz',
+	'outlook.com.au',
+	'live.co.nz',
+	'live.com.au',
+	'yahoo.co.uk',
+	'yahoo.com.au',
+	'ymail.com',
+	'rocketmail.com',
+	'clear.net.nz',
+	'vodafone.co.nz',
+	'slingshot.co.nz',
+	'orcon.net.nz',
+	'paradise.net.nz',
+	'ihug.co.nz',
+]);
+
+const ADDRESS_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const DOMAIN_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/;
+/** Longest address accepted (RFC 5321's limit). */
+const MAX_ADDRESS = 254;
+
+/** An address as it's compared and stored: trimmed and lower-cased, or '' if it isn't one. */
+export function normaliseEmail(value: unknown): string {
+	if (typeof value !== 'string') return '';
+	const address = value.trim().toLowerCase();
+	return address.length <= MAX_ADDRESS && ADDRESS_RE.test(address) ? address : '';
+}
+
+export type AllowEntry = { kind: 'address' | 'domain'; value: string } | { kind: 'public-domain' | 'invalid'; value: string };
+
+/** What one whitelist entry is. */
+export function parseAllowEntry(value: unknown): AllowEntry {
+	const entry = typeof value === 'string' ? value.trim().toLowerCase() : '';
+	if (entry.startsWith('@')) {
+		const domain = entry.slice(1);
+		if (!DOMAIN_RE.test(domain)) return { kind: 'invalid', value: entry };
+		if (PUBLIC_MAIL_DOMAINS.has(domain)) return { kind: 'public-domain', value: entry };
+		return { kind: 'domain', value: domain };
+	}
+	if (normaliseEmail(entry)) return { kind: 'address', value: entry };
+	return { kind: 'invalid', value: entry };
+}

package/src/live/auth/allow.ts

@@ -0,0 +1,128 @@
+/**
+ * Who may sign in: the whitelist (M4 Decision 15; the template's `server/admin-access.mjs`).
+ *
+ * Two halves, one rule:
+ * - **The agency half, `CARACMS_ALLOW`**: comma-separated. Read once at startup
+ *   (mode.ts → `LiveSettings.allow`), so nobody can edit the agency out from the editor.
+ * - **The client half, `editors` in `content/site-settings.json`**, read from the
+ *   in-memory `drafts` copy on every check, so a change takes effect at once, with no
+ *   deploy. A missing file is an empty half. A file that doesn't parse, or whose
+ *   `editors` isn't a list of strings, is an empty half too, **logged once per version
+ *   of the file**.
+ *
+ * An entry is an exact address (`aoife@fernhill.ie`) or a whole domain (`@fernhill.ie`),
+ * lower-cased and trimmed. **A public mail domain is never accepted as a domain entry**:
+ * it's ignored, logged once (per entry, per half, per process). An exact address at one
+ * of those domains is fine. Anything that is neither shape is ignored the same way.
+ *
+ * The backup account is its own path (backup.ts), not on this list.
+ */
+import { createHash } from 'node:crypto';
+
+export { PUBLIC_MAIL_DOMAINS, normaliseEmail, parseAllowEntry, type AllowEntry } from './allow-rules.ts';
+import { normaliseEmail, parseAllowEntry } from './allow-rules.ts';
+
+export interface AllowList {
+	addresses: Set<string>;
+	domains: Set<string>;
+}
+
+type Log = (line: string) => void;
+
+/** Addresses and domains out of raw entries; public-domain and malformed ones dropped, each logged once. */
+export function compileAllowList(entries: readonly unknown[], source: string, log: Log, warned: Set<string>): AllowList {
+	const addresses = new Set<string>();
+	const domains = new Set<string>();
+	for (const raw of entries) {
+		const parsed = parseAllowEntry(raw);
+		if (parsed.kind === 'address') addresses.add(parsed.value);
+		else if (parsed.kind === 'domain') domains.add(parsed.value);
+		else {
+			const key = `${source}\u0000${parsed.value}`;
+			if (warned.has(key)) continue;
+			warned.add(key);
+			log(
+				parsed.kind === 'public-domain'
+					? `ignoring "${parsed.value}" in ${source}: a public mail domain can't be a whole-domain entry (add exact addresses instead).`
+					: `ignoring "${printable(parsed.value)}" in ${source}: not an email address or @domain.`,
+			);
+		}
+	}
+	return { addresses, domains };
+}
+
+/** Whether a normalised address matches a list: the exact address, or its domain. */
+export function matchesAllowList(email: string, list: AllowList): boolean {
+	if (!email) return false;
+	if (list.addresses.has(email)) return true;
+	return list.domains.has(email.slice(email.lastIndexOf('@') + 1));
+}
+
+/**
+ * The client half's entries out of Site Settings' text. Null text (no file) is an
+ * empty half; text that doesn't parse, or an `editors` that isn't a list of strings,
+ * is an empty half plus a reason to log.
+ */
+export function editorsFrom(text: string | null): { entries: string[]; problem: string | null } {
+	if (text === null) return { entries: [], problem: null };
+	let doc: unknown;
+	try {
+		doc = JSON.parse(text);
+	} catch {
+		return { entries: [], problem: "it isn't valid JSON" };
+	}
+	if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return { entries: [], problem: "it isn't a JSON object" };
+	const editors = (doc as Record<string, unknown>).editors;
+	if (editors === undefined) return { entries: [], problem: null };
+	if (!Array.isArray(editors) || !editors.every((e) => typeof e === 'string')) return { entries: [], problem: '"editors" isn\'t a list of strings' };
+	return { entries: editors as string[], problem: null };
+}
+
+export interface Whitelist {
+	/** Whether this address may sign in right now. */
+	allows(email: unknown): boolean;
+}
+
+/**
+ * The whitelist over both halves. `agency` is CARACMS_ALLOW's entries; `readSettings`
+ * gives Site Settings' current text from the `drafts` copy (or null), read on every
+ * check. The compiled client half is cached per version of the file.
+ */
+export function createWhitelist(options: {
+	agency: readonly string[];
+	readSettings: () => string | null;
+	settingsFile: string;
+	log: Log;
+}): Whitelist {
+	const warned = new Set<string>();
+	const agency = compileAllowList(options.agency, 'CARACMS_ALLOW', options.log, warned);
+	let cached: { text: string | null; list: AllowList } | null = null;
+	const loggedVersions = new Set<string>();
+	const client = (): AllowList => {
+		const text = options.readSettings();
+		if (cached && cached.text === text) return cached.list;
+		const { entries, problem } = editorsFrom(text);
+		if (problem) {
+			const version = createHash('sha256').update(text ?? '').digest('hex');
+			if (!loggedVersions.has(version)) {
+				loggedVersions.add(version);
+				options.log(`${options.settingsFile}: ${problem}, so its editors list is empty; only CARACMS_ALLOW (and the backup account) can sign in.`);
+			}
+		}
+		const list = compileAllowList(entries, `${options.settingsFile} → editors`, options.log, warned);
+		cached = { text, list };
+		return list;
+	};
+	return {
+		allows(email) {
+			const address = normaliseEmail(email);
+			if (!address) return false;
+			return matchesAllowList(address, agency) || matchesAllowList(address, client());
+		},
+	};
+}
+
+function printable(value: string): string {
+	const shown = JSON.stringify(value).slice(1, -1);
+	return shown.length > 80 ? `${shown.slice(0, 77)}...` : shown;
+}

package/src/live/auth/auth.ts

@@ -0,0 +1,155 @@
+/**
+ * Sign-in's pieces, built once per process over the live runtime (M4 Phase 3):
+ * the whitelist, link tokens and rate limits in Redis, the backup account and the
+ * session. The guard (guard.ts) and the sign-in pages (login.ts) share one of these.
+ *
+ * `identify()` is the per-request check: the signed cookie, then **the whitelist
+ * again** (a `link` session whose address is no longer on it is `removed`, Decision
+ * 11), or the backup account with the same username and password as at sign-in.
+ * It makes no Redis call: the whitelist's client half is read from the in-memory
+ * `drafts` copy, so a guard check never wakes Redis.
+ */
+import { SITE_SETTINGS_FILE } from '../git.ts';
+import type { Person } from '../messages.ts';
+import type { RedisClient } from '../redis.ts';
+import { createWhitelist, type Whitelist } from './allow.ts';
+import { deliverLink, type Delivery } from './email.ts';
+import { createLinkStore, createRateLimits, type LinkStore, type RateLimits } from './links.ts';
+import {
+	backupConfig,
+	backupPerson,
+	clearedSessionCookie,
+	freshPayload,
+	readCookie,
+	safeEqual,
+	SESSION_MAX_AGE_S,
+	SESSION_RENEW_MS,
+	sessionCookie,
+	sessionCookieName,
+	signSession,
+	verifySession,
+	type BackupConfig,
+	type SessionPayload,
+} from './session.ts';
+
+export type SignedOutReason = 'signed-out' | 'removed';
+
+export type Identity =
+	| { state: 'in'; person: Person; payload: SessionPayload; /** A renewed Set-Cookie value, when the cookie is over an hour old. */ renew: string | null }
+	| { state: 'out'; reason: SignedOutReason };
+
+export interface AuthOptions {
+	secret: string;
+	/** CARACMS_ALLOW's entries (mode.ts → LiveSettings.allow). */
+	agency: readonly string[];
+	backup: { user: string; password: string } | null;
+	/** Secure cookies (`__Host-`, `Secure`): a production server. */
+	secure: boolean;
+	redis: RedisClient;
+	/** Site Settings' text from the `drafts` copy, or null. */
+	readSettings: () => string | null;
+	/** The site's name, for the email and the confirm page: a getter reads Site Settings' brand as committed (M5a Decision 10). */
+	siteName: string | (() => string);
+	/**
+	 * The origin emailed links point at (the site's public address). Required to email
+	 * a link: a request's own Host header is never used for an emailed link, or anyone
+	 * could have a real token mailed out pointing at their own host.
+	 */
+	siteOrigin: string | null;
+	env: Record<string, string | undefined>;
+	now?: () => number;
+	log?: (line: string) => void;
+	/** Tests: replace the delivery (email or log). */
+	deliver?: typeof deliverLink;
+}
+
+export interface Auth {
+	readonly secure: boolean;
+	readonly cookieName: string;
+	readonly whitelist: Whitelist;
+	readonly links: LinkStore;
+	readonly limits: RateLimits;
+	readonly backup: BackupConfig;
+	/** Read on each use: Site Settings' brand name can change while the server runs (M5a). */
+	readonly siteName: string;
+	readonly now: () => number;
+	readonly log: (line: string) => void;
+	identify(cookieHeader: string | null): Identity;
+	/** The Set-Cookie value for a new session. */
+	startSession(identity: { kind: 'link'; email: string } | { kind: 'backup' }): string;
+	clearCookie(): string;
+	/** Issue and deliver a link, after the response. Never throws. */
+	sendLink(email: string, next: string, requestOrigin: string): Promise<Delivery | 'not-sent'>;
+	/** Links being sent right now (tests wait on them). */
+	readonly sending: Set<Promise<unknown>>;
+}
+
+export function createAuth(options: AuthOptions): Auth {
+	const now = options.now ?? Date.now;
+	const log = options.log ?? ((line: string) => console.log(`[caracms] sign-in: ${line}`));
+	const backup = backupConfig(options.backup, options.secret, log);
+	const whitelist = createWhitelist({ agency: options.agency, readSettings: options.readSettings, settingsFile: SITE_SETTINGS_FILE, log });
+	const links = createLinkStore(options.redis);
+	const limits = createRateLimits(options.redis);
+	const cookieName = sessionCookieName(options.secure);
+	const sending = new Set<Promise<unknown>>();
+	const cookieFor = (payload: SessionPayload) => sessionCookie(signSession(payload, options.secret), { secure: options.secure });
+
+	return {
+		secure: options.secure,
+		cookieName,
+		whitelist,
+		links,
+		limits,
+		backup,
+		get siteName() {
+			return typeof options.siteName === 'function' ? options.siteName() : options.siteName;
+		},
+		now,
+		log,
+		sending,
+		identify(cookieHeader) {
+			const payload = verifySession(readCookie(cookieHeader, cookieName), options.secret, now());
+			if (!payload) return { state: 'out', reason: 'signed-out' };
+			let person: Person;
+			if (payload.kind === 'link') {
+				if (!whitelist.allows(payload.email)) return { state: 'out', reason: 'removed' };
+				person = { email: payload.email };
+			} else {
+				// Same username AND the same password as at sign-in, and the account still on.
+				const ok = backup.enabled && safeEqual(payload.user, backup.user) && safeEqual(payload.fingerprint, backup.fingerprint);
+				if (!ok) return { state: 'out', reason: 'signed-out' };
+				person = backupPerson(backup.user);
+			}
+			const renew = now() - payload.renewed > SESSION_RENEW_MS ? cookieFor({ ...payload, renewed: now(), expires: now() + SESSION_MAX_AGE_S * 1000 }) : null;
+			return { state: 'in', person, payload, renew };
+		},
+		startSession(identity) {
+			if (identity.kind === 'link') return cookieFor(freshPayload({ kind: 'link', email: identity.email }, now()));
+			if (!backup.enabled) throw new Error('the backup account is off');
+			return cookieFor(freshPayload({ kind: 'backup', user: backup.user, fingerprint: backup.fingerprint }, now()));
+		},
+		clearCookie: () => clearedSessionCookie({ secure: options.secure }),
+		sendLink(email, next, requestOrigin) {
+			const work = (async (): Promise<Delivery | 'not-sent'> => {
+				try {
+					const emailing = options.env['NODE_ENV'] === 'production';
+					const origin = options.siteOrigin ?? (emailing ? null : requestOrigin);
+					if (!origin) {
+						log("no sign-in link sent: the site's public address isn't known (set Astro's `site`, or run on Railway, which sets RAILWAY_PUBLIC_DOMAIN).");
+						return 'not-sent';
+					}
+					const token = await links.issue(email, next);
+					const link = `${origin}/admin/login/confirm?token=${token}`;
+					return await (options.deliver ?? deliverLink)({ to: email, link, siteName: typeof options.siteName === 'function' ? options.siteName() : options.siteName, env: options.env, log });
+				} catch (error) {
+					log(`could not issue a sign-in link: ${error instanceof Error ? error.message : String(error)}`);
+					return 'not-sent';
+				}
+			})();
+			sending.add(work);
+			void work.finally(() => sending.delete(work));
+			return work;
+		},
+	};
+}

package/src/live/auth/email.ts

@@ -0,0 +1,84 @@
+/**
+ * The sign-in link email, and the one place that decides whether it's emailed or
+ * logged (M4 Decision 14; the template's `server/login-email.mjs`).
+ *
+ * **Only when `NODE_ENV` is `production`** is it sent, through Resend
+ * (`RESEND_API_KEY`) from `FORMS_FROM`. Everywhere else the link is printed to the
+ * server log and nothing is sent, so no test from a laptop reaches anyone's inbox.
+ * The email names the site by its brand name. The link carries only the token.
+ *
+ * The HTML part is one table layout with inline styles (mail clients strip `<style>`),
+ * the system font stack, no images; the plain-text part says the same.
+ */
+import { sendEmail, sendsEmail } from '../../email.ts';
+
+export { RESEND_URL } from '../../email.ts';
+const FONT = "ui-sans-serif,system-ui,-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif";
+
+const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+
+export function buildLinkEmail({ siteName, link, email }: { siteName: string; link: string; email: string }): { subject: string; text: string; html: string } {
+	const site = siteName.trim();
+	const subject = site ? `Sign in to the ${site} website` : 'Sign in to the website';
+	const button = site ? `Sign in to ${site}` : 'Sign in';
+	const expiry = 'The link expires in 15 minutes and works once.';
+	const ignore = "Didn't ask for this? Ignore it.";
+	const text = [subject, '', `Open this link and press "Sign in" to sign in as ${email}:`, '', link, '', expiry, '', ignore, ''].join('\n');
+	const href = escapeHtml(link);
+	const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light">
+<title>${escapeHtml(subject)}</title>
+</head>
+<body style="margin:0;padding:0;background:#f5f5f2;">
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="background:#f5f5f2;font-family:${FONT};">
+<tr><td align="center" style="padding:32px 16px;">
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="max-width:480px;background:#ffffff;border:1px solid #e3e3de;border-radius:10px;">
+<tr><td style="padding:28px 28px 8px;font-family:${FONT};font-size:20px;line-height:1.3;font-weight:600;color:#1b1b19;">${escapeHtml(subject)}</td></tr>
+<tr><td style="padding:0 28px 20px;font-family:${FONT};font-size:15px;line-height:1.5;color:#1b1b19;">Sign in as <strong>${escapeHtml(email)}</strong>.</td></tr>
+<tr><td style="padding:0 28px 20px;">
+<table role="presentation" cellpadding="0" cellspacing="0" border="0"><tr><td style="background:#1b1b19;border-radius:6px;">
+<a href="${href}" style="display:inline-block;padding:13px 22px;font-family:${FONT};font-size:15px;font-weight:600;line-height:1;color:#ffffff;text-decoration:none;border-radius:6px;">${escapeHtml(button)}</a>
+</td></tr></table>
+</td></tr>
+<tr><td style="padding:0 28px 8px;font-family:${FONT};font-size:13px;line-height:1.5;color:#5e5e58;">${escapeHtml(expiry)}</td></tr>
+<tr><td style="padding:0 28px 24px;font-family:${FONT};font-size:13px;line-height:1.5;color:#5e5e58;">${escapeHtml(ignore)}</td></tr>
+<tr><td style="padding:16px 28px 24px;border-top:1px solid #e3e3de;font-family:${FONT};font-size:12px;line-height:1.5;color:#5e5e58;word-break:break-all;">Button not working? Paste this into your browser:<br><a href="${href}" style="color:#1b1b19;">${href}</a></td></tr>
+</table>
+</td></tr>
+</table>
+</body>
+</html>
+`;
+	return { subject, text, html };
+}
+
+export type Delivery = 'sent' | 'logged' | 'failed';
+
+/**
+ * Email the link in production, log it everywhere else. Never throws: a Resend failure
+ * is logged, and the page never says whether a link went out. The sending is the
+ * package's one sender (../../email.ts, M6 Decision 8).
+ */
+export async function deliverLink(input: {
+	to: string;
+	link: string;
+	siteName: string;
+	env: Record<string, string | undefined>;
+	log: (line: string) => void;
+	fetch?: typeof fetch;
+}): Promise<Delivery> {
+	const { to, link, siteName, env, log } = input;
+	if (!sendsEmail(env)) {
+		log(`sign-in link for ${to} (not emailed outside production): ${link}`);
+		return 'logged';
+	}
+	const { subject, text, html } = buildLinkEmail({ siteName, link, email: to });
+	const result = await sendEmail({ to: [to], subject, text, html }, { env, fetch: input.fetch });
+	if (result.status === 'sent') return 'sent';
+	log(`could not email a sign-in link: ${result.error}`);
+	return 'failed';
+}

package/src/live/auth/guard.ts

@@ -0,0 +1,111 @@
+/**
+ * The guard (M4 Decision 14): **one check on path prefixes**, `/admin` and
+ * `/_caracms/`, in live mode only. It knows no list of the editor's routes, so every
+ * route Phase 2 adds under those prefixes is covered without this file changing.
+ *
+ * - **Let through**: the sign-in pages, exactly (`/admin/login` and its own subpages,
+ *   letters and hyphens only, no encoding), `POST /_caracms/github` (the webhook,
+ *   which checks GitHub's signature instead, Decision 14), and `POST /_caracms/form`
+ *   (the public forms' endpoint, M6 Decision 5: anyone, from anywhere).
+ * - **Every write** (any method but GET and HEAD) **also requires the same origin**
+ *   (request.ts → isSameOrigin), else 403, checked before the session.
+ * - **No session**: a page (`/admin…`) redirects to sign-in with `next`; an API
+ *   (`/_caracms/…`) answers 401 JSON, `{ error, code: 'signed-out', reason, signIn }`. **When the cookie is
+ *   valid but the address is no longer on the whitelist, `reason` is `removed`**
+ *   (Decision 11); otherwise `signed-out`. The page redirect is the same for everyone.
+ * - **A pass** gives the person (the caller records it with `setPerson`) and, when the
+ *   cookie is over an hour old, a renewed one to set.
+ *
+ * Which paths count is decided on a normalised path (percent-decoded, lower-cased,
+ * repeated slashes collapsed), so `/ADMIN`, `/%61dmin` and `//admin` are guarded too.
+ * A path that won't decode is guarded. The let-through is decided on the raw path.
+ */
+import type { Person } from '../messages.ts';
+import type { Auth, SignedOutReason } from './auth.ts';
+import { isRead, isSameOrigin } from './request.ts';
+import { cleanNext, LOGIN_PATH, loginHref } from './session.ts';
+
+/** Whether the guard looks at this path at all. */
+export function isGuardedPath(rawPathname: string): boolean {
+	let path: string;
+	try {
+		path = decodeURIComponent(rawPathname);
+	} catch {
+		return true;
+	}
+	path = path.replace(/\\/g, '/').replace(/\/{2,}/g, '/').toLowerCase();
+	return path === '/admin' || path.startsWith('/admin/') || path.startsWith('/admin.') || path === '/_caracms' || path.startsWith('/_caracms/');
+}
+
+const LOGIN_RE = /^\/admin\/login(?:\/[a-z-]+)?\/?$/;
+
+/** The sign-in pages, the webhook and the form endpoint: reached with no session. */
+export function isLetThrough(rawPathname: string, method: string): boolean {
+	if (LOGIN_RE.test(rawPathname)) return true;
+	if (method !== 'POST') return false;
+	return rawPathname === '/_caracms/github' || rawPathname === '/_caracms/github/' || isFormEndpoint(rawPathname);
+}
+
+/** `/_caracms/form`, exactly (a trailing slash allowed, no encoding): public in every mode (M6 Decision 5). */
+export const isFormEndpoint = (rawPathname: string): boolean => rawPathname === '/_caracms/form' || rawPathname === '/_caracms/form/';
+
+/** An API path: answered with JSON, never a redirect. */
+const isApi = (rawPathname: string) => !/^\/+admin(?:[/.]|$)/i.test(safeDecode(rawPathname));
+const safeDecode = (s: string) => {
+	try {
+		return decodeURIComponent(s);
+	} catch {
+		return s;
+	}
+};
+
+/** The 401 body an API answers with no session. Phase 4's signed-out state reads it. */
+export interface SignedOutBody {
+	error: string;
+	/** Always `signed-out`: types.ts → ApiError's code for a 401. */
+	code: 'signed-out';
+	/** `removed`: the cookie was valid but the address is no longer on the whitelist (Decision 11). */
+	reason: SignedOutReason;
+	/** Where "Sign in again" goes (opened in a new tab). */
+	signIn: string;
+}
+
+export interface ForbiddenBody {
+	error: string;
+	code: 'cross-origin';
+}
+
+const NO_STORE = { 'Cache-Control': 'private, no-store' };
+const json = (status: number, body: unknown) =>
+	new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json; charset=utf-8', ...NO_STORE } });
+
+export const SIGNED_OUT_MESSAGE: Record<SignedOutReason, string> = {
+	'signed-out': "You're signed out. Sign in again to keep editing.",
+	removed: "You can no longer sign in to this site, so your latest changes couldn't be kept.",
+};
+
+export type GuardResult = { kind: 'skip' } | { kind: 'pass'; person: Person; setCookie: string | null } | { kind: 'respond'; response: Response };
+
+export function guard(request: Request, auth: Auth): GuardResult {
+	const url = new URL(request.url);
+	const raw = url.pathname;
+	if (!isGuardedPath(raw) || isLetThrough(raw, request.method)) return { kind: 'skip' };
+	const api = isApi(raw);
+
+	if (!isRead(request.method) && !isSameOrigin(request)) {
+		const error = 'This only takes requests from the editor on this site.';
+		if (api) return { kind: 'respond', response: json(403, { error, code: 'cross-origin' } satisfies ForbiddenBody) };
+		return { kind: 'respond', response: new Response(error, { status: 403, headers: { 'Content-Type': 'text/plain; charset=utf-8', ...NO_STORE } }) };
+	}
+
+	const who = auth.identify(request.headers.get('cookie'));
+	if (who.state === 'in') return { kind: 'pass', person: who.person, setCookie: who.renew };
+
+	if (api) {
+		const body: SignedOutBody = { error: SIGNED_OUT_MESSAGE[who.reason], code: 'signed-out', reason: who.reason, signIn: LOGIN_PATH };
+		return { kind: 'respond', response: json(401, body) };
+	}
+	// A page: the same redirect for everyone (the sign-in pages never say why).
+	const next = cleanNext(`${raw}${url.search}`);
+	return { kind: 'respond', response: new Response(null, { status: 303, headers: { Location: loginHref({}, next), ...NO_STORE } }) };
+}

package/src/live/auth/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Sign-in for the running server (M4 Phase 3): one `Auth` per process over the live
+ * runtime, shared by the guard (middleware.ts) and the sign-in route
+ * (`../../editor/routes/login/login.ts`). Map of this folder:
+ *
+ * | File | What |
+ * |---|---|
+ * | `allow.ts` | The whitelist: `PUBLIC_MAIL_DOMAINS`, entries, `createWhitelist` (CARACMS_ALLOW + Site Settings' `editors`) |
+ * | `session.ts` | The signed cookie, the backup account's config and fingerprint, `cleanNext` |
+ * | `links.ts` | Link tokens (SHA-256 only, 15 min, GETDEL) and rate limits, in Redis |
+ * | `email.ts` | The link email: Resend in production, the server log otherwise |
+ * | `request.ts` | The client IP (X-Real-IP first), same-origin |
+ * | `auth.ts` | `createAuth`: the pieces together, `identify()` per request |
+ * | `guard.ts` | The one check on `/admin` and `/_caracms/` |
+ * | `login.ts` | The `/admin/login…` pages |
+ * | `views.ts` | Their HTML, CSS and the one script |
+ * | `middleware.ts` | The guard as Astro middleware |
+ * | `routes.ts` | `LOGIN_ROUTES`, for the integration |
+ */
+import { SITE_SETTINGS_FILE, type ResolvedSite } from '../../config.ts';
+import { brandFrom } from '../../editor/brand.ts';
+import type { LiveSettings } from '../mode.ts';
+import { liveRuntime } from '../runtime.ts';
+import { createAuth, type Auth } from './auth.ts';
+
+const SHARED = Symbol.for('caracms.auth');
+type Shared = { [SHARED]?: Promise<Auth> };
+
+/**
+ * The site's public origin for emailed links: Astro's `site`, else Railway's public
+ * domain. Never a request's Host header (auth.ts → `siteOrigin`).
+ */
+export function publicOrigin(astroSite: URL | undefined, env: Record<string, string | undefined> = process.env): string | null {
+	if (astroSite) return astroSite.origin;
+	const domain = env['RAILWAY_PUBLIC_DOMAIN']?.trim();
+	return domain ? `https://${domain}` : null;
+}
+
+/** The process's Auth, built on first use over the shared live runtime. */
+export function authFor(site: ResolvedSite, settings: LiveSettings, astroSite?: URL): Promise<Auth> {
+	const g = globalThis as Shared;
+	g[SHARED] ??= liveRuntime(site, settings)
+		.then((rt) =>
+			createAuth({
+				secret: settings.secret,
+				agency: settings.allow,
+				backup: settings.backup,
+				secure: settings.production,
+				redis: rt.redis,
+				readSettings: () => rt.git.read(SITE_SETTINGS_FILE),
+				// M5a Decision 10: Site Settings' brand name as committed in `drafts`.
+				siteName: () => brandFrom(rt.git.read(SITE_SETTINGS_FILE), site).name,
+				siteOrigin: publicOrigin(astroSite),
+				env: process.env,
+				now: rt.now,
+			}),
+		)
+		.catch((error: unknown) => {
+			delete g[SHARED];
+			throw error;
+		});
+	return g[SHARED];
+}
+
+/** Forget the shared Auth (tests). */
+export function resetAuth(): void {
+	delete (globalThis as Shared)[SHARED];
+}