@voidbase-cloud/voidbase 0.1.0

package/src/server/hardening.ts

@@ -0,0 +1,136 @@
+// Core middleware parity (apis/middlewares*.go): real client IP through settings.trustedProxy, PocketBase's rate
+// limit rules (labels, audiences, prefix rules, fixed windows per client) and the default 32 MB body limit.
+// Counters live in isolate memory, so limits are approximate across isolates; PocketBase's are per process. On
+// Cloudflare a rate-limit binding (RATE_LIMITER, declared by the deploy) adds an exact per-location ceiling per IP.
+import type { Context, MiddlewareHandler } from "hono";
+import { findCollection } from "./collections/model";
+import { ApiError } from "./errors";
+import { loadSettings, type Settings } from "./settings";
+import type { AppEnv } from "./types";
+
+const isIP = (s: string) => /^(\d{1,3}\.){3}\d{1,3}$/.test(s) || /^[0-9a-fA-F:]+$/.test(s);
+
+// core/event_request.go RealIP: trusted proxy headers (last value, leftmost or rightmost IP), else the connection IP
+export function realIPWith(settings: Settings, c: Context<AppEnv>): string {
+  for (const h of settings.trustedProxy.headers) {
+    const raw = c.req.header(h);
+    if (!raw) continue;
+    const ips = raw.split(",").map((s) => s.trim()).filter(isIP);
+    if (!ips.length) continue;
+    return settings.trustedProxy.useLeftmostIP ? ips[0]! : ips[ips.length - 1]!;
+  }
+  return c.req.header("CF-Connecting-IP") ?? c.req.header("X-Real-IP") ?? "127.0.0.1"; // the connection's own address on Workers
+}
+export async function realIP(c: Context<AppEnv>): Promise<string> { return realIPWith(await loadSettings(c.env.DB), c); }
+
+export function ipInList(list: string[], ip: string): boolean {
+  if (!list.length || !ip) return false;
+  const v4 = (s: string): number | null => { const m = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(s); return m ? ((+m[1]! << 24) | (+m[2]! << 16) | (+m[3]! << 8) | +m[4]!) >>> 0 : null; };
+  for (const item of list) {
+    if (item === ip) return true;
+    if (!item.includes("/")) continue;
+    const [net, bitsStr] = item.split("/"); const bits = Number(bitsStr);
+    const a = v4(net ?? ""), b = v4(ip);
+    if (a === null || b === null) continue;
+    const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+    if (((a & mask) >>> 0) === ((b & mask) >>> 0)) return true;
+  }
+  return false;
+}
+
+// ---- rate limits ---------------------------------------------------------------------------------
+interface Rule { label: string; audience: string; duration: number; maxRequests: number }
+interface Window { start: number; count: number }
+const limiters = new Map<string, Map<string, Window>>();
+let lastSweep = 0;
+
+// tags per route as bound in apis/record_auth.go, record_crud.go and file.go
+const COLLECTION_ROUTES: { re: RegExp; method: string; tags: string[]; pattern: string }[] = [
+  { re: /^\/api\/collections\/([^/]+)\/records$/, method: "GET", tags: ["list"], pattern: "GET /api/collections/{collection}/records" },
+  { re: /^\/api\/collections\/([^/]+)\/records$/, method: "POST", tags: ["create"], pattern: "POST /api/collections/{collection}/records" },
+  { re: /^\/api\/collections\/([^/]+)\/records\/[^/]+$/, method: "GET", tags: ["view"], pattern: "GET /api/collections/{collection}/records/{id}" },
+  { re: /^\/api\/collections\/([^/]+)\/records\/[^/]+$/, method: "PATCH", tags: ["update"], pattern: "PATCH /api/collections/{collection}/records/{id}" },
+  { re: /^\/api\/collections\/([^/]+)\/records\/[^/]+$/, method: "DELETE", tags: ["delete"], pattern: "DELETE /api/collections/{collection}/records/{id}" },
+  { re: /^\/api\/files\/([^/]+)\/[^/]+\/[^/]+$/, method: "GET", tags: ["file"], pattern: "GET /api/files/{collection}/{recordId}/{filename}" },
+  { re: /^\/api\/collections\/([^/]+)\/auth-methods$/, method: "GET", tags: ["listAuthMethods"], pattern: "GET /api/collections/{collection}/auth-methods" },
+  { re: /^\/api\/collections\/([^/]+)\/auth-refresh$/, method: "POST", tags: ["authRefresh"], pattern: "POST /api/collections/{collection}/auth-refresh" },
+  { re: /^\/api\/collections\/([^/]+)\/auth-with-password$/, method: "POST", tags: ["authWithPassword", "auth"], pattern: "POST /api/collections/{collection}/auth-with-password" },
+  { re: /^\/api\/collections\/([^/]+)\/auth-with-oauth2$/, method: "POST", tags: ["authWithOAuth2", "auth"], pattern: "POST /api/collections/{collection}/auth-with-oauth2" },
+  { re: /^\/api\/collections\/([^/]+)\/request-otp$/, method: "POST", tags: ["requestOTP"], pattern: "POST /api/collections/{collection}/request-otp" },
+  { re: /^\/api\/collections\/([^/]+)\/auth-with-otp$/, method: "POST", tags: ["authWithOTP", "auth"], pattern: "POST /api/collections/{collection}/auth-with-otp" },
+  { re: /^\/api\/collections\/([^/]+)\/request-password-reset$/, method: "POST", tags: ["requestPasswordReset"], pattern: "POST /api/collections/{collection}/request-password-reset" },
+  { re: /^\/api\/collections\/([^/]+)\/confirm-password-reset$/, method: "POST", tags: ["confirmPasswordReset"], pattern: "POST /api/collections/{collection}/confirm-password-reset" },
+  { re: /^\/api\/collections\/([^/]+)\/request-verification$/, method: "POST", tags: ["requestVerification"], pattern: "POST /api/collections/{collection}/request-verification" },
+  { re: /^\/api\/collections\/([^/]+)\/confirm-verification$/, method: "POST", tags: ["confirmVerification"], pattern: "POST /api/collections/{collection}/confirm-verification" },
+  { re: /^\/api\/collections\/([^/]+)\/request-email-change$/, method: "POST", tags: ["requestEmailChange"], pattern: "POST /api/collections/{collection}/request-email-change" },
+  { re: /^\/api\/collections\/([^/]+)\/confirm-email-change$/, method: "POST", tags: ["confirmEmailChange"], pattern: "POST /api/collections/{collection}/confirm-email-change" },
+];
+
+// RateLimitsConfig.FindRateLimitRule: exact label in order, prefix rules ("/api/") against the first label only
+function findRule(rules: Rule[], labels: string[], audiences: string[]): Rule | null {
+  const prefixRules: Rule[] = [];
+  for (let i = 0; i < labels.length; i++) {
+    const label = labels[i]!;
+    for (const r of rules) {
+      if (label === r.label && audiences.includes(r.audience)) return r;
+      if (i === 0 && r.label.endsWith("/")) prefixRules.push(r);
+    }
+    for (const r of prefixRules) if ((label + "/").startsWith(r.label) && audiences.includes(r.audience)) return r;
+  }
+  return null;
+}
+
+function consume(limiterId: string, clientKey: string, rule: Rule): boolean {
+  const now = Date.now();
+  if (now - lastSweep > 60_000) { lastSweep = now; for (const [id, m] of limiters) { for (const [k, w] of m) if (now - w.start > 1800_000) m.delete(k); if (!m.size) limiters.delete(id); } }
+  let clients = limiters.get(limiterId);
+  if (!clients) { clients = new Map(); limiters.set(limiterId, clients); }
+  let w = clients.get(clientKey);
+  if (!w || now - w.start >= rule.duration * 1000) { w = { start: now, count: 0 }; clients.set(clientKey, w); }
+  w.count++;
+  return w.count <= rule.maxRequests;
+}
+
+export function rateLimitMiddleware(): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    const settings = await loadSettings(c.env.DB);
+    const auth = c.get("auth");
+    const ip = realIPWith(settings, c);
+    if (!settings.rateLimits.enabled || (auth && auth.collection.name === "_superusers") || ipInList(settings.rateLimits.excludedIPs, ip)) return next();
+    // the binding's counters are shared by every isolate in a location (its limit and period are fixed at deploy time)
+    if (c.env.RATE_LIMITER && !(await c.env.RATE_LIMITER.limit({ key: ip })).success) throw new ApiError(429, "Too Many Requests.", {});
+    const path = new URL(c.req.url).pathname;
+    const method = c.req.method.toUpperCase();
+    const audiences = auth ? ["", "@auth"] : ["", "@guest"];
+    const rules = settings.rateLimits.rules as Rule[];
+    const route = COLLECTION_ROUTES.find((r) => r.method === method && r.re.test(path));
+    let rule: Rule | null = null; let limiterId = "";
+    if (route) {
+      const collName = route.re.exec(path)![1]!;
+      const collection = await findCollection(c.env.DB, collName);
+      if (!collection) throw new ApiError(404, "Missing or invalid collection context.", {});
+      const labels = [...route.tags.map((t) => `${collection.name}:${t}`), ...route.tags.map((t) => `*:${t}`), `${method} ${path}`, path];
+      rule = findRule(rules, labels, audiences);
+      if (rule) limiterId = collection.id + route.pattern + route.tags.join("") + rule.audience;
+    } else {
+      rule = findRule(rules, [`${method} ${path}`, path], audiences);
+      if (rule) limiterId = rule.label + rule.audience;
+    }
+    if (rule) {
+      if (rule.audience === "@guest" && auth) return next();
+      if (rule.audience === "@auth" && !auth) return next();
+      if (!consume(limiterId, ip, rule)) throw new ApiError(429, "Too Many Requests.", {});
+    }
+    return next();
+  };
+}
+
+// apis/middlewares_body_limit.go: 32 MB unless a route says otherwise (batch inlines its own limit)
+const DEFAULT_MAX_BODY = 32 << 20;
+export function bodyLimitMiddleware(): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    const len = Number(c.req.header("content-length") ?? 0);
+    if (len > DEFAULT_MAX_BODY && !new URL(c.req.url).pathname.startsWith("/api/batch") && !new URL(c.req.url).pathname.startsWith("/api/backups/upload")) throw new ApiError(413, "Request entity too large.", {});
+    return next();
+  };
+}

package/src/server/hooks/index.ts

@@ -0,0 +1,147 @@
+// Loads the bundled pb_hooks files, exposes the JSVM-compatible globals, mounts routerAdd routes.
+import { logger } from "#platform/log";
+import type { Hono, MiddlewareHandler } from "hono";
+import { files, hooks, hooksDir, modules } from "#platform/hooks";
+import { loadCollections } from "../collections/model";
+import { loadSettings } from "../settings";
+import type { AppEnv } from "../types";
+import { CollectionRef, HookRecord } from "./record";
+import {
+  $apis, $app, $dbx, $filesystem, $http, $security, BadRequestError, ForbiddenError, InternalServerError, MailerMessage, NotFoundError,
+  RecordUpsertFormFactory, RequestEvent, UnauthorizedError, ValidationError, authToHookRecord, cronAdd, cronRemove, hookStore,
+  crons, eventHooks, makeOs, onEvent, routerAdd, routerUse, routes, type HookMiddleware,
+} from "./runtime";
+import { ApiError } from "../errors";
+
+const HOOKS_PREFIX = "/pb_hooks";
+const $os = makeOs(files, HOOKS_PREFIX);
+const moduleCache = new Map<string, unknown>();
+
+class DateTime { d: Date; constructor(v?: string | number | Date) { this.d = v === undefined ? new Date() : new Date(v); } string() { return this.d.toISOString().replace("T", " "); } time() { return this.d; } unix() { return Math.floor(this.d.getTime() / 1000); } toJSON() { return this.string(); } }
+
+// new Field({...}) / new TextField({...}) in JSVM code produce plain field data
+function fieldClass(type?: string) {
+  return class { constructor(data: Record<string, unknown> = {}) { return { ...(type ? { type } : {}), ...data }; } };
+}
+
+function buildGlobals(): Record<string, unknown> {
+  const g: Record<string, unknown> = {
+    $app, $apis, $http, $os, $filesystem, $security,
+    $mails: {}, $template: { loadFiles: () => ({ render: () => "" }) }, $dbx,
+    routerAdd, routerUse, cronAdd, cronRemove,
+    migrate: () => { /* migrations are applied by the migrations runner, not at hook load */ },
+    Record: class Record extends HookRecord { constructor(collection: CollectionRef, data?: { [k: string]: unknown }) { super(collection, data ?? {}); } },
+    Collection: CollectionRef,
+    Field: fieldClass(), TextField: fieldClass("text"), EditorField: fieldClass("editor"), NumberField: fieldClass("number"), BoolField: fieldClass("bool"),
+    EmailField: fieldClass("email"), URLField: fieldClass("url"), DateField: fieldClass("date"), AutodateField: fieldClass("autodate"), SelectField: fieldClass("select"),
+    FileField: fieldClass("file"), RelationField: fieldClass("relation"), JSONField: fieldClass("json"), GeoPointField: fieldClass("geoPoint"), PasswordField: fieldClass("password"),
+    RecordUpsertForm: RecordUpsertFormFactory($app),
+    MailerMessage, DateTime, RequestInfo: class {},
+    ApiError, NotFoundError, BadRequestError, ForbiddenError, UnauthorizedError, InternalServerError, ValidationError,
+    __hooks: HOOKS_PREFIX,
+    console,
+    toString: (v: unknown) => String(v), sleep: (ms: number) => new Promise((r) => setTimeout(r, ms)), arrayOf: () => [], unmarshal: (v: unknown, dst: unknown) => Object.assign(dst as object, v as object),
+    module: { exports: {} }, exports: {},
+    require: (path: string) => requireModule(path),
+  };
+  for (const name of Object.keys(g)) void name;
+  // event hook registration functions: onRecordCreate(fn, ...tags) etc.
+  const proxy = new Proxy(g, {
+    get(target, prop: string) {
+      if (prop in target) return target[prop];
+      if (typeof prop === "string" && prop.startsWith("on")) return (fn: (e: unknown) => unknown, ...tags: string[]) => onEvent(prop, fn, tags);
+      return undefined;
+    },
+  });
+  return proxy;
+}
+
+function requireModule(path: string): unknown {
+  const rel = path.replace(/^\.\//, "").replace(new RegExp("^" + HOOKS_PREFIX + "/?"), "").replace(/\.js$/, "");
+  if (moduleCache.has(rel)) return moduleCache.get(rel);
+  const factory = modules[rel];
+  if (!factory) throw new Error(`Cannot find module '${path}'`);
+  const module = { exports: {} as Record<string, unknown> };
+  const target: Record<string, unknown> = { ...Object.fromEntries(Object.entries(GLOBALS)), module, exports: module.exports };
+  const g = new Proxy(target, {
+    get(t, prop: string) { return prop in t ? t[prop] : (GLOBALS as Record<string, unknown>)[prop]; },
+  });
+  const result = factory(g);
+  // module bodies rarely await at the top level; when they do, the promise resolves to module.exports
+  const exported = result instanceof Promise ? module.exports : (result ?? module.exports);
+  moduleCache.set(rel, exported);
+  return exported;
+}
+
+const GLOBALS = buildGlobals();
+export const hookGlobals = () => GLOBALS;
+
+let loaded = false;
+export function loadHooks() {
+  if (loaded) return;
+  loaded = true;
+  // a dev reload re-evaluates this module while runtime.ts keeps its registries: start from empty
+  routes.length = 0;
+  eventHooks.clear();
+  crons.clear();
+  for (const h of hooks) {
+    try {
+      // top-level registrations run synchronously inside run(); the returned promise only settles handlers
+      void h.run(GLOBALS).catch((err) => logger.error("voidbase: hook file failed", { hook: h.name, error: err instanceof Error ? `${err.name}: ${err.message}` : String(err) }));
+    } catch (err) { logger.error("voidbase: hook file failed", { hook: h.name, error: err instanceof Error ? `${err.name}: ${err.message}` : String(err) }); }
+  }
+  console.log(`voidbase: loaded ${hooks.length} hook file(s) from ${hooksDir}, ${routes.length} route(s)`);
+}
+
+// Runs handlers registered with routerAdd. Registered after the core routes so PocketBase's own API wins.
+// Hook routes (routerAdd from pb_hooks or a project's main.ts) are served by one catch-all registered after the core
+// routes, matching against the live registry at request time. Hono builds its matcher on the first request and
+// ignores routes added afterwards, so registrations may happen at any time (a main.ts composes after the JS hooks).
+interface Compiled { route: (typeof routes)[number]; re: RegExp; keys: string[]; score: number }
+let compiled: Compiled[] | null = null; let compiledFor = -1;
+function compile(): Compiled[] {
+  if (compiled && compiledFor === routes.length) return compiled;
+  // Go's ServeMux picks the most specific pattern: literal segments beat params beat wildcards
+  const score = (p: string) => (p.includes("*") ? 0 : 1000) + p.split("/").filter((s) => s && !s.startsWith(":")).length * 10 + p.split("/").length;
+  compiled = routes.map((route) => {
+    const keys: string[] = [];
+    const src = route.path.split("/").map((seg) => {
+      if (seg === "*") return ".*";
+      if (seg.startsWith(":")) { keys.push(seg.slice(1)); return "([^/]+)"; }
+      return seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }).join("/");
+    return { route, re: new RegExp(`^${src}/?$`), keys, score: score(route.path) };
+  }).sort((a, b) => b.score - a.score);
+  compiledFor = routes.length;
+  return compiled;
+}
+export function mountHookRoutes(app: Hono<AppEnv>) {
+  app.all("*", async (c) => {
+    const path = new URL(c.req.url).pathname;
+    for (const { route, re, keys } of compile()) {
+      if (route.method !== "ALL" && route.method !== c.req.method) continue;
+      const m = re.exec(path); if (!m) continue;
+      const ev = new RequestEvent(c, authToHookRecord(c.get("auth")));
+      keys.forEach((k, i) => { ev.params[k] = decodeURIComponent(m[i + 1] ?? ""); });
+      const chain: HookMiddleware[] = [...route.middlewares, route.handler];
+      let i = 0;
+      const next = async (): Promise<unknown> => { const mw = chain[i++]; if (!mw) return undefined; return (typeof mw === "function" ? mw : mw.func)(ev); };
+      ev.next = next;
+      const result = await next();
+      if (result instanceof Response) return result;
+      if (ev.written) return ev.written;
+      return c.body(null, 204);
+    }
+    return c.notFound();
+  });
+}
+
+// Per-request state for $app and friends.
+export function hookMiddleware(): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    const collections = await loadCollections(c.env.DB);
+    const settings = await loadSettings(c.env.DB);
+    const { recordContextFor } = await import("../app");
+    return hookStore.run({ c, ctx: () => recordContextFor(c), collections, settings, env: c.env as unknown as Record<string, unknown> }, next);
+  };
+}

package/src/server/hooks/migrations.ts

@@ -0,0 +1,58 @@
+// PocketBase-style JS migrations (pb_migrations/*.js): `migrate(up, down)` files applied once at bootstrap,
+// tracked in _pbMigrations (file, applied). The `app` handed to `up` is $app plus importCollections, so the
+// starter's snapshot migration creates its schema on a fresh database and later migrations can use
+// findCollectionByNameOrId / save / delete like they do in PocketBase.
+import { migrations } from "#platform/migrations";
+import { invalidateCollections, loadCollections } from "../collections/model";
+import { importCollections } from "../collections/service";
+import { all, stmt } from "../db";
+import { loadSettings } from "../settings";
+import type { RecordContext } from "../records/service";
+import type { AppEnv } from "../types";
+import { hookStore } from "./runtime";
+
+export type MigrationFn = (app: Record<string, unknown>) => unknown;
+
+// Runs fn inside a superuser hook store outside any request (migrations, cron jobs), so $app works as in a request.
+export async function withHookStore<T>(db: D1Database, bindings: AppEnv["Bindings"] | undefined, fn: () => Promise<T> | T): Promise<T> {
+  const collections = await loadCollections(db);
+  const ctx = async (): Promise<RecordContext> => ({
+    db, storage: bindings?.STORAGE as R2Bucket, auth: null, superuser: true,
+    request: { auth: null, method: "GET", query: {}, headers: {}, body: {}, context: "default" },
+    collections: await loadCollections(db),
+  });
+  const store = { c: undefined as never, ctx, collections, settings: await loadSettings(db), env: (bindings ?? {}) as Record<string, unknown> };
+  return hookStore.run(store, () => fn());
+}
+
+export async function applyPendingMigrations(db: D1Database, globals: Record<string, unknown> = {}, bindings?: AppEnv["Bindings"]): Promise<string[]> {
+  if (!migrations.length) return [];
+  return withHookStore(db, bindings, () => runPending(db, globals));
+}
+
+async function runPending(db: D1Database, globals: Record<string, unknown>): Promise<string[]> {
+  const applied = new Set((await all<{ file: string }>(db, "SELECT file FROM `_pbMigrations`")).map((r) => r.file));
+  const own: Record<string, unknown> = {
+    importCollections: (list: Record<string, unknown>[], deleteMissing = false) => importCollections(db, list, deleteMissing),
+  };
+  const $app = (globals.$app ?? {}) as Record<string, unknown>;
+  const app = new Proxy(own, { get: (t, k) => (k in t ? t[k as string] : $app[k as string]), has: (t, k) => k in t || k in $app });
+  const done: string[] = [];
+  for (const m of [...migrations].sort((a, b) => a.name.localeCompare(b.name))) {
+    if (applied.has(m.name)) continue;
+    let up: MigrationFn | null = null;
+    const migrate = (u: MigrationFn, _down?: MigrationFn) => { up = u; };
+    try {
+      await m.run({ ...globals, migrate });
+      if (up) await (up as MigrationFn)(app);
+    } catch (err) {
+      console.error(`voidbase: migration ${m.name} failed:`, err instanceof Error ? err.message : err);
+      throw err;
+    }
+    invalidateCollections();
+    await stmt(db, "INSERT OR IGNORE INTO `_pbMigrations` (file, applied) VALUES (?, ?)", [m.name, Date.now()]).run();
+    done.push(m.name);
+  }
+  if (done.length) console.log(`voidbase: applied ${done.length} pb_migrations: ${done.join(", ")}`);
+  return done;
+}

package/src/server/hooks/node-async-hooks.d.ts

@@ -0,0 +1,7 @@
+// Minimal typing for the Workers-provided node:async_hooks (nodejs_compat).
+declare module "node:async_hooks" {
+  export class AsyncLocalStorage<T> {
+    run<R>(store: T, fn: () => R): R;
+    getStore(): T | undefined;
+  }
+}

package/src/server/hooks/record.ts

@@ -0,0 +1,152 @@
+// JSVM-compatible Record / Collection wrappers used by hook code ($app, Record, RecordUpsertForm).
+import { isMultiple, type Field } from "../collections/fields";
+import type { Collection } from "../collections/model";
+import { recordToJSON } from "../records/json";
+import { fromColumn, normalizeInput, type Upload } from "../records/values";
+import type { Row } from "../types";
+
+// Field list with the JSVM helpers generated migrations use (collection.fields.addAt(...), removeById(...)).
+export type FieldList = Field[] & {
+  add(...fields: Field[]): void; addAt(index: number, ...fields: Field[]): void;
+  removeById(id: string): void; removeByName(name: string): void;
+  getById(id: string): Field | undefined; getByName(name: string): Field | undefined;
+};
+export function fieldList(fields: Field[]): FieldList {
+  const list = fields as FieldList;
+  if (typeof list.addAt === "function") return list;
+  Object.defineProperties(list, {
+    add: { value(...fs: Field[]) { list.push(...fs); } },
+    addAt: { value(index: number, ...fs: Field[]) { list.splice(Math.max(0, Math.min(index, list.length)), 0, ...fs); } },
+    removeById: { value(id: string) { const i = list.findIndex((f) => f.id === id); if (i >= 0) list.splice(i, 1); } },
+    removeByName: { value(name: string) { const i = list.findIndex((f) => f.name === name); if (i >= 0) list.splice(i, 1); } },
+    getById: { value(id: string) { return list.find((f) => f.id === id); } },
+    getByName: { value(name: string) { return list.find((f) => f.name === name); } },
+  });
+  return list;
+}
+
+// `new Collection({...})` in hooks and migrations, and what $app.findCollectionByNameOrId returns.
+// Property reads and writes fall through to the underlying collection data (unmarshal({...}, collection) works).
+export class CollectionRef {
+  readonly data: Collection;
+  constructor(data: Collection | Record<string, unknown> = {}) {
+    const d = { fields: [], indexes: [], ...(data as Record<string, unknown>) } as unknown as Collection;
+    d.fields = fieldList([...(d.fields as Field[])].map((f) => ({ ...f })));
+    this.data = d;
+    return new Proxy(this, {
+      get(target, prop, receiver) {
+        if (prop in target) return Reflect.get(target, prop, receiver);
+        return (target.data as unknown as Record<string | symbol, unknown>)[prop];
+      },
+      set(target, prop, value) {
+        if (prop in target && typeof prop === "string" && !["id", "name", "type", "system", "fields"].includes(prop)) return Reflect.set(target, prop, value);
+        (target.data as unknown as Record<string | symbol, unknown>)[prop] = prop === "fields" ? fieldList(value as Field[]) : value;
+        return true;
+      },
+      has(target, prop) { return prop in target || prop in (target.data as object); },
+    });
+  }
+  get id() { return this.data.id; }
+  set id(v: string) { this.data.id = v; }
+  get name() { return this.data.name; }
+  set name(v: string) { this.data.name = v; }
+  get type() { return this.data.type; }
+  set type(v: string) { (this.data as { type: string }).type = v; }
+  get fields(): FieldList { return fieldList(this.data.fields as Field[]); }
+  set fields(v: Field[]) { this.data.fields = fieldList(v); }
+  get system() { return this.data.system; }
+  isAuth() { return this.data.type === "auth"; }
+  isView() { return this.data.type === "view"; }
+  isBase() { return this.data.type === "base"; }
+  // plain JSON for the collections service
+  toRaw(): Record<string, unknown> { return JSON.parse(JSON.stringify(this.data)) as Record<string, unknown>; }
+}
+
+export class HookRecord {
+  values: Record<string, unknown>;
+  private originalValues: Record<string, unknown>;
+  private hidden = new Set<string>();
+  private emailVisible = false;
+  uploads: Record<string, Upload[]> = {};
+  isNewRecord: boolean;
+
+  constructor(public readonly coll: CollectionRef, data: Record<string, unknown> = {}, opts: { fromRow?: boolean; isNew?: boolean } = {}) {
+    this.values = {};
+    this.originalValues = {};
+    for (const f of this.fields()) {
+      this.values[f.name] = opts.fromRow ? fromColumn(f, data[f.name]) : this.empty(f);
+      if (f.hidden) this.hidden.add(f.name);
+    }
+    this.isNewRecord = opts.isNew ?? !opts.fromRow;
+    if (opts.fromRow) this.originalValues = { ...this.values };
+    if (!opts.fromRow) this.load(data);
+    if (opts.fromRow && data.password !== undefined) this.values.password = data.password; // keep the hash for auth checks
+  }
+
+  static fromRow(coll: Collection, row: Row) { return new HookRecord(new CollectionRef(coll), row, { fromRow: true }); }
+
+  private fields() { return this.coll.data.fields as Field[]; }
+  private empty(f: Field): unknown {
+    if (f.type === "bool") return false;
+    if (f.type === "number") return 0;
+    if (f.type === "json") return null;
+    if (f.type === "geoPoint") return { lon: 0, lat: 0 };
+    return isMultiple(f) ? [] : "";
+  }
+
+  get id() { return String(this.values.id ?? ""); }
+  set id(v: string) { this.values.id = v; }
+  collection() { return this.coll; }
+  isNew() { return this.isNewRecord; }
+  original() { const r = new HookRecord(this.coll, {}, { isNew: this.isNewRecord }); r.values = { ...this.originalValues }; r.originalValues = { ...this.originalValues }; return r; }
+  fresh() { const r = new HookRecord(this.coll, {}, { isNew: this.isNewRecord }); r.values = { ...this.values }; r.originalValues = { ...this.originalValues }; return r; }
+  clone() { return this.fresh(); }
+  setOriginal(values: Record<string, unknown>) { this.originalValues = { ...values }; }
+  markAsNew() { this.isNewRecord = true; }
+  markAsNotNew() { this.isNewRecord = false; }
+
+  load(data: Record<string, unknown>) { for (const [k, v] of Object.entries(data ?? {})) this.set(k, v); }
+  get(name: string): unknown { return this.values[name]; }
+  set(name: string, value: unknown) {
+    const f = this.fields().find((x) => x.name === name);
+    if (!f) { this.values[name] = value; return; }
+    if (f.type === "file") {
+      const list = Array.isArray(value) ? value : value == null || value === "" ? [] : [value];
+      const names: string[] = [];
+      for (const item of list) {
+        if (item && typeof item === "object" && "bytes" in (item as object)) { const up = item as Upload; (this.uploads[name] ??= []).push(up); names.push(up.name); }
+        else if (typeof item === "string") names.push(item);
+      }
+      this.values[name] = isMultiple(f) ? names : (names[names.length - 1] ?? "");
+      return;
+    }
+    if (f.type === "password") { this.values[name] = value == null ? "" : String(value); return; }
+    this.values[name] = normalizeInput(f, value);
+  }
+  getString(name: string) { const v = this.values[name]; return v == null ? "" : Array.isArray(v) ? String(v[0] ?? "") : typeof v === "object" ? JSON.stringify(v) : String(v); }
+  getBool(name: string) { return !!this.values[name]; }
+  getInt(name: string) { return Math.trunc(Number(this.values[name]) || 0); }
+  getFloat(name: string) { return Number(this.values[name]) || 0; }
+  getStringSlice(name: string) { const v = this.values[name]; return Array.isArray(v) ? v.map(String) : v ? [String(v)] : []; }
+  getDateTime(name: string) { return this.getString(name); }
+  getRaw(name: string) { return this.values[name]; }
+  email() { return this.getString("email"); }
+  verified() { return this.getBool("verified"); }
+  tokenKey() { return this.getString("tokenKey"); }
+  isSuperuser() { return this.coll.name === "_superusers"; }
+  ignoreEmailVisibility(v = true) { this.emailVisible = v; return this; }
+  hide(...names: string[]) { for (const n of names) this.hidden.add(n); return this; }
+  unhide(...names: string[]) { for (const n of names) this.hidden.delete(n); return this; }
+  hiddenFields(): string[] { return [...this.hidden]; }
+  expand: Record<string, unknown> | null = null; // set by $apis.enrichRecord / $app.expandRecord
+  fieldsData() { return { ...this.values }; }
+  // JSON export as the API would return it (email included when visibility is ignored)
+  publicExport(): Record<string, unknown> {
+    const row: Row = {};
+    for (const f of this.fields()) row[f.name] = this.values[f.name];
+    const out = recordToJSON(this.coll.data, row, { own: this.emailVisible, expand: this.expand ?? undefined });
+    for (const n of this.hidden) delete out[n];
+    return out;
+  }
+  toJSON() { return this.publicExport(); }
+}