emdash-multisite 0.0.0-stage → 0.7.0

package/src/dialect.ts

@@ -0,0 +1,109 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type {
+	CompiledQuery,
+	DatabaseConnection,
+	Dialect,
+	Driver,
+	QueryResult,
+	TransactionSettings,
+} from "kysely";
+import { rewriteParams, rewriteSql, suffixFor, translateRows } from "./rewrite.ts";
+
+// On globalThis so duplicated bundle chunks share one store.
+const SITE_STORE = Symbol.for("emdash-multisite:site-store");
+const siteStore = ((globalThis as Record<symbol, unknown>)[SITE_STORE] ??= new AsyncLocalStorage<string>()) as AsyncLocalStorage<string>;
+
+/**
+ * Run `fn` as `site`. Used by provisioning, cron and anything else that runs
+ * outside a request (requests get their site baked into a per-site Kysely).
+ */
+export const runAsSite = <T>(site: string, fn: () => T): T => siteStore.run(site, fn);
+export const currentSite = (): string | undefined => siteStore.getStore();
+
+/**
+ * Wrap `inner` so every query is rewritten for the site `getSite()` returns.
+ *
+ * All wrapped dialects built from the same `inner` share ONE inner driver:
+ * SQLite has a single connection, and its mutex lives in the driver, so
+ * per-site drivers would let one site's transaction swallow another's queries.
+ */
+export function siteDialect(inner: Dialect, getSite: () => string, primary: string): Dialect {
+	const shared = sharedDriver(inner);
+	return {
+		createAdapter: () => scopeBatch(inner.createAdapter(), getSite, primary),
+		createQueryCompiler: () => inner.createQueryCompiler(),
+		createIntrospector: (db) => inner.createIntrospector(db),
+		createDriver: (): Driver => ({
+			init: () => shared.init(),
+			// ponytail: no-op; the shared inner driver outlives any one site's Kysely.
+			destroy: async () => {},
+			acquireConnection: async () => scoped(await shared.driver.acquireConnection(), getSite, primary),
+			beginTransaction: (c: DatabaseConnection, s: TransactionSettings) =>
+				shared.driver.beginTransaction(unscoped(c), s),
+			commitTransaction: (c) => shared.driver.commitTransaction(unscoped(c)),
+			rollbackTransaction: (c) => shared.driver.rollbackTransaction(unscoped(c)),
+			releaseConnection: (c) => shared.driver.releaseConnection(unscoped(c)),
+		}),
+	};
+}
+
+/**
+ * D1 has no transactions, so EmDash calls `adapter.executeAtomicBatch(queries)`
+ * (content writes, block types, ...). That path never touches a connection, so
+ * the per-connection rewrite above is skipped and the writes land in the
+ * PRIMARY site's tables. Wrap it with the same rewrite.
+ */
+function scopeBatch<A extends object>(adapter: A, getSite: () => string, primary: string): A {
+	const batch = (adapter as { executeAtomicBatch?: (qs: CompiledQuery[]) => Promise<QueryResult<unknown>[]> })
+		.executeAtomicBatch;
+	if (typeof batch !== "function") return adapter;
+	(adapter as { executeAtomicBatch: typeof batch }).executeAtomicBatch = async (qs) => {
+		const suffix = suffixFor(getSite(), primary);
+		if (!suffix) return batch.call(adapter, qs);
+		const results = await batch.call(
+			adapter,
+			qs.map((q) => ({ ...q, sql: rewriteSql(q.sql, suffix), parameters: rewriteParams(q.sql, q.parameters, suffix) })),
+		);
+		return results.map((r, i) => ({ ...r, rows: translateRows(qs[i]!.sql, r.rows as never, suffix) }));
+	};
+	return adapter;
+}
+const sharedByInner = new WeakMap<Dialect, { driver: Driver; init: () => Promise<void> }>();
+function sharedDriver(inner: Dialect) {
+	let s = sharedByInner.get(inner);
+	if (!s) {
+		const driver = inner.createDriver();
+		let started: Promise<void> | undefined;
+		s = { driver, init: () => (started ??= driver.init()) };
+		sharedByInner.set(inner, s);
+	}
+	return s;
+}
+
+const REAL = Symbol("realConnection");
+type Scoped = DatabaseConnection & { [REAL]: DatabaseConnection };
+const unscoped = (c: DatabaseConnection): DatabaseConnection => (c as Scoped)[REAL] ?? c;
+
+function scoped(real: DatabaseConnection, getSite: () => string, primary: string): DatabaseConnection {
+	const conn: Scoped = {
+		[REAL]: real,
+		async executeQuery<R>(q: CompiledQuery): Promise<QueryResult<R>> {
+			const suffix = suffixFor(getSite(), primary);
+			if (!suffix) return real.executeQuery<R>(q);
+			const result = await real.executeQuery<R>({
+				...q,
+				sql: rewriteSql(q.sql, suffix),
+				parameters: rewriteParams(q.sql, q.parameters, suffix),
+			});
+			return { ...result, rows: translateRows(q.sql, result.rows, suffix) };
+		},
+		streamQuery<R>(q: CompiledQuery, chunkSize: number) {
+			const suffix = suffixFor(getSite(), primary);
+			return real.streamQuery<R>(
+				suffix ? { ...q, sql: rewriteSql(q.sql, suffix), parameters: rewriteParams(q.sql, q.parameters, suffix) } : q,
+				chunkSize,
+			);
+		},
+	};
+	return conn;
+}

package/src/edge-cache.ts

@@ -0,0 +1,249 @@
+/**
+ * Host-aware edge cache helpers. Design, evidence and the incident behind it:
+ * emdash-plan/product/hostmyemdash-edge-cache-design.md
+ *
+ * Why this exists: Cloudflare Workers Cache keys entries by path + query (+ Worker version), NOT by hostname. One Worker serves
+ * every site, so the host must be put into the key by a gateway (ctx.props of a cached inner entrypoint). The host Worker
+ * (src/worker.ts) owns the two entrypoints; this module owns the rules, so they are testable under plain Node.
+ *
+ * Principles: default-deny (anything not provably public + anonymous + 200 is `no-store`), fail closed (a response that cannot
+ * be tagged to a site is never stored, because it could not be purged), and purge is best-effort but never throws.
+ */
+import { isThemed } from "./rules.ts";
+
+/** Internal response header: the middleware tells the cache layer which site rendered the response. Stripped before storing. */
+export const SITE_HEADER = "x-ms-site";
+/** Internal REQUEST header set by the cached entrypoint: only then does the middleware label the response with its site. */
+export const EDGE_REQUEST_HEADER = "x-ms-edge";
+/** Name of the cached entrypoint exported by the host Worker. */
+export const CACHE_ENTRYPOINT = "PublicCache";
+export const siteTag = (site: string) => `site:${site}`;
+
+// Core serves these per site (they are not themed) but they are public and safe to cache per host.
+const PUBLIC_FILES = /^\/(?:llms\.txt|rss\.xml|robots\.txt|sitemap(?:-[^/]+)?\.xml)$/;
+const CACHEABLE_TYPE = /^(?:text\/(?:html|plain|xml)|application\/(?:xml|rss\+xml))/;
+
+/** Lowercase, drop the port and a trailing dot, so `Acme.com.:443` and `acme.com` share one entry. */
+export function normalizeHost(h: string): string {
+	return h.toLowerCase().replace(/:\d+$/, "").replace(/\.$/, "");
+}
+
+/** Anonymous = no Authorization, and no cookies except the privacy plugin's consent cookie (`c15t*`). Anything else counts as signed in. */
+export function isAnonymous(headers: Headers): boolean {
+	if (headers.has("authorization")) return false;
+	const cookie = headers.get("cookie");
+	if (!cookie) return true;
+	return cookie.split(";").every((c) => {
+		const name = c.trim().split("=")[0] ?? "";
+		return name === "" || name.startsWith("c15t");
+	});
+}
+
+/** Request side (gateway): may this request be served from / stored in the shared cache? */
+export function cacheableRequest(method: string, url: URL, headers: Headers): boolean {
+	if (method !== "GET" && method !== "HEAD") return false;
+	if (url.search !== "") return false;
+	if (!isAnonymous(headers)) return false;
+	return isThemed(url.pathname) || PUBLIC_FILES.test(url.pathname);
+}
+
+/**
+ * Response side (inner entrypoint): the single choke point. Store only a clean anonymous 200 of an allowed type that the
+ * middleware tagged with its site. Everything else gets an explicit `no-store` (Workers Cache would otherwise cache a bare
+ * 404 for ~3 min and a bare 200 for ~2 h; verified in the spike). The internal site header is always removed.
+ */
+export function guardResponse(res: Response): Response {
+	const site = res.headers.get(SITE_HEADER);
+	const out = new Response(res.body, res);
+	out.headers.delete(SITE_HEADER);
+	const ok = res.status === 200 && !!site && !res.headers.has("set-cookie") && CACHEABLE_TYPE.test(res.headers.get("content-type") ?? "");
+	if (ok) {
+		// 1 h + 1 day stale-while-revalidate. Freshness comes from purging the site tag on every edit that changes a public page
+		// (hooks in plugin-entry.ts, mutation watcher in middleware.ts); the TTL is only the backstop if a purge is lost.
+		out.headers.set("cache-control", "public, max-age=3600, stale-while-revalidate=86400");
+		out.headers.set("cache-tag", siteTag(site));
+	} else {
+		out.headers.set("cache-control", "no-store");
+	}
+	return out;
+}
+
+/** Middleware side: label a successful GET/HEAD response with its site so the cache layer can tag it. */
+export function tagSite(res: Response, method: string, site: string): Response {
+	if (res.status !== 200 || (method !== "GET" && method !== "HEAD")) return res;
+	const out = new Response(res.body, res);
+	out.headers.set(SITE_HEADER, site);
+	return out;
+}
+
+// ---- Which admin writes change a public page -----------------------------------------------------------------------------
+// EmDash has plugin hooks for content and bylines only. Menus, widgets, settings, taxonomies, redirects, sections, media
+// edits and imports have none, so the middleware watches the admin API instead: a 2xx answer to one of these writes means an
+// authorized user changed something. Public routes (form submits, consent saves, ...) are deliberately not listed, otherwise
+// any visitor could burn the shared purge budget.
+const EDIT_API = "/_emdash/api/";
+const ALWAYS_EDIT: RegExp[] = [
+	/^(?:menus|widget-areas|settings|sections|taxonomies|redirects|schema|import)(?:\/|$)/,
+	/^admin\/(?:transfer\/imports\/[^/]+\/execute|plugins\/[^/]+\/(?:settings|enable|disable|uninstall))$/,
+	/^content\/[^/]+\/[^/]+\/terms\//, // term assignment to an entry
+	/^revisions\/[^/]+\/restore$/, // collections without revisions write the live row
+];
+const MEDIA_EDIT = /^media\/[^/]+(?:\/replace)?$/; // PUT/PATCH/DELETE only: new uploads change nothing public until used
+
+export type EditKind = "always" | "content-put" | "content-create";
+/** Does this request look like an admin write that can change a public page? `content-*` kinds need the body (see touchesPublicPage). */
+export function classifyEdit(method: string, pathname: string): EditKind | null {
+	if (method === "GET" || method === "HEAD" || method === "OPTIONS" || !pathname.startsWith(EDIT_API)) return null;
+	const rest = pathname.slice(EDIT_API.length).replace(/\/$/, "");
+	if (ALWAYS_EDIT.some((r) => r.test(rest))) return "always";
+	if (method !== "POST" && MEDIA_EDIT.test(rest)) return "always";
+	if ((method === "PUT" || method === "PATCH") && /^content\/[^/]+\/[^/]+$/.test(rest)) return "content-put";
+	if (method === "POST" && /^content\/[^/]+$/.test(rest)) return "content-create";
+	return null;
+}
+
+// Mirrors DRAFT_ONLY_UPDATE_KEYS in emdash core (emdash-runtime.ts): a save that sends only these stages a draft revision and
+// leaves the live page unchanged (autosave). Any other key (status, bylines, seo, publishedAt, ...) writes live columns.
+// A key core adds later makes us purge more often, never less.
+const DRAFT_ONLY_KEYS = new Set(["data", "slug", "locale", "skipRevision", "references", "actor", "migrateBlocks", "replaceBlocks", "_rev"]);
+export function touchesPublicPage(kind: EditKind, body: unknown): boolean {
+	if (kind === "always") return true;
+	if (typeof body !== "object" || body === null) return false;
+	const b = body as Record<string, unknown>;
+	if (kind === "content-create") return b.status === "published";
+	return Object.entries(b).some(([k, v]) => v !== undefined && !DRAFT_ONLY_KEYS.has(k));
+}
+
+/**
+ * Purge budget. Workers Cache purges always use Cloudflare's FREE-tier limits, whatever the plan: 5 requests per minute
+ * (bucket of 25), 100 tags per request, counted per ACCOUNT, so every tenant shares it. A rate-limited purge resolves
+ * `{ success: false }` instead of throwing, which is why every send is checked and retried. Ceiling: about two edit bursts
+ * per minute across the whole platform once the bucket is empty. Past that, switch to a per-site version in the cache key
+ * (no purge calls at all) or batch purges through one Durable Object. Do not call this per keystroke.
+ */
+const TRAIL_MS = 4000; // a render that began before the edit can finish after the first purge and re-store the old page
+const RETRY_MS = 13000; // one token refills every 12 s
+const MAX_TRIES = 3;
+const MAX_TAGS = 100;
+
+export interface PurgeEnv {
+	/** Purge these tags. Resolves false when the purge was not accepted (rate limit, error). Never throws. */
+	send(tags: string[]): Promise<boolean>;
+	sleep(ms: number): Promise<void>;
+	now(): number;
+	/** Keep background work alive after the response (waitUntil). */
+	defer(work: Promise<unknown>): void;
+}
+
+/**
+ * Per-isolate purge scheduler. A purge call resolves after the first send (callers never wait for the follow-ups). Then:
+ * - same-tick calls for different sites share one send (one budget token);
+ * - an edit that lands while a send is in flight is sent again right after it, never dropped;
+ * - every purged site is purged once more after TRAIL_MS (an edit during that wait pushes it back);
+ * - a rejected send is retried every RETRY_MS, MAX_TRIES attempts in total.
+ */
+export function createPurger(env: PurgeEnv, log: (e: Record<string, unknown>) => void = () => {}) {
+	const pending = new Set<string>();
+	const due = new Map<string, { at: number; tries: number }>();
+	let draining: Promise<boolean> | null = null;
+	let ticking = false;
+
+	const sendAll = async (sites: string[]) => {
+		let ok = true;
+		for (let i = 0; i < sites.length; i += MAX_TAGS) ok = (await env.send(sites.slice(i, i + MAX_TAGS).map(siteTag))) && ok;
+		return ok;
+	};
+	const schedule = (sites: string[], ms: number, tries: number) => {
+		for (const s of sites) due.set(s, { at: env.now() + ms, tries });
+		if (!ticking) {
+			ticking = true;
+			env.defer(tick());
+		}
+	};
+	const tick = async () => {
+		try {
+			while (due.size) {
+				const wait = Math.min(...[...due.values()].map((d) => d.at)) - env.now();
+				if (wait > 0) await env.sleep(wait);
+				const now = env.now();
+				const batch = [...due].filter(([, d]) => d.at <= now);
+				if (!batch.length) continue;
+				for (const [s] of batch) due.delete(s);
+				if (await sendAll(batch.map(([s]) => s))) continue;
+				for (const [s, d] of batch) {
+					if (d.tries + 1 >= MAX_TRIES) log({ event: "cache.purge_gave_up", site: s });
+					else if (!due.has(s)) due.set(s, { at: env.now() + RETRY_MS, tries: d.tries + 1 });
+				}
+			}
+		} finally {
+			ticking = false;
+		}
+	};
+	const drain = async () => {
+		let ok = true;
+		try {
+			await 0; // let same-tick callers join this batch
+			while (pending.size) {
+				const batch = [...pending];
+				pending.clear();
+				schedule(batch, TRAIL_MS, 0); // before the send: it supersedes any follow-up still waiting for these sites
+				const sent = await sendAll(batch);
+				ok = sent && ok;
+				if (!sent) schedule(batch, RETRY_MS, 1);
+			}
+		} finally {
+			draining = null;
+		}
+		return ok;
+	};
+	return (site: string): Promise<boolean> => {
+		pending.add(site);
+		return (draining ??= drain());
+	};
+}
+
+type CacheEntry = (o: unknown) => { purgeTag(t: string[]): Promise<{ success?: boolean; errors?: unknown } | undefined> };
+async function cacheEntry(): Promise<CacheEntry | null> {
+	try {
+		const specifier = "cloudflare:workers";
+		const { exports } = (await import(/* @vite-ignore */ specifier)) as { exports?: Record<string, CacheEntry | undefined> };
+		return exports?.[CACHE_ENTRYPOINT] ?? null;
+	} catch {
+		return null; // off Workers (Node/SQLite lab)
+	}
+}
+const log = (e: Record<string, unknown>) => console.log(JSON.stringify(e));
+const purger = createPurger(
+	{
+		async send(tags) {
+			try {
+				const entry = await cacheEntry();
+				if (!entry) return true; // nothing cached here, nothing to purge
+				const res = await entry({ props: { host: "purge", gpc: false } }).purgeTag(tags);
+				const ok = res?.success !== false;
+				log(ok ? { event: "cache.purged", tags } : { event: "cache.purge_failed", tags, errors: JSON.stringify(res?.errors ?? null).slice(0, 300) });
+				return ok;
+			} catch (e) {
+				log({ event: "cache.purge_failed", tags, error: String(e) });
+				return false;
+			}
+		},
+		sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+		now: Date.now,
+		defer(work) {
+			const specifier = "cloudflare:workers";
+			import(/* @vite-ignore */ specifier).then((m: { waitUntil?: (p: Promise<unknown>) => void }) => m.waitUntil?.(work), () => {});
+		},
+	},
+	log,
+);
+
+/**
+ * Drop every cached page of a site (all of its hostnames carry the same `site:<slug>` tag). Must run INSIDE the cached
+ * entrypoint (a purge from anywhere else reports success and does nothing; verified in the spike), so it calls an RPC method
+ * on it. Never throws. Returns whether the first purge was accepted; follow-ups (trailing purge, retries) run in the background.
+ */
+export async function purgeSiteCache(site: string): Promise<boolean> {
+	if (!(await cacheEntry())) return false;
+	return purger(site);
+}

package/src/fleet-actions.ts

@@ -0,0 +1,44 @@
+/**
+ * Run a fleet action picked on the control plane's Site page (see fleet-blocks.ts). Same rules as the
+ * HTTP routes in middleware.ts: state changes go through `transition`, purge needs a deleted site.
+ * Slow work (a purge drops ~90 tables, a retry may migrate and seed) continues after the response.
+ */
+import { after } from "emdash";
+import { backupSite } from "./backup.ts";
+import { runAsSite } from "./dialect.ts";
+import type { FleetAction } from "./fleet-blocks.ts";
+import { reconcile } from "./orgs.ts";
+import { purgeSite } from "./purge.ts";
+import { purgeSiteCache } from "./edge-cache.ts";
+import { readSiteState, writeSiteState } from "./registry.ts";
+import { transition, type StateAction } from "./rules.ts";
+import { scopeState } from "./scope.ts";
+import type { SitesConfig } from "./sites.ts";
+
+const STATE_ACTIONS = new Set<FleetAction>(["suspend", "resume", "delete", "restore"]);
+
+export async function runFleetAction(sites: SitesConfig, slug: string, action: FleetAction): Promise<{ ok: boolean; message: string }> {
+	const primary = scopeState().primary;
+	if (slug === primary) return { ok: false, message: "The control plane is not managed here." };
+	if (STATE_ACTIONS.has(action)) {
+		const result = transition(await readSiteState(slug), action as StateAction, { staff: true, owner: false });
+		if (!result.ok) return { ok: false, message: `Cannot ${action} "${slug}" in its current state.` };
+		await writeSiteState(slug, result.next ? { state: result.next, at: new Date().toISOString(), reason: `${action} from the fleet page` } : null);
+		await purgeSiteCache(slug);
+		return { ok: true, message: `${slug}: ${action} done.` };
+	}
+	if (action === "backup") {
+		const { bytes } = await runAsSite(primary, () => backupSite(slug));
+		return { ok: true, message: `${slug}: backed up (${Math.round(bytes / 1024)} KB).` };
+	}
+	if (action === "retry") {
+		after(() => runAsSite(primary, () => reconcile(sites, slug)).then(() => undefined));
+		return { ok: true, message: `${slug}: setup restarted. Reload in a minute.` };
+	}
+	if (action === "purge") {
+		if ((await readSiteState(slug))?.state !== "deleted") return { ok: false, message: `"${slug}" is not deleted.` };
+		after(() => runAsSite(primary, () => purgeSite(slug)).then(() => undefined));
+		return { ok: true, message: `${slug}: purge started. It takes about a minute.` };
+	}
+	return { ok: false, message: "Unknown action." };
+}

package/src/fleet-blocks.ts

@@ -0,0 +1,115 @@
+/**
+ * The fleet as an EmDash admin page (Block Kit), for staff on the control plane.
+ * Pure: takes the site list, returns blocks; no database, so a plain-Node self-check covers it
+ * (scripts/fleet.selfcheck.ts). The actions themselves run in fleet-actions.ts.
+ */
+import { isSiteId } from "./rewrite.ts";
+
+/** What the page needs to know about a site (a subset of `FleetSite`). */
+export interface FleetRow {
+	slug: string;
+	name: string;
+	ownerEmail: string | null;
+	status: "provisioning" | "ready" | "failed" | "unknown";
+	state: "active" | "suspended" | "deleted";
+	createdAt: string | null;
+	userCount: number;
+}
+
+export type FleetAction = "suspend" | "resume" | "delete" | "restore" | "retry" | "backup" | "purge";
+const ACTIONS: ReadonlySet<string> = new Set<FleetAction>(["suspend", "resume", "delete", "restore", "retry", "backup", "purge"]);
+export const ROW_ACTION_PREFIX = "fleet:";
+export const PURGE_FORM_ACTION = "fleet_purge";
+
+const LABELS: Record<FleetAction, string> = {
+	suspend: "Suspend",
+	resume: "Resume",
+	delete: "Delete (kept 14 days)",
+	restore: "Restore",
+	retry: "Retry setup",
+	backup: "Back up now",
+	purge: "Purge",
+};
+
+/** Actions that make sense for a site in its current state. Purge is not here: it has its own confirmed form. */
+export function actionsFor(site: FleetRow): FleetAction[] {
+	if (site.state === "deleted") return ["restore"];
+	if (site.state === "suspended") return ["resume", "backup", "delete"];
+	return site.status === "ready" ? ["suspend", "backup", "delete"] : ["retry", "suspend", "delete"];
+}
+
+/** Read a menu click: `fleet:<slug>` + the chosen value. `null` for anything else. */
+export function parseFleetAction(actionId: unknown, value: unknown): { slug: string; action: FleetAction } | null {
+	if (typeof actionId !== "string" || !actionId.startsWith(ROW_ACTION_PREFIX) || typeof value !== "string") return null;
+	const slug = actionId.slice(ROW_ACTION_PREFIX.length);
+	if (!isSiteId(slug) || !ACTIONS.has(value) || value === "purge") return null;
+	return { slug, action: value as FleetAction };
+}
+
+export function fleetBlocks(all: FleetRow[], primary: string): unknown[] {
+	const sites = all.filter((s) => s.slug !== primary);
+	const count = (f: (s: FleetRow) => boolean) => sites.filter(f).length;
+	const deleted = sites.filter((s) => s.state === "deleted");
+	const attention = count((s) => s.state === "active" && s.status !== "ready");
+	const blocks: unknown[] = [
+		{ type: "header", text: "Fleet" },
+		{
+			type: "stats",
+			items: [
+				{ label: "Sites", value: sites.length - deleted.length },
+				{ label: "Needs attention", value: attention, trend: attention ? "down" : "neutral" },
+				{ label: "Suspended", value: count((s) => s.state === "suspended") },
+				{ label: "Deleted, not purged", value: deleted.length },
+				{ label: "Users on sites", value: sites.reduce((n, s) => n + s.userCount, 0) },
+			],
+		},
+	];
+	blocks.push({
+		type: "table",
+		page_action_id: "fleet_page",
+		empty_text: "No sites yet.",
+		columns: [
+			{ key: "site", label: "Site", format: "code" },
+			{ key: "owner", label: "Owner" },
+			{ key: "status", label: "Setup", format: "badge" },
+			{ key: "state", label: "State", format: "badge" },
+			{ key: "users", label: "Users", format: "number" },
+			{ key: "created", label: "Created", format: "relative_time" },
+			{ key: "actions", label: "", format: "element" },
+		],
+		rows: sites.map((s) => ({
+			site: s.slug,
+			owner: s.ownerEmail ?? "-",
+			status: s.status,
+			state: s.state,
+			users: s.userCount,
+			created: s.createdAt ?? "",
+			actions: {
+				type: "menu",
+				action_id: `${ROW_ACTION_PREFIX}${s.slug}`,
+				label: "Actions",
+				items: actionsFor(s).map((a) => ({ label: LABELS[a], value: a })),
+			},
+		})),
+	});
+	if (deleted.length) {
+		blocks.push(
+			{ type: "divider" },
+			{ type: "header", text: "Purge" },
+			{
+				type: "context",
+				text: "Deleted sites are destroyed automatically after the grace period. Purging now removes the tables, files, backups and organization for good.",
+			},
+			{
+				type: "form",
+				block_id: "purge",
+				fields: [
+					{ type: "select", action_id: "slug", label: "Deleted site", options: deleted.map((s) => ({ label: s.slug, value: s.slug })), initial_value: deleted[0]!.slug },
+					{ type: "toggle", action_id: "confirm", label: "I understand this cannot be undone", initial_value: false },
+				],
+				submit: { label: "Purge now", action_id: PURGE_FORM_ACTION },
+			},
+		);
+	}
+	return blocks;
+}

package/src/fleet.ts

@@ -0,0 +1,151 @@
+/**
+ * Fleet view for the hosting provider (super-admin).
+ *
+ * Read-only to start: list every site with its status, owner and user count.
+ * The data lives in EmDash, not in Better Auth — the registry is control-plane
+ * `options` rows (`multisite:site:<slug>`) + the Better Auth org/member records
+ * in plugin storage + each site's own `users` table — so this is ours to serve,
+ * gated to staff on the control-plane host.
+ *
+ * Staff = a user with EmDash role 50 (admin) on the CONTROL-PLANE site. That is
+ * your account, not a tenant admin: tenant admins are role 50 only on their own
+ * site's `users` table, which this never consults for the gate.
+ */
+import { Kysely, sql } from "kysely";
+import { siteDialect, runAsSite } from "./dialect.ts";
+import { isSiteId, isSiteTable } from "./rewrite.ts";
+import { isTemplateId } from "./rules.ts";
+import { scopeState } from "./scope.ts";
+import type { SiteStatus } from "./orgs.ts";
+import { readAllStates } from "./registry.ts";
+
+function controlDb(): Kysely<never> {
+	const st = scopeState();
+	if (!st.inner) throw new Error("[multisite] database not initialised yet");
+	return new Kysely<never>({ dialect: siteDialect(st.inner, st.activeSite, st.primary) });
+}
+
+/**
+ * Is `userId` a staff member? True only when they are role 50 on the
+ * control-plane `users` table. `userId` comes from the EmDash session.
+ */
+export async function isStaff(userId: string | null | undefined): Promise<boolean> {
+	if (!userId) return false;
+	const db = controlDb();
+	const row = await runAsSite(scopeState().primary, () =>
+		sql<{ role: number }>`SELECT role FROM users WHERE id = ${userId}`.execute(db),
+	);
+	return (row.rows[0]?.role ?? 0) >= 50;
+}
+
+export interface FleetSite {
+	slug: string;
+	name: string;
+	ownerEmail: string | null;
+	status: SiteStatus["status"] | "unknown";
+	/** active, or suspended / deleted by staff or the owner. */
+	state: "active" | "suspended" | "deleted";
+	createdAt: string | null;
+	userCount: number;
+}
+
+/**
+ * Every provisioned tenant site + the control plane itself. One pass over the
+ * control-plane registry, then a per-site COUNT. Reads only; no tenant content.
+ */
+export async function listSites(): Promise<FleetSite[]> {
+	const db = controlDb();
+	const primary = scopeState().primary;
+
+	return runAsSite(primary, async () => {
+		// Which per-site tables physically exist -> the set of provisioned sites.
+		const tables = await sql<{ name: string }>`
+			SELECT name FROM sqlite_master WHERE type = 'table' AND name LIKE 'users$%' ESCAPE '\\'`.execute(db);
+		// NOTE: translateRows strips the suffix from sqlite_master names for the
+		// PRIMARY site; here we are the primary, so suffix stripping is OFF and we
+		// see the real physical names. Guard anyway.
+		const slugs = tables.rows
+			.map((r) => r.name)
+			.filter((n) => n.startsWith("users$"))
+			.map((n) => n.slice("users$".length))
+			.filter((id) => isSiteId(id) && !isTemplateId(id));
+
+		// Org name/slug/createdAt + owner, from Better Auth storage on the primary.
+		const orgs = await sql<{ data: string }>`
+			SELECT data FROM _plugin_storage WHERE collection = 'organizations'`.execute(db);
+		const members = await sql<{ data: string }>`
+			SELECT data FROM _plugin_storage WHERE collection = 'members'`.execute(db);
+		const states = await readAllStates();
+		const statusRows = await sql<{ name: string; value: string }>`
+			SELECT name, value FROM options WHERE name LIKE 'multisite:site:%'`.execute(db);
+
+		const orgBySlug = new Map<string, { name: string; id: string; createdAt: string }>();
+		for (const r of orgs.rows) {
+			try {
+				const o = JSON.parse(r.data) as { slug?: string; name?: string; id?: string; createdAt?: string };
+				if (o.slug) orgBySlug.set(o.slug, { name: o.name ?? o.slug, id: o.id ?? "", createdAt: o.createdAt ?? "" });
+			} catch {}
+		}
+		const ownerIdByOrgId = new Map<string, string>();
+		for (const r of members.rows) {
+			try {
+				const m = JSON.parse(r.data) as { organizationId?: string; userId?: string; role?: string };
+				if (m.organizationId && m.userId && m.role === "owner") ownerIdByOrgId.set(m.organizationId, m.userId);
+			} catch {}
+		}
+		const statusBySlug = new Map<string, SiteStatus["status"]>();
+		for (const r of statusRows.rows) {
+			const slug = r.name.slice("multisite:site:".length);
+			try {
+				statusBySlug.set(slug, (JSON.parse(r.value) as SiteStatus).status);
+			} catch {}
+		}
+
+		const out: FleetSite[] = [];
+		// The control plane itself (unprefixed `users`), shown first.
+		out.push({
+			slug: primary,
+			name: "(control plane)",
+			ownerEmail: null,
+			status: "ready",
+			state: "active",
+			createdAt: null,
+			userCount: await countUsers(db, primary, primary),
+		});
+
+		for (const slug of slugs.sort()) {
+			const org = orgBySlug.get(slug);
+			const ownerId = org ? ownerIdByOrgId.get(org.id) : undefined;
+			const ownerEmail = ownerId ? await emailOf(db, ownerId) : null;
+			out.push({
+				slug,
+				name: org?.name ?? slug,
+				ownerEmail,
+				status: statusBySlug.get(slug) ?? "unknown",
+				state: states.get(slug)?.state ?? "active",
+				createdAt: org?.createdAt || null,
+				userCount: await countUsers(db, slug, primary),
+			});
+		}
+		return out;
+	});
+}
+
+async function emailOf(db: Kysely<never>, userId: string): Promise<string | null> {
+	const r = await sql<{ email: string }>`SELECT email FROM users WHERE id = ${userId}`.execute(db);
+	return r.rows[0]?.email ?? null;
+}
+
+/** COUNT a site's own users table. `site` is validated; table name is built, never interpolated from input beyond that. */
+async function countUsers(db: Kysely<never>, site: string, primary: string): Promise<number> {
+	if (!isSiteId(site) || !isSiteTable("users")) return 0;
+	// Run AS the site so the dialect rewrites `users` -> `users$site` for us.
+	return runAsSite(site, async () => {
+		try {
+			const r = await sql<{ c: number }>`SELECT COUNT(*) AS c FROM users`.execute(db);
+			return Number(r.rows[0]?.c ?? 0);
+		} catch {
+			return 0;
+		}
+	});
+}