@voidbase-cloud/voidbase 0.1.0

package/src/server/records/thumbs.ts

@@ -0,0 +1,148 @@
+// Thumbnails, mirroring PocketBase's apis/file.go + tools/filesystem CreateThumb (disintegration/imaging semantics):
+// WxH fill+crop (center), WxHt (top), WxHb (bottom), WxHf fit without upscaling, 0xH / Wx0 resize by one side.
+// Only sizes declared on the field (plus the default 100x100) are honoured; anything else, a non-image original
+// or a failed generation serves the original, exactly like PocketBase. Generated thumbs are cached in R2 under
+// {collection}/{record}/thumbs_{filename}/{size}_{filename}. Resizing runs in Photon (Rust -> wasm).
+import type { PhotonImage as PhotonImageT } from "#platform/photon";
+// Photon (Rust -> wasm) is loaded on the first thumbnail so every other request keeps a small cold start
+let photonModule: Promise<typeof import("#platform/photon")> | null = null;
+const photon = () => (photonModule ??= import("#platform/photon"));
+let P: Awaited<ReturnType<typeof photon>>; // set by createThumb before the helpers below run
+type PhotonImage = PhotonImageT;
+
+export const THUMB_SIZE_RE = /^(\d+)x(\d+)(t|b|f)?$/;
+export const IMAGE_CONTENT_TYPES = ["image/png", "image/jpg", "image/jpeg", "image/gif", "image/webp"];
+export const DEFAULT_THUMB_SIZES = ["100x100"];
+
+export interface ByteRange { offset: number; length: number }
+export interface ServedFile { body: ReadableStream | Uint8Array; size: number; contentType: string; uploaded: Date; name: string; range?: ByteRange }
+
+// Parses a single `Range: bytes=a-b` header against the total size; null when absent, "invalid" when unsatisfiable.
+export function parseRange(header: string | undefined, size: number): ByteRange | null | "invalid" {
+  if (!header) return null;
+  const m = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+  if (!m || (m[1] === "" && m[2] === "")) return "invalid";
+  let start: number, end: number;
+  if (m[1] === "") { const suffix = Number(m[2]); if (suffix <= 0) return "invalid"; start = Math.max(0, size - suffix); end = size - 1; }
+  else { start = Number(m[1]); end = m[2] === "" ? size - 1 : Math.min(size - 1, Number(m[2])); }
+  if (start >= size || start > end) return "invalid";
+  return { offset: start, length: end - start + 1 };
+}
+
+const attrsOf = (h: R2Object | null) => ({ size: h?.size ?? 0, type: h?.httpMetadata?.contentType ?? "application/octet-stream" });
+const sliceRange = (bytes: Uint8Array, range: ByteRange | undefined) => range ? bytes.subarray(range.offset, range.offset + range.length) : bytes;
+
+async function getObject(storage: R2Bucket, key: string, rangeHeader: string | undefined): Promise<{ obj: R2ObjectBody; range?: ByteRange } | null | "invalid"> {
+  const head = rangeHeader ? await storage.head(key) : null;
+  if (rangeHeader && !head) return null;
+  const range = rangeHeader ? parseRange(rangeHeader, head!.size) : null;
+  if (range === "invalid") return "invalid";
+  const obj = await storage.get(key, range ? { range } : undefined);
+  if (!obj) return null;
+  return { obj, range: range ?? undefined };
+}
+
+const served = (obj: R2ObjectBody, name: string, fallbackType: string, range?: ByteRange): ServedFile =>
+  ({ body: obj.body, size: obj.size, contentType: obj.httpMetadata?.contentType ?? fallbackType, uploaded: obj.uploaded, name, range });
+
+export class RangeNotSatisfiable extends Error { constructor(public size: number, public contentType: string, public name: string) { super("range not satisfiable"); } }
+
+export async function resolveServedFile(storage: R2Bucket, key: string, filename: string, thumbSize: string, fieldThumbs: string[], rangeHeader?: string): Promise<ServedFile | null> {
+  if (thumbSize && (DEFAULT_THUMB_SIZES.includes(thumbSize) || fieldThumbs.includes(thumbSize))) {
+    const attrs = await storage.head(key);
+    if (!attrs) return null;
+    const originalType = attrs.httpMetadata?.contentType ?? "";
+    if (IMAGE_CONTENT_TYPES.includes(originalType)) {
+      const servedName = `${thumbSize}_${filename}`;
+      const thumbKey = `${key.slice(0, key.length - filename.length)}thumbs_${filename}/${servedName}`;
+      const cached = await getObject(storage, thumbKey, rangeHeader);
+      if (cached === "invalid") { const h = await storage.head(thumbKey); throw new RangeNotSatisfiable(h?.size ?? 0, h?.httpMetadata?.contentType ?? "image/png", servedName); }
+      if (cached) return served(cached.obj, servedName, "image/png", cached.range);
+      const original = await storage.get(key);
+      if (!original) return null;
+      try {
+        const bytes = new Uint8Array(await original.arrayBuffer());
+        const thumb = await createThumb(bytes, originalType, thumbSize);
+        await storage.put(thumbKey, thumb.bytes, { httpMetadata: { contentType: thumb.contentType } });
+        const range = parseRange(rangeHeader, thumb.bytes.byteLength);
+        if (range === "invalid") throw new RangeNotSatisfiable(thumb.bytes.byteLength, thumb.contentType, servedName);
+        return { body: sliceRange(thumb.bytes, range ?? undefined), size: thumb.bytes.byteLength, contentType: thumb.contentType, uploaded: new Date(), name: servedName, range: range ?? undefined };
+      } catch (err) {
+        if (err instanceof RangeNotSatisfiable) throw err;
+        console.warn(`voidbase: fallback to original - failed to create thumb ${servedName}`, err);
+      }
+    }
+  }
+  const got = await getObject(storage, key, rangeHeader);
+  if (got === "invalid") throw new RangeNotSatisfiable(attrsOf(await storage.head(key)).size, attrsOf(await storage.head(key)).type, filename);
+  if (!got) return null;
+  return served(got.obj, filename, "application/octet-stream", got.range);
+}
+
+// Output format follows PocketBase: JPEG stays JPEG, everything else (png, webp, gif) is encoded as PNG.
+export async function createThumb(bytes: Uint8Array, contentType: string, thumbSize: string): Promise<{ bytes: Uint8Array; contentType: string }> {
+  P = await photon();
+  const m = THUMB_SIZE_RE.exec(thumbSize);
+  if (!m) throw new Error("thumb size must be in WxH, WxHt, WxHb or WxHf format");
+  const width = Number(m[1]), height = Number(m[2]), resizeType = m[3] ?? "";
+  if (width === 0 && height === 0) throw new Error("thumb width and height cannot be zero at the same time");
+  const img = P.PhotonImage.new_from_byteslice(bytes);
+  try {
+    let out: PhotonImage;
+    if (width === 0 || height === 0) out = resizeTo(img, width, height);
+    else if (resizeType === "f") out = fit(img, width, height);
+    else out = fill(img, width, height, resizeType === "t" ? "top" : resizeType === "b" ? "bottom" : "center");
+    try {
+      if (contentType === "image/jpeg" || contentType === "image/jpg") return { bytes: out.get_bytes_jpeg(95), contentType: "image/jpeg" };
+      return { bytes: out.get_bytes(), contentType: "image/png" };
+    } finally { if (out !== img) out.free(); }
+  } finally { img.free(); }
+}
+
+const roundHalfUp = (v: number) => Math.max(1, Math.floor(v + 0.5));
+
+// imaging.Resize: a zero side is derived from the aspect ratio (round half up, at least 1)
+function resizeTo(img: PhotonImage, w: number, h: number): PhotonImage {
+  const sw = img.get_width(), sh = img.get_height();
+  if (w === 0) w = roundHalfUp((h * sw) / sh);
+  if (h === 0) h = roundHalfUp((w * sh) / sw);
+  if (w === sw && h === sh) return img;
+  return P.resize(img, w, h, P.SamplingFilter.Triangle);
+}
+
+// imaging.Fit: scale down to fit inside the box, never upscale (int truncation as in Go)
+function fit(img: PhotonImage, maxW: number, maxH: number): PhotonImage {
+  const sw = img.get_width(), sh = img.get_height();
+  if (sw <= maxW && sh <= maxH) return img;
+  const srcAspect = sw / sh, maxAspect = maxW / maxH;
+  let nw: number, nh: number;
+  if (srcAspect > maxAspect) { nw = maxW; nh = Math.trunc(nw / srcAspect); } else { nh = maxH; nw = Math.trunc(nh * srcAspect); }
+  return P.resize(img, Math.max(1, nw), Math.max(1, nh), P.SamplingFilter.Triangle);
+}
+
+// imaging.Fill: sources of at least 100x100 are cropped to the target aspect first and then resized;
+// smaller ones are resized to cover and then cropped. Both end at exactly w x h.
+function fill(img: PhotonImage, w: number, h: number, anchor: "center" | "top" | "bottom"): PhotonImage {
+  const sw = img.get_width(), sh = img.get_height();
+  if (sw === w && sh === h) return img;
+  const srcAspect = sw / sh, dstAspect = w / h;
+  if (sw >= 100 && sh >= 100) {
+    let cw = sw, ch = sh;
+    if (srcAspect < dstAspect) ch = Math.trunc(Math.max(1, (sw * h) / w) + 0.5);
+    else cw = Math.trunc(Math.max(1, (sh * w) / h) + 0.5);
+    const cropped = cropAnchor(img, cw, ch, anchor);
+    try { return P.resize(cropped, w, h, P.SamplingFilter.Triangle); } finally { if (cropped !== img) cropped.free(); }
+  }
+  const tmp = srcAspect < dstAspect ? resizeTo(img, w, 0) : resizeTo(img, 0, h);
+  try { return cropAnchor(tmp, w, h, anchor); } finally { if (tmp !== img) tmp.free(); }
+}
+
+// imaging.CropAnchor with the Center / Top / Bottom anchors, clamped to the image
+function cropAnchor(img: PhotonImage, w: number, h: number, anchor: "center" | "top" | "bottom"): PhotonImage {
+  const sw = img.get_width(), sh = img.get_height();
+  const x = Math.trunc((sw - w) / 2);
+  const y = anchor === "top" ? 0 : anchor === "bottom" ? sh - h : Math.trunc((sh - h) / 2);
+  const x1 = Math.max(0, x), y1 = Math.max(0, y), x2 = Math.min(sw, x + w), y2 = Math.min(sh, y + h);
+  if (x1 === 0 && y1 === 0 && x2 === sw && y2 === sh) return img;
+  return P.crop(img, x1, y1, x2, y2);
+}

package/src/server/records/values.ts

@@ -0,0 +1,295 @@
+// Record value normalization and validation per field type, mirroring core/field_*.go ValidateValue.
+import { isMultiple, type Field } from "../collections/fields";
+import type { Collection } from "../collections/model";
+import { all, ident } from "../db";
+import { nowString } from "../ids";
+import type { Row } from "../types";
+
+export interface FieldError { code: string; message: string; params?: Record<string, unknown> }
+export type RecordErrors = Record<string, FieldError>;
+const err = (code: string, message: string, params?: Record<string, unknown>): FieldError => (params ? { code, message, params } : { code, message });
+export const REQUIRED = err("validation_required", "Cannot be blank.");
+
+export interface Upload { name: string; type: string; size: number; bytes: ArrayBuffer }
+// value of a file field during an upsert: kept names plus new uploads (already renamed)
+export interface FileValue { names: string[]; uploads: Map<string, Upload> }
+
+const EMAIL_RE = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$/;
+
+// ---- reading rows ---------------------------------------------------------
+export function fromColumn(f: Field, v: unknown): unknown {
+  if (f.type === "bool") return !!v;
+  if (f.type === "number") return typeof v === "number" ? v : Number(v ?? 0) || 0;
+  if (f.type === "json") {
+    if (v === null || v === undefined) return null;
+    if (typeof v === "string") { try { return JSON.parse(v); } catch { return v; } }
+    return v;
+  }
+  if (f.type === "geoPoint") {
+    if (typeof v === "string") { try { const o = JSON.parse(v); return { lon: Number(o?.lon ?? 0), lat: Number(o?.lat ?? 0) }; } catch { /* fallthrough */ } }
+    return { lon: 0, lat: 0 };
+  }
+  if (isMultiple(f)) {
+    if (Array.isArray(v)) return v.map(String);
+    if (typeof v === "string" && v !== "") { try { const a = JSON.parse(v); return Array.isArray(a) ? a.map(String) : [String(v)]; } catch { return [v]; } }
+    return [];
+  }
+  if (v === null || v === undefined) return "";
+  return String(v);
+}
+
+export function rowToValues(c: Collection, row: Row): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const f of c.fields as Field[]) out[f.name] = fromColumn(f, row[f.name]);
+  return out;
+}
+
+// ---- writing rows ---------------------------------------------------------
+export function toColumn(f: Field, v: unknown): unknown {
+  if (f.type === "bool") return v ? 1 : 0;
+  if (f.type === "number") return typeof v === "number" ? v : Number(v) || 0;
+  if (f.type === "json") return v === null || v === undefined ? null : JSON.stringify(v);
+  if (f.type === "geoPoint") { const o = (v ?? {}) as { lon?: unknown; lat?: unknown }; return JSON.stringify({ lon: Number(o.lon ?? 0) || 0, lat: Number(o.lat ?? 0) || 0 }); }
+  if (isMultiple(f)) return JSON.stringify(Array.isArray(v) ? v : v === "" || v == null ? [] : [String(v)]);
+  if (f.type === "file" || f.type === "select" || f.type === "relation") return Array.isArray(v) ? String(v[0] ?? "") : v == null ? "" : String(v);
+  return v == null ? "" : String(v);
+}
+
+// ---- input normalization (Record.Set semantics) ---------------------------
+export function normalizeInput(f: Field, raw: unknown): unknown {
+  switch (f.type) {
+    case "bool": return raw === true || raw === "true" || raw === 1 || raw === "1";
+    case "number": {
+      if (raw === "" || raw === null || raw === undefined) return 0;
+      // cast.ToFloat64 semantics: anything that does not parse becomes 0 (no validation error)
+      const n = typeof raw === "number" ? raw : Number(raw);
+      return Number.isFinite(n) ? n : 0;
+    }
+    case "json": {
+      if (raw === undefined) return null;
+      if (typeof raw === "string") { const s = raw.trim(); if (s === "") return null; try { return JSON.parse(s); } catch { return raw; } }
+      return raw;
+    }
+    case "geoPoint": {
+      let o = raw;
+      if (typeof raw === "string") { try { o = JSON.parse(raw); } catch { o = null; } }
+      const g = (o ?? {}) as { lon?: unknown; lat?: unknown };
+      return { lon: Number(g.lon ?? 0) || 0, lat: Number(g.lat ?? 0) || 0 };
+    }
+    case "date": return normalizeDate(raw);
+    case "select": case "relation": case "file": {
+      let list: string[];
+      if (Array.isArray(raw)) list = raw.map(String);
+      else if (typeof raw === "string") { const s = raw.trim(); if (s.startsWith("[") && isMultiple(f)) { try { list = (JSON.parse(s) as unknown[]).map(String); } catch { list = [s]; } } else list = s === "" ? [] : [s]; }
+      else list = raw == null ? [] : [String(raw)];
+      list = uniqueStrings(list.map((s) => s.trim()).filter(Boolean));
+      return isMultiple(f) ? list : (list[list.length - 1] ?? "");
+    }
+    default: return raw == null ? "" : typeof raw === "object" ? JSON.stringify(raw) : String(raw);
+  }
+}
+
+export const uniqueStrings = (list: string[]) => [...new Set(list)];
+
+export function normalizeDate(raw: unknown): string {
+  if (raw === null || raw === undefined || raw === "") return "";
+  if (raw instanceof Date) return nowString(raw);
+  const s = String(raw).trim();
+  if (!s) return "";
+  if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(s)) return s;
+  const iso = /^\d{4}-\d{2}-\d{2}(?:[ T]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)?(?:Z|[+-]\d{2}:?\d{2})?$/.test(s) ? s.replace(" ", "T") : s;
+  const d = new Date(/^\d{4}-\d{2}-\d{2}$/.test(iso) ? iso + "T00:00:00Z" : /Z|[+-]\d{2}:?\d{2}$/.test(iso) || !/T/.test(iso) ? iso : iso + "Z");
+  return Number.isNaN(d.getTime()) ? "" : nowString(d);
+}
+
+// ---- validation ----------------------------------------------------------
+export interface ValidateContext {
+  db: D1Database;
+  collections: Map<string, Collection>;
+  isNew: boolean;
+  originalId?: string;
+  uploads: Record<string, Map<string, Upload>>; // per file field: newly uploaded name -> upload
+  existingFiles: Record<string, string[]>; // per file field: names stored before this request
+}
+
+const len = (s: string) => [...s].length;
+const isEmpty = (v: unknown) => v === null || v === undefined || v === "" || (Array.isArray(v) && v.length === 0) || (typeof v === "number" && v === 0);
+
+export async function validateValues(c: Collection, values: Record<string, unknown>, ctx: ValidateContext): Promise<RecordErrors> {
+  const errors: RecordErrors = {};
+  for (const f of c.fields as Field[]) {
+    const e = await validateField(f, values[f.name], ctx, values);
+    if (e) errors[f.name] = e;
+  }
+  return errors;
+}
+
+async function validateField(f: Field, v: unknown, ctx: ValidateContext, values: Record<string, unknown>): Promise<FieldError | null> {
+  const n = (x: unknown) => (x === null || x === undefined ? null : Number(x));
+  switch (f.type) {
+    case "text": {
+      const s = String(v ?? "");
+      if (f.primaryKey) {
+        if (!ctx.isNew && ctx.originalId !== undefined && s !== ctx.originalId) return err("validation_pk_change", "The record primary key cannot be changed.");
+        if (s === "") return REQUIRED;
+      } else if (f.required && s === "") return REQUIRED;
+      if (s === "") return null;
+      if (n(f.min) && len(s) < (n(f.min) as number)) return err("validation_min_text_constraint", `Must be at least ${f.min} character(s).`, { min: f.min });
+      if (n(f.max) && len(s) > (n(f.max) as number)) return err("validation_max_text_constraint", `Must be no more than ${f.max} character(s).`, { max: f.max });
+      if (f.pattern && !safeRegex(String(f.pattern)).test(s)) return err("validation_invalid_format", "Invalid value format.");
+      return null;
+    }
+    case "editor": {
+      const s = String(v ?? "");
+      if (f.required && s === "") return REQUIRED;
+      if (n(f.maxSize) && new TextEncoder().encode(s).length > (n(f.maxSize) as number)) return err("validation_content_size_limit", `The maximum allowed content size is ${f.maxSize} bytes.`, { maxSize: f.maxSize });
+      return null;
+    }
+    case "number": {
+      if (typeof v === "number" && Number.isNaN(v)) return err("validation_not_a_number", "The submitted number is not properly formatted");
+      const x = Number(v ?? 0);
+      if (f.required && x === 0) return REQUIRED;
+      if (f.onlyInt && !Number.isInteger(x)) return err("validation_only_int_constraint", "Decimal numbers are not allowed");
+      if (n(f.min) !== null && x < (n(f.min) as number)) return err("validation_min_number_constraint", `Must be greater or equal than ${f.min}.`, { min: f.min });
+      if (n(f.max) !== null && x > (n(f.max) as number)) return err("validation_max_number_constraint", `Must be less or equal than ${f.max}.`, { max: f.max });
+      return null;
+    }
+    case "bool": return f.required && !v ? REQUIRED : null;
+    case "email": {
+      const s = String(v ?? "");
+      if (f.required && s === "") return REQUIRED;
+      if (s === "") return null;
+      if (!EMAIL_RE.test(s)) return err("validation_is_email", "Must be a valid email address.");
+      const domain = s.split("@")[1]!.toLowerCase();
+      const only = f.onlyDomains as string[] | null; const except = f.exceptDomains as string[] | null;
+      if (only?.length && !only.map((d) => d.toLowerCase()).includes(domain)) return err("validation_email_domain_not_allowed", "Email domain is not allowed");
+      if (except?.length && except.map((d) => d.toLowerCase()).includes(domain)) return err("validation_email_domain_not_allowed", "Email domain is not allowed");
+      return null;
+    }
+    case "url": {
+      const s = String(v ?? "");
+      if (f.required && s === "") return REQUIRED;
+      if (s === "") return null;
+      let host = "";
+      try { const u = new URL(s); if (!/^https?:$/.test(u.protocol) || !u.hostname) throw new Error(); host = u.hostname.toLowerCase(); } catch { return err("validation_invalid_url", "Must be a valid url."); }
+      const only = f.onlyDomains as string[] | null; const except = f.exceptDomains as string[] | null;
+      if (only?.length && !only.map((d) => d.toLowerCase()).includes(host)) return err("validation_url_domain_not_allowed", "Url domain is not allowed");
+      if (except?.length && except.map((d) => d.toLowerCase()).includes(host)) return err("validation_url_domain_not_allowed", "Url domain is not allowed");
+      return null;
+    }
+    case "date": {
+      const s = String(v ?? "");
+      if (f.required && s === "") return REQUIRED;
+      if (s === "") return null;
+      if (f.min && s < String(f.min)) return err("validation_min_date_constraint", `Must be later than ${f.min}`, { min: f.min });
+      if (f.max && s > String(f.max)) return err("validation_max_date_constraint", `Must be earlier than ${f.max}`, { max: f.max });
+      return null;
+    }
+    case "autodate": return null;
+    case "select": {
+      const list = Array.isArray(v) ? (v as string[]) : v ? [String(v)] : [];
+      if (f.required && list.length === 0) return REQUIRED;
+      const max = isMultiple(f) ? Number(f.maxSelect) : 1;
+      if (list.length > max) return err("validation_too_many_values", `Select no more than ${max}`, { maxSelect: max });
+      const allowed = (f.values as string[] | null) ?? [];
+      for (const s of list) if (!allowed.includes(s)) return err("validation_invalid_value", `Invalid value ${s}.`, { value: s });
+      return null;
+    }
+    case "relation": {
+      const list = Array.isArray(v) ? (v as string[]) : v ? [String(v)] : [];
+      if (f.required && list.length === 0) return REQUIRED;
+      const max = isMultiple(f) ? Number(f.maxSelect) : 1;
+      const min = Number(f.minSelect ?? 0);
+      if (min > 0 && list.length < min) return err("validation_not_enough_values", `Select at least ${min}`, { minSelect: min });
+      if (max > 0 && list.length > max) return err("validation_too_many_values", `Select no more than ${max}`, { maxSelect: max });
+      if (list.length === 0) return null;
+      const rel = ctx.collections.get(String(f.collectionId));
+      if (!rel) return err("validation_missing_rel_collection", "Relation connection is missing or cannot be accessed");
+      const found = new Set<string>();
+      for (let i = 0; i < list.length; i += 90) {
+        const chunk = list.slice(i, i + 90);
+        const rows = await all<{ id: string }>(ctx.db, `SELECT id FROM ${ident(rel.name)} WHERE id IN (${chunk.map(() => "?").join(",")})`, chunk);
+        for (const r of rows) found.add(r.id);
+      }
+      if (list.some((id) => !found.has(id))) return err("validation_missing_rel_records", "Failed to find all relation records with the provided ids.");
+      return null;
+    }
+    case "file": {
+      const list = Array.isArray(v) ? (v as string[]) : v ? [String(v)] : [];
+      if (f.required && list.length === 0) return REQUIRED;
+      const max = isMultiple(f) ? Number(f.maxSelect) : 1;
+      if (max > 0 && list.length > max) return err("validation_too_many_files", `The maximum allowed files is ${max}`, { maxSelect: max });
+      const uploads = ctx.uploads[f.name] ?? new Map<string, Upload>();
+      const existing = new Set(ctx.existingFiles[f.name] ?? []);
+      const invalid = list.filter((name) => !uploads.has(name) && !existing.has(name));
+      if (invalid.length) return err("validation_invalid_file", `Invalid new files: ${invalid.join(", ")}.`, { invalidFiles: invalid.join(", ") });
+      const mimeTypes = (f.mimeTypes as string[] | null) ?? [];
+      const maxSize = Number(f.maxSize ?? 0);
+      for (const name of list) {
+        const up = uploads.get(name);
+        if (!up) continue;
+        if (maxSize > 0 && up.size > maxSize) return err("validation_file_size_limit", `Failed to upload "${name}" - the maximum allowed file size is ${maxSize} bytes.`, { maxSize });
+        if (mimeTypes.length && !mimeTypes.includes(up.type)) return err("validation_invalid_mime_type", `"${name}" mime type must be one of: ${mimeTypes.join(", ")}.`);
+      }
+      return null;
+    }
+    case "json": {
+      if (f.required && (v === null || v === undefined || v === "" || (Array.isArray(v) && v.length === 0) || (typeof v === "object" && v && Object.keys(v as object).length === 0))) return REQUIRED;
+      const bytes = new TextEncoder().encode(JSON.stringify(v ?? null)).length;
+      if (n(f.maxSize) && bytes > (n(f.maxSize) as number)) return err("validation_json_size_limit", `The maximum allowed JSON size is ${f.maxSize} bytes.`, { maxSize: f.maxSize });
+      return null;
+    }
+    case "password": {
+      // v here is the plain text password when it is being set; empty means untouched
+      const s = String(v ?? "");
+      if (s === "") return null;
+      if (n(f.min) && len(s) < (n(f.min) as number)) return err("validation_min_text_constraint", `Must be at least ${f.min} character(s).`);
+      if (n(f.max) && len(s) > (n(f.max) as number)) return err("validation_max_text_constraint", `Must be no more than ${f.max} character(s).`);
+      if (f.pattern && !safeRegex(String(f.pattern)).test(s)) return err("validation_invalid_format", "Invalid value format.");
+      return null;
+    }
+    case "geoPoint": {
+      const g = (v ?? {}) as { lon?: number; lat?: number };
+      const lon = Number(g.lon ?? 0), lat = Number(g.lat ?? 0);
+      if (f.required && lon === 0 && lat === 0) return REQUIRED;
+      if (lon < -180 || lon > 180) return err("validation_invalid_longitude", "Longitude must be between -180 and 180 degrees.");
+      if (lat < -90 || lat > 90) return err("validation_invalid_latitude", "Latitude must be between -90 and 90 degrees.");
+      return null;
+    }
+  }
+  void values; void isEmpty;
+  return null;
+}
+
+const regexCache = new Map<string, RegExp>();
+function safeRegex(p: string): RegExp {
+  let r = regexCache.get(p);
+  if (!r) { try { r = new RegExp(p); } catch { r = /$^/; } regexCache.set(p, r); }
+  return r;
+}
+
+// Generates a value for autogeneratePattern: literal chars and [class]{n} groups (the forms PocketBase ships).
+export function autogenerate(pattern: string): string {
+  let out = "";
+  const re = /\[([^\]]+)\]\{(\d+)(?:,(\d+))?\}|\[([^\]]+)\]|(\\?.)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(pattern))) {
+    if (m[1] !== undefined) out += randomFromClass(m[1], Number(m[2]) + (m[3] ? Math.floor(Math.random() * (Number(m[3]) - Number(m[2]) + 1)) : 0));
+    else if (m[4] !== undefined) out += randomFromClass(m[4], 1);
+    else out += m[5]!.replace(/^\\/, "");
+  }
+  return out;
+}
+function randomFromClass(cls: string, count: number): string {
+  const chars: string[] = [];
+  for (let i = 0; i < cls.length; i++) {
+    if (cls[i + 1] === "-" && i + 2 < cls.length) {
+      for (let c = cls.charCodeAt(i); c <= cls.charCodeAt(i + 2); c++) chars.push(String.fromCharCode(c));
+      i += 2;
+    } else chars.push(cls[i]!);
+  }
+  const bytes = crypto.getRandomValues(new Uint8Array(count));
+  let s = "";
+  for (let i = 0; i < count; i++) s += chars[bytes[i]! % chars.length];
+  return s;
+}

package/src/server/settings-api.ts

@@ -0,0 +1,104 @@
+// /api/settings (superuser): update, test email, test S3, Apple client secret (apis/settings.go).
+import type { Context, Hono } from "hono";
+import { ApiError, badRequest } from "./errors";
+import { loadCollections } from "./collections/model";
+import { sendRecordAuthAlert, sendRecordChangeEmail, sendRecordOTP, sendRecordPasswordReset, sendRecordVerification } from "./mail";
+import { lengthErr, loadSettings, maxErr, mergeSettings, minErr, publicSettings, saveSettings, sortNested, validateSettings, type NestedErrors } from "./settings";
+import { randomString } from "./ids";
+import type { AppEnv, Row } from "./types";
+import type { Field } from "./collections/fields";
+import { requireSuperuser } from "./auth";
+import { S3Bucket } from "./storage/s3";
+import { requestHook, trigger } from "./hooks/runtime";
+
+const readBody = async (c: Context<AppEnv>): Promise<Record<string, unknown>> => {
+  try { const v = await c.req.json(); if (!v || typeof v !== "object" || Array.isArray(v)) throw new Error(); return v as Record<string, unknown>; }
+  catch { throw badRequest("An error occurred while loading the submitted data."); }
+};
+const req = { code: "validation_required", message: "Cannot be blank." };
+
+export function mountSettingsApi(app: Hono<AppEnv>) {
+  app.patch("/api/settings", async (c) => {
+    requireSuperuser(c);
+    const body = await readBody(c);
+    const current = await loadSettings(c.env.DB);
+    const merged = mergeSettings(current, body);
+    return requestHook("onSettingsUpdateRequest", c, null, { oldSettings: structuredClone(current), newSettings: merged }, async (ev) => {
+      const next = ev.newSettings as typeof merged;
+      const errs = validateSettings(next);
+      if (Object.keys(errs).length) throw new ApiError(400, "An error occurred while saving the new settings.", errs as never);
+      // PocketBase keeps the stored secrets when the submitted ones are blank (validation already saw the blank value)
+      if (!next.smtp.password) next.smtp.password = current.smtp.password;
+      if (!next.s3.secret) next.s3.secret = current.s3.secret;
+      if (!next.backups.s3.secret) next.backups.s3.secret = current.backups.s3.secret;
+      await saveSettings(c.env.DB, next);
+      await trigger("onSettingsReload", { app: undefined as unknown, next: async () => undefined as unknown }, null, async () => undefined);
+      return c.json(publicSettings(next));
+    });
+  });
+
+  app.post("/api/settings/test/email", async (c) => {
+    requireSuperuser(c);
+    const body = await readBody(c);
+    const email = String(body.email ?? ""), template = String(body.template ?? ""), collName = String(body.collection ?? "");
+    const errs: NestedErrors = {};
+    const collections = await loadCollections(c.env.DB);
+    if (collName) {
+      if (collName.length > 255) errs.collection = lengthErr(1, 255);
+      else { const cc = collections.get(collName); if (!cc || cc.type !== "auth") errs.collection = { code: "validation_invalid_auth_collection", message: "Must be a valid auth collection id or name." }; }
+    }
+    if (!email) errs.email = req; else if (email.length > 255) errs.email = lengthErr(1, 255); else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) errs.email = { code: "validation_is_email", message: "Must be a valid email address." };
+    if (!template) errs.template = req; else if (!["verification", "password-reset", "email-change", "otp", "login-alert"].includes(template)) errs.template = { code: "validation_in_invalid", message: "Must be a valid value." };
+    if (Object.keys(errs).length) throw new ApiError(400, "Failed to send the test email.", sortNested(errs) as never);
+    const collection = collections.get(collName || "_superusers")!;
+    const row: Row = {};
+    for (const f of collection.fields as Field[]) if (!f.hidden) row[f.name] = `__pb_test_${f.name}__`;
+    row.tokenKey = randomString(50); row.email = email;
+    try {
+      const inline = { inline: true }; // PocketBase reports the SMTP error to the panel, so deliver now, not from the queue
+      if (template === "verification") await sendRecordVerification(c.env.DB, collection, row, inline);
+      else if (template === "password-reset") await sendRecordPasswordReset(c.env.DB, collection, row, inline);
+      else if (template === "email-change") await sendRecordChangeEmail(c.env.DB, collection, row, email, inline);
+      else if (template === "otp") await sendRecordOTP(c.env.DB, collection, row, "_PB_TEST_OTP_ID_", "123456", inline);
+      else await sendRecordAuthAlert(c.env.DB, collection, row, `${new Date().toISOString().replace("T", " ").replace(/\.\d{3}Z$/, ".000Z")} - TEST_IP TEST_USER_AGENT`, inline);
+    } catch (err) { throw badRequest("Failed to send the test email. Raw error: \n" + (err instanceof Error ? err.message : String(err))); }
+    return c.body(null, 204);
+  });
+
+  app.post("/api/settings/test/s3", async (c) => {
+    requireSuperuser(c);
+    const body = await readBody(c);
+    const fs = String(body.filesystem ?? "");
+    if (!fs) throw new ApiError(400, "Failed to test the S3 filesystem.", { filesystem: req } as never);
+    if (!["storage", "backups"].includes(fs)) throw new ApiError(400, "Failed to test the S3 filesystem.", { filesystem: { code: "validation_in_invalid", message: "Must be a valid value." } } as never);
+    const settings = await loadSettings(c.env.DB);
+    const cfg = fs === "storage" ? settings.s3 : settings.backups.s3;
+    if (!cfg.enabled) throw badRequest(`Failed to test the S3 filesystem. Raw error: \nS3 storage filesystem is not enabled`);
+    try { await new S3Bucket(cfg).test(); } catch (err) { throw badRequest(`Failed to test the S3 filesystem. Raw error: \n${err instanceof Error ? err.message : String(err)}`); }
+    return c.body(null, 204);
+  });
+
+  app.post("/api/settings/apple/generate-client-secret", async (c) => {
+    requireSuperuser(c);
+    const body = await readBody(c);
+    const clientId = String(body.clientId ?? ""), teamId = String(body.teamId ?? ""), keyId = String(body.keyId ?? ""), privateKey = String(body.privateKey ?? ""), duration = Number(body.duration ?? 0);
+    const errs: NestedErrors = {};
+    if (!clientId) errs.clientId = req;
+    if (!teamId) errs.teamId = req; else if (teamId.length !== 10) errs.teamId = lengthErr(10, 10);
+    if (!keyId) errs.keyId = req; else if (keyId.length !== 10) errs.keyId = lengthErr(10, 10);
+    if (!privateKey) errs.privateKey = req; else if (!/^-----BEGIN PRIVATE KEY-----[\s\S]+-----END PRIVATE KEY-----\s*$/.test(privateKey.trim())) errs.privateKey = { code: "validation_match_invalid", message: "Must be in a valid format." };
+    if (!duration) errs.duration = req; else if (duration < 1) errs.duration = minErr(1); else if (duration > 15777000) errs.duration = maxErr(15777000);
+    if (Object.keys(errs).length) throw new ApiError(400, "Invalid client secret data.", sortNested(errs) as never);
+    try {
+      const pem = privateKey.trim().replace(/-----BEGIN PRIVATE KEY-----|-----END PRIVATE KEY-----/g, "").replace(/\s+/g, "");
+      const der = Uint8Array.from(atob(pem), (ch) => ch.charCodeAt(0));
+      const key = await crypto.subtle.importKey("pkcs8", der, { name: "ECDSA", namedCurve: "P-256" }, false, ["sign"]);
+      const b64 = (v: ArrayBuffer | Uint8Array | string) => { const bytes = typeof v === "string" ? new TextEncoder().encode(v) : new Uint8Array(v as ArrayBuffer); return btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""); };
+      const now = Math.floor(Date.now() / 1000);
+      const header = b64(JSON.stringify({ alg: "ES256", kid: keyId, typ: "JWT" }));
+      const claims = b64(JSON.stringify({ aud: ["https://appleid.apple.com"], exp: now + duration, iat: now, iss: teamId, sub: clientId }));
+      const sig = await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, key, new TextEncoder().encode(`${header}.${claims}`));
+      return c.json({ secret: `${header}.${claims}.${b64(sig)}` });
+    } catch (err) { throw badRequest("Failed to generate client secret. Raw error: \n" + (err instanceof Error ? err.message : String(err))); }
+  });
+}