@voidbase-cloud/voidbase 0.1.0

package/src/server/backups.ts

@@ -0,0 +1,234 @@
+// Backups (apis/backup*.go): zip archives kept in R2 under __backups__/. A voidbase archive holds data.json
+// (every D1 table: columns and rows) and storage/<key> for every uploaded file, so a restore can rebuild the
+// collections, tables, rows and files. PocketBase archives (SQLite files) cannot be restored here.
+import type { Context, Hono } from "hono";
+import { unzipSync, zipSync } from "fflate";
+import { findAuthRecordByToken, requireSuperuser } from "./auth";
+import { ipInList, realIP } from "./hardening";
+import { invalidateCollections, loadCollections } from "./collections/model";
+import { planCreate } from "./collections/service";
+import { createViewSQL } from "./collections/ddl";
+import { all, ident, one, run, stmt } from "./db";
+import { ApiError, badRequest, forbidden } from "./errors";
+import { trigger } from "./hooks/runtime";
+import { withHookStore } from "./hooks/migrations";
+import { nowString } from "./ids";
+import { dispatch, registerJobHandler } from "./jobs";
+import { loadSettings } from "./settings";
+import { s3Bucket, withS3Storage } from "./storage/s3";
+import { normalizeFilename } from "./records/files";
+import type { AppEnv } from "./types";
+
+const PREFIX = "__backups__/";
+const LOCK_KEY = "__activeBackup__";
+const NAME_RE = /^[a-z0-9_-]+\.zip$/;
+const INTERNAL_TABLES = /^(_cf_|__drizzle|_void|d1_migrations|sqlite_)/;
+const SKIP_TABLES = new Set(["_changes", "_realtime_clients"]);
+
+interface Dump { format: "voidbase-backup"; version: 1; created: string; tables: Record<string, { columns: string[]; rows: unknown[][] }>; files: string[] }
+
+const snake = (s: string) => s.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+export async function generateBackupName(db: D1Database, prefix = "pb_backup_"): Promise<string> {
+  const appName = snake((await loadSettings(db)).meta.appName).slice(0, 50);
+  const d = new Date(); const p = (n: number) => String(n).padStart(2, "0");
+  return `${prefix}${appName}_${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}.zip`;
+}
+
+async function activeBackup(db: D1Database): Promise<string | null> {
+  const row = await one<{ value: string }>(db, "SELECT value FROM `_params` WHERE id = ?", [LOCK_KEY]);
+  if (!row) return null;
+  const { name, at } = JSON.parse(row.value) as { name: string; at: number };
+  if (Date.now() - at > 10 * 60_000) { await run(db, "DELETE FROM `_params` WHERE id = ?", [LOCK_KEY]); return null; }
+  return name;
+}
+const lock = (db: D1Database, name: string) => run(db, "INSERT OR REPLACE INTO `_params` (id, value, created, updated) VALUES (?, ?, ?, ?)", [LOCK_KEY, JSON.stringify({ name, at: Date.now() }), nowString(), nowString()]);
+const unlock = (db: D1Database) => run(db, "DELETE FROM `_params` WHERE id = ?", [LOCK_KEY]);
+// apis/health.go canBackup: no backup or restore currently holds the lock
+export async function backupActive(db: D1Database): Promise<boolean> {
+  const row = await db.prepare("SELECT value FROM `_params` WHERE id = ?").bind(LOCK_KEY).first<{ value: string }>();
+  if (!row) return false;
+  try { const at = Number((JSON.parse(row.value) as { at?: number }).at ?? 0); return Date.now() - at < 30 * 60_000; } catch { return true; }
+}
+
+// where the archives live: settings.backups.s3 when enabled, otherwise next to the files
+// PocketBase keeps archives at the root of a dedicated S3 backups bucket, so the __backups__/ prefix used inside
+// the shared R2 bucket is stripped on the way to S3 and re-added on the way back.
+async function backupsStorage(env: AppEnv["Bindings"]): Promise<R2Bucket> {
+  const cfg = (await loadSettings(env.DB)).backups.s3;
+  if (!cfg.enabled) return env.STORAGE;
+  const s3 = s3Bucket(cfg);
+  const strip = (k: string) => (k.startsWith(PREFIX) ? k.slice(PREFIX.length) : k);
+  const view = {
+    put: (k: string, v: unknown, o?: unknown) => s3.put(strip(k), v as never, o as never),
+    get: async (k: string, o?: unknown) => { const r = await s3.get(strip(k), o as never); return r ? Object.assign(r, { key: PREFIX + r.key }) : null; },
+    head: async (k: string) => { const r = await s3.head(strip(k)); return r ? Object.assign(r, { key: PREFIX + r.key }) : null; },
+    delete: (k: string | string[]) => s3.delete(Array.isArray(k) ? k.map(strip) : strip(k)),
+    list: async (o: { prefix?: string; cursor?: string; limit?: number } = {}) => { const r = await s3.list({ ...o, prefix: strip(o.prefix ?? "") }); return { ...r, objects: r.objects.map((x) => Object.assign(x, { key: PREFIX + x.key })) }; },
+  };
+  return view as unknown as R2Bucket;
+}
+
+async function listAll(storage: R2Bucket, prefix: string): Promise<R2Object[]> {
+  const out: R2Object[] = []; let cursor: string | undefined;
+  do { const l = await storage.list({ prefix, cursor }); out.push(...l.objects); cursor = l.truncated ? l.cursor : undefined; } while (cursor);
+  return out;
+}
+
+export async function createBackup(env: AppEnv["Bindings"], name: string): Promise<string> {
+  const db = env.DB;
+  if (await activeBackup(db)) throw new Error("try again later - another backup/restore operation has already been started");
+  const ev = { app: undefined as unknown, name, exclude: [] as string[], next: async () => undefined as unknown };
+  await trigger("onBackupCreate", ev, null, async () => {
+    if (!ev.name) ev.name = await generateBackupName(db);
+    await lock(db, ev.name);
+    try {
+      const tables = (await all<{ name: string }>(db, "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name")).map((t) => t.name).filter((t) => !INTERNAL_TABLES.test(t) && !SKIP_TABLES.has(t));
+      const dump: Dump = { format: "voidbase-backup", version: 1, created: nowString(), tables: {}, files: [] };
+      for (const t of tables) {
+        const rows = await all<Record<string, unknown>>(db, `SELECT * FROM ${ident(t)}`);
+        const columns = rows.length ? Object.keys(rows[0]!) : (await all<{ name: string }>(db, `PRAGMA table_info(${ident(t)})`)).map((c) => c.name);
+        dump.tables[t] = { columns, rows: rows.map((r) => columns.map((c) => r[c] ?? null)) };
+      }
+      const entries: Record<string, [Uint8Array, { level: 0 | 6 }]> = {};
+      for (const obj of await listAll(env.STORAGE, "")) {
+        if (obj.key.startsWith(PREFIX)) continue;
+        const body = await env.STORAGE.get(obj.key);
+        if (!body) continue;
+        dump.files.push(obj.key);
+        entries[`storage/${obj.key}`] = [new Uint8Array(await body.arrayBuffer()), { level: 0 }];
+      }
+      entries["data.json"] = [new TextEncoder().encode(JSON.stringify(dump)), { level: 6 }];
+      const zip = zipSync(entries);
+      await (await backupsStorage(env)).put(PREFIX + ev.name, zip, { httpMetadata: { contentType: "application/zip" } });
+    } finally { await unlock(db); }
+  });
+  return ev.name;
+}
+
+export async function restoreBackup(env: AppEnv["Bindings"], key: string): Promise<void> {
+  const db = env.DB;
+  const obj = await (await backupsStorage(env)).get(PREFIX + key);
+  if (!obj) throw new Error("missing or invalid backup file");
+  const files = unzipSync(new Uint8Array(await obj.arrayBuffer()));
+  const raw = files["data.json"];
+  if (!raw) throw new Error("not a voidbase backup archive (PocketBase SQLite archives cannot be restored on this server)");
+  const dump = JSON.parse(new TextDecoder().decode(raw)) as Dump;
+  if (dump.format !== "voidbase-backup") throw new Error("unsupported backup format");
+  await lock(db, key);
+  try {
+    const ev = { app: undefined as unknown, name: key, exclude: [] as string[], next: async () => undefined as unknown };
+    await trigger("onBackupRestore", ev, null, async () => {
+      // 1. drop every user collection table/view, 2. restore _collections and rebuild the tables, 3. rows, 4. files
+      const current = await loadCollections(db);
+      const drops: D1PreparedStatement[] = [];
+      for (const c of new Set(current.values())) if (!c.system) drops.push(stmt(db, c.type === "view" ? `DROP VIEW IF EXISTS ${ident(c.name)}` : `DROP TABLE IF EXISTS ${ident(c.name)}`, []));
+      if (drops.length) await db.batch(drops);
+      const insertRows = async (table: string, columns: string[], rows: unknown[][]) => {
+        for (let i = 0; i < rows.length; i += 40) {
+          const chunk = rows.slice(i, i + 40);
+          await db.batch(chunk.map((r) => stmt(db, `INSERT OR REPLACE INTO ${ident(table)} (${columns.map(ident).join(", ")}) VALUES (${columns.map(() => "?").join(", ")})`, r.map((v) => (v === undefined ? null : v)))));
+        }
+      };
+      const coll = dump.tables["_collections"];
+      if (coll) { await run(db, "DELETE FROM `_collections`"); await insertRows("_collections", coll.columns, coll.rows); }
+      invalidateCollections();
+      const restored = await loadCollections(db);
+      const creates: D1PreparedStatement[] = [];
+      for (const c of new Set(restored.values())) {
+        if (c.system) continue;
+        if (c.type === "view") creates.push(db.prepare(createViewSQL(c.name, String(c.options.viewQuery ?? ""))));
+        else for (const sql of planCreate(c)) creates.push(db.prepare(sql));
+      }
+      if (creates.length) await db.batch(creates);
+      for (const [table, data] of Object.entries(dump.tables)) {
+        if (table === "_collections") continue;
+        const exists = await one(db, "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?", [table]);
+        if (!exists) continue;
+        await run(db, `DELETE FROM ${ident(table)}`);
+        await insertRows(table, data.columns, data.rows);
+      }
+      for (const o of await listAll(env.STORAGE, "")) if (!o.key.startsWith(PREFIX)) await env.STORAGE.delete(o.key);
+      for (const f of dump.files) { const bytes = files[`storage/${f}`]; if (bytes) await env.STORAGE.put(f, bytes); }
+      invalidateCollections();
+    });
+  } finally { await unlock(db); }
+}
+
+// autobackup (core/backup.go registerAutobackupHooks): settings.backups.cron, keeping the newest cronMaxKeep
+export async function autoBackup(env: AppEnv["Bindings"]): Promise<void> {
+  const name = await generateBackupName(env.DB, "@auto_pb_backup_");
+  await dispatch({ type: "backup", name }, { env });
+}
+// runs from the jobs queue on Cloudflare (inline elsewhere): create, then keep the newest cronMaxKeep
+registerJobHandler("backup", async (env, job) => {
+  env = await withS3Storage(env);
+  const settings = await loadSettings(env.DB);
+  try { await withHookStore(env.DB, env, () => createBackup(env, job.name)); } catch (err) { console.error("voidbase: [Backup cron] Failed to create backup", job.name, err); return; }
+  const maxKeep = settings.backups.cronMaxKeep;
+  if (!maxKeep) return;
+  const bk = await backupsStorage(env);
+  const autos = (await listAll(bk, PREFIX + "@auto_pb_backup_")).sort((a, b) => b.uploaded.getTime() - a.uploaded.getTime());
+  for (const o of autos.slice(maxKeep)) await bk.delete(o.key);
+});
+
+export function mountBackupsApi(app: Hono<AppEnv>) {
+  app.get("/api/backups", async (c) => {
+    requireSuperuser(c);
+    const objs = await listAll(await backupsStorage(c.env), PREFIX);
+    return c.json(objs.sort((a, b) => (a.key < b.key ? -1 : 1)).map((o) => ({ key: o.key.slice(PREFIX.length), modified: nowString(o.uploaded), size: o.size })));
+  });
+  app.post("/api/backups", async (c) => {
+    requireSuperuser(c);
+    if (await activeBackup(c.env.DB)) throw badRequest("Try again later - another backup/restore process has already been started");
+    let body: Record<string, unknown> = {};
+    try { body = (await c.req.json()) ?? {}; } catch { body = {}; }
+    const name = String(body.name ?? "");
+    if (name) {
+      if (name.length > 150) throw new ApiError(400, "An error occurred while validating the submitted data.", { name: { code: "validation_length_out_of_range", message: "The length must be between 1 and 150.", params: { max: 150, min: 1 } } } as never);
+      if (!NAME_RE.test(name)) throw new ApiError(400, "An error occurred while validating the submitted data.", { name: { code: "validation_match_invalid", message: "Must be in a valid format." } } as never);
+      if (await (await backupsStorage(c.env)).head(PREFIX + name)) throw new ApiError(400, "An error occurred while validating the submitted data.", { name: { code: "validation_backup_name_exists", message: "The backup file name is invalid or already exists." } } as never);
+    }
+    try { await createBackup(c.env, name); } catch (err) { throw badRequest("Failed to create backup."); void err; }
+    return c.body(null, 204);
+  });
+  app.post("/api/backups/upload", async (c) => {
+    requireSuperuser(c);
+    let file: File | null = null;
+    try { const fd = await c.req.formData(); const f = fd.get("file"); if (f instanceof File) file = f; } catch { /* no multipart */ }
+    if (!file) throw new ApiError(400, "An error occurred while validating the submitted data.", { file: { code: "validation_required", message: "Cannot be blank." } } as never);
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    const isZip = bytes.length > 3 && bytes[0] === 0x50 && bytes[1] === 0x4b && (bytes[2] === 0x03 || bytes[2] === 0x05 || bytes[2] === 0x07);
+    if (!isZip) throw new ApiError(400, "An error occurred while validating the submitted data.", { file: { code: "validation_invalid_mime_type", message: `"${normalizeFilename(file.name, file.name.includes(".") ? file.name.slice(file.name.lastIndexOf(".")).toLowerCase() : "")}" mime type must be one of: application/zip.` } } as never);
+    const bk = await backupsStorage(c.env);
+    if (await bk.head(PREFIX + file.name)) throw new ApiError(400, "An error occurred while validating the submitted data.", { file: { code: "validation_backup_name_exists", message: "Backup file with the specified name already exists." } } as never);
+    await bk.put(PREFIX + file.name, bytes, { httpMetadata: { contentType: "application/zip" } });
+    return c.body(null, 204);
+  });
+  app.get("/api/backups/:key", async (c) => {
+    const auth = await findAuthRecordByToken(c.env.DB, c.req.query("token") ?? "", "file");
+    if (!auth || auth.collection.name !== "_superusers") throw forbidden("Insufficient permissions to access the resource.");
+    const allowed = (await loadSettings(c.env.DB)).superuserIPs;
+    if (allowed.length && !ipInList(allowed, await realIP(c))) throw forbidden("Insufficient permissions to access the resource.");
+    const key = c.req.param("key") ?? "";
+    const obj = await (await backupsStorage(c.env)).get(PREFIX + key);
+    if (!obj) throw new ApiError(404, "The requested resource wasn't found.", {});
+    return new Response(obj.body, { headers: { "Content-Type": "application/zip", "Content-Length": String(obj.size), "Content-Disposition": `attachment; filename=${JSON.stringify(key.split("/").pop() ?? key)}`, "Content-Security-Policy": "default-src 'none'; media-src 'self'; style-src 'unsafe-inline'; sandbox" } });
+  });
+  app.delete("/api/backups/:key", async (c) => {
+    requireSuperuser(c);
+    const key = c.req.param("key") ?? "";
+    if (key && (await activeBackup(c.env.DB)) === key) throw badRequest("The backup is currently being used and cannot be deleted.");
+    const bk = await backupsStorage(c.env);
+    if (!(await bk.head(PREFIX + key))) throw badRequest("Invalid or already deleted backup file. Raw error: \nbackup does not exist");
+    await bk.delete(PREFIX + key);
+    return c.body(null, 204);
+  });
+  app.post("/api/backups/:key/restore", async (c) => {
+    requireSuperuser(c);
+    if (await activeBackup(c.env.DB)) throw badRequest("Try again later - another backup/restore process has already been started.");
+    const key = c.req.param("key") ?? "";
+    if (!(await (await backupsStorage(c.env)).head(PREFIX + key))) throw badRequest("Missing or invalid backup file.");
+    c.executionCtx.waitUntil(restoreBackup(c.env, key).catch((err) => console.error("voidbase: Failed to restore backup", key, err)));
+    return c.body(null, 204);
+  });
+}

package/src/server/batch.ts

@@ -0,0 +1,123 @@
+// POST /api/batch (apis/batch.go): a list of record create/update/upsert/delete requests executed in order
+// through the same handlers. D1 has no interactive transactions, so atomicity is emulated: every applied
+// request records an undo statement (delete the created row, restore the previous row) and a failure rolls
+// them back in one D1 batch before answering with PocketBase's error shape. Files of rolled-back creates are
+// removed; files removed by a rolled-back delete cannot be restored, and cascades are not undone.
+import type { Context, Hono } from "hono";
+import { loadCollections } from "./collections/model";
+import { ident, one, stmt } from "./db";
+import { ApiError, badRequest, forbidden } from "./errors";
+import { deletePrefix, normalizeFilename } from "./records/files";
+import { loadSettings } from "./settings";
+import { requestHook } from "./hooks/runtime";
+import type { AppEnv, Row } from "./types";
+import type { Field } from "./collections/fields";
+import { toColumn } from "./records/values";
+
+interface InternalRequest { method?: string; url?: string; headers?: Record<string, string>; body?: Record<string, unknown> }
+const ACTIONS: { re: RegExp; kind: "upsert" | "create" | "update" | "delete" }[] = [
+  { re: /^PUT \/api\/collections\/([^/?]+)\/records(\?.*)?$/, kind: "upsert" },
+  { re: /^POST \/api\/collections\/([^/?]+)\/records(\?.*)?$/, kind: "create" },
+  { re: /^PATCH \/api\/collections\/([^/?]+)\/records\/([^/?]+)(\?.*)?$/, kind: "update" },
+  { re: /^DELETE \/api\/collections\/([^/?]+)\/records\/([^/?]+)(\?.*)?$/, kind: "delete" },
+];
+export const BATCH_CONTEXT_HEADER = "x-voidbase-internal-context";
+// per isolate; external requests cannot forge it. Generated lazily: Workers forbid random values at module scope.
+let batchToken: string | null = null;
+export const batchContextToken = () => (batchToken ??= crypto.randomUUID());
+
+export function mountBatch(app: Hono<AppEnv>) {
+  app.post("/api/batch", async (c) => {
+    const settings = await loadSettings(c.env.DB);
+    if (!settings.batch.enabled || settings.batch.maxRequests <= 0) throw forbidden("Batch requests are not allowed.");
+    const { requests: parsed, files } = await readBatchBody(c);
+    if (!parsed) throw new ApiError(400, "Invalid batch request data.", { requests: { code: "validation_required", message: "Cannot be blank." } } as never);
+    if (parsed.length > settings.batch.maxRequests) throw new ApiError(400, "Invalid batch request data.", { requests: { code: "validation_length_too_long", message: `The length must be no more than ${settings.batch.maxRequests}.`, params: { max: settings.batch.maxRequests, min: 0 } } } as never);
+    return requestHook("onBatchRequest", c, null, { batch: parsed }, async (ev) => {
+    const requests = ev.batch as InternalRequest[];
+    const collections = await loadCollections(c.env.DB);
+    const origin = new URL(c.req.url).origin;
+    const results: { body: unknown; status: number }[] = [];
+    const undo: { statements: D1PreparedStatement[]; filePrefixes: string[] } = { statements: [], filePrefixes: [] };
+    const fail = async (index: number, response: unknown) => {
+      if (undo.statements.length) { try { await c.env.DB.batch(undo.statements.reverse()); } catch (err) { console.error("voidbase: batch rollback failed", err); } }
+      for (const p of undo.filePrefixes) { try { await deletePrefix(c.env.STORAGE, p); } catch { /* best effort */ } }
+      throw new ApiError(400, "Batch transaction failed.", { requests: { [String(index)]: { code: "batch_request_failed", message: "Batch request failed.", response } } } as never);
+    };
+    for (let i = 0; i < requests.length; i++) {
+      const ir = requests[i] ?? {};
+      let method = String(ir.method ?? "").toUpperCase(), url = String(ir.url ?? "");
+      const action = ACTIONS.map((a) => ({ a, m: a.re.exec(`${method} ${url}`) })).find((x) => x.m);
+      if (!action) await fail(i, { data: {}, message: "Something went wrong while processing your request.", status: 400 });
+      const [, collName, maybeId] = action!.m!;
+      const collection = collections.get(collName!) ?? null;
+      let kind = action!.a.kind;
+      let id = kind === "update" || kind === "delete" ? maybeId! : "";
+      if (kind === "upsert") {
+        const bodyId = String(ir.body?.id ?? "");
+        const existing = bodyId && collection ? await one<Row>(c.env.DB, `SELECT id FROM ${ident(collection.name)} WHERE id = ? LIMIT 1`, [bodyId]) : null;
+        const query = action!.m![2] ?? "";
+        if (existing) { kind = "update"; id = bodyId; method = "PATCH"; url = `/api/collections/${collName}/records/${bodyId}${query}`; }
+        else { kind = "create"; method = "POST"; url = `/api/collections/${collName}/records${query}`; }
+      }
+      // snapshot for the undo of updates and deletes
+      const before = (kind === "update" || kind === "delete") && collection ? await one<Row>(c.env.DB, `SELECT * FROM ${ident(collection.name)} WHERE id = ? LIMIT 1`, [id]) : null;
+      const headers = new Headers(c.req.raw.headers);
+      headers.delete("content-type"); headers.delete("content-length");
+      for (const [k, v] of Object.entries(ir.headers ?? {})) if (k.toLowerCase() !== "authorization") headers.set(k, v);
+      headers.set(BATCH_CONTEXT_HEADER, batchContextToken());
+      let body: BodyInit | undefined;
+      const reqFiles = files.get(i);
+      if (reqFiles && reqFiles.length) {
+        const fd = new FormData();
+        fd.append("@jsonPayload", JSON.stringify(ir.body ?? {}));
+        // PocketBase normalizes the uploaded name once here (NewFileFromMultipart) and again in the record form
+        for (const [field, file] of reqFiles) fd.append(field, file, normalizeFilename(file.name, file.name.includes(".") ? file.name.slice(file.name.lastIndexOf(".")).toLowerCase() : ""));
+        body = fd;
+      } else if (method !== "DELETE") { body = JSON.stringify(ir.body ?? {}); headers.set("content-type", "application/json"); }
+      const res = await app.fetch(new Request(origin + url, { method, headers, body }), c.env, c.executionCtx);
+      const text = await res.text();
+      let json: unknown = null; try { json = text ? JSON.parse(text) : null; } catch { json = text; }
+      if (res.status >= 400) await fail(i, json);
+      results.push({ body: json, status: res.status });
+      if (!collection) continue;
+      const table = ident(collection.name);
+      if (kind === "create") {
+        const createdId = String((json as { id?: string })?.id ?? "");
+        if (createdId) { undo.statements.push(stmt(c.env.DB, `DELETE FROM ${table} WHERE id = ?`, [createdId])); undo.filePrefixes.push(`${collection.id}/${createdId}/`); }
+      } else if (before) {
+        const fields = collection.fields as Field[];
+        const cols = fields.map((f) => ident(f.name));
+        const params = fields.map((f) => before[f.name] === undefined ? null : toColumn(f, before[f.name]));
+        undo.statements.push(kind === "delete"
+          ? stmt(c.env.DB, `INSERT OR REPLACE INTO ${table} (${cols.join(", ")}) VALUES (${cols.map(() => "?").join(", ")})`, params)
+          : stmt(c.env.DB, `UPDATE ${table} SET ${fields.filter((f) => f.name !== "id").map((f) => `${ident(f.name)} = ?`).join(", ")} WHERE id = ?`, [...fields.filter((f) => f.name !== "id").map((f) => before[f.name] === undefined ? null : toColumn(f, before[f.name])), id]));
+      }
+    }
+    return c.json(results);
+    });
+  });
+}
+
+async function readBatchBody(c: Context<AppEnv>): Promise<{ requests: InternalRequest[] | null; files: Map<number, [string, File][]> }> {
+  const ct = c.req.header("content-type") ?? "";
+  const files = new Map<number, [string, File][]>();
+  try {
+    if (ct.includes("multipart/form-data")) {
+      const fd = await c.req.formData();
+      let payload: { requests?: InternalRequest[] } = {};
+      const raw = fd.get("@jsonPayload");
+      if (typeof raw === "string") payload = JSON.parse(raw) as typeof payload;
+      for (const [key, value] of fd.entries()) {
+        const m = /^requests[.[](\d+)[.\]]\.?(.+)$/.exec(key.replace(/\]\./, "."));
+        if (!m || typeof value === "string") continue;
+        const idx = Number(m[1]); const field = m[2]!.replace(/^\./, "");
+        if (!files.has(idx)) files.set(idx, []);
+        files.get(idx)!.push([field, value]);
+      }
+      return { requests: Array.isArray(payload.requests) && payload.requests.length ? payload.requests : null, files };
+    }
+    const json = (await c.req.json()) as { requests?: InternalRequest[] };
+    return { requests: Array.isArray(json?.requests) && json.requests.length ? json.requests : null, files };
+  } catch { throw badRequest("Failed to read the submitted batch data."); }
+}

package/src/server/bootstrap.ts

@@ -0,0 +1,71 @@
+import { env as voidEnv } from "#platform/env";
+import { invalidateCollections, type Collection } from "./collections/model";
+import { systemCollections } from "./collections/system";
+import { all, ident, one, run } from "./db";
+import { nowString, randomId, randomString } from "./ids";
+import { hashPassword } from "./password";
+import { ensureSettingsRow } from "./settings";
+
+let pending: Promise<void> | null = null;
+type AfterSystem = (db: D1Database) => Promise<unknown>;
+
+// Runs once per isolate; idempotent across isolates (INSERT OR IGNORE on unique keys).
+// `afterSystem` runs after the system tables exist (used for the bundled pb_migrations).
+export function ensureBootstrapped(db: D1Database, afterSystem?: AfterSystem): Promise<void> {
+  return (pending ??= bootstrap(db, afterSystem).catch((err) => {
+    pending = null;
+    throw err;
+  }));
+}
+
+async function bootstrap(db: D1Database, afterSystem?: AfterSystem): Promise<void> {
+  const existing = new Set((await all<{ name: string }>(db, "SELECT name FROM `_collections` WHERE system = 1")).map((r) => r.name));
+  const now = nowString();
+  for (const c of systemCollections()) {
+    if (existing.has(c.name)) continue;
+    await insertCollection(db, c, now);
+  }
+  if (existing.size === 0) invalidateCollections();
+  await ensureSettingsRow(db);
+  await upsertSuperuserFromEnv(db);
+  if (afterSystem) await afterSystem(db);
+}
+
+export async function insertCollection(db: D1Database, c: Collection, now = nowString()): Promise<void> {
+  await run(
+    db,
+    "INSERT OR IGNORE INTO `_collections` (id, system, type, name, fields, indexes, listRule, viewRule, createRule, updateRule, deleteRule, options, created, updated) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+    [c.id, c.system, c.type, c.name, JSON.stringify(c.fields), JSON.stringify(c.indexes),
+      c.listRule, c.viewRule, c.createRule, c.updateRule, c.deleteRule, JSON.stringify(c.options), c.created || now, c.updated || now],
+  );
+}
+
+// Mirrors `pocketbase superuser upsert EMAIL PASS` from env, so a fresh deploy has a way in.
+async function upsertSuperuserFromEnv(db: D1Database): Promise<void> {
+  const email = voidEnv.VOIDBASE_SUPERUSER_EMAIL;
+  const password = voidEnv.VOIDBASE_SUPERUSER_PASSWORD;
+  if (!email || !password) return;
+  await upsertSuperuser(db, email, password);
+}
+
+// `pocketbase superuser upsert EMAIL PASS`
+export async function upsertSuperuser(db: D1Database, email: string, password: string): Promise<"created" | "updated" | "unchanged"> {
+  const table = ident("_superusers");
+  const existing = await one(db, `SELECT id, password FROM ${table} WHERE email = ? LIMIT 1`, [email]);
+  const now = nowString();
+  if (existing) {
+    // Only rehash when the stored hash no longer matches the configured password (cheap check first).
+    const { verifyPassword } = await import("./password");
+    if (await verifyPassword(password, String(existing.password ?? ""))) return "unchanged";
+    await run(db, `UPDATE ${table} SET password = ?, tokenKey = ?, updated = ? WHERE id = ?`, [
+      await hashPassword(password), randomString(50), now, existing.id,
+    ]);
+    return "updated";
+  }
+  await run(
+    db,
+    `INSERT OR IGNORE INTO ${table} (id, password, tokenKey, email, emailVisibility, verified, created, updated) VALUES (?,?,?,?,?,?,?,?)`,
+    [randomId(), await hashPassword(password), randomString(50), email, false, true, now, now],
+  );
+  return "created";
+}

package/src/server/collections/auth-option-shape.json

@@ -0,0 +1,71 @@
+{
+ "authRule": null,
+ "manageRule": null,
+ "authAlert": {
+  "enabled": null,
+  "emailTemplate": {
+   "subject": null,
+   "body": null
+  }
+ },
+ "oauth2": {
+  "providers": null,
+  "mappedFields": {
+   "id": null,
+   "name": null,
+   "username": null,
+   "avatarURL": null
+  },
+  "enabled": null
+ },
+ "passwordAuth": {
+  "enabled": null,
+  "identityFields": null
+ },
+ "mfa": {
+  "enabled": null,
+  "duration": null,
+  "rule": null
+ },
+ "otp": {
+  "enabled": null,
+  "duration": null,
+  "length": null,
+  "emailTemplate": {
+   "subject": null,
+   "body": null
+  }
+ },
+ "authToken": {
+  "secret": null,
+  "duration": null
+ },
+ "passwordResetToken": {
+  "secret": null,
+  "duration": null
+ },
+ "emailChangeToken": {
+  "secret": null,
+  "duration": null
+ },
+ "verificationToken": {
+  "secret": null,
+  "duration": null
+ },
+ "fileToken": {
+  "secret": null,
+  "duration": null
+ },
+ "verificationTemplate": {
+  "subject": null,
+  "body": null
+ },
+ "resetPasswordTemplate": {
+  "subject": null,
+  "body": null
+ },
+ "confirmEmailChangeTemplate": {
+  "subject": null,
+  "body": null
+ }
+}

package/src/server/collections/ddl.ts

@@ -0,0 +1,127 @@
+// SQL generation mirroring PocketBase core/collection_record_table_sync.go.
+// Everything returns statement strings; the service runs them in one D1 batch.
+import { ident } from "../db";
+import { columnType, isMultiple, type Field } from "./fields";
+import type { Collection } from "./model";
+
+export interface ParsedIndex {
+  unique: boolean;
+  optional: boolean;
+  name: string;
+  table: string;
+  columns: string;
+  where: string;
+  raw: string;
+}
+
+// CREATE [UNIQUE] INDEX [IF NOT EXISTS] `name` ON `table` (cols) [WHERE expr]
+const INDEX_RE = /^\s*CREATE\s+(UNIQUE\s+)?\s*INDEX\s*(IF\s+NOT\s+EXISTS\s+)?([^\s(]*)\s+ON\s+([^\s(]*)\s*\(([\s\S]*)\)(?:\s*WHERE\s+([\s\S]*))?\s*;?\s*$/i;
+
+export function parseIndex(raw: string): ParsedIndex | null {
+  const m = INDEX_RE.exec(raw);
+  if (!m) return null;
+  const unq = (v: string) => v.trim().replace(/^[`"']|[`"']$/g, "");
+  return { unique: !!m[1], optional: !!m[2], name: unq(m[3] ?? ""), table: unq(m[4] ?? ""), columns: (m[5] ?? "").trim(), where: (m[6] ?? "").trim(), raw };
+}
+
+// Mirrors dbutils.Index.Build(): backticked names, multi-column bodies on indented lines, COLLATE and sort kept.
+export function buildIndex(idx: ParsedIndex, table: string): string {
+  const cols = idx.columns.split(",").map((c) => c.trim()).filter(Boolean).map((raw) => {
+    const m = /^([\s\S]+?)(?:\s+collate\s+(\w+))?(?:\s+(asc|desc))?$/i.exec(raw);
+    const name = (m?.[1] ?? raw).trim().replace(/^[`"']|[`"']$/g, "");
+    const quoted = name.includes("(") || name.includes(" ") ? name : "`" + name + "`";
+    return quoted + (m?.[2] ? ` COLLATE ${m[2]}` : "") + (m?.[3] ? ` ${m[3].toUpperCase()}` : "");
+  });
+  let out = `CREATE ${idx.unique ? "UNIQUE " : ""}INDEX ${idx.optional ? "IF NOT EXISTS " : ""}\`${idx.name}\` ON \`${table}\` (`;
+  out += cols.length > 1 ? "\n  " + cols.join(",\n  ") + "\n" : cols.join("");
+  out += ")";
+  if (idx.where) out += ` WHERE ${idx.where}`;
+  return out;
+}
+
+// Normalize an index expression the way PocketBase stores it: parsed, table name replaced, rebuilt.
+export function normalizeIndex(raw: string, table: string): string {
+  const idx = parseIndex(raw);
+  return idx ? buildIndex(idx, table) : raw;
+}
+
+export function createTableSQL(c: Collection): string {
+  const cols = (c.fields as Field[]).map((f) => `${ident(f.name)} ${columnType(f)}`);
+  return `CREATE TABLE ${ident(c.name)} (${cols.join(", ")})`;
+}
+
+export function createIndexesSQL(c: Collection): string[] {
+  return c.indexes.map((raw) => {
+    const idx = parseIndex(raw);
+    if (!idx) throw new Error(`invalid index expression: ${raw}`);
+    return buildIndex(idx, c.name);
+  });
+}
+
+export function dropIndexesSQL(c: Collection): string[] {
+  return c.indexes.map((raw) => parseIndex(raw)).filter((i): i is ParsedIndex => !!i && !!i.name).map((i) => `DROP INDEX IF EXISTS ${ident(i.name)}`);
+}
+
+export const dropTableSQL = (name: string) => `DROP TABLE IF EXISTS ${ident(name)}`;
+export const dropViewSQL = (name: string) => `DROP VIEW IF EXISTS ${ident(name)}`;
+export const truncateSQL = (name: string) => `DELETE FROM ${ident(name)}`;
+export const createViewSQL = (name: string, query: string) => `CREATE VIEW ${ident(name)} AS ${query.trim().replace(/;\s*$/, "")}`;
+
+let tempCounter = 0;
+const temp = (base: string) => `${base}_vb${(++tempCounter).toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+
+// Statements to bring the table for `oldC` in line with `newC` (fields matched by id, as PocketBase does).
+export function syncTableSQL(oldC: Collection, newC: Collection): string[] {
+  const out: string[] = [];
+  const oldFields = oldC.fields as Field[];
+  const newFields = newC.fields as Field[];
+  const renameTable = oldC.name.toLowerCase() !== newC.name.toLowerCase();
+  const indexesChanged = renameTable || JSON.stringify(oldFields) !== JSON.stringify(newFields) || JSON.stringify(oldC.indexes) !== JSON.stringify(newC.indexes);
+
+  if (indexesChanged) out.push(...dropIndexesSQL(oldC));
+  if (renameTable) out.push(`ALTER TABLE ${ident(oldC.name)} RENAME TO ${ident(newC.name)}`);
+  const table = newC.name;
+
+  // removed columns
+  for (const of of oldFields) {
+    if (!newFields.some((f) => f.id === of.id)) out.push(`ALTER TABLE ${ident(table)} DROP COLUMN ${ident(of.name)}`);
+  }
+  // added + renamed columns, via temp names so swaps cannot collide
+  const toRename: Array<[string, string]> = [];
+  for (const f of newFields) {
+    const of = oldFields.find((x) => x.id === f.id);
+    if (!of) {
+      const t = temp(f.name);
+      toRename.push([t, f.name]);
+      out.push(`ALTER TABLE ${ident(table)} ADD COLUMN ${ident(t)} ${columnType(f)}`);
+    } else if (of.name !== f.name) {
+      const t = temp(f.name);
+      toRename.push([t, f.name]);
+      out.push(`ALTER TABLE ${ident(table)} RENAME COLUMN ${ident(of.name)} TO ${ident(t)}`);
+    }
+  }
+  for (const [t, name] of toRename) out.push(`ALTER TABLE ${ident(table)} RENAME COLUMN ${ident(t)} TO ${ident(name)}`);
+
+  // single <-> multiple value conversions (select, file, relation)
+  for (const f of newFields) {
+    const of = oldFields.find((x) => x.id === f.id);
+    if (!of || of.type !== f.type) continue;
+    const wasMulti = isMultiple(of);
+    const isMulti = isMultiple(f);
+    if (wasMulti === isMulti) continue;
+    const col = ident(f.name);
+    const old = temp("_" + f.name);
+    out.push(`ALTER TABLE ${ident(table)} RENAME COLUMN ${col} TO ${ident(old)}`);
+    out.push(`ALTER TABLE ${ident(table)} ADD COLUMN ${col} ${columnType(f)}`);
+    const o = ident(old);
+    out.push(
+      isMulti
+        ? `UPDATE ${ident(table)} SET ${col} = (CASE WHEN COALESCE(${o}, '') = '' THEN '[]' ELSE (CASE WHEN json_valid(${o}) AND json_type(${o}) = 'array' THEN ${o} ELSE json_array(${o}) END) END)`
+        : `UPDATE ${ident(table)} SET ${col} = (CASE WHEN COALESCE(${o}, '[]') = '[]' THEN '' ELSE (CASE WHEN json_valid(${o}) AND json_type(${o}) = 'array' THEN COALESCE(json_extract(${o}, '$[#-1]'), '') ELSE ${o} END) END)`,
+    );
+    out.push(`ALTER TABLE ${ident(table)} DROP COLUMN ${o}`);
+  }
+
+  if (indexesChanged) out.push(...createIndexesSQL(newC));
+  return out;
+}