@voidbase-cloud/voidbase 0.1.0

package/src/server/settings.ts

@@ -0,0 +1,215 @@
+import { one, run } from "./db";
+import { nowString } from "./ids";
+import { env as voidEnv } from "#platform/env";
+import { aesOpen, aesSeal } from "./crypto";
+
+// Defaults mirror PocketBase core/settings_model.go (captured from a 0.40.2 instance).
+// Stored as JSON in _params under id "settings". Secrets are stored but never returned by GET.
+export function defaultSettings() {
+  return {
+    superuserIPs: [] as string[],
+    smtp: { enabled: false, port: 587, host: "smtp.example.com", username: "", password: "", authMethod: "", tls: false, localName: "" },
+    backups: { cron: "", cronMaxKeep: 3, s3: { enabled: false, bucket: "", region: "", endpoint: "", accessKey: "", secret: "", forcePathStyle: false } },
+    s3: { enabled: false, bucket: "", region: "", endpoint: "", accessKey: "", secret: "", forcePathStyle: false },
+    meta: { accentColor: "#1055c9", appName: "Acme", appURL: "http://localhost:8090", senderName: "Support", senderAddress: "support@example.com", hideControls: false },
+    rateLimits: {
+      rules: [
+        { label: "*:auth", audience: "", duration: 3, maxRequests: 2 },
+        { label: "*:create", audience: "", duration: 5, maxRequests: 20 },
+        { label: "/api/batch", audience: "", duration: 1, maxRequests: 3 },
+        { label: "/api/", audience: "", duration: 10, maxRequests: 300 },
+      ],
+      excludedIPs: [] as string[],
+      enabled: false,
+    },
+    trustedProxy: { headers: [] as string[], useLeftmostIP: false },
+    batch: { enabled: false, maxRequests: 50, timeout: 3, maxBodySize: 0 },
+    logs: { maxDays: 5, minLevel: 0, logIP: true, logAuthId: false },
+  };
+}
+
+export type Settings = ReturnType<typeof defaultSettings>;
+
+// The public shape: same as stored minus smtp.password, s3.secret, backups.s3.secret.
+export function publicSettings(s: Settings) {
+  const { password: _p, ...smtp } = s.smtp;
+  const { secret: _s, ...s3 } = s.s3;
+  const { secret: _b, ...backupsS3 } = s.backups.s3;
+  return { ...s, smtp, backups: { ...s.backups, s3: backupsS3 }, s3 };
+}
+
+let cached: { value: Settings; at: number } | null = null;
+const TTL = 5_000;
+
+export function invalidateSettings() {
+  cached = null;
+}
+
+// ---- encryption at rest (PocketBase --encryptionEnv): AES-GCM with the key from VOIDBASE_ENCRYPTION_KEY --------
+const encryptionKey = () => { try { return String((voidEnv as Record<string, unknown>).VOIDBASE_ENCRYPTION_KEY ?? ""); } catch { return ""; } };
+export const encryptSettings = (json: string, key: string): Promise<string> => aesSeal(json, key);
+export const decryptSettings = (encoded: string, key: string): Promise<string> => aesOpen(encoded, key);
+async function readStored(raw: string): Promise<unknown> {
+  if (raw.trimStart().startsWith("{")) return JSON.parse(raw);
+  const key = encryptionKey();
+  if (!key) throw new Error("settings are encrypted but VOIDBASE_ENCRYPTION_KEY is not set");
+  return JSON.parse(await decryptSettings(raw, key));
+}
+
+export async function loadSettings(db: D1Database): Promise<Settings> {
+  if (cached && Date.now() - cached.at < TTL) return cached.value;
+  const row = await one<{ value: string }>(db, "SELECT value FROM `_params` WHERE id = 'settings'");
+  const value = row?.value ? deepMerge(defaultSettings(), await readStored(row.value)) : defaultSettings();
+  cached = { value, at: Date.now() };
+  return value;
+}
+
+export async function ensureSettingsRow(db: D1Database): Promise<void> {
+  const row = await one(db, "SELECT id FROM `_params` WHERE id = 'settings'");
+  if (row) return;
+  const now = nowString();
+  await run(db, "INSERT OR IGNORE INTO `_params` (id, value, created, updated) VALUES ('settings', ?, ?, ?)", [
+    JSON.stringify(defaultSettings()), now, now,
+  ]);
+}
+
+function deepMerge<T>(base: T, patch: unknown): T {
+  if (patch === null || typeof patch !== "object" || Array.isArray(patch)) return (patch === undefined ? base : patch) as T;
+  const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+  for (const [k, v] of Object.entries(patch as Record<string, unknown>)) {
+    const cur = out[k];
+    out[k] = cur !== null && typeof cur === "object" && !Array.isArray(cur) ? deepMerge(cur, v) : v;
+  }
+  return out as T;
+}
+
+// ---- update (apis/settings.go settingsSet + core/settings_model.go Validate) -----------------------
+export interface FieldErr { code: string; message: string; params?: Record<string, unknown> }
+export type NestedErrors = { [k: string]: FieldErr | NestedErrors };
+
+// json.Unmarshal into a clone: nested objects merge field by field, arrays are replaced, unknown keys are dropped,
+// omitted secrets keep their stored value
+export function mergeSettings(current: Settings, patch: unknown): Settings {
+  const walk = (base: unknown, p: unknown): unknown => {
+    if (p === undefined) return base;
+    if (base !== null && typeof base === "object" && !Array.isArray(base)) {
+      if (p === null || typeof p !== "object" || Array.isArray(p)) return base;
+      const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+      for (const k of Object.keys(out)) if (k in (p as Record<string, unknown>)) out[k] = walk(out[k], (p as Record<string, unknown>)[k]);
+      return out;
+    }
+    return p;
+  };
+  return walk(current, patch) as Settings;
+}
+
+const required: FieldErr = { code: "validation_required", message: "Cannot be blank." };
+const isEmail = (v: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v);
+const isURL = (v: string) => { try { const u = new URL(v); return !!u.protocol && !!u.host; } catch { return false; } };
+const isHost = (v: string) => /^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$/.test(v) || /^(\d{1,3}\.){3}\d{1,3}$/.test(v) || /^[0-9a-fA-F:]+$/.test(v);
+const isHexColor = (v: string) => /^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(v);
+const isIPOrSubnet = (v: string) => /^(\d{1,3}\.){3}\d{1,3}(\/\d{1,2})?$/.test(v) || /^[0-9a-fA-F:]+(\/\d{1,3})?$/.test(v);
+export const lengthErr = (min: number, max: number): FieldErr => (min === max ? { code: "validation_length_invalid", message: `The length must be exactly ${min}.`, params: { max, min } } : { code: "validation_length_out_of_range", message: `The length must be between ${min} and ${max}.`, params: { max, min } });
+export const minErr = (n: number): FieldErr => ({ code: "validation_min_greater_equal_than_required", message: `Must be no less than ${n}.`, params: { threshold: n } });
+export const maxErr = (n: number): FieldErr => ({ code: "validation_max_less_equal_than_required", message: `Must be no greater than ${n}.`, params: { threshold: n } });
+const inInvalid: FieldErr = { code: "validation_in_invalid", message: "Must be a valid value." };
+const MAX_SAFE = 9007199254740991;
+
+const CRON_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 sentenize = (m: string) => { const t = m.charAt(0).toUpperCase() + m.slice(1); return /[.!?]$/.test(t) ? t : t + "."; };
+const atoi = (v: string): number | string => (/^[+-]?\d+$/.test(v) ? Number(v) : `strconv.Atoi: parsing ${JSON.stringify(v)}: invalid syntax`);
+// tools/cron/schedule.go NewSchedule + parseCronSegment, same checks in the same order
+function cronError(expr: string): string | null {
+  const segments = (CRON_MACROS[expr] ?? expr).split(" ");
+  if (segments.length !== 5) return sentenize("invalid cron expression - must be a valid macro or to have exactly 5 space separated segments");
+  const bounds: [number, number][] = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 6]];
+  for (let i = 0; i < 5; i++) {
+    const [min, max] = bounds[i]!;
+    for (const p of segments[i]!.split(",")) {
+      const stepParts = p.split("/");
+      let step = 1;
+      if (stepParts.length === 2) {
+        const parsed = atoi(stepParts[1]!); if (typeof parsed === "string") return sentenize(parsed);
+        if (parsed < 1 || parsed > max) return sentenize(`invalid segment step boundary - the step must be between 1 and the ${max}`);
+        step = parsed;
+      } else if (stepParts.length > 2) return sentenize("invalid segment step format - must be in the format */n or 1-30/n");
+      if (stepParts[0] !== "*") {
+        const rangeParts = stepParts[0]!.split("-");
+        if (rangeParts.length === 1) {
+          if (step !== 1) return sentenize("invalid segment step - step > 1 could be used only with the wildcard or range format");
+          const parsed = atoi(rangeParts[0]!); if (typeof parsed === "string") return sentenize(parsed);
+          if (parsed < min || parsed > max) return sentenize("invalid segment value - must be between the min and max of the segment");
+        } else if (rangeParts.length === 2) {
+          const lo = atoi(rangeParts[0]!); if (typeof lo === "string") return sentenize(lo);
+          if (lo < min || lo > max) return sentenize(`invalid segment range minimum - must be between ${min} and ${max}`);
+          const hi = atoi(rangeParts[1]!); if (typeof hi === "string") return sentenize(hi);
+          if (hi < lo || hi > max) return sentenize(`invalid segment range maximum - must be between ${lo} and ${max}`);
+        } else return sentenize("invalid segment range format - the range must have 1 or 2 parts");
+      }
+    }
+  }
+  return null;
+}
+const RATE_LIMIT_LABEL = /^(\w+ \/[\w/-]*|\/[\w/-]*|\w+:\w+|\*:\w+|\w+)$/; // rateLimitRuleLabelRegex
+
+export function validateSettings(s: Settings): NestedErrors {
+  const errs: NestedErrors = {};
+  const set = (path: string[], e: FieldErr) => { let cur = errs; for (const k of path.slice(0, -1)) cur = (cur[k] ??= {}) as NestedErrors; cur[path[path.length - 1]!] = e; };
+  s.superuserIPs.forEach((ip, i) => { if (!ip) set(["superuserIPs", String(i)], required); else if (!isIPOrSubnet(ip)) set(["superuserIPs", String(i)], { code: "validation_invlaid_ip_or_subnet", message: "Invalid IP or CIDR subnet." }); });
+  const m = s.meta;
+  if (m.accentColor.length !== 7) set(["meta", "accentColor"], lengthErr(7, 7)); else if (!isHexColor(m.accentColor)) set(["meta", "accentColor"], { code: "validation_is_hex_color", message: "Must be a valid hexadecimal color code." });
+  if (!m.appName) set(["meta", "appName"], required); else if (m.appName.length > 255) set(["meta", "appName"], lengthErr(1, 255));
+  if (!m.appURL) set(["meta", "appURL"], required); else if (!isURL(m.appURL)) set(["meta", "appURL"], { code: "validation_is_url", message: "Must be a valid URL." });
+  if (!m.senderName) set(["meta", "senderName"], required); else if (m.senderName.length > 255) set(["meta", "senderName"], lengthErr(1, 255));
+  if (!m.senderAddress) set(["meta", "senderAddress"], required); else if (!isEmail(m.senderAddress)) set(["meta", "senderAddress"], { code: "validation_is_email", message: "Must be a valid email address." });
+  const l = s.logs as Settings["logs"] & { maxDataSize?: number };
+  if ((l.maxDataSize ?? 0) < 0) set(["logs", "maxDataSize"], minErr(0)); else if ((l.maxDataSize ?? 0) > MAX_SAFE) set(["logs", "maxDataSize"], maxErr(MAX_SAFE));
+  if (l.maxDays < 0) set(["logs", "maxDays"], minErr(0)); else if (l.maxDays > MAX_SAFE) set(["logs", "maxDays"], maxErr(MAX_SAFE));
+  if (l.minLevel > MAX_SAFE) set(["logs", "minLevel"], maxErr(MAX_SAFE));
+  const smtp = s.smtp;
+  if (smtp.enabled && !smtp.host) set(["smtp", "host"], required); else if (smtp.host && !isHost(smtp.host)) set(["smtp", "host"], { code: "validation_is_host", message: "Must be a valid IP address or DNS name." });
+  if (smtp.enabled && !smtp.port) set(["smtp", "port"], required); else if (smtp.port < 0) set(["smtp", "port"], minErr(0));
+  if (smtp.authMethod && !["PLAIN", "LOGIN"].includes(smtp.authMethod)) set(["smtp", "authMethod"], inInvalid);
+  if (smtp.localName && !isHost(smtp.localName)) set(["smtp", "localName"], { code: "validation_is_host", message: "Must be a valid IP address or DNS name." });
+  const s3 = (cfg: Settings["s3"], path: string[]) => {
+    if (cfg.endpoint && !isURL(cfg.endpoint)) set([...path, "endpoint"], { code: "validation_is_url", message: "Must be a valid URL." }); else if (cfg.enabled && !cfg.endpoint) set([...path, "endpoint"], required);
+    for (const k of ["bucket", "region", "accessKey", "secret"] as const) if (cfg.enabled && !cfg[k]) set([...path, k], required);
+  };
+  s3(s.s3, ["s3"]); s3(s.backups.s3, ["backups", "s3"]);
+  const cronErr = s.backups.cron ? cronError(s.backups.cron) : null;
+  if (cronErr) set(["backups", "cron"], { code: "validation_invalid_cron", message: cronErr });
+  const b = s.batch;
+  if (b.enabled && !b.maxRequests) set(["batch", "maxRequests"], required); else if (b.maxRequests < 0) set(["batch", "maxRequests"], minErr(0));
+  if (b.enabled && !b.timeout) set(["batch", "timeout"], required); else if (b.timeout < 0) set(["batch", "timeout"], minErr(0));
+  if (b.maxBodySize < 0) set(["batch", "maxBodySize"], minErr(0));
+  let rulesValid = true;
+  s.rateLimits.rules.forEach((r, i) => {
+    const p = ["rateLimits", "rules", String(i)];
+    const before = JSON.stringify(errs);
+    if (!r.label) set([...p, "label"], required); else if (!RATE_LIMIT_LABEL.test(r.label)) set([...p, "label"], { code: "validation_match_invalid", message: "Must be in a valid format." });
+    if (!r.maxRequests) set([...p, "maxRequests"], required); else if (r.maxRequests < 1) set([...p, "maxRequests"], minErr(1));
+    if (!r.duration) set([...p, "duration"], required); else if (r.duration < 1) set([...p, "duration"], minErr(1));
+    if (r.audience && !["", "@guest", "@auth"].includes(r.audience)) set([...p, "audience"], inInvalid);
+    if (JSON.stringify(errs) !== before) rulesValid = false;
+  });
+  if (rulesValid) { // checkUniqueRuleLabel runs only when every rule validated (ozzo stops at the first failing rule)
+    const existing: string[] = [];
+    for (const [i, r] of s.rateLimits.rules.entries()) {
+      const fullKey = r.label + "@@" + (r.audience ?? "");
+      if (existing.some((k) => k.startsWith(fullKey) || fullKey.startsWith(k))) { set(["rateLimits", "rules", String(i), "label"], { code: "validation_conflicting_rate_limit_rule", message: `Rate limit rule configuration with label ${r.label} already exists or conflicts with another rule.`, params: { label: r.label } }); break; }
+      existing.push(fullKey);
+    }
+  }
+  s.rateLimits.excludedIPs.forEach((ip, i) => { if (!ip) set(["rateLimits", "excludedIPs", String(i)], required); else if (!isIPOrSubnet(ip)) set(["rateLimits", "excludedIPs", String(i)], { code: "validation_invlaid_ip_or_subnet", message: "Invalid IP or CIDR subnet." }); });
+  return sortNested(errs);
+}
+export function sortNested(e: NestedErrors): NestedErrors {
+  return Object.fromEntries(Object.entries(e).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([k, v]) => [k, "code" in v && typeof v.code === "string" ? v : sortNested(v as NestedErrors)])) as NestedErrors;
+}
+
+export async function saveSettings(db: D1Database, s: Settings): Promise<void> {
+  const key = encryptionKey();
+  const value = key ? await encryptSettings(JSON.stringify(s), key) : JSON.stringify(s);
+  await run(db, "UPDATE `_params` SET value = ?, updated = ? WHERE id = 'settings'", [value, nowString()]);
+  invalidateSettings();
+}

package/src/server/sql.ts

@@ -0,0 +1,61 @@
+// POST /api/sql (apis/sql.go, the panel's SQL console): superuser-only raw SQL against D1, at most 1000 rows.
+import type { Hono } from "hono";
+import { requireSuperuser } from "./auth";
+import { ApiError, badRequest } from "./errors";
+import type { AppEnv } from "./types";
+
+const MAX_ROWS = 1000;
+const WRITE_PREFIXES = ["INSERT", "CREATE", "UPDATE", "DELETE", "DROP", "DETACH", "ALTER", "REPLACE"];
+
+export function mountSqlApi(app: Hono<AppEnv>) {
+  app.post("/api/sql", async (c) => {
+    requireSuperuser(c);
+    let body: Record<string, unknown> = {};
+    try { body = (await c.req.json()) ?? {}; } catch { throw badRequest("An error occurred while loading the submitted data."); }
+    const query = String(body.query ?? "");
+    if (!query) throw new ApiError(400, "An error occurred while validating the submitted data.", { query: { code: "validation_required", message: "Cannot be blank." } } as never);
+    if (query.length > 5000) throw new ApiError(400, "An error occurred while validating the submitted data.", { query: { code: "validation_length_too_long", message: "The length must be no more than 5000.", params: { max: 5000, min: 0 } } } as never);
+    const trimmed = query.trim();
+    const upper = trimmed.toUpperCase();
+    const isWrite = !upper.startsWith("SELECT") && WRITE_PREFIXES.some((p) => upper.startsWith(p));
+    const started = Date.now();
+    try {
+      if (isWrite) {
+        const res = await c.env.DB.prepare(trimmed).run();
+        return c.json({ execTime: Date.now() - started, affectedRows: Number(res.meta?.changes ?? 0), columns: [], rows: [] });
+      }
+      const raw = await c.env.DB.prepare(trimmed).raw({ columnNames: true }) as unknown[][];
+      const names = (raw[0] ?? []) as string[];
+      // database/sql scans every value as a string; column types come from the table declarations
+      const rows = raw.slice(1, 1 + MAX_ROWS).map((r) => r.map((v) => (v === null || v === undefined ? null : String(v))));
+      const declared = new Map<string, string>();
+      for (const table of [...trimmed.matchAll(/\b(?:FROM|JOIN)\s+[`"[]?([A-Za-z_][\w]*)[`"\]]?/gi)].map((m) => m[1]!)) {
+        try { for (const col of await c.env.DB.prepare(`PRAGMA table_info("${table.replace(/"/g, "")}")`).all<{ name: string; type: string }>().then((r) => r.results)) if (!declared.has(col.name)) declared.set(col.name, col.type); } catch { /* not a table */ }
+      }
+      // database/sql reports a declared type only for plain column references; expressions and aliases of them are ""
+      const sel = /^SELECT\s+(?:DISTINCT\s+)?([\s\S]*?)\s+FROM\s/i.exec(trimmed);
+      const plain = new Map<string, string>(); let star = false;
+      if (sel) {
+        const items: string[] = []; let depth = 0, cur = "", quote = "";
+        for (const ch of sel[1]!) {
+          if (quote) { cur += ch; if (ch === quote) quote = ""; continue; }
+          if (ch === "'" || ch === '"' || ch === "`") { quote = ch; cur += ch; continue; }
+          if (ch === "(") depth++; if (ch === ")") depth--;
+          if (ch === "," && depth === 0) { items.push(cur); cur = ""; } else cur += ch;
+        }
+        items.push(cur);
+        for (const item of items) {
+          const t = item.trim();
+          if (t === "*" || /^\w+\.\*$/.test(t)) { star = true; continue; }
+          const m = /^(?:[\w`"]+\.)?[`"]?(\w+)[`"]?(?:\s+(?:AS\s+)?[`"]?(\w+)[`"]?)?$/i.exec(t);
+          if (m) plain.set(m[2] ?? m[1]!, m[1]!);
+        }
+      }
+      const columns = names.map((name) => ({ name, type: plain.has(name) ? declared.get(plain.get(name)!) ?? "" : star ? declared.get(name) ?? "" : "", nullable: true }));
+      return c.json({ execTime: Date.now() - started, affectedRows: 0, columns, rows });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message.replace(/^D1_ERROR: /, "") : String(err);
+      throw badRequest("Failed to execute query. Raw error:\n" + msg);
+    }
+  });
+}

package/src/server/static.ts

@@ -0,0 +1,17 @@
+// PocketBase static serving for `voidbase serve` (Bun) for everything outside /api (on Cloudflare the asset layer does this, see docs/differences.md): the matching file when there is one, otherwise the app's
+// index.html (200); the admin panel under /_/ falls back to its own index.html; /api keeps its JSON 404s.
+const PASSTHROUGH = ["/api/", "/__void", "/cdn-cgi/"];
+export interface AssetFetcher { fetch(req: Request): Promise<Response> }
+export async function staticFallback(req: Request, assets: AssetFetcher | undefined): Promise<Response | null> {
+  const url = new URL(req.url); const path = url.pathname;
+  if (!assets || PASSTHROUGH.some((p) => path === p.slice(0, -1) || path.startsWith(p))) return null;
+  if (req.method === "GET" || req.method === "HEAD") {
+    const file = await assets.fetch(new Request(url, { method: req.method, headers: req.headers }));
+    if (file.status !== 404) return file;
+  }
+  const index = path === "/_" || path.startsWith("/_/") ? "/_/index.html" : "/index.html";
+  const shell = await assets.fetch(new Request(new URL(index, url), { method: "GET", headers: { accept: "text/html" } }));
+  if (!shell.ok) return null;
+  const headers = new Headers(shell.headers); headers.delete("content-length");
+  return new Response(shell.body, { status: 200, headers });
+}

package/src/server/storage/s3.ts

@@ -0,0 +1,118 @@
+// S3-compatible file backend (settings.s3 / settings.backups.s3), the same subset of the R2Bucket API the server
+// uses, over fetch with AWS Signature v4 (tools/filesystem/internal/s3blob semantics: path-style or virtual-host
+// URLs, unsigned or sha256 payloads, ListObjectsV2). Chosen per request when settings.s3.enabled, so the rest of
+// the code keeps talking to `STORAGE` whether it is R2 or S3.
+export interface S3Config { enabled: boolean; bucket: string; region: string; endpoint: string; accessKey: string; secret: string; forcePathStyle: boolean }
+
+const enc = new TextEncoder();
+const hex = (buf: ArrayBuffer | Uint8Array) => Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+const sha256 = async (data: Uint8Array | string) => hex(await crypto.subtle.digest("SHA-256", typeof data === "string" ? enc.encode(data) : (data as unknown as ArrayBuffer)));
+async function hmac(key: ArrayBuffer | Uint8Array, data: string): Promise<ArrayBuffer> {
+  const k = await crypto.subtle.importKey("raw", key as unknown as ArrayBuffer, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return crypto.subtle.sign("HMAC", k, enc.encode(data));
+}
+// RFC 3986 encoding as the S3 canonical request wants it (space -> %20, keep unreserved)
+export const rfc3986 = (s: string) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());
+const escapePath = (path: string) => path.split("/").map((seg) => rfc3986(decodeURIComponent(seg))).join("/");
+export const amzDate = (d = new Date()) => d.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+
+export async function signV4(req: { method: string; url: URL; headers: Record<string, string>; payloadHash: string }, cfg: { accessKey: string; secret: string; region: string }, now = new Date()): Promise<Record<string, string>> {
+  const headers: Record<string, string> = { ...req.headers, host: req.url.host, "x-amz-content-sha256": req.payloadHash, "x-amz-date": amzDate(now) };
+  const date = headers["x-amz-date"]!.slice(0, 8);
+  const names = Object.keys(headers).map((k) => k.toLowerCase()).sort();
+  const canonicalHeaders = names.map((k) => `${k}:${String(headers[Object.keys(headers).find((h) => h.toLowerCase() === k)!]).trim().replace(/\s+/g, " ")}\n`).join("");
+  const query = [...req.url.searchParams.entries()].map(([k, v]) => [rfc3986(k), rfc3986(v)] as const).sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : 1)).map(([k, v]) => `${k}=${v}`).join("&");
+  const canonical = [req.method, escapePath(req.url.pathname), query, canonicalHeaders, names.join(";"), req.payloadHash].join("\n");
+  const scope = `${date}/${cfg.region}/s3/aws4_request`;
+  const toSign = ["AWS4-HMAC-SHA256", headers["x-amz-date"], scope, await sha256(canonical)].join("\n");
+  let key: ArrayBuffer = await hmac(enc.encode("AWS4" + cfg.secret), date);
+  for (const part of [cfg.region, "s3", "aws4_request"]) key = await hmac(key, part);
+  const signature = hex(await hmac(key, toSign));
+  headers.authorization = `AWS4-HMAC-SHA256 Credential=${cfg.accessKey}/${scope}, SignedHeaders=${names.join(";")}, Signature=${signature}`;
+  delete headers.host; // fetch sets it
+  return headers;
+}
+
+export class S3Error extends Error { constructor(public status: number, public code: string, message: string) { super(message); } }
+const xmlText = (xml: string, tag: string) => { const m = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`).exec(xml); return m ? m[1]!.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&") : null; };
+
+interface StoredObject { key: string; size: number; uploaded: Date; etag: string; httpMetadata: { contentType?: string } }
+export class S3Bucket {
+  constructor(private cfg: S3Config) {}
+  private url(key: string, query: Record<string, string> = {}): URL {
+    const raw = this.cfg.endpoint.includes("://") ? this.cfg.endpoint : `https://${this.cfg.endpoint}`;
+    const ep = new URL(raw);
+    const path = key.split("/").map(rfc3986).join("/");
+    const u = this.cfg.forcePathStyle || !this.cfg.endpoint ? new URL(`${ep.protocol}//${ep.host}/${rfc3986(this.cfg.bucket)}${path ? "/" + path : ""}`) : new URL(`${ep.protocol}//${this.cfg.bucket}.${ep.host}/${path}`);
+    for (const [k, v] of Object.entries(query)) u.searchParams.set(k, v);
+    return u;
+  }
+  private async send(method: string, key: string, opts: { query?: Record<string, string>; headers?: Record<string, string>; body?: Uint8Array; allow404?: boolean } = {}): Promise<Response> {
+    const url = this.url(key, opts.query);
+    const payloadHash = opts.body ? await sha256(opts.body) : "UNSIGNED-PAYLOAD";
+    const headers = await signV4({ method, url, headers: { ...(opts.headers ?? {}) }, payloadHash }, this.cfg);
+    const res = await fetch(url, { method, headers, body: opts.body as unknown as BodyInit | undefined });
+    if (res.status >= 400 && !(opts.allow404 && res.status === 404)) {
+      const text = await res.text();
+      throw new S3Error(res.status, xmlText(text, "Code") ?? String(res.status), xmlText(text, "Message") ?? text.slice(0, 200) ?? `HTTP ${res.status}`);
+    }
+    return res;
+  }
+  private meta(key: string, res: Response): StoredObject {
+    const cr = /bytes \d+-\d+\/(\d+)/.exec(res.headers.get("content-range") ?? "");
+    return { key, size: cr ? Number(cr[1]) : Number(res.headers.get("content-length") ?? 0), uploaded: new Date(res.headers.get("last-modified") ?? Date.now()), etag: (res.headers.get("etag") ?? "").replace(/"/g, ""), httpMetadata: { contentType: res.headers.get("content-type") ?? undefined } };
+  }
+  async head(key: string): Promise<StoredObject | null> {
+    const res = await this.send("HEAD", key, { allow404: true });
+    if (res.status === 404) return null;
+    return this.meta(key, res);
+  }
+  async get(key: string, opts?: { range?: { offset: number; length: number } }): Promise<(StoredObject & { body: ReadableStream; arrayBuffer(): Promise<ArrayBuffer>; text(): Promise<string>; json<T>(): Promise<T> }) | null> {
+    const headers: Record<string, string> = {};
+    if (opts?.range) headers.range = `bytes=${opts.range.offset}-${opts.range.offset + opts.range.length - 1}`;
+    const res = await this.send("GET", key, { headers, allow404: true });
+    if (res.status === 404) return null;
+    const m = this.meta(key, res);
+    return { ...m, body: res.body!, arrayBuffer: () => res.arrayBuffer(), text: () => res.text(), json: <T>() => res.json() as Promise<T> };
+  }
+  async put(key: string, value: ArrayBuffer | Uint8Array | string | ReadableStream | Blob | null, opts?: { httpMetadata?: { contentType?: string } }): Promise<StoredObject> {
+    let bytes: Uint8Array;
+    if (value === null) bytes = new Uint8Array();
+    else if (typeof value === "string") bytes = enc.encode(value);
+    else if (value instanceof Uint8Array) bytes = value;
+    else if (value instanceof ArrayBuffer) bytes = new Uint8Array(value);
+    else if (value instanceof Blob) bytes = new Uint8Array(await value.arrayBuffer());
+    else bytes = new Uint8Array(await new Response(value).arrayBuffer());
+    const headers: Record<string, string> = { "content-length": String(bytes.byteLength) };
+    if (opts?.httpMetadata?.contentType) headers["content-type"] = opts.httpMetadata.contentType;
+    const res = await this.send("PUT", key, { headers, body: bytes });
+    return { key, size: bytes.byteLength, uploaded: new Date(), etag: (res.headers.get("etag") ?? "").replace(/"/g, ""), httpMetadata: { contentType: opts?.httpMetadata?.contentType } };
+  }
+  async delete(keys: string | string[]): Promise<void> {
+    for (const key of Array.isArray(keys) ? keys : [keys]) await this.send("DELETE", key);
+  }
+  async list(opts: { prefix?: string; cursor?: string; limit?: number } = {}): Promise<{ objects: StoredObject[]; truncated: boolean; cursor?: string; delimitedPrefixes: string[] }> {
+    const query: Record<string, string> = { "list-type": "2", "max-keys": String(opts.limit ?? 1000) };
+    if (opts.prefix) query.prefix = opts.prefix;
+    if (opts.cursor) query["continuation-token"] = opts.cursor;
+    const xml = await (await this.send("GET", "", { query })).text();
+    const objects: StoredObject[] = [];
+    for (const m of xml.matchAll(/<Contents>([\s\S]*?)<\/Contents>/g)) {
+      const c = m[1]!;
+      objects.push({ key: xmlText(c, "Key") ?? "", size: Number(xmlText(c, "Size") ?? 0), uploaded: new Date(xmlText(c, "LastModified") ?? Date.now()), etag: (xmlText(c, "ETag") ?? "").replace(/"/g, ""), httpMetadata: {} });
+    }
+    const truncated = xmlText(xml, "IsTruncated") === "true";
+    return { objects, truncated, cursor: truncated ? xmlText(xml, "NextContinuationToken") ?? undefined : undefined, delimitedPrefixes: [] };
+  }
+  // forms/test_s3_filesystem.go: connect and list to prove the credentials and bucket work
+  async test(): Promise<void> { await this.list({ limit: 1 }); }
+}
+
+export const s3Bucket = (cfg: S3Config) => new S3Bucket(cfg) as unknown as R2Bucket;
+
+// Outside a request (queue jobs, crons) the settings.s3 swap that the bootstrap middleware does per request
+export async function withS3Storage<E extends { DB: D1Database; STORAGE: R2Bucket }>(env: E): Promise<E> {
+  const { loadSettings } = await import("../settings");
+  const s3 = (await loadSettings(env.DB)).s3;
+  return s3.enabled ? { ...env, STORAGE: s3Bucket(s3) } : env;
+}

package/src/server/types.ts

@@ -0,0 +1,25 @@
+/// <reference types="@cloudflare/workers-types" />
+import type { Collection } from "./collections/model";
+
+export type Row = Record<string, unknown>;
+
+export interface AuthRecord {
+  collection: Collection;
+  row: Row;
+}
+
+export interface Bindings {
+  DB: D1Database;
+  STORAGE: R2Bucket;
+  // optional Cloudflare bindings, declared by the deploy (queues/jobs.ts, wrangler ratelimits / analytics_engine_datasets)
+  QUEUE_JOBS?: { send(body: unknown, options?: { delaySeconds?: number }): Promise<void> };
+  RATE_LIMITER?: { limit(options: { key: string }): Promise<{ success: boolean }> };
+  LOGS_ANALYTICS?: { writeDataPoint(point: { blobs?: string[]; doubles?: number[]; indexes?: string[] }): void };
+  HUB?: DurableObjectNamespace; // the instance's realtime hub (src/server/hub.ts)
+}
+
+export interface Variables {
+  auth: AuthRecord | null;
+}
+
+export type AppEnv = { Bindings: Bindings; Variables: Variables };

package/src/server/webauthn.ts

@@ -0,0 +1,168 @@
+// Passkeys for the starter: the same four routes its Go backend (pb/webauthn/webauthn.go, go-webauthn) exposes,
+// implemented with @simplewebauthn/server on Workers. Same request/response contract, same error strings.
+// Credentials live in the app's `passkeys` collection (user, credential_id, credentials) exactly like the Go code;
+// the pending challenge lives in _params (the Go version keeps it in memory, which a Worker cannot rely on).
+import type { Context, Hono } from "hono";
+import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse } from "@simplewebauthn/server";
+import { recordAuthResponse } from "./auth-response";
+import { loadCollections } from "./collections/model";
+import { all, ident, one, run } from "./db";
+import { nowString, randomId } from "./ids";
+import { loadSettings } from "./settings";
+import type { AppEnv, Row } from "./types";
+
+const RESPONSES = {
+  failed: "Failed to authenticate",
+  reg_error: "Failed to register",
+  login_error: "Failed to login",
+  reg_success: "Successfully registered",
+  cred_error: "Failed to save credentials",
+};
+const SESSION_TTL_MS = 5 * 60 * 1000;
+
+type Transport = "ble" | "cable" | "hybrid" | "internal" | "nfc" | "smart-card" | "usb";
+interface StoredCredential { id: string; publicKey: string; counter: number; transports?: Transport[]; deviceType?: string; backedUp?: boolean }
+
+const b64url = {
+  encode: (bytes: Uint8Array) => btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""),
+  decode: (s: string) => Uint8Array.from(atob(s.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(s.length / 4) * 4, "=")), (ch) => ch.charCodeAt(0)),
+};
+const b64std = (bytes: Uint8Array) => btoa(String.fromCharCode(...bytes));
+
+// RP settings: PocketBase's Meta.AppURL when configured, otherwise the origin the browser is talking to.
+async function relyingParty(c: Context<AppEnv>) {
+  const settings = await loadSettings(c.env.DB);
+  const meta = (settings as { meta?: { appURL?: string; appName?: string } }).meta ?? {};
+  const configured = meta.appURL && !/^https?:\/\/localhost:8090\/?$/.test(meta.appURL) ? meta.appURL.replace(/\/$/, "") : "";
+  const origin = configured || c.req.header("Origin") || new URL(c.req.url).origin;
+  return { origin, rpID: new URL(origin).hostname, rpName: meta.appName || "voidbase" };
+}
+
+async function findUser(db: D1Database, usernameOrEmail: string): Promise<Row | null> {
+  const users = (await loadCollections(db)).get("users");
+  if (!users) return null;
+  const hasUsername = users.fields.some((f) => f.name === "username");
+  const sql = hasUsername ? `SELECT * FROM ${ident("users")} WHERE username = ?1 OR email = ?1 LIMIT 1` : `SELECT * FROM ${ident("users")} WHERE email = ?1 LIMIT 1`;
+  return one<Row>(db, sql, [usernameOrEmail]);
+}
+
+async function credentialsOf(db: D1Database, userId: string): Promise<{ row: Row; cred: StoredCredential }[]> {
+  const rows = await all<Row>(db, `SELECT * FROM ${ident("passkeys")} WHERE user = ?`, [userId]);
+  const out: { row: Row; cred: StoredCredential }[] = [];
+  for (const row of rows) {
+    try {
+      const cred = (typeof row.credentials === "string" ? JSON.parse(row.credentials) : row.credentials) as StoredCredential;
+      if (cred && cred.id && cred.publicKey) out.push({ row, cred });
+    } catch { /* not ours */ }
+  }
+  return out;
+}
+
+async function saveCredential(db: D1Database, userId: string, cred: StoredCredential) {
+  const credId = b64std(b64url.decode(cred.id)); // the Go code stores base64.StdEncoding of the raw id
+  const existing = await one<Row>(db, `SELECT id FROM ${ident("passkeys")} WHERE credential_id = ? LIMIT 1`, [credId]);
+  const now = nowString();
+  if (existing) await run(db, `UPDATE ${ident("passkeys")} SET credentials = ?, updated = ? WHERE id = ?`, [JSON.stringify(cred), now, existing.id]);
+  else await run(db, `INSERT INTO ${ident("passkeys")} (id, user, label, credential_id, credentials, created, updated) VALUES (?, ?, '', ?, ?, ?, ?)`, [randomId(), userId, credId, JSON.stringify(cred), now, now]);
+}
+
+async function putSession(db: D1Database, userId: string, challenge: string) {
+  const now = nowString();
+  await run(db, "INSERT OR REPLACE INTO `_params` (id, value, created, updated) VALUES (?, ?, ?, ?)", [`webauthn:session:${userId}`, JSON.stringify({ challenge, expires: Date.now() + SESSION_TTL_MS }), now, now]);
+}
+async function takeSession(db: D1Database, userId: string): Promise<string | null> {
+  const row = await one<{ value: string }>(db, "SELECT value FROM `_params` WHERE id = ?", [`webauthn:session:${userId}`]);
+  if (!row) return null;
+  await run(db, "DELETE FROM `_params` WHERE id = ?", [`webauthn:session:${userId}`]);
+  const s = JSON.parse(row.value) as { challenge: string; expires: number };
+  return s.expires > Date.now() ? s.challenge : null;
+}
+
+export function mountWebAuthn(app: Pick<Hono<AppEnv>, "get" | "post"> | { get: (p: string, h: (c: Context<AppEnv>) => Promise<Response>) => void; post: (p: string, h: (c: Context<AppEnv>) => Promise<Response>) => void }) {
+  app.get("/api/webauthn/registration-options", async (c) => {
+    const user = await findUser(c.env.DB, c.req.query("usernameOrEmail") ?? "");
+    if (!user) return c.json(RESPONSES.failed, 400);
+    try {
+      const rp = await relyingParty(c);
+      const existing = await credentialsOf(c.env.DB, String(user.id));
+      const options = await generateRegistrationOptions({
+        rpName: rp.rpName, rpID: rp.rpID,
+        userID: new TextEncoder().encode(String(user.id)),
+        userName: String(user.username || user.email || user.id),
+        userDisplayName: String(user.name ?? ""),
+        excludeCredentials: existing.map((e) => ({ id: e.cred.id, transports: e.cred.transports })),
+        authenticatorSelection: { residentKey: "preferred", userVerification: "preferred" },
+      });
+      await putSession(c.env.DB, String(user.id), options.challenge);
+      return c.json({ publicKey: options });
+    } catch (err) {
+      console.error("voidbase: webauthn registration-options", err);
+      return c.json(RESPONSES.reg_error, 500);
+    }
+  });
+
+  app.post("/api/webauthn/register", async (c) => {
+    const body = await c.req.json().catch(() => ({})) as Record<string, unknown>;
+    const user = await findUser(c.env.DB, String(body.usernameOrEmail ?? ""));
+    if (!user) return c.json(RESPONSES.failed, 400);
+    try {
+      const rp = await relyingParty(c);
+      const challenge = await takeSession(c.env.DB, String(user.id));
+      if (!challenge) return c.json(RESPONSES.reg_error, 500);
+      const { usernameOrEmail: _u, ...response } = body;
+      const verification = await verifyRegistrationResponse({ response: response as never, expectedChallenge: challenge, expectedOrigin: rp.origin, expectedRPID: rp.rpID, requireUserVerification: false });
+      if (!verification.verified || !verification.registrationInfo) return c.json(RESPONSES.reg_error, 500);
+      const info = verification.registrationInfo;
+      const cred: StoredCredential = {
+        id: info.credential.id, publicKey: b64url.encode(info.credential.publicKey), counter: info.credential.counter,
+        transports: info.credential.transports as Transport[] | undefined, deviceType: info.credentialDeviceType, backedUp: info.credentialBackedUp,
+      };
+      try { await saveCredential(c.env.DB, String(user.id), cred); } catch (err) { console.error("voidbase: webauthn save", err); return c.json(RESPONSES.cred_error, 500); }
+      return c.json(RESPONSES.reg_success);
+    } catch (err) {
+      console.error("voidbase: webauthn register", err);
+      return c.json(RESPONSES.reg_error, 500);
+    }
+  });
+
+  app.get("/api/webauthn/login-options", async (c) => {
+    const user = await findUser(c.env.DB, c.req.query("usernameOrEmail") ?? "");
+    if (!user) return c.json(RESPONSES.failed, 400);
+    try {
+      const rp = await relyingParty(c);
+      const creds = await credentialsOf(c.env.DB, String(user.id));
+      const options = await generateAuthenticationOptions({ rpID: rp.rpID, userVerification: "preferred", allowCredentials: creds.map((e) => ({ id: e.cred.id, transports: e.cred.transports })) });
+      await putSession(c.env.DB, String(user.id), options.challenge);
+      return c.json({ publicKey: options });
+    } catch (err) {
+      console.error("voidbase: webauthn login-options", err);
+      return c.json(RESPONSES.login_error, 500);
+    }
+  });
+
+  app.post("/api/webauthn/login", async (c) => {
+    const body = await c.req.json().catch(() => ({})) as Record<string, unknown>;
+    const user = await findUser(c.env.DB, String(body.usernameOrEmail ?? ""));
+    if (!user) return c.json(RESPONSES.failed, 400);
+    try {
+      const rp = await relyingParty(c);
+      const challenge = await takeSession(c.env.DB, String(user.id));
+      if (!challenge) return c.json(RESPONSES.login_error, 500);
+      const { usernameOrEmail: _u, ...response } = body;
+      const match = (await credentialsOf(c.env.DB, String(user.id))).find((e) => e.cred.id === response.id);
+      if (!match) return c.json(RESPONSES.login_error, 500);
+      const verification = await verifyAuthenticationResponse({
+        response: response as never, expectedChallenge: challenge, expectedOrigin: rp.origin, expectedRPID: rp.rpID, requireUserVerification: false,
+        credential: { id: match.cred.id, publicKey: b64url.decode(match.cred.publicKey), counter: match.cred.counter, transports: match.cred.transports },
+      });
+      if (!verification.verified) return c.json(RESPONSES.login_error, 500);
+      try { await saveCredential(c.env.DB, String(user.id), { ...match.cred, counter: verification.authenticationInfo.newCounter }); } catch { return c.json(RESPONSES.cred_error, 500); }
+      const users = (await loadCollections(c.env.DB)).get("users")!;
+      const { recordContextFor } = await import("./app");
+      return recordAuthResponse(c, await recordContextFor(c), users, user, "passkey", { body });
+    } catch (err) {
+      console.error("voidbase: webauthn login", err);
+      return c.json(RESPONSES.login_error, 500);
+    }
+  });
+}