a2a-exposed 0.4.1 → 0.6.0

package/worker/src/backup.ts

@@ -0,0 +1,186 @@
+// Daily SQL snapshots. The R2 binding and the `0 3 * * *` trigger exist only when the deploy sets
+// A2A_BACKUP_BUCKET=1. With that unset there is no bucket and this module is not called.
+// Objects are `tenants/<id>/<YYYY-MM-DD>.sql`. A dated object is removed when its date is 30 or more
+// days before the run (UTC), which keeps 30 daily snapshots.
+
+import { exportRows, toSql, ExportError } from "./export.ts";
+import { parseDirectoryEntry, pinDirectoryRegion, tenantRegion, TENANT_NAME, type DirectoryEntry } from "./directory.ts";
+import { namespaceForRegion, parseGates, type DoNamespace, type KvNamespace, type SqlDb, type WorkerBindings } from "./tenancy.ts";
+
+export const DAILY_CRON = "0 3 * * *";
+export const RETENTION_DAYS = 30;
+/** Self-host has one inbox, so its objects live under this id. */
+export const SELF_TENANT_ID = "self";
+
+const TENANT_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export type R2BucketLike = NonNullable<WorkerBindings["BACKUP_BUCKET"]>;
+
+export interface BackupWritten {
+	tenantId: string;
+	key: string;
+	deleted: string[];
+}
+
+export interface BackupReport {
+	written: BackupWritten[];
+	skipped: { tenantId: string; status: string }[];
+	failed: { tenantId: string; error: string }[];
+}
+
+export function dayUtc(now: Date): string {
+	return now.toISOString().slice(0, 10);
+}
+
+/** UTC midnight for a real calendar day, or null. */
+export function parseDay(day: string): number | null {
+	const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(day);
+	if (!m) return null;
+	const y = Number(m[1]), mo = Number(m[2]), d = Number(m[3]);
+	const t = Date.UTC(y, mo - 1, d);
+	const dt = new Date(t);
+	if (dt.getUTCFullYear() !== y || dt.getUTCMonth() !== mo - 1 || dt.getUTCDate() !== d) return null;
+	return t;
+}
+
+/** True when `fileDay` is at least {@link RETENTION_DAYS} before `today`. */
+export function olderThanRetention(fileDay: string, today: string): boolean {
+	const file = parseDay(fileDay);
+	const now = parseDay(today);
+	if (file === null || now === null) return false;
+	return now - file >= RETENTION_DAYS * DAY_MS;
+}
+
+export function snapshotKey(tenantId: string, day: string): string {
+	if (!TENANT_ID.test(tenantId)) throw new ExportError("backup: tenant id is invalid");
+	if (parseDay(day) === null) throw new ExportError("backup: day is invalid");
+	return `tenants/${tenantId}/${day}.sql`;
+}
+
+/** The `YYYY-MM-DD` in `tenants/<id>/<day>.sql`, or null when the key is not one of ours. */
+export function objectDay(key: string, tenantId: string): string | null {
+	const prefix = `tenants/${tenantId}/`;
+	if (!key.startsWith(prefix) || !key.endsWith(".sql")) return null;
+	const day = key.slice(prefix.length, -".sql".length);
+	return parseDay(day) === null ? null : day;
+}
+
+async function listAll(bucket: R2BucketLike, prefix: string): Promise<string[]> {
+	const keys: string[] = [];
+	let cursor: string | undefined;
+	for (;;) {
+		const res = await bucket.list({ prefix, cursor, limit: 1000 });
+		for (const obj of res.objects ?? []) keys.push(obj.key);
+		if (!res.truncated) return keys;
+		if (!res.cursor || res.cursor === cursor) throw new ExportError("backup: snapshot listing did not finish");
+		cursor = res.cursor;
+	}
+}
+
+/** Delete dated objects for this tenant that are past retention. The object written today stays. */
+export async function pruneSnapshots(bucket: R2BucketLike, tenantId: string, today: string): Promise<string[]> {
+	if (!TENANT_ID.test(tenantId)) throw new ExportError("backup: tenant id is invalid");
+	const doomed = (await listAll(bucket, `tenants/${tenantId}/`)).filter((key) => {
+		const day = objectDay(key, tenantId);
+		return day !== null && olderThanRetention(day, today);
+	});
+	for (let i = 0; i < doomed.length; i += 1000) await bucket.delete(doomed.slice(i, i + 1000));
+	return doomed;
+}
+
+export async function writeSnapshot(bucket: R2BucketLike, tenantId: string, sql: string, now = new Date()): Promise<BackupWritten> {
+	const day = dayUtc(now);
+	const key = snapshotKey(tenantId, day);
+	await bucket.put(key, sql, { httpMetadata: { contentType: "application/sql" } });
+	const deleted = await pruneSnapshots(bucket, tenantId, day);
+	return { tenantId, key, deleted };
+}
+
+/** One self-host inbox, under {@link SELF_TENANT_ID}. */
+export async function backupDatabase(bucket: R2BucketLike, db: SqlDb, tenantId = SELF_TENANT_ID, now = new Date()): Promise<BackupWritten> {
+	const file = await exportRows(db, now);
+	return writeSnapshot(bucket, tenantId, toSql(file), now);
+}
+
+interface KvLister extends KvNamespace {
+	list?(options?: { prefix?: string; cursor?: string; limit?: number }): Promise<{
+		keys: { name: string }[];
+		list_complete: boolean;
+		cursor?: string;
+	}>;
+}
+
+async function directoryNames(kv: KvLister): Promise<string[]> {
+	if (typeof kv.list !== "function") throw new ExportError("backup: directory cannot be listed");
+	const names: string[] = [];
+	let cursor: string | undefined;
+	for (;;) {
+		const res = await kv.list({ prefix: "tenant:", cursor, limit: 1000 });
+		for (const k of res.keys ?? []) {
+			const name = k.name.startsWith("tenant:") ? k.name.slice("tenant:".length) : "";
+			if (TENANT_NAME.test(name)) names.push(name);
+		}
+		if (res.list_complete !== false) return names;
+		if (!res.cursor || res.cursor === cursor) throw new ExportError("backup: directory listing did not finish");
+		cursor = res.cursor;
+	}
+}
+
+function clip(e: unknown): string {
+	const msg = e instanceof Error ? e.message : String(e);
+	return msg.slice(0, 200);
+}
+
+/**
+ * Fan-out for a hosted deploy. Active tenants are exported; other statuses are skipped.
+ * An entry with no region yet is pinned the same way a request would pin it, then read.
+ * One tenant's failure is recorded and the rest still run.
+ */
+export async function backupDirectory(
+	kv: KvLister,
+	bucket: R2BucketLike,
+	ns: DoNamespace,
+	dataRegion: string,
+	now = new Date(),
+): Promise<BackupReport> {
+	const report: BackupReport = { written: [], skipped: [], failed: [] };
+	const names = await directoryNames(kv);
+	for (const name of names) {
+		let entry: DirectoryEntry | null = null;
+		try {
+			const raw = await kv.get(`tenant:${name}`, "json");
+			entry = parseDirectoryEntry(raw);
+			if (!entry) throw new ExportError("backup: directory entry is unreadable");
+			const pinned = await pinDirectoryRegion(kv, name, entry, dataRegion);
+			if (!pinned) throw new ExportError("backup: directory unavailable");
+			entry = pinned;
+			if (entry.status !== "active") {
+				report.skipped.push({ tenantId: entry.id, status: entry.status });
+				continue;
+			}
+			const sql = await exportTenantSql(ns, entry);
+			report.written.push(await writeSnapshot(bucket, entry.id, sql.sql, now));
+		} catch (e) {
+			report.failed.push({ tenantId: entry?.id || name, error: clip(e) });
+		}
+	}
+	return report;
+}
+
+export async function exportTenantSql(ns: DoNamespace, entry: DirectoryEntry): Promise<{ sql: string; exportedAt: string }> {
+	const bound = namespaceForRegion(ns, tenantRegion(entry));
+	const stub = bound.get(bound.idFromName(entry.id)) as { exportSql?: () => Promise<{ sql: string; exportedAt: string }> };
+	if (typeof stub.exportSql !== "function") throw new ExportError("exportSql: not available");
+	const out = await stub.exportSql();
+	if (!out || typeof out.sql !== "string" || typeof out.exportedAt !== "string") throw new ExportError("exportSql: empty");
+	return out;
+}
+
+/** Hosted daily job. Returns null when this invocation is not the backup cron or the bucket is unset. */
+export async function hostedDailyBackup(controller: { cron?: string }, env: WorkerBindings, now = new Date()): Promise<BackupReport | null> {
+	if (controller.cron !== DAILY_CRON || !env.BACKUP_BUCKET) return null;
+	if (env.TENANCY !== "host" || !env.TENANT_DO) return null;
+	if (!env.TENANT_DIRECTORY) throw new ExportError("backup: directory cannot be listed");
+	return backupDirectory(env.TENANT_DIRECTORY, env.BACKUP_BUCKET, env.TENANT_DO, parseGates(env).gates.dataRegion, now);
+}

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(); }));
+}