a2a-exposed 0.5.0 → 0.6.0

package/worker/src/directory.ts

@@ -0,0 +1,120 @@
+// Host → tenant name directory. The hosted router reads this before it touches a Durable Object.
+// Control (later) writes `tenant:<name>` = { id, status, region, version }. No secrets live here.
+// An entry with an empty region is pinned on first sight (`eu`, `fedramp`, or `default`) and then only read.
+// The isolate caches each lookup, including "not in the directory", for 60 seconds, capped so a scan of
+// random names cannot grow it without bound.
+
+import type { KvNamespace } from "./tenancy.ts";
+
+/** 4–32 characters: letter or digit, then letters, digits or hyphens, ending in a letter or digit. */
+export const TENANT_NAME = /^[a-z0-9](?:[a-z0-9-]{2,30}[a-z0-9])$/;
+
+export const DIRECTORY_TTL_MS = 60_000;
+/** Isolate cap. A scan of random names must not keep a map entry for every miss. */
+export const DIRECTORY_MAX = 1024;
+
+export interface DirectoryEntry {
+	id: string;
+	status: string;
+	/**
+	 * Placement, pinned once. `eu` and `fedramp` select that jurisdiction. `default` is the namespace's
+	 * default placement. `""` means not pinned yet.
+	 */
+	region: string;
+	version: number;
+}
+
+const cache = new Map<string, { at: number; entry: DirectoryEntry | null }>();
+
+export function clearDirectoryCache(): void {
+	cache.clear();
+}
+
+/** Move `name` to the newest end and drop expired, then oldest, entries past the cap. */
+function remember(name: string, at: number, entry: DirectoryEntry | null, now: number): void {
+	cache.delete(name);
+	cache.set(name, { at, entry });
+	if (cache.size <= DIRECTORY_MAX) return;
+	for (const [k, v] of cache) if (now - v.at >= DIRECTORY_TTL_MS) cache.delete(k);
+	while (cache.size > DIRECTORY_MAX) {
+		const oldest = cache.keys().next().value;
+		if (oldest === undefined) break;
+		cache.delete(oldest);
+	}
+}
+
+export function directoryKey(name: string): string {
+	return `tenant:${name}`;
+}
+
+/**
+ * First label under `domain`, or null. The apex, a nested name (`a.b.domain`) and a different parent do not match.
+ * `domain` is compared already normalised (lowercase, no surrounding dots).
+ */
+export function tenantNameFromHost(host: string, domain: string): string | null {
+	const h = host.toLowerCase();
+	const d = domain.toLowerCase();
+	if (!d || h === d || !h.endsWith("." + d)) return null;
+	const name = h.slice(0, -(d.length + 1));
+	return TENANT_NAME.test(name) ? name : null;
+}
+
+/** `eu` or `fedramp` when the directory entry says so. `default` and anything else use the default namespace. */
+export function tenantRegion(entry: DirectoryEntry): string {
+	return entry.region === "eu" || entry.region === "fedramp" ? entry.region : "";
+}
+
+/**
+ * Write a placement into an entry that does not have one yet, then return that entry.
+ * `DATA_REGION` is read only here. A later change to it does not move a tenant whose row already
+ * has `eu`, `fedramp`, or `default`. Returns null when the write fails; the caller must not address
+ * an object until the placement is stored.
+ */
+export async function pinDirectoryRegion(
+	kv: Pick<KvNamespace, "put">,
+	name: string,
+	entry: DirectoryEntry,
+	dataRegion: string,
+	now = Date.now(),
+): Promise<DirectoryEntry | null> {
+	if (entry.region !== "") return entry;
+	const region = dataRegion === "eu" || dataRegion === "fedramp" ? dataRegion : "default";
+	const pinned: DirectoryEntry = { ...entry, region };
+	try {
+		await kv.put(directoryKey(name), JSON.stringify(pinned));
+	} catch {
+		return null;
+	}
+	remember(name, now, pinned, now);
+	return pinned;
+}
+
+export function parseDirectoryEntry(raw: unknown): DirectoryEntry | null {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+	const o = raw as Record<string, unknown>;
+	if (typeof o.id !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(o.id)) return null;
+	if (typeof o.status !== "string" || !/^[a-z]{1,32}$/.test(o.status)) return null;
+	const region = typeof o.region === "string" ? o.region : "";
+	const version = typeof o.version === "number" && Number.isSafeInteger(o.version) ? o.version : 0;
+	return { id: o.id, status: o.status, region, version };
+}
+
+/**
+ * Cached directory lookup. A missing or unreadable value is cached as "unknown" so a scan of random names
+ * does not hit KV on every request. Pass `now` from tests.
+ */
+export async function lookupDirectory(kv: Pick<KvNamespace, "get">, name: string, now = Date.now()): Promise<DirectoryEntry | null> {
+	const hit = cache.get(name);
+	if (hit && now - hit.at < DIRECTORY_TTL_MS) {
+		remember(name, hit.at, hit.entry, now);
+		return hit.entry;
+	}
+	let entry: DirectoryEntry | null = null;
+	try {
+		entry = parseDirectoryEntry(await kv.get(directoryKey(name), "json"));
+	} catch {
+		entry = null;
+	}
+	remember(name, now, entry, now);
+	return entry;
+}

package/worker/src/export.ts

@@ -0,0 +1,156 @@
+// Inbox export. Both the owner HTTP API and the hosted Durable Object use this.
+// The allowlist is the application tables. `d1_migrations` and the hosted `tenant_config` row (it holds
+// `secrets_enc`) are left out. The SQL text is a dump the operator already owns.
+
+import type { SqlDb } from "./tenancy.ts";
+
+export class ExportError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ExportError";
+	}
+}
+
+/** Application tables, in a stable order. Schema changes add a table here in the same change as the migration. */
+export const EXPORT_TABLES = [
+	"peers", "tasks", "messages", "history", "outbound", "wakes",
+	"rate", "wake_budget", "device_requests", "pairing_rate", "settings",
+	"facade_owners", "oauth_clients", "oauth_codes", "mcp_grants",
+	"outbound_peers", "oauth_client_metadata", "oidc_txns",
+] as const;
+
+export type ExportTable = (typeof EXPORT_TABLES)[number];
+
+export interface ExportFile {
+	format: "a2a-exposed-export";
+	version: 1;
+	exportedAt: string;
+	tables: { [K in ExportTable]?: Record<string, unknown>[] };
+}
+
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function quoteIdent(name: string): string {
+	if (!IDENT.test(name)) throw new ExportError("export: bad column");
+	return `"${name}"`;
+}
+
+function cell(v: unknown): unknown {
+	if (v === null || typeof v === "string" || typeof v === "boolean") return v;
+	if (typeof v === "number") {
+		if (!Number.isFinite(v)) throw new ExportError("export: non-finite number");
+		return v;
+	}
+	if (typeof v === "bigint") {
+		if (v > BigInt(Number.MAX_SAFE_INTEGER) || v < BigInt(Number.MIN_SAFE_INTEGER)) throw new ExportError("export: integer out of range");
+		return Number(v);
+	}
+	throw new ExportError("export: unsupported value");
+}
+
+function normalizeRow(row: Record<string, unknown>): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	for (const [k, v] of Object.entries(row)) {
+		if (!IDENT.test(k)) throw new ExportError("export: bad column");
+		out[k] = cell(v);
+	}
+	return out;
+}
+
+/** A SQL string literal. SQLite rejects a script that contains a NUL byte, so U+0000 is `char(0)` instead of a raw byte. */
+function sqlString(v: string): string {
+	const parts = v.split("\u0000");
+	if (parts.length === 1) return `'${v.replaceAll("'", "''")}'`;
+	const bits: string[] = [];
+	for (let i = 0; i < parts.length; i++) {
+		if (parts[i]) bits.push(`'${parts[i].replaceAll("'", "''")}'`);
+		if (i < parts.length - 1) bits.push("char(0)");
+	}
+	return bits.length === 1 ? bits[0] : `(${bits.join(" || ")})`;
+}
+
+function sqlLit(v: unknown): string {
+	if (v === null) return "NULL";
+	if (typeof v === "boolean") return v ? "1" : "0";
+	if (typeof v === "number") return Number.isInteger(v) ? String(v) : JSON.stringify(v);
+	if (typeof v === "string") return sqlString(v);
+	throw new ExportError("export: unsupported value");
+}
+
+/**
+ * Every allowlisted table, including ones with no rows.
+ * One `batch` is one transaction. D1 runs the batch as a single transaction, so a concurrent write cannot
+ * land between tables. The Durable Object adapter runs that batch inside `transactionSync`, which blocks
+ * other requests for the whole read. Do not split this back into per-table queries.
+ */
+export async function exportRows(db: SqlDb, now = new Date()): Promise<ExportFile> {
+	const out = await db.batch(EXPORT_TABLES.map((name) => db.prepare(`SELECT * FROM ${quoteIdent(name)}`)));
+	const tables: ExportFile["tables"] = {};
+	EXPORT_TABLES.forEach((name, i) => {
+		tables[name] = ((out[i]?.results ?? []) as Record<string, unknown>[]).map(normalizeRow);
+	});
+	return { format: "a2a-exposed-export", version: 1, exportedAt: now.toISOString(), tables };
+}
+
+/** DELETE then INSERT for every allowlisted table. Safe to run on a database that already has the schema. */
+export function toSql(file: ExportFile): string {
+	if (file.format !== "a2a-exposed-export" || file.version !== 1) throw new ExportError("export: bad file");
+	if (!/^[\dTZ:.-]+$/.test(file.exportedAt)) throw new ExportError("export: bad timestamp");
+	const lines = [
+		`-- a2a-exposed-export ${file.version}`,
+		`-- exported_at ${file.exportedAt}`,
+	];
+	for (const name of EXPORT_TABLES) {
+		lines.push(`DELETE FROM ${quoteIdent(name)};`);
+		for (const row of file.tables[name] ?? []) {
+			const cols = Object.keys(row);
+			if (!cols.length) continue;
+			lines.push(`INSERT INTO ${quoteIdent(name)} (${cols.map(quoteIdent).join(", ")}) VALUES (${cols.map((c) => sqlLit(row[c])).join(", ")});`);
+		}
+	}
+	return lines.join("\n") + "\n";
+}
+
+export interface BookmarkStorage {
+	getBookmarkForTime?(timeMs: number): Promise<string>;
+	onNextSessionRestoreBookmark?(bookmark: string): Promise<unknown> | unknown;
+}
+
+/** Admin RPC helper. The storage runtime's method is called only when it exists. */
+export async function bookmarkForTime(storage: BookmarkStorage, timeMs: number): Promise<{ bookmark: string }> {
+	if (typeof timeMs !== "number" || !Number.isFinite(timeMs)) throw new ExportError("bookmarkForTime: timeMs must be a finite number");
+	if (typeof storage.getBookmarkForTime !== "function") throw new ExportError("bookmarkForTime: point-in-time restore is not available on this storage");
+	const bookmark = await storage.getBookmarkForTime(timeMs);
+	if (typeof bookmark !== "string" || !bookmark) throw new ExportError("bookmarkForTime: storage returned no bookmark");
+	return { bookmark };
+}
+
+/**
+ * How long the RPC result is given to leave before `ctx.abort()`.
+ * The reset waits out this turn and a busy caller: aborting sooner drops the result.
+ */
+export const RESTORE_RESTART_DELAY_MS = 1000;
+
+/**
+ * Schedule `bookmark` for the next session and return `{ ok: true }`. Does not reset the object: `ctx.abort()` in
+ * this turn would drop the RPC. The Durable Object calls `restartAfterResult` after this returns. A storage error
+ * is thrown and the current database keeps running.
+ */
+export async function restoreBookmark(storage: BookmarkStorage, bookmark: string): Promise<{ ok: true; undo?: string }> {
+	if (typeof bookmark !== "string" || bookmark.length < 1 || bookmark.length > 4096) throw new ExportError("restoreBookmark: bookmark is invalid");
+	if (typeof storage.onNextSessionRestoreBookmark !== "function") throw new ExportError("restoreBookmark: point-in-time restore is not available on this storage");
+	let raw: unknown;
+	try {
+		raw = await storage.onNextSessionRestoreBookmark(bookmark);
+	} catch (e) {
+		if (e instanceof ExportError) throw e;
+		throw new ExportError(`restoreBookmark: ${e instanceof Error ? e.message : String(e)}`);
+	}
+	const undo = typeof raw === "string" && raw.length > 0 ? raw : undefined;
+	return undo ? { ok: true, undo } : { ok: true };
+}
+
+/** Queue `restart` so the caller can return first. The timer is longer than this turn, so the RPC result is delivered. */
+export function restartAfterResult(waitUntil: (p: Promise<unknown>) => void, restart: () => void, wait: (ms: number) => Promise<void>): void {
+	waitUntil(wait(RESTORE_RESTART_DELAY_MS).then(() => { restart(); }));
+}

package/worker/src/hosted.ts

@@ -0,0 +1,403 @@
+// Hosted entrypoint. Used only when the deploy sets TENANCY=host (see cloudflare.config.ts).
+// With that set and a TENANT_DO binding, `<name>.<TENANT_DOMAIN>` is looked up in the KV directory and forwarded
+// to that tenant's SQLite Durable Object. The object runs the same inbox as self-host (`dispatch` in index.ts)
+// against its own database. Anything else — TENANCY unset, or no TENANT_DO binding — calls the self-host fetch
+// handler on env.DB.
+//
+// Tenant config is a versioned row pushed into the object (`pushConfig`). It does not travel on the request.
+// An object with no row answers 404 and does not create application tables.
+//
+// Hosted wake debounce and the cron's housekeeping run from this object's alarm. The Worker minute cron stays a no-op
+// while TENANCY=host, so there is no shared database to flush. Self-host still uses its minute cron.
+// The daily backup cron runs only when BACKUP_BUCKET is bound, and it returns before any flush.
+// Usage push is not in this change. Approval OIDC, when configured (self-host settings, or the pushed tenant
+// `approval` object), uses the same pages as self-host.
+import { DurableObject } from "cloudflare:workers";
+import worker, { cronFlush, dispatch, nextCronAt, onWakeWrite } from "./index.ts";
+import { doSqlD1, migrateDo, type SqlStorageLike, type TxRunner } from "./storage.ts";
+import { MIGRATIONS } from "./migrations.ts";
+import { bookmarkForTime as readBookmark, exportRows, restoreBookmark as applyBookmark, restartAfterResult, toSql, ExportError, type BookmarkStorage } from "./export.ts";
+import { hostedDailyBackup } from "./backup.ts";
+import { lookupDirectory, pinDirectoryRegion, tenantNameFromHost, tenantRegion, TENANT_NAME, type DirectoryEntry } from "./directory.ts";
+import { hostedTenantContext, namespaceForRegion, parseGates, type WorkerBindings } from "./tenancy.ts";
+
+export { clearDirectoryCache, directoryKey, lookupDirectory, parseDirectoryEntry, pinDirectoryRegion, tenantNameFromHost, tenantRegion, TENANT_NAME } from "./directory.ts";
+export type { DirectoryEntry };
+
+const JSON_HDR = { "content-type": "application/json", "cache-control": "no-store" };
+const notFound = () => Response.json({ error: "no such agent" }, { status: 404, headers: JSON_HDR });
+const unavailable = () => Response.json({ error: "directory unavailable" }, { status: 503, headers: JSON_HDR });
+const suspended = () => Response.json({ error: "this agent is suspended" }, { status: 403, headers: JSON_HDR });
+const gone = () => Response.json({ error: "this agent is gone" }, { status: 410, headers: JSON_HDR });
+
+const TENANT_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+
+/** Versioned config pushed by the control plane. `secretsEnc` is stored and not decrypted here. */
+export interface TenantConfigPush {
+	version: number;
+	tenantId: string;
+	name: string;
+	status: string;
+	config?: Record<string, unknown>;
+	limits?: Record<string, unknown>;
+	approval?: Record<string, unknown>;
+	ownerTokenHash?: string | null;
+	secretsEnc?: string | null;
+}
+
+interface StoredConfig {
+	version: number;
+	tenantId: string;
+	name: string;
+	status: string;
+	config: Record<string, string | undefined>;
+	limits: Record<string, unknown>;
+	approval: Record<string, unknown>;
+	ownerTokenHash: string | null;
+	secretsEnc: string | null;
+}
+
+const CREATE_CONFIG = `CREATE TABLE IF NOT EXISTS tenant_config (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  version INTEGER NOT NULL,
+  tenant_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  status TEXT NOT NULL,
+  config_json TEXT NOT NULL,
+  limits_json TEXT NOT NULL,
+  approval_json TEXT NOT NULL,
+  owner_token_hash TEXT,
+  secrets_enc TEXT,
+  updated_at TEXT NOT NULL
+)`;
+
+function readRow(sql: SqlStorageLike): StoredConfig | null {
+	const exists = sql.exec("SELECT 1 AS n FROM sqlite_master WHERE type = 'table' AND name = 'tenant_config'").toArray();
+	if (!exists.length) return null;
+	const rows = sql.exec("SELECT version, tenant_id, name, status, config_json, limits_json, approval_json, owner_token_hash, secrets_enc FROM tenant_config WHERE id = 1").toArray();
+	const r = rows[0];
+	if (!r) return null;
+	return {
+		version: Number(r.version),
+		tenantId: String(r.tenant_id),
+		name: String(r.name),
+		status: String(r.status),
+		config: stringRecord(JSON.parse(String(r.config_json || "{}"))),
+		limits: objectRecord(JSON.parse(String(r.limits_json || "{}"))),
+		approval: objectRecord(JSON.parse(String(r.approval_json || "{}"))),
+		ownerTokenHash: r.owner_token_hash == null ? null : String(r.owner_token_hash),
+		secretsEnc: r.secrets_enc == null ? null : String(r.secrets_enc),
+	};
+}
+
+function stringRecord(v: unknown): Record<string, string | undefined> {
+	const out: Record<string, string | undefined> = {};
+	if (!v || typeof v !== "object" || Array.isArray(v)) return out;
+	for (const [k, val] of Object.entries(v)) if (typeof val === "string") out[k] = val;
+	return out;
+}
+
+function objectRecord(v: unknown): Record<string, unknown> {
+	if (!v || typeof v !== "object" || Array.isArray(v)) return {};
+	return v as Record<string, unknown>;
+}
+
+function requireObject(v: unknown, what: string): Record<string, unknown> {
+	if (v == null) return {};
+	if (typeof v !== "object" || Array.isArray(v)) throw new Error(`pushConfig: ${what} must be an object`);
+	return v as Record<string, unknown>;
+}
+
+function checkPush(body: TenantConfigPush): void {
+	if (!body || typeof body !== "object") throw new Error("pushConfig: body is required");
+	if (typeof body.version !== "number" || !Number.isSafeInteger(body.version) || body.version < 1) throw new Error("pushConfig: version must be an integer >= 1");
+	if (typeof body.tenantId !== "string" || !TENANT_ID.test(body.tenantId)) throw new Error("pushConfig: tenantId is invalid");
+	if (typeof body.name !== "string" || !TENANT_NAME.test(body.name)) throw new Error("pushConfig: name is invalid");
+	if (typeof body.status !== "string" || !/^[a-z]{1,32}$/.test(body.status)) throw new Error("pushConfig: status is invalid");
+	if (body.ownerTokenHash != null && body.ownerTokenHash !== "" && !/^[0-9a-fA-F]{64}$/.test(body.ownerTokenHash)) throw new Error("pushConfig: ownerTokenHash must be 64 hex characters");
+	if (body.secretsEnc != null && typeof body.secretsEnc !== "string") throw new Error("pushConfig: secretsEnc must be a string");
+}
+
+/** Both are required. TENANCY=host alone, or a binding without the flag, stays on env.DB. */
+function hostedOn(env: WorkerBindings): env is WorkerBindings & { TENANT_DO: NonNullable<WorkerBindings["TENANT_DO"]> } {
+	return env.TENANCY === "host" && !!env.TENANT_DO;
+}
+
+function appTables(sql: SqlStorageLike): string[] {
+	return sql.exec("SELECT name FROM sqlite_master WHERE type = 'table'").toArray()
+		.map((r) => String(r.name))
+		.filter((n) => !n.startsWith("sqlite_") && !n.startsWith("_cf_"))
+		.sort();
+}
+
+export class TenantStore extends DurableObject<WorkerBindings> {
+	#sql: SqlStorageLike;
+	#tx: TxRunner;
+	#db: ReturnType<typeof doSqlD1>;
+	#row: StoredConfig | null = null;
+
+	constructor(ctx: DurableObjectState, env: WorkerBindings) {
+		super(ctx, env);
+		const storage = ctx.storage as unknown as { sql: SqlStorageLike; transactionSync: TxRunner };
+		this.#sql = storage.sql;
+		// Call through `storage` so `this` stays bound. An extracted method throws Illegal invocation.
+		this.#tx = (fn) => storage.transactionSync(fn);
+		this.#db = doSqlD1(this.#sql, this.#tx);
+		// Read only. Migrations run once a config row exists, so a scan that instantiates an object writes nothing.
+		ctx.blockConcurrencyWhile(async () => {
+			this.#row = readRow(this.#sql);
+			if (this.#row) migrateDo(this.#sql, this.#tx, MIGRATIONS);
+			if (this.#row?.status === "active") await this.#enqueueArm(false);
+		});
+	}
+
+	#tenant(fallbackOrigin = "") {
+		const row = this.#row;
+		if (!row) return null;
+		const domain = parseGates(this.env).gates.tenantDomain;
+		const publicUrl = domain ? `https://${row.name}.${domain}` : (fallbackOrigin || this.env.PUBLIC_URL || "");
+		return hostedTenantContext(this.env, {
+			id: row.tenantId, db: this.#db, publicUrl, ownerTokenHash: row.ownerTokenHash,
+			config: row.config, limits: row.limits, approval: row.approval, status: row.status,
+		});
+	}
+
+	#arming: Promise<void> = Promise.resolve();
+
+	/** Run alarm updates one at a time, so an earlier read cannot setAlarm over a retry row written later. */
+	#enqueueArm(afterRun: boolean): Promise<void> {
+		const run = this.#arming.then(() => this.#arm(afterRun), () => this.#arm(afterRun));
+		this.#arming = run.then(() => undefined, () => undefined);
+		return run;
+	}
+
+	#ectx(background?: Promise<unknown>[]): ExecutionContext {
+		const ectx = {
+			waitUntil: (p: Promise<unknown>) => {
+				const settled = Promise.resolve(p).then(() => undefined, () => undefined);
+				if (background) background.push(settled);
+				// Arm when the task finishes, not when it was scheduled. sendWake inserts the retry before it resolves.
+				this.ctx.waitUntil(settled.then(() => this.#enqueueArm(false)));
+			},
+			passThroughOnException() {},
+		} as ExecutionContext;
+		// requeueWake calls this in the same turn as the insert, including after the inbox response has returned.
+		onWakeWrite(ectx, () => this.#enqueueArm(false));
+		return ectx;
+	}
+
+	/** One alarm per object. `afterRun` waits a second when work is still due, so a full batch cannot spin. */
+	async #arm(afterRun: boolean): Promise<void> {
+		const storage = this.ctx.storage as unknown as {
+			setAlarm(scheduledTime: number): Promise<void>;
+			deleteAlarm(): Promise<void>;
+		};
+		const row = this.#row;
+		try {
+			if (!row || row.status !== "active") {
+				await storage.deleteAlarm();
+				return;
+			}
+			const tenant = this.#tenant();
+			if (!tenant) return;
+			const at = await nextCronAt(tenant);
+			if (at == null || !Number.isFinite(at)) {
+				await storage.deleteAlarm();
+				return;
+			}
+			const now = Date.now();
+			const when = afterRun && at <= now ? now + 1000 : Math.max(at, now);
+			await storage.setAlarm(when);
+		} catch (e) {
+			console.log(JSON.stringify({ ts: new Date().toISOString(), event: "alarm_arm_failed", error: String(e).slice(0, 200) }));
+		}
+	}
+
+	/** Same flush and deletes as the self-host minute cron, for this tenant only. */
+	async alarm(): Promise<void> {
+		await this.#runAlarm();
+	}
+
+	/**
+	 * Run the alarm body now. `alarm` itself is reserved and cannot be called over RPC, so tests use this.
+	 */
+	async runAlarm(): Promise<void> {
+		await this.#runAlarm();
+	}
+
+	async #runAlarm(): Promise<void> {
+		const tenant = this.#row?.status === "active" ? this.#tenant() : null;
+		if (tenant) {
+			try { await cronFlush(tenant, this.#ectx()); }
+			catch (e) { console.log(JSON.stringify({ ts: new Date().toISOString(), event: "alarm_failed", error: String(e).slice(0, 200) })); }
+		}
+		await this.#enqueueArm(true);
+	}
+
+	/** When the alarm is set to run, or null. No secrets. */
+	async alarmAt(): Promise<number | null> {
+		const storage = this.ctx.storage as unknown as { getAlarm(): Promise<number | null> };
+		try {
+			const at = await storage.getAlarm();
+			return typeof at === "number" && Number.isFinite(at) ? at : null;
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * Control-plane push. A version less than or equal to the stored one is ignored, so a reordered or repeated
+	 * push does not roll the row backwards. The first accepted push creates `tenant_config` and then runs migrations.
+	 */
+	async pushConfig(body: TenantConfigPush): Promise<{ version: number; applied: boolean }> {
+		return await this.ctx.blockConcurrencyWhile(async () => {
+			checkPush(body);
+			const current = this.#row ?? readRow(this.#sql);
+			if (current && body.version <= current.version) {
+				// A previous push may have stored this version and then failed while migrating. Catch up; don't rewrite the row.
+				migrateDo(this.#sql, this.#tx, MIGRATIONS);
+				this.#row = current;
+				await this.#enqueueArm(false);
+				return { version: current.version, applied: false };
+			}
+			const config = requireObject(body.config, "config");
+			const limits = requireObject(body.limits, "limits");
+			const approval = requireObject(body.approval, "approval");
+			const next: StoredConfig = {
+				version: body.version,
+				tenantId: body.tenantId,
+				name: body.name,
+				status: body.status,
+				config: stringRecord(config),
+				limits,
+				approval,
+				ownerTokenHash: body.ownerTokenHash ? body.ownerTokenHash.toLowerCase() : null,
+				secretsEnc: body.secretsEnc ?? null,
+			};
+			const now = new Date().toISOString();
+			this.#tx(() => {
+				this.#sql.exec(CREATE_CONFIG);
+				this.#sql.exec(
+					`INSERT INTO tenant_config (id, version, tenant_id, name, status, config_json, limits_json, approval_json, owner_token_hash, secrets_enc, updated_at)
+					 VALUES (1, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+					 ON CONFLICT(id) DO UPDATE SET
+					   version = excluded.version, tenant_id = excluded.tenant_id, name = excluded.name, status = excluded.status,
+					   config_json = excluded.config_json, limits_json = excluded.limits_json, approval_json = excluded.approval_json,
+					   owner_token_hash = excluded.owner_token_hash, secrets_enc = excluded.secrets_enc, updated_at = excluded.updated_at`,
+					next.version, next.tenantId, next.name, next.status,
+					JSON.stringify(config), JSON.stringify(limits), JSON.stringify(approval),
+					next.ownerTokenHash, next.secretsEnc, now,
+				);
+			});
+			try {
+				migrateDo(this.#sql, this.#tx, MIGRATIONS);
+			} finally {
+				// Remember the row even if a migration throws, so a later request is not stuck on the empty-object 404.
+				this.#row = readRow(this.#sql) ?? next;
+			}
+			await this.#enqueueArm(false);
+			return { version: this.#row.version, applied: true };
+		});
+	}
+
+	/** No secrets. Tests use this to show a 404 did not create application tables. */
+	async storageStatus(): Promise<{ configured: boolean; version: number; tables: string[] }> {
+		return { configured: this.#row !== null, version: this.#row?.version ?? 0, tables: appTables(this.#sql) };
+	}
+
+	/** SQL dump of the application tables. Refuses an object that has no config row. */
+	async exportSql(): Promise<{ sql: string; exportedAt: string }> {
+		return await this.ctx.blockConcurrencyWhile(async () => {
+			if (!this.#row) throw new ExportError("exportSql: tenant is not configured");
+			const file = await exportRows(this.#db);
+			return { sql: toSql(file), exportedAt: file.exportedAt };
+		});
+	}
+
+	/** Point-in-time bookmark for this object only. The storage method is required; otherwise this throws. */
+	async bookmarkForTime(timeMs: number): Promise<{ bookmark: string }> {
+		if (!this.#row) throw new ExportError("bookmarkForTime: tenant is not configured");
+		return readBookmark(this.ctx.storage as BookmarkStorage, timeMs);
+	}
+
+	/**
+	 * Schedule `bookmark` and return `{ ok: true }`. The reset is queued for a later turn: `ctx.abort()` here would
+	 * fail the RPC before the caller saw that result. An in-flight alarm was for the pre-restore database, so it is not retried.
+	 */
+	async restoreBookmark(bookmark: string): Promise<{ ok: true; undo?: string }> {
+		if (!this.#row) throw new ExportError("restoreBookmark: tenant is not configured");
+		const tenantId = this.#row.tenantId;
+		const out = await applyBookmark(this.ctx.storage as BookmarkStorage, bookmark);
+		console.log(JSON.stringify({ ts: new Date().toISOString(), event: "bookmark_restore", tenant: tenantId, undo: out.undo ?? null }));
+		restartAfterResult(
+			(p) => this.ctx.waitUntil(p),
+			() => this.ctx.abort("restore bookmark", { retryAlarm: false }),
+			(ms) => scheduler.wait(ms),
+		);
+		return out;
+	}
+
+	async fetch(req: Request): Promise<Response> {
+		const row = this.#row;
+		if (!row) return notFound();
+		if (row.status !== "active") {
+			await this.#enqueueArm(false);
+			if (row.status === "suspended") return suspended();
+			if (row.status === "deleting") return gone();
+			return notFound();
+		}
+		const tenant = this.#tenant(new URL(req.url).origin);
+		if (!tenant) return notFound();
+		// Do not arm from the rows visible here. sendWake runs in waitUntil and, on 429/503, inserts the retry
+		// after this response returns. requeueWake arms in that insert. Arm again when those tasks finish so a
+		// quiet tenant is on Retry-After, not the rate-row timer from an earlier read.
+		const background: Promise<unknown>[] = [];
+		const res = await dispatch(req, tenant, this.#ectx(background));
+		if (background.length) {
+			const pending = background.slice();
+			this.ctx.waitUntil(Promise.allSettled(pending).then(() => this.#enqueueArm(false)));
+		}
+		return res;
+	}
+}
+
+function routeStatus(entry: DirectoryEntry): Response | null {
+	if (entry.status === "deleted") return notFound();
+	if (entry.status === "suspended") return suspended();
+	if (entry.status === "deleting") return gone();
+	if (entry.status !== "active") return notFound();
+	return null;
+}
+
+export default {
+	async fetch(req: Request<unknown, IncomingRequestCfProperties>, env: WorkerBindings, ectx: ExecutionContext): Promise<Response> {
+		if (!hostedOn(env)) return worker.fetch(req, env, ectx);
+		const domain = parseGates(env).gates.tenantDomain;
+		const name = tenantNameFromHost(new URL(req.url).hostname, domain);
+		if (!name || !env.TENANT_DIRECTORY) return notFound();
+		const entry = await lookupDirectory(env.TENANT_DIRECTORY, name);
+		if (!entry) return notFound();
+		// Pin once, including for a suspended or deleted row, so a later DATA_REGION change cannot move the object.
+		const pinned = await pinDirectoryRegion(env.TENANT_DIRECTORY, name, entry, parseGates(env).gates.dataRegion);
+		if (!pinned) return unavailable();
+		const early = routeStatus(pinned);
+		if (early) return early;
+		const region = tenantRegion(pinned);
+		const ns = namespaceForRegion(env.TENANT_DO, region);
+		// The spike carried the tenant row on this header. Drop it so a client cannot supply config.
+		const headers = new Headers(req.headers);
+		headers.delete("x-a2a-tenant");
+		return ns.get(ns.idFromName(entry.id)).fetch(new Request(req, { headers }));
+	},
+	// Self-host cron flushes env.DB. Hosted has no single database; each tenant's alarm runs that flush.
+	// The daily backup cron (only present when BACKUP_BUCKET is bound) exports each active tenant and returns.
+	async scheduled(controller: ScheduledController, env: WorkerBindings, ectx: ExecutionContext): Promise<void> {
+		const backup = await hostedDailyBackup(controller, env);
+		if (backup) {
+			for (const f of backup.failed) console.log(JSON.stringify({ ts: new Date().toISOString(), event: "backup_failed", tenant: f.tenantId, error: f.error }));
+			console.log(JSON.stringify({ ts: new Date().toISOString(), event: "backup_done", written: backup.written.length, skipped: backup.skipped.length, failed: backup.failed.length }));
+			return;
+		}
+		if (!hostedOn(env)) await worker.scheduled(controller, env, ectx);
+	},
+};