@voidbase-cloud/voidbase 0.1.0

package/src/server/collections/validate.ts

@@ -0,0 +1,239 @@
+// Collection validation mirroring PocketBase core/collection_validate.go (codes and messages).
+import type { FieldErrors } from "../errors";
+import { compileFilter, FilterError } from "../filter/compile";
+import { FilterSyntaxError } from "../filter/lexer";
+import { parseIndex } from "./ddl";
+import { FIELD_TYPES, isFieldType, type Field } from "./fields";
+import type { Collection } from "./model";
+
+type Errs = Record<string, unknown>; // nested: { name: {code,message}, fields: { "1": { name: {...} } } }
+const err = (code: string, message: string) => ({ code, message });
+
+const NAME_RE = /^\w+$/;
+const ID_RE = /^[^@#$&|.,'"\\/\s]+$/;
+const RESERVED_FIELD_NAMES = ["collectionId", "collectionName", "expand"];
+const RESERVED_AUTH_KEYS = ["passwordConfirm", "oldPassword"];
+const INTERNAL_TABLES = ["_collections", "_params", "_migrations", "_pbMigrations", "_void_migrations", "_changes", "_realtime_clients", "_logs"];
+
+export interface ValidateContext {
+  all: Collection[]; // every known collection (including ones being imported in the same batch)
+  usedIndexNames: Map<string, string>; // lowercase index name -> table name (from sqlite_master)
+}
+
+export function validateCollection(c: Collection, old: Collection | null, ctx: ValidateContext): Errs {
+  const errs: Errs = {};
+  const isNew = !old;
+
+  const nameErr = validateName(c, old, ctx);
+  if (nameErr) errs.name = nameErr;
+
+  if (!c.id) errs.id = err("validation_required", "Cannot be blank.");
+  else if (isNew && (c.id.length > 100 || !ID_RE.test(c.id))) errs.id = err("validation_match_invalid", "Must be in a valid format.");
+  else if (isNew && !nameErr && ctx.all.some((x) => x !== c && x.id === c.id)) errs.id = err("validation_invalid_id", "The model id is invalid or already exists.");
+  else if (!isNew && c.id !== old.id) errs.id = err("validation_values_mismatch", "Values don't match.");
+
+  if (!isNew && c.system !== old.system) errs.system = err("validation_collection_system_flag_change", "System collection state cannot be changed.");
+
+  if (!c.type) errs.type = err("validation_required", "Cannot be blank.");
+  else if (!["base", "auth", "view"].includes(c.type)) errs.type = err("validation_in_invalid", "Must be a valid value.");
+  else if (!isNew && c.type !== old.type) errs.type = err("validation_collection_type_change", "Collection type cannot be changed.");
+
+  const fieldsErr = validateFields(c, old);
+  if (fieldsErr) errs.fields = fieldsErr;
+
+  const idxErr = validateIndexes(c, old, ctx);
+  if (idxErr) errs.indexes = idxErr;
+
+  // API rules: view collections cannot have write rules (ozzo Nil), every rule must compile against the
+  // collection's own fields (checkRule), system collection rules are frozen (ensureNoSystemRuleChange).
+  const frozen = !isNew && old.system;
+  const ruleChange = (nv: unknown, ov: unknown) => (frozen && (nv ?? null) !== (ov ?? null) ? err("validation_collection_system_rule_change", "System collection API rule cannot be changed.") : null);
+  for (const k of ["listRule", "viewRule", "createRule", "updateRule", "deleteRule"] as const) {
+    const v = (c[k] ?? null) as string | null;
+    if (c.type === "view" && k !== "listRule" && k !== "viewRule" && v !== null) errs[k] = err("validation_nil", "Must be blank.");
+    else errs[k] = ruleError(v, c, ctx) ?? ruleChange(v, old?.[k]);
+    if (!errs[k]) delete errs[k];
+  }
+  if (c.type === "auth") {
+    const opts = c.options as { authRule?: string | null; manageRule?: string | null; mfa?: { enabled?: boolean; rule?: string } };
+    const oldOpts = (old?.options ?? {}) as typeof opts;
+    const authRuleErr = ruleError(opts.authRule ?? null, c, ctx) ?? ruleChange(opts.authRule, oldOpts.authRule);
+    if (authRuleErr) errs.authRule = authRuleErr;
+    const manageRuleErr = opts.manageRule === "" ? err("validation_nil_or_not_empty_required", "Cannot be blank.") : ruleError(opts.manageRule ?? null, c, ctx) ?? ruleChange(opts.manageRule, oldOpts.manageRule);
+    if (manageRuleErr) errs.manageRule = manageRuleErr;
+    // collection_model_auth_options.go returns the struct errors first; the mfa rule is only checked after they pass
+    const mfaRule = opts.mfa?.rule ?? "";
+    if (opts.mfa?.enabled && mfaRule && !authRuleErr && !manageRuleErr) { const e = ruleError(mfaRule, c, ctx) ?? ruleChange(mfaRule, oldOpts.mfa?.rule ?? ""); if (e) errs.mfa = { rule: e }; }
+  }
+  // Go serializes validation.Errors (a map) with sorted keys
+  return Object.fromEntries(Object.entries(errs).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+// core/collection_validate.go checkRule: a dry compile with an empty request (no auth) - the same resolver the
+// records API uses, so unknown fields, bad relation paths and syntax errors surface at save time.
+function ruleError(rule: string | null, c: Collection, ctx: ValidateContext) {
+  if (rule === null || rule === "") return null;
+  const collections = new Map<string, Collection>();
+  for (const x of ctx.all) { collections.set(x.id, x); collections.set(x.name, x); }
+  try {
+    compileFilter(rule, { base: c, collections, request: { auth: null, method: "GET", query: {}, headers: {}, body: {}, context: "default" }, allowHiddenFields: true });
+    return null;
+  } catch (e) {
+    // search.FilterData.BuildExpr: parse failures collapse to one message; resolver failures keep their text
+    const raw = e instanceof FilterSyntaxError ? "invalid or incomplete filter expression" : e instanceof FilterError ? e.message : null;
+    if (raw === null) throw e;
+    return err("validation_invalid_rule", `Invalid rule. Raw error: ${/[.!?]$/.test(raw) ? raw : raw + "."}`);
+  }
+}
+
+function validateName(c: Collection, old: Collection | null, ctx: ValidateContext) {
+  if (!c.name) return err("validation_required", "Cannot be blank.");
+  if (c.name.length > 255) return err("validation_length_out_of_range", "The length must be between 1 and 255.");
+  if (c.name.includes("_via_")) return err("validation_found_via", `The value cannot contain "_via_".`);
+  if (!NAME_RE.test(c.name)) return err("validation_match_invalid", "Must be in a valid format.");
+  if (old?.system && old.name !== c.name) return err("validation_collection_system_name_change", "System collection name cannot be changed.");
+  const lower = c.name.toLowerCase();
+  if (ctx.all.some((x) => x !== c && x.name.toLowerCase() === lower)) {
+    return err("validation_collection_name_exists", "Collection name must be unique (case insensitive).");
+  }
+  if (ctx.all.some((x) => x !== c && x.id.toLowerCase() === lower)) {
+    return err("validation_collection_name_id_duplicate", "The name must not match an existing collection id.");
+  }
+  if (INTERNAL_TABLES.some((t) => t.toLowerCase() === lower) || lower.startsWith("sqlite_")) {
+    return err("validation_collection_name_invalid", "The name shouldn't match with an existing internal table.");
+  }
+  return null;
+}
+
+function validateFields(c: Collection, old: Collection | null): Errs | { code: string; message: string } | null {
+  const fields = c.fields as Field[];
+  const ids = new Set<string>();
+  const names = new Set<string>();
+  const perField: Errs = {};
+  const exclude = [...RESERVED_FIELD_NAMES, ...(c.type === "auth" ? [] : [])];
+
+  fields.forEach((f, i) => {
+    const fe: Errs = {};
+    if (!f.type || !isFieldType(f.type)) fe.type = err("validation_in_invalid", `Must be one of ${FIELD_TYPES.join(", ")}.`);
+    if (ids.has(f.id)) return void (perField[String(i)] = { id: err("validation_duplicated_field_id", `Duplicated or invalid field id "${f.id}"`) });
+    ids.add(f.id);
+    const lower = f.name.toLowerCase();
+    if (names.has(lower)) return void (perField[String(i)] = { name: err("validation_duplicated_field_name", `Duplicated or invalid field name ${f.name}`) });
+    names.add(lower);
+    if (!f.name) fe.name = err("validation_required", "Cannot be blank.");
+    else if (f.name.length > 100) fe.name = err("validation_length_out_of_range", "The length must be between 1 and 100.");
+    else if (!NAME_RE.test(f.name)) fe.name = err("validation_match_invalid", "Must be in a valid format.");
+    else if (exclude.includes(f.name)) fe.name = err("validation_not_in_invalid", "Must not be in list.");
+    else if (f.name.includes("_via_")) fe.name = err("validation_found_via", `The value cannot contain "_via_".`);
+    else if (c.type === "auth" && RESERVED_AUTH_KEYS.includes(f.name)) fe.name = err("validation_reserved_field_name", "The field name is reserved and cannot be used.");
+    if (f.help && String(f.help).length > 300) fe.help = err("validation_length_out_of_range", "The length must be between 0 and 300.");
+    if (old) {
+      const of = (old.fields as Field[]).find((x) => x.id === f.id);
+      if (of && of.type !== f.type) fe.type = err("validation_field_type_change", "Field type cannot be changed.");
+    }
+    Object.assign(fe, fieldSettingsErrors(f, c));
+    if (Object.keys(fe).length) perField[String(i)] = fe;
+  });
+  if (Object.keys(perField).length) return perField;
+
+  if (c.type !== "view") {
+    const pk = fields.find((f) => f.name === "id");
+    if (!pk || pk.type !== "text" || !pk.primaryKey || !pk.system) return err("validation_missing_primary_key", `Missing or invalid "id" PK field.`);
+    if (c.type === "auth") {
+      const need: Array<[string, string, string]> = [
+        ["password", "password", "validation_missing_password_field"],
+        ["tokenKey", "text", "validation_missing_tokenKey_field"],
+        ["email", "email", "validation_missing_email_field"],
+        ["emailVisibility", "bool", "validation_missing_emailVisibility_field"],
+        ["verified", "bool", "validation_missing_verified_field"],
+      ];
+      for (const [name, type, code] of need) {
+        const f = fields.find((x) => x.name === name);
+        if (!f || f.type !== type || !f.system) return err(code, `System "${name}" field is required.`);
+      }
+    }
+    if (old) {
+      for (const of of old.fields as Field[]) {
+        if (!of.system) continue;
+        const nf = fields.find((x) => x.id === of.id);
+        if (!nf || nf.name !== of.name) return err("validation_system_field_change", "System fields cannot be deleted or renamed.");
+      }
+    }
+  }
+  return null;
+}
+
+function fieldSettingsErrors(f: Field, c: Collection): Errs {
+  const e: Errs = {};
+  const n = (v: unknown) => (v === null || v === undefined ? null : Number(v));
+  switch (f.type) {
+    case "text":
+      if (f.primaryKey && f.name !== "id") e.name = err("validation_in_invalid", "Must be a valid value.");
+      if ((n(f.min) ?? 0) < 0) e.min = err("validation_min_greater_equal_than_required", "Must be no less than 0.");
+      if ((n(f.max) ?? 0) < 0 || ((n(f.max) ?? 0) > 0 && (n(f.max) ?? 0) < (n(f.min) ?? 0))) e.max = err("validation_min_greater_equal_than_required", `Must be no less than ${n(f.min) ?? 0}.`);
+      break;
+    case "number":
+      if (f.onlyInt) {
+        if (n(f.min) !== null && !Number.isInteger(n(f.min))) e.min = err("validation_only_int_constraint", "Must be an integer.");
+        if (n(f.max) !== null && !Number.isInteger(n(f.max))) e.max = err("validation_only_int_constraint", "Must be an integer.");
+      }
+      if (n(f.min) !== null && n(f.max) !== null && (n(f.max) as number) < (n(f.min) as number)) e.max = err("validation_min_greater_equal_than_required", `Must be no less than ${n(f.min)}.`);
+      break;
+    case "select": {
+      const values = Array.isArray(f.values) ? f.values : [];
+      if (values.length === 0) e.values = err("validation_required", "Cannot be blank.");
+      if ((n(f.maxSelect) ?? 0) < 0 || (n(f.maxSelect) ?? 0) > values.length) e.maxSelect = err("validation_max_less_equal_than_required", `Must be no greater than ${values.length}.`);
+      break;
+    }
+    case "file":
+      if ((n(f.maxSelect) ?? 0) < 0) e.maxSelect = err("validation_min_greater_equal_than_required", "Must be no less than 0.");
+      if ((n(f.maxSize) ?? 0) < 0) e.maxSize = err("validation_min_greater_equal_than_required", "Must be no less than 0.");
+      break;
+    case "relation":
+      if (!f.collectionId) e.collectionId = err("validation_required", "Cannot be blank.");
+      if ((n(f.minSelect) ?? 0) < 0) e.minSelect = err("validation_min_greater_equal_than_required", "Must be no less than 0.");
+      if ((n(f.maxSelect) ?? 0) < 0 || ((n(f.maxSelect) ?? 0) > 0 && (n(f.maxSelect) ?? 0) < (n(f.minSelect) ?? 0))) e.maxSelect = err("validation_min_greater_equal_than_required", `Must be no less than ${n(f.minSelect) ?? 0}.`);
+      break;
+    case "editor": case "json":
+      if ((n(f.maxSize) ?? 0) < 0) e.maxSize = err("validation_min_greater_equal_than_required", "Must be no less than 0.");
+      break;
+    case "password": {
+      // ozzo-validation skips zero values for Min/Max, so 0 means "unset"
+      const min = n(f.min) ?? 0;
+      const max = n(f.max) ?? 0;
+      if (min !== 0 && (min < 1 || min > 71)) e.min = err("validation_min_greater_equal_than_required", "Must be between 1 and 71.");
+      if (max !== 0 && (max < min || max > 71)) e.max = err("validation_max_less_equal_than_required", `Must be between ${min} and 71.`);
+      break;
+    }
+    case "autodate":
+      if (!f.onCreate && !f.onUpdate) e.onCreate = err("validation_required", "Cannot be blank.");
+      break;
+    case "date":
+      if (f.min && f.max && String(f.max) < String(f.min)) e.max = err("validation_min_greater_equal_than_required", `Must be no less than ${f.min}.`);
+      break;
+  }
+  void c;
+  return e;
+}
+
+function validateIndexes(c: Collection, old: Collection | null, ctx: ValidateContext): Errs | { code: string; message: string } | null {
+  if (c.type === "view" && c.indexes.length > 0) return err("validation_indexes_not_supported", "View collections don't support indexes.");
+  const names = new Set<string>();
+  const defs = new Set<string>();
+  const per: Errs = {};
+  c.indexes.forEach((raw, i) => {
+    const p = parseIndex(raw);
+    if (!p || !p.name || !p.columns) return void (per[String(i)] = err("validation_invalid_index_expression", "Invalid CREATE INDEX expression."));
+    const lower = p.name.toLowerCase();
+    if (names.has(lower)) return void (per[String(i)] = err("validation_duplicated_index_name", "The index name already exists."));
+    names.add(lower);
+    const usedBy = ctx.usedIndexNames.get(lower);
+    if (usedBy && usedBy.toLowerCase() !== c.name.toLowerCase() && usedBy.toLowerCase() !== (old?.name ?? "").toLowerCase()) {
+      return void (per[String(i)] = err("validation_existing_index_name", `The index name is already used in ${usedBy} collection.`));
+    }
+    const def = `${p.unique}|${p.columns.replace(/\s+/g, "").toLowerCase()}|${p.where.toLowerCase()}`;
+    if (defs.has(def)) return void (per[String(i)] = err("validation_duplicated_index_definition", "The index definition already exists."));
+    defs.add(def);
+  });
+  return Object.keys(per).length ? per : null;
+}

package/src/server/crc32.ts

@@ -0,0 +1,13 @@
+// IEEE CRC32 as an unsigned decimal string (PocketBase uses crc32.ChecksumIEEE for field ids).
+const table = new Uint32Array(256);
+for (let i = 0; i < 256; i++) {
+  let c = i;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  table[i] = c >>> 0;
+}
+export function crc32(input: string): string {
+  const bytes = new TextEncoder().encode(input);
+  let crc = 0xffffffff;
+  for (const b of bytes) crc = table[(crc ^ b) & 0xff]! ^ (crc >>> 8);
+  return String((crc ^ 0xffffffff) >>> 0);
+}

package/src/server/crons.ts

@@ -0,0 +1,100 @@
+// Cron registry (apis/cron.go + core built-ins): jobs registered by hooks (cronAdd) plus PocketBase's own
+// maintenance jobs. Cloudflare fires crons/every-minute.ts once a minute; runDue matches every job's expression
+// against that minute. The superuser API lists jobs and runs one on demand.
+import type { Hono } from "hono";
+import { logger } from "#platform/log";
+import { requireSuperuser } from "./auth";
+import { run } from "./db";
+import { notFound } from "./errors";
+import { crons as hookCrons } from "./hooks/runtime";
+import { withHookStore } from "./hooks/migrations";
+import { nowString } from "./ids";
+import { deleteOldLogs } from "./logs";
+import { autoBackup } from "./backups";
+import { attachJobs } from "./jobs";
+import { loadSettings } from "./settings";
+import { s3Bucket } from "./storage/s3";
+import type { AppEnv } from "./types";
+
+export interface CronJob { id: string; expr: string; fn: (env: AppEnv["Bindings"]) => Promise<unknown> | unknown }
+
+const BUILTIN: CronJob[] = [
+  { id: "__pbDBOptimize__", expr: "0 0 * * *", fn: async () => undefined /* D1 maintains itself */ },
+  { id: "__pbMFACleanup__", expr: "0 * * * *", fn: async (env) => { await run(env.DB, "DELETE FROM `_mfas` WHERE created < ?", [nowString(new Date(Date.now() - 24 * 3600_000))]); } },
+  { id: "__pbOTPCleanup__", expr: "0 * * * *", fn: async (env) => { await run(env.DB, "DELETE FROM `_otps` WHERE created < ?", [nowString(new Date(Date.now() - 24 * 3600_000))]); } },
+  { id: "__pbLogsCleanup__", expr: "0 */6 * * *", fn: async (env) => deleteOldLogs(env.DB, (await loadSettings(env.DB)).logs.maxDays) },
+  // voidbase: the realtime change feed and stale stream rows only need to survive a few poll intervals
+  { id: "__vbChangesCleanup__", expr: "*/10 * * * *", fn: async (env) => { await run(env.DB, "DELETE FROM `_changes` WHERE created < ?", [nowString(new Date(Date.now() - 10 * 60_000))]); await run(env.DB, "DELETE FROM `_realtime_clients` WHERE updated < ?", [nowString(new Date(Date.now() - 6 * 3600_000))]); } },
+];
+
+export function allJobs(backupsCron = ""): CronJob[] {
+  const fromHooks: CronJob[] = [...hookCrons.entries()].map(([id, j]) => ({ id, expr: j.expr, fn: async () => j.fn() })).sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  const auto: CronJob[] = backupsCron ? [{ id: "__pbAutoBackup__", expr: backupsCron, fn: (env) => autoBackup(env) }] : [];
+  // cronsList: user jobs alphabetically, then PocketBase's own jobs in registration order, then voidbase's
+  return [...fromHooks, ...BUILTIN, ...auto];
+}
+
+export async function runJob(env: AppEnv["Bindings"], job: CronJob): Promise<void> {
+  const s3 = (await loadSettings(env.DB)).s3;
+  if (s3.enabled) env = { ...env, STORAGE: s3Bucket(s3) };
+  try { await withHookStore(env.DB, env, () => job.fn(env)); } catch (err) { logger.error("voidbase: cron job failed", { job: job.id, error: err instanceof Error ? `${err.name}: ${err.message}` : String(err) }); }
+}
+
+// tools/cron matcher for one minute (UTC, like PocketBase)
+export function matches(expr: string, date: Date): boolean {
+  const macros: Record<string, string> = { "@yearly": "0 0 1 1 *", "@annually": "0 0 1 1 *", "@monthly": "0 0 1 * *", "@weekly": "0 0 * * 0", "@daily": "0 0 * * *", "@midnight": "0 0 * * *", "@hourly": "0 * * * *" };
+  const segments = (macros[expr] ?? expr).split(" ");
+  if (segments.length !== 5) return false;
+  const values = [date.getUTCMinutes(), date.getUTCHours(), date.getUTCDate(), date.getUTCMonth() + 1, date.getUTCDay()];
+  const bounds: [number, number][] = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 6]];
+  return segments.every((seg, i) => seg.split(",").some((part) => {
+    const [range, stepStr] = part.split("/"); const step = stepStr ? Number(stepStr) : 1;
+    let lo = bounds[i]![0], hi = bounds[i]![1];
+    if (range !== "*") { const [a, b] = range!.split("-").map(Number); lo = a!; hi = b ?? a!; }
+    const v = values[i]!;
+    return v >= lo && v <= hi && (v - lo) % step === 0;
+  }));
+}
+
+export async function runDue(env: AppEnv["Bindings"], date: Date): Promise<string[]> {
+  attachJobs(env);
+  const ran: string[] = [];
+  const settings = await loadSettings(env.DB);
+  // triggers fire at the hook expressions and hourly: catch every job due since the previous tick (at most an hour)
+  const from = new Date(Math.max(lastTick ?? 0, date.getTime() - 3600_000)); lastTick = date.getTime();
+  for (const job of allJobs(settings.backups.cron)) {
+    const due = job.id.startsWith("__pb") || job.id.startsWith("__vb") ? matches(job.expr, date) || dueWithin(job.expr, from, date) : matches(job.expr, date) || dueWithin(job.expr, from, date);
+    if (due) { await runJob(env, job); ran.push(job.id); }
+  }
+  return ran;
+}
+let lastTick: number | null = null;
+function dueWithin(expr: string, from: Date, to: Date): boolean {
+  for (let t = Math.ceil(from.getTime() / 60_000) * 60_000; t < Math.floor(to.getTime() / 60_000) * 60_000; t += 60_000) if (matches(expr, new Date(t))) return true;
+  return false;
+}
+
+// Lazy maintenance: PocketBase's cleanups (and an overdue backups cron) run from a request at most once an hour per
+// isolate, so an app with no cron hooks needs no trigger to stay tidy and an idle app runs nothing at all.
+let lastMaintenance = 0;
+export function maintenanceIfDue(env: AppEnv["Bindings"], waitUntil: (p: Promise<unknown>) => void): void {
+  const now = Date.now();
+  if (now - lastMaintenance < 3600_000) return;
+  lastMaintenance = now;
+  waitUntil((async () => {
+    const settings = await loadSettings(env.DB);
+    const since = new Date(now - 3600_000);
+    for (const job of allJobs(settings.backups.cron)) if (!hookCrons.has(job.id) && dueWithin(job.expr, since, new Date(now))) await runJob(env, job);
+  })());
+}
+
+export function mountCronsApi(app: Hono<AppEnv>) {
+  app.get("/api/crons", async (c) => { requireSuperuser(c); return c.json(allJobs((await loadSettings(c.env.DB)).backups.cron).map((j) => ({ id: j.id, expression: j.expr }))); });
+  app.post("/api/crons/:id", async (c) => {
+    requireSuperuser(c);
+    const job = allJobs((await loadSettings(c.env.DB)).backups.cron).find((j) => j.id === c.req.param("id"));
+    if (!job) throw notFound("Missing or invalid cron job");
+    c.executionCtx.waitUntil(runJob(c.env, job));
+    return c.body(null, 204);
+  });
+}

package/src/server/crypto.ts

@@ -0,0 +1,26 @@
+// AES-GCM at rest with the key from VOIDBASE_ENCRYPTION_KEY (PocketBase's --encryptionEnv shape: 16, 24 or 32 chars).
+// Used for the settings row and, through voidbase/cloud, for what a control plane must keep (OAuth tokens).
+const b64 = { enc: (b: Uint8Array) => btoa(String.fromCharCode(...b)), dec: (s: string) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0)) };
+const aesKey = (key: string) => crypto.subtle.importKey("raw", new TextEncoder().encode(key), { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
+
+/** nonce || ciphertext || tag, base64 (like PocketBase's security.Encrypt) */
+export async function aesSeal(plain: string, key: string): Promise<string> {
+  const nonce = crypto.getRandomValues(new Uint8Array(12));
+  const sealed = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce }, await aesKey(key), new TextEncoder().encode(plain)));
+  const out = new Uint8Array(nonce.length + sealed.length); out.set(nonce); out.set(sealed, nonce.length);
+  return b64.enc(out);
+}
+export async function aesOpen(encoded: string, key: string): Promise<string> {
+  const bytes = b64.dec(encoded);
+  return new TextDecoder().decode(await crypto.subtle.decrypt({ name: "AES-GCM", iv: bytes.slice(0, 12) }, await aesKey(key), bytes.slice(12)));
+}
+
+// A secret stored in a record field: "enc:" + sealed, so a value written before a key existed still reads back.
+const PREFIX = "enc:";
+export const isSealed = (value: string): boolean => value.startsWith(PREFIX);
+export async function sealSecret(plain: string, key: string): Promise<string> { return plain ? PREFIX + (await aesSeal(plain, key)) : ""; }
+export async function openSecret(stored: string, key: string): Promise<string> {
+  if (!isSealed(stored)) return stored;
+  if (!key) throw new Error("the value is encrypted but VOIDBASE_ENCRYPTION_KEY is not set");
+  return aesOpen(stored.slice(PREFIX.length), key);
+}

package/src/server/db.ts

@@ -0,0 +1,37 @@
+import type { Row } from "./types";
+
+// Quote an identifier for SQLite. Rejects backticks outright rather than escaping them.
+export function ident(name: string): string {
+  if (!/^\w+$/.test(name)) throw new Error(`invalid identifier: ${name}`);
+  return "`" + name + "`";
+}
+
+// D1 binds: null, number, string, boolean(as 0/1), ArrayBuffer. Everything else is JSON text.
+export function bindValue(v: unknown): unknown {
+  if (v === undefined) return null;
+  if (typeof v === "boolean") return v ? 1 : 0;
+  if (v === null || typeof v === "number" || typeof v === "string" || v instanceof ArrayBuffer) return v;
+  return JSON.stringify(v);
+}
+
+export function stmt(db: D1Database, sql: string, params: unknown[] = []): D1PreparedStatement {
+  return db.prepare(sql).bind(...params.map(bindValue));
+}
+
+export async function all<T = Row>(db: D1Database, sql: string, params: unknown[] = []): Promise<T[]> {
+  const r = await stmt(db, sql, params).all<T>();
+  return r.results ?? [];
+}
+
+export async function one<T = Row>(db: D1Database, sql: string, params: unknown[] = []): Promise<T | null> {
+  return (await stmt(db, sql, params).first<T>()) ?? null;
+}
+
+export async function run(db: D1Database, sql: string, params: unknown[] = []): Promise<D1Result> {
+  return stmt(db, sql, params).run();
+}
+
+export async function batch(db: D1Database, statements: D1PreparedStatement[]): Promise<D1Result[]> {
+  if (statements.length === 0) return [];
+  return db.batch(statements);
+}

package/src/server/errors.ts

@@ -0,0 +1,53 @@
+// PocketBase error envelope: { status, message, data }
+// data holds per-field validation errors: { field: { code, message } }
+export type FieldErrors = Record<string, { code: string; message: string }>;
+
+// PocketBase passes messages through inflector.Sentenize: capitalized, ending with punctuation.
+export function sentenize(message: string): string {
+  const m = message.trim();
+  if (!m) return m;
+  const cap = m[0]!.toUpperCase() + m.slice(1);
+  return /[.!?]$/.test(cap) ? cap : cap + ".";
+}
+
+export class ApiError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+    public data: FieldErrors | Record<string, unknown> = {},
+  ) {
+    super(sentenize(message));
+  }
+  toJSON() {
+    return { data: this.data, message: this.message, status: this.status };
+  }
+  response() {
+    return jsonResponse(this.toJSON(), { status: this.status });
+  }
+}
+
+export const badRequest = (message = "Something went wrong while processing your request.", data: FieldErrors = {}) =>
+  new ApiError(400, message, data);
+export const unauthorized = (message = "The request requires valid record authorization token.") => new ApiError(401, message);
+export const forbidden = (message = "You are not allowed to perform this request.") => new ApiError(403, message);
+export const notFound = (message = "The requested resource wasn't found.") => new ApiError(404, message);
+export const internal = (message = "Something went wrong while processing your request.") => new ApiError(500, message);
+
+export const validationFailed = (data: FieldErrors) =>
+  badRequest("An error occurred while validating the submitted data.", data);
+
+export const V = {
+  required: { code: "validation_required", message: "Cannot be blank." },
+  length: (min: number, max: number) => ({
+    code: "validation_length_out_of_range",
+    message: `The length must be between ${min} and ${max}.`,
+  }),
+  invalidFormat: { code: "validation_invalid_format", message: "Invalid format." },
+};
+
+// Response.json() picks a runtime-specific default content type (workerd: application/json, Bun: with charset);
+// PocketBase answers with a bare application/json, so set it explicitly.
+export function jsonResponse(body: unknown, init: ResponseInit = {}): Response {
+  const headers = new Headers(init.headers); headers.set("content-type", "application/json");
+  return new Response(JSON.stringify(body), { ...init, headers });
+}

package/src/server/files-api.ts

@@ -0,0 +1,52 @@
+// File tokens (apis/file.go fileToken): short-lived JWTs signed with the collection's fileToken secret that
+// let a client fetch protected files with ?token=... The files route uses `protectedAccess` for the check.
+import type { Context, Hono } from "hono";
+import { findAuthRecordByToken } from "./auth";
+import { ipInList, realIP } from "./hardening";
+import type { Collection } from "./collections/model";
+import { unauthorized } from "./errors";
+import { HookRecord } from "./hooks/record";
+import { trigger } from "./hooks/runtime";
+import { signJWT } from "./jwt";
+import { recordMatchesRule, type RecordContext } from "./records/service";
+import { rowToValues } from "./records/values";
+import { loadSettings } from "./settings";
+import type { AppEnv, AuthRecord, Row } from "./types";
+
+const tokenOption = (c: Collection) => ((c.options as Record<string, unknown>).fileToken ?? {}) as { secret?: string; duration?: number };
+
+export async function newFileToken(auth: AuthRecord): Promise<string> {
+  const opt = tokenOption(auth.collection);
+  const key = String(auth.row.tokenKey ?? "") + String(opt.secret ?? "");
+  if (!key) throw new Error("missing or invalid signing key");
+  return signJWT({ type: "file", id: String(auth.row.id), collectionId: auth.collection.id }, key, Number(opt.duration ?? 0) || 180);
+}
+
+export function mountFilesApi(app: Hono<AppEnv>) {
+  app.post("/api/files/token", async (c) => {
+    const auth = c.get("auth");
+    if (!auth) throw unauthorized("The request requires valid record authorization token.");
+    const token = await newFileToken(auth);
+    const ev = { app: undefined as unknown, token, record: HookRecord.fromRow(auth.collection, auth.row), next: async () => undefined as unknown };
+    let res: Response | null = null;
+    await trigger("onFileTokenRequest", ev, auth.collection.name, async () => { res = c.json({ token: ev.token }); });
+    return res ?? c.json({ token });
+  });
+}
+
+// protected file: the ?token= file token (superusers subject to the IP allowlist) must satisfy the view rule
+export async function protectedAccess(c: Context<AppEnv>, ctx: RecordContext, collection: Collection, row: Row): Promise<boolean> {
+  const token = c.req.query("token") ?? "";
+  let auth = token ? await findAuthRecordByToken(c.env.DB, token, "file") : null;
+  if (auth && auth.collection.name === "_superusers") {
+    const allowed = (await loadSettings(c.env.DB)).superuserIPs;
+    if (allowed.length && !ipInList(allowed, await realIP(c))) auth = null;
+  }
+  const superuser = !!auth && auth.collection.name === "_superusers";
+  const viewRule = collection.viewRule;
+  if (superuser) return true;
+  if (viewRule === null) return false;
+  const fctx: RecordContext = { ...ctx, auth, superuser, request: { ...ctx.request, auth: auth ? { collection: auth.collection, row: auth.row } : null, context: "protectedFile" } };
+  if (viewRule.trim() === "") return true;
+  return recordMatchesRule(fctx, collection, viewRule, rowToValues(collection, row));
+}