@voidbase-cloud/voidbase 0.1.0

package/src/server/logs.ts

@@ -0,0 +1,144 @@
+// Logs (apis/logs.go + apis/middlewares.go logRequest): every API request writes a _logs row after the response,
+// app-level messages go through appLog, and the superuser API lists, filters, views, aggregates and truncates them.
+import type { Context, Hono, MiddlewareHandler } from "hono";
+import { env as voidEnv, defaultLogMinLevel } from "#platform/env";
+// the platform default for request logs, overridable per deployment (PocketBase levels: -4 debug, 0 info, 4 warn, 8 error)
+const envLogMinLevel = () => { const v = (voidEnv as Record<string, unknown>).VOIDBASE_LOG_MIN_LEVEL; const n = v === undefined || v === "" ? NaN : Number(v); return Number.isFinite(n) ? n : defaultLogMinLevel; };
+import type { Collection } from "./collections/model";
+import { all, one, run, stmt } from "./db";
+import { ApiError, badRequest, notFound } from "./errors";
+import { compileFilter, compileSort, FilterError } from "./filter/compile";
+import { FilterSyntaxError } from "./filter/lexer";
+import { nowString, randomId } from "./ids";
+import { loadSettings } from "./settings";
+import type { AppEnv } from "./types";
+import { requireSuperuser } from "./auth";
+
+export const LEVEL = { debug: -4, info: 0, warn: 4, error: 8 } as const;
+const cut = (s: string, max: number) => (s.length > max ? s.slice(0, max) + "..." : s);
+const sorted = (o: Record<string, unknown>) => Object.fromEntries(Object.entries(o).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+
+export async function appLog(db: D1Database, level: number, message: string, data: Record<string, unknown> = {}): Promise<void> {
+  const settings = await loadSettings(db);
+  if (settings.logs.maxDays === 0 || level < settings.logs.minLevel) return;
+  await run(db, "INSERT INTO `_logs` (id, created, data, message, level) VALUES (?, ?, ?, ?, ?)", [randomId(), nowString(), JSON.stringify(sorted(data)), message, level]);
+}
+
+const SKIP_PREFIXES = ["/api/logs", "/api/realtime"];
+
+// Records the request after the response is written (PocketBase logs in a goroutine; here waitUntil).
+export function requestLogger(): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    const started = Date.now();
+    let thrown: unknown = null;
+    try { await next(); } catch (err) { thrown = err; throw err; }
+    finally {
+      const path = new URL(c.req.url).pathname;
+      const skip = SKIP_PREFIXES.some((p) => path.startsWith(p)) && !thrown;
+      if (!skip) c.executionCtx.waitUntil(logRequest(c, started, thrown).catch((err) => console.error("voidbase: request log failed", err)));
+    }
+  };
+}
+
+async function logRequest(c: Context<AppEnv>, started: number, err: unknown): Promise<void> {
+  const settings = await loadSettings(c.env.DB);
+  if (settings.logs.maxDays === 0) return;
+  const url = new URL(c.req.url);
+  const requestUri = cut(url.pathname + url.search, 3000);
+  const method = cut(c.req.method.toUpperCase(), 50);
+  const data: Record<string, unknown> = { type: "request", execTime: Date.now() - started };
+  let status = c.res?.status ?? 0;
+  let failed = !!err;
+  if (err) {
+    if (err instanceof ApiError) { if (!status || status === 500) status = err.status; data.error = err.message; data.details = err.data ?? {}; }
+    else data.error = err instanceof Error ? err.message : String(err);
+  } else if (status >= 400 && c.res) {
+    // handlers (hook routes among them) may answer an API error directly instead of throwing it
+    failed = true;
+    try { const body = (await c.res.clone().json()) as { message?: string; data?: unknown }; data.error = body.message ?? ""; data.details = body.data ?? {}; } catch { data.error = `${status}`; }
+  }
+  Object.assign(data, { url: requestUri, method, status, referer: cut(c.req.header("Referer") ?? "", 2000), userAgent: cut(c.req.header("User-Agent") ?? "", 2000) });
+  const auth = c.get("auth");
+  data.auth = auth ? auth.collection.name : "";
+  if (auth && settings.logs.logAuthId) data.authId = String(auth.row.id);
+  if (settings.logs.logIP) {
+    data.userIP = c.req.header("CF-Connecting-IP") ?? c.req.header("X-Forwarded-For")?.split(",")[0]?.trim() ?? "127.0.0.1";
+    data.remoteIP = c.req.header("CF-Connecting-IP") ?? "127.0.0.1";
+  }
+  const level = failed ? LEVEL.error : LEVEL.info;
+  // Analytics Engine (binding LOGS_ANALYTICS, declared by the deploy): one data point per request, whatever the level
+  c.env.LOGS_ANALYTICS?.writeDataPoint({ blobs: [method, cut(url.pathname, 256), String(status), String(data.auth ?? ""), cut(String(data.error ?? ""), 256), failed ? "error" : "info"], doubles: [Number(data.execTime), status], indexes: [cut(url.pathname, 96)] });
+  if (level < Math.max(settings.logs.minLevel, envLogMinLevel())) return;
+  let message = method + " ";
+  try { message += decodeURIComponent(requestUri); } catch { message += requestUri; }
+  await run(c.env.DB, "INSERT INTO `_logs` (id, created, data, message, level) VALUES (?, ?, ?, ?, ?)", [randomId(), nowString(), JSON.stringify(sorted(data)), message, level]);
+}
+
+export async function deleteOldLogs(db: D1Database, maxDays: number): Promise<void> {
+  if (maxDays <= 0) return;
+  const before = nowString(new Date(Date.now() - maxDays * 86400_000));
+  await run(db, "DELETE FROM `_logs` WHERE created <= ?", [before]);
+}
+
+// the filter/sort compiler works on a collection shape; logs get a pseudo collection with their columns
+const LOGS_COLLECTION: Collection = {
+  id: "_logs", name: "_logs", type: "base", system: true, listRule: null, viewRule: null, createRule: null, updateRule: null, deleteRule: null, indexes: [], options: {}, created: "", updated: "",
+  fields: [
+    { id: "text_id", name: "id", type: "text", system: true, required: true, hidden: false, presentable: false },
+    { id: "date_created", name: "created", type: "date", system: true, required: false, hidden: false, presentable: false },
+    { id: "text_message", name: "message", type: "text", system: true, required: false, hidden: false, presentable: false },
+    { id: "number_level", name: "level", type: "number", system: true, required: false, hidden: false, presentable: false },
+    { id: "json_data", name: "data", type: "json", system: true, required: false, hidden: false, presentable: false },
+  ] as never,
+} as Collection;
+const toJSON = (r: Record<string, unknown>) => ({ id: r.id, created: r.created, data: typeof r.data === "string" ? JSON.parse(r.data) : r.data, message: r.message, level: r.level });
+
+export function mountLogsApi(app: Hono<AppEnv>) {
+  const sub = (c: Context<AppEnv>) => requireSuperuser(c);
+  app.get("/api/logs", async (c) => {
+    sub(c);
+    const page = Math.max(1, Number(c.req.query("page") ?? 1) || 1);
+    const perPage = Math.min(1000, Math.max(1, Number(c.req.query("perPage") ?? 30) || 30));
+    let where = "1=1", params: unknown[] = [];
+    try {
+      const filter = c.req.query("filter") ?? "";
+      if (filter.trim()) { const f = compileFilter(filter, { base: LOGS_COLLECTION, baseTable: "_logs", collections: new Map(), request: { auth: null, method: "GET", query: {}, headers: {}, body: {}, context: "default" }, allowHiddenFields: true }); where = f.where; params = f.params; }
+    } catch (err) { if (err instanceof FilterError || err instanceof FilterSyntaxError) throw badRequest("Invalid filter format."); throw err; }
+    const sortParam = (c.req.query("sort") ?? "").trim();
+    let order = "`_logs`.rowid DESC";
+    if (sortParam) {
+      order = sortParam.split(",").map((s) => s.trim()).filter(Boolean).map((s) => {
+        const desc = s.startsWith("-"); const name = s.replace(/^[+-]/, "");
+        if (name === "rowid" || name === "@rowid") return `\`_logs\`.rowid ${desc ? "DESC" : "ASC"}`; // the panel sorts by -@rowid
+        if (name.startsWith("data.")) return `json_extract(\`_logs\`.data, '$.${name.slice(5).replace(/'/g, "")}') ${desc ? "DESC" : "ASC"}`;
+        if (!["id", "created", "message", "level"].includes(name)) throw badRequest("Invalid sort format.");
+        return `\`_logs\`.\`${name}\` ${desc ? "DESC" : "ASC"}`;
+      }).join(", ");
+    }
+    void compileSort;
+    const total = (await one<{ n: number }>(c.env.DB, `SELECT COUNT(*) AS n FROM \`_logs\` WHERE ${where}`, params))?.n ?? 0;
+    const rows = await all<Record<string, unknown>>(c.env.DB, `SELECT * FROM \`_logs\` WHERE ${where} ORDER BY ${order} LIMIT ? OFFSET ?`, [...params, perPage, (page - 1) * perPage]);
+    return c.json({ page, perPage, totalItems: total, totalPages: Math.ceil(total / perPage), items: rows.map(toJSON) });
+  });
+  app.get("/api/logs/stats", async (c) => {
+    sub(c);
+    let where = "1=1", params: unknown[] = [];
+    try {
+      const filter = c.req.query("filter") ?? "";
+      if (filter.trim()) { const f = compileFilter(filter, { base: LOGS_COLLECTION, baseTable: "_logs", collections: new Map(), request: { auth: null, method: "GET", query: {}, headers: {}, body: {}, context: "default" }, allowHiddenFields: true }); where = f.where; params = f.params; }
+    } catch (err) { if (err instanceof FilterError || err instanceof FilterSyntaxError) throw badRequest("Invalid filter format."); throw err; }
+    const rows = await all<{ total: number; date: string }>(c.env.DB, `SELECT COUNT(id) AS total, strftime('%Y-%m-%d %H:00:00', created) AS date FROM \`_logs\` WHERE ${where} GROUP BY date`, params);
+    return c.json(rows.map((r) => ({ date: r.date.replace(" ", " ") + ".000Z", total: r.total })));
+  });
+  app.get("/api/logs/:id", async (c) => {
+    sub(c);
+    const row = await one<Record<string, unknown>>(c.env.DB, "SELECT * FROM `_logs` WHERE id = ? LIMIT 1", [c.req.param("id") ?? ""]);
+    if (!row) throw notFound();
+    return c.json(toJSON(row));
+  });
+  app.delete("/api/logs", async (c) => {
+    sub(c);
+    await c.env.DB.batch([stmt(c.env.DB, "DELETE FROM `_logs`", [])]);
+    return c.body(null, 204);
+  });
+}

package/src/server/mail/index.ts

@@ -0,0 +1,99 @@
+// Outbound mail: PocketBase's record emails (verification, password reset, email change, OTP, auth alert) and the
+// generic mailer used by $app.newMailClient(). Delivery goes through the SMTP settings when enabled; otherwise the
+// message is logged (PocketBase would hand it to sendmail, which a Worker does not have). System emails leave through
+// the jobs queue when the deploy has one (src/server/jobs.ts), so the request never waits on SMTP.
+import type { Collection } from "../collections/model";
+import { signJWT } from "../jwt";
+import { env as voidEnv } from "#platform/env";
+import { loadSettings } from "../settings";
+import type { Row } from "../types";
+import { trigger } from "../hooks/runtime";
+import { HookRecord } from "../hooks/record";
+import { buildMime, htmlToText, type MailMessage } from "./message";
+import { sendSMTP } from "./smtp";
+import { dispatch, registerJobHandler } from "../jobs";
+import type { Bindings } from "../types";
+import { collectionTemplate, PLACEHOLDER, resolveEmailTemplate, type EmailTemplate } from "./templates";
+
+export type { MailMessage } from "./message";
+
+// Alternative transport: an HTTP mail API (Resend-compatible request shape). Configured by environment, not by the
+// PocketBase settings, so the settings JSON stays wire-identical.
+const httpMail = { get url() { return String((voidEnv as Record<string, unknown>).VOIDBASE_MAIL_HTTP_URL ?? "").trim(); }, get key() { return String((voidEnv as Record<string, unknown>).VOIDBASE_MAIL_HTTP_KEY ?? ""); } };
+const addr = (a: { name?: string; address: string }) => (a.name ? `${a.name} <${a.address}>` : a.address);
+async function sendHTTP(m: MailMessage, text: string): Promise<void> {
+  const payload: Record<string, unknown> = { from: addr(m.from), to: m.to.map(addr), subject: m.subject, html: m.html, text };
+  if (m.cc?.length) payload.cc = m.cc.map(addr);
+  if (m.bcc?.length) payload.bcc = m.bcc.map(addr);
+  if (m.headers && Object.keys(m.headers).length) payload.headers = m.headers;
+  const res = await fetch(httpMail.url, { method: "POST", headers: { "content-type": "application/json", ...(httpMail.key ? { authorization: `Bearer ${httpMail.key}` } : {}) }, body: JSON.stringify(payload) });
+  if (!res.ok) throw new Error(`mail provider ${new URL(httpMail.url).host} answered ${res.status}: ${(await res.text()).slice(0, 200)}`);
+}
+
+export interface SendOptions { inline?: boolean } // inline: deliver now and surface transport errors to the caller
+
+// The transport step: an HTTP mail API when configured, else the SMTP settings, else a log line. On Cloudflare it
+// runs from the jobs queue (retries, no request time spent on SMTP); inline for the panel's test email and hooks.
+export async function deliverMail(env: Bindings, m: MailMessage, text: string): Promise<void> {
+  if (httpMail.url) { await sendHTTP(m, text); return; }
+  const settings = await loadSettings(env.DB);
+  if (!settings.smtp.enabled) {
+    console.log(`voidbase: mail not delivered (SMTP disabled): "${m.subject}" -> ${m.to.map((t) => t.address).join(", ")}`);
+    return;
+  }
+  const mime = buildMime(m, text);
+  await sendSMTP(settings.smtp, { from: mime.from, to: mime.rcpts, data: mime.data });
+}
+registerJobHandler("mail", (env, job) => deliverMail(env, job.message, job.text));
+
+export async function sendMail(db: D1Database, message: MailMessage, opts: SendOptions = {}): Promise<void> {
+  const ev = { app: undefined as unknown, message, mailer: null as unknown, next: async () => undefined as unknown };
+  // hooks (onMailerSend) run here, in the request, on the message that is then queued or delivered
+  await trigger("onMailerSend", ev, null, async () => {
+    const m = ev.message;
+    const text = m.text || htmlToText(m.html);
+    await dispatch({ type: "mail", message: m, text }, { env: { DB: db } as Bindings, inline: opts.inline });
+  });
+}
+
+const tokenOption = (c: Collection, key: string) => ((c.options as Record<string, unknown>)[key] ?? {}) as { secret?: string; duration?: number };
+
+async function recordToken(c: Collection, row: Row, type: "verification" | "passwordReset" | "emailChange", extra: Record<string, unknown> = {}): Promise<string> {
+  const optKey = type === "verification" ? "verificationToken" : type === "passwordReset" ? "passwordResetToken" : "emailChangeToken";
+  const opt = tokenOption(c, optKey);
+  const key = String(row.tokenKey ?? "") + String(opt.secret ?? "");
+  if (!key) throw new Error("missing or invalid signing key");
+  return signJWT({ type, id: String(row.id), collectionId: c.id, email: String(row.email ?? ""), ...extra }, key, Number(opt.duration ?? 0) || 604800);
+}
+
+async function recordMail(db: D1Database, c: Collection, row: Row, template: EmailTemplate, placeholders: Record<string, string>, to: string, hook: string, meta: Record<string, unknown>, opts: SendOptions = {}): Promise<MailMessage> {
+  const settings = await loadSettings(db);
+  const { subject, body } = resolveEmailTemplate(settings.meta, c, row, template, placeholders);
+  const message: MailMessage = { from: { name: settings.meta.senderName, address: settings.meta.senderAddress }, to: [{ address: to }], subject, html: body };
+  const ev = { app: undefined as unknown, message, record: HookRecord.fromRow(c, row), meta, mailer: null as unknown, next: async () => undefined as unknown };
+  await trigger(hook, ev, c.name, () => sendMail(db, ev.message, opts));
+  return ev.message;
+}
+
+export async function sendRecordVerification(db: D1Database, c: Collection, row: Row, opts: SendOptions = {}): Promise<{ token: string; message: MailMessage }> {
+  const token = await recordToken(c, row, "verification");
+  const message = await recordMail(db, c, row, collectionTemplate(c, "verificationTemplate"), { [PLACEHOLDER.token]: token }, String(row.email), "onMailerRecordVerificationSend", { token }, opts);
+  return { token, message };
+}
+export async function sendRecordPasswordReset(db: D1Database, c: Collection, row: Row, opts: SendOptions = {}): Promise<{ token: string; message: MailMessage }> {
+  const token = await recordToken(c, row, "passwordReset");
+  const message = await recordMail(db, c, row, collectionTemplate(c, "resetPasswordTemplate"), { [PLACEHOLDER.token]: token }, String(row.email), "onMailerRecordPasswordResetSend", { token }, opts);
+  return { token, message };
+}
+export async function sendRecordChangeEmail(db: D1Database, c: Collection, row: Row, newEmail: string, opts: SendOptions = {}): Promise<{ token: string; message: MailMessage }> {
+  const token = await recordToken(c, row, "emailChange", { newEmail });
+  const message = await recordMail(db, c, row, collectionTemplate(c, "confirmEmailChangeTemplate"), { [PLACEHOLDER.token]: token }, newEmail, "onMailerRecordEmailChangeSend", { token, newEmail }, opts);
+  return { token, message };
+}
+export async function sendRecordOTP(db: D1Database, c: Collection, row: Row, otpId: string, pass: string, opts: SendOptions = {}): Promise<MailMessage> {
+  return recordMail(db, c, row, collectionTemplate(c, "otp"), { [PLACEHOLDER.otpId]: otpId, [PLACEHOLDER.otp]: pass }, String(row.email), "onMailerRecordOTPSend", { otpId, password: pass }, opts);
+}
+export async function sendRecordAuthAlert(db: D1Database, c: Collection, row: Row, info: string, opts: SendOptions = {}): Promise<MailMessage> {
+  const escaped = info.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&#34;").replace(/'/g, "&#39;");
+  return recordMail(db, c, row, collectionTemplate(c, "authAlert"), { [PLACEHOLDER.alertInfo]: escaped }, String(row.email), "onMailerRecordAuthAlertSend", { info: escaped }, opts);
+}

package/src/server/mail/message.ts

@@ -0,0 +1,43 @@
+// RFC 5322 message construction (what mailyak does for PocketBase): multipart/alternative with a text and an
+// HTML part, encoded words for non-ASCII headers, Message-ID from the sender's domain when none is given.
+export interface Address { address: string; name?: string }
+export interface MailMessage { from: Address; to: Address[]; cc?: Address[]; bcc?: Address[]; subject: string; html: string; text?: string; headers?: Record<string, string> }
+
+const isAscii = (s: string) => /^[\x20-\x7e]*$/.test(s);
+const encodeWord = (s: string) => (isAscii(s) ? s : `=?UTF-8?B?${btoa(String.fromCharCode(...new TextEncoder().encode(s)))}?=`);
+// net/mail Address.String(): the display name is quoted only when it contains something other than atext and spaces
+const needsQuote = (s: string) => !/^[A-Za-z0-9!#$%&'*+/=?^_`{|}~ .-]*$/.test(s);
+const quote = (s: string) => `"${s.replace(/["\\]/g, "\\$&")}"`;
+export const formatAddress = (a: Address) => (a.name ? `${!isAscii(a.name) ? encodeWord(a.name) : needsQuote(a.name) ? quote(a.name) : a.name} <${a.address}>` : a.address);
+const base64Lines = (s: string) => btoa(String.fromCharCode(...new TextEncoder().encode(s))).replace(/(.{76})/g, "$1\r\n");
+export const randomToken = (n: number) => { const chars = "abcdefghijklmnopqrstuvwxyz0123456789"; let out = ""; const bytes = crypto.getRandomValues(new Uint8Array(n)); for (const b of bytes) out += chars[b % chars.length]; return out; };
+
+export function buildMime(m: MailMessage, text: string): { from: string; rcpts: string[]; data: string } {
+  const boundary = `--pb-${randomToken(24)}`;
+  const headers: [string, string][] = [
+    ["From", formatAddress(m.from)],
+    ["To", m.to.map(formatAddress).join(", ")],
+  ];
+  if (m.cc?.length) headers.push(["Cc", m.cc.map(formatAddress).join(", ")]);
+  headers.push(["Subject", encodeWord(m.subject)], ["Date", new Date().toUTCString().replace("GMT", "+0000")], ["MIME-Version", "1.0"]);
+  const extra = Object.entries(m.headers ?? {});
+  if (!extra.some(([k]) => k.toLowerCase() === "message-id")) {
+    const domain = m.from.address.split("@")[1];
+    if (domain) headers.push(["Message-ID", `<${randomToken(15)}@${domain}>`]);
+  }
+  for (const [k, v] of extra) headers.push([k, v]);
+  headers.push(["Content-Type", `multipart/alternative; boundary="${boundary}"`]);
+  const part = (type: string, body: string) => `--${boundary}\r\nContent-Type: ${type}; charset=UTF-8\r\nContent-Transfer-Encoding: base64\r\n\r\n${base64Lines(body)}\r\n`;
+  const data = headers.map(([k, v]) => `${k}: ${v}`).join("\r\n") + "\r\n\r\n" + part("text/plain", text) + part("text/html", m.html) + `--${boundary}--\r\n`;
+  return { from: m.from.address, rcpts: [...m.to, ...(m.cc ?? []), ...(m.bcc ?? [])].map((a) => a.address), data };
+}
+
+// tools/mailer/html2text.go, simplified: block tags and <br> become CRLF, inline tags vanish, links keep their text
+export function htmlToText(html: string): string {
+  let s = html.replace(/<head[\s\S]*?<\/head>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<script[\s\S]*?<\/script>/gi, "");
+  s = s.replace(/<br\s*\/?>/gi, "\r\n");
+  s = s.replace(/<\/(p|div|h[1-6]|li|tr|table|blockquote|pre|ul|ol|section|article|header|footer)>/gi, "\r\n");
+  s = s.replace(/<[^>]+>/g, "");
+  s = s.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+  return s.split(/\r?\n/).map((l) => l.replace(/\s+/g, " ").trim()).filter((l, i, arr) => l !== "" || (i > 0 && arr[i - 1] !== "")).join("\r\n").trim();
+}

package/src/server/mail/smtp.ts

@@ -0,0 +1,82 @@
+// SMTP client on Cloudflare TCP sockets (tools/mailer/smtp.go semantics): implicit TLS when settings.smtp.tls,
+// otherwise opportunistic STARTTLS when the server offers it; AUTH PLAIN (default) or LOGIN; EHLO with localName.
+import { connect, type Socket } from "#platform/sockets";
+
+export interface SMTPConfig { host: string; port: number; username: string; password: string; authMethod: string; tls: boolean; localName: string }
+export interface Envelope { from: string; to: string[]; data: string }
+
+const TIMEOUT_MS = 30_000;
+
+class Conn {
+  private buf = "";
+  private reader: ReadableStreamDefaultReader<Uint8Array>;
+  private writer: WritableStreamDefaultWriter<Uint8Array>;
+  private dec = new TextDecoder(); private enc = new TextEncoder();
+  constructor(private socket: Socket) { this.reader = socket.readable.getReader(); this.writer = socket.writable.getWriter(); }
+  async startTls(): Promise<Conn> {
+    this.reader.releaseLock(); this.writer.releaseLock();
+    return new Conn(this.socket.startTls());
+  }
+  // one SMTP reply, possibly multi-line ("250-..." continuation lines)
+  async reply(): Promise<{ code: number; lines: string[] }> {
+    const lines: string[] = [];
+    for (;;) {
+      const line = await this.line();
+      lines.push(line.slice(4));
+      if (line.length >= 4 && line[3] === " ") return { code: Number(line.slice(0, 3)), lines };
+      if (line.length < 4) throw new Error(`smtp: malformed reply ${JSON.stringify(line)}`);
+    }
+  }
+  private async line(): Promise<string> {
+    for (;;) {
+      const i = this.buf.indexOf("\r\n");
+      if (i >= 0) { const l = this.buf.slice(0, i); this.buf = this.buf.slice(i + 2); return l; }
+      const { value, done } = await this.reader.read();
+      if (done) throw new Error("smtp: connection closed");
+      this.buf += this.dec.decode(value, { stream: true });
+    }
+  }
+  async cmd(text: string, expect: number[]): Promise<{ code: number; lines: string[] }> {
+    await this.writer.write(this.enc.encode(text + "\r\n"));
+    const r = await this.reply();
+    if (!expect.includes(r.code)) throw new Error(`smtp: ${text.split(" ")[0]} failed: ${r.code} ${r.lines.join(" ")}`);
+    return r;
+  }
+  async raw(text: string) { await this.writer.write(this.enc.encode(text)); }
+  async close() { try { await this.writer.close(); } catch { /* closed */ } try { this.socket.close(); } catch { /* closed */ } }
+}
+
+export async function sendSMTP(cfg: SMTPConfig, env: Envelope): Promise<void> {
+  const run = async () => {
+    const socket = connect({ hostname: cfg.host, port: cfg.port }, { secureTransport: cfg.tls ? "on" : "starttls", allowHalfOpen: false });
+    let conn = new Conn(socket);
+    const name = cfg.localName || "localhost";
+    try {
+      const greeting = await conn.reply();
+      if (greeting.code !== 220) throw new Error(`smtp: unexpected greeting ${greeting.code}`);
+      let ehlo = await conn.cmd(`EHLO ${name}`, [250]);
+      if (!cfg.tls && ehlo.lines.some((l) => l.toUpperCase().startsWith("STARTTLS"))) {
+        await conn.cmd("STARTTLS", [220]);
+        conn = await conn.startTls();
+        ehlo = await conn.cmd(`EHLO ${name}`, [250]);
+      }
+      if (cfg.username || cfg.password) {
+        if (cfg.authMethod === "LOGIN") {
+          await conn.cmd("AUTH LOGIN", [334]);
+          await conn.cmd(btoa(cfg.username), [334]);
+          await conn.cmd(btoa(cfg.password), [235]);
+        } else {
+          await conn.cmd(`AUTH PLAIN ${btoa(`\0${cfg.username}\0${cfg.password}`)}`, [235]);
+        }
+      }
+      await conn.cmd(`MAIL FROM:<${env.from}>`, [250]);
+      for (const rcpt of env.to) await conn.cmd(`RCPT TO:<${rcpt}>`, [250, 251]);
+      await conn.cmd("DATA", [354]);
+      const stuffed = env.data.replace(/\r?\n/g, "\r\n").replace(/(^|\r\n)\./g, "$1..");
+      await conn.raw(stuffed.endsWith("\r\n") ? stuffed : stuffed + "\r\n");
+      await conn.cmd(".", [250]);
+      try { await conn.cmd("QUIT", [221]); } catch { /* some servers close right away */ }
+    } finally { await conn.close(); }
+  };
+  await Promise.race([run(), new Promise<never>((_, rej) => setTimeout(() => rej(new Error("smtp: timeout")), TIMEOUT_MS))]);
+}

package/src/server/mail/templates.ts

@@ -0,0 +1,168 @@
+// PocketBase's email templates (core/collection_model_auth_templates.go + mails/templates): the per-collection
+// template resolves {APP_NAME}, {APP_URL}, {TOKEN}, {OTP}, {OTP_ID}, {ALERT_INFO} and {RECORD:field}, and the
+// result is wrapped in the shared HTML layout.
+import type { Collection } from "../collections/model";
+import type { Row } from "../types";
+import { fromColumn } from "../records/values";
+import type { Field } from "../collections/fields";
+
+export interface EmailTemplate { subject: string; body: string }
+export const PLACEHOLDER = { appName: "{APP_NAME}", appURL: "{APP_URL}", token: "{TOKEN}", otp: "{OTP}", otpId: "{OTP_ID}", alertInfo: "{ALERT_INFO}" };
+
+export const DEFAULT_TEMPLATES: Record<"verification" | "resetPassword" | "confirmEmailChange" | "otp" | "authAlert", EmailTemplate> = {
+  verification: { subject: "Verify your {APP_NAME} email", body: `<p>Hello,</p>
+<p>Thank you for joining us at {APP_NAME}.</p>
+<p>Click on the button below to verify your email address.</p>
+<p>
+  <a class="btn" href="{APP_URL}/_/#/auth/confirm-verification/{TOKEN}" target="_blank" rel="noopener">Verify</a>
+</p>
+<p><i>If you didn't recently register, please ignore this email.</i></p>
+<p>
+  Thanks,<br/>
+  {APP_NAME} team
+</p>` },
+  resetPassword: { subject: "Reset your {APP_NAME} password", body: `<p>Hello,</p>
+<p>Click on the button below to reset your password.</p>
+<p>
+  <a class="btn" href="{APP_URL}/_/#/auth/confirm-password-reset/{TOKEN}" target="_blank" rel="noopener">Reset password</a>
+</p>
+<p><i>If you didn't ask to reset your password, please ignore this email.</i></p>
+<p>
+  Thanks,<br/>
+  {APP_NAME} team
+</p>` },
+  confirmEmailChange: { subject: "Confirm your {APP_NAME} new email address", body: `<p>Hello,</p>
+<p>Click on the button below to confirm your new email address.</p>
+<p>
+  <a class="btn" href="{APP_URL}/_/#/auth/confirm-email-change/{TOKEN}" target="_blank" rel="noopener">Confirm new email</a>
+</p>
+<p><i>If you didn't ask to change your email address, please ignore this email.</i></p>
+<p>
+  Thanks,<br/>
+  {APP_NAME} team
+</p>` },
+  otp: { subject: "OTP for {APP_NAME}", body: `<p>Hello,</p>
+<p>Your one-time password is: <strong>{OTP}</strong></p>
+<p><i>If you didn't ask for the one-time password, you can ignore this email.</i></p>
+<p>
+  Thanks,<br/>
+  {APP_NAME} team
+</p>` },
+  authAlert: { subject: "Login from a new location", body: `<p>Hello,</p>
+<p>We noticed a login to your {APP_NAME} account from a new location:</p>
+<p><em>{ALERT_INFO}</em></p>
+<p><strong>If this wasn't you, you should immediately change your {APP_NAME} account password to revoke access from all other locations.</strong></p>
+<p>If this was you, you may disregard this email.</p>
+<p>
+  Thanks,<br/>
+  {APP_NAME} team
+</p>` },
+};
+
+export const LAYOUT = `
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <style>
+        body, html {
+            padding: 0;
+            margin: 0;
+            border: 0;
+            color: #16161a;
+            background: #fff;
+            font-size: 14px;
+            line-height: 20px;
+            font-weight: normal;
+            font-family: Source Sans Pro, sans-serif, emoji;
+        }
+        body {
+            padding: 20px 30px;
+        }
+        strong {
+            font-weight: bold;
+        }
+        em, i {
+            font-style: italic;
+        }
+        p {
+            display: block;
+            margin: 10px 0;
+            font-family: inherit;
+        }
+        small {
+            font-size: 12px;
+            line-height: 16px;
+        }
+        hr {
+            display: block;
+            height: 1px;
+            border: 0;
+            width: 100%;
+            background: #e1e6ea;
+            margin: 10px 0;
+        }
+        a {
+            color: inherit;
+        }
+        .hidden {
+            display: none !important;
+        }
+        .btn {
+            display: inline-block;
+            vertical-align: top;
+            border: 0;
+            cursor: pointer;
+            color: #fff !important;
+            background: #16161a !important;
+            text-decoration: none !important;
+            line-height: 40px;
+            width: auto;
+            min-width: 150px;
+            text-align: center;
+            padding: 0 20px;
+            margin: 5px 0;
+            font-family: Source Sans Pro, sans-serif, emoji;;
+            font-size: 14px;
+            font-weight: bold;
+            border-radius: 6px;
+            box-sizing: border-box;
+        }
+    </style>
+</head>
+<body>
+    {{CONTENT}}
+</body>
+</html>
+`;
+
+const escapeHtml = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&#34;").replace(/'/g, "&#39;");
+const NONESCAPE_TYPES = ["editor"];
+
+export function collectionTemplate(c: Collection, key: "verificationTemplate" | "resetPasswordTemplate" | "confirmEmailChangeTemplate" | "otp" | "authAlert"): EmailTemplate {
+  const o = c.options as Record<string, unknown>;
+  if (key === "otp") { const t = (o.otp as { emailTemplate?: EmailTemplate } | undefined)?.emailTemplate; return t?.subject ? t : DEFAULT_TEMPLATES.otp; }
+  if (key === "authAlert") { const t = (o.authAlert as { emailTemplate?: EmailTemplate } | undefined)?.emailTemplate; return t?.subject ? t : DEFAULT_TEMPLATES.authAlert; }
+  const t = o[key] as EmailTemplate | undefined;
+  if (t?.subject) return t;
+  return key === "verificationTemplate" ? DEFAULT_TEMPLATES.verification : key === "resetPasswordTemplate" ? DEFAULT_TEMPLATES.resetPassword : DEFAULT_TEMPLATES.confirmEmailChange;
+}
+
+// mails/record.go resolveEmailTemplate
+export function resolveEmailTemplate(meta: { appName: string; appURL: string }, c: Collection, row: Row, template: EmailTemplate, placeholders: Record<string, string>): { subject: string; body: string } {
+  const all: Record<string, string> = { ...placeholders };
+  if (!(PLACEHOLDER.appName in all)) all[PLACEHOLDER.appName] = meta.appName;
+  if (!(PLACEHOLDER.appURL in all)) all[PLACEHOLDER.appURL] = meta.appURL;
+  for (const f of c.fields as Field[]) {
+    if (f.hidden) continue;
+    const key = `{RECORD:${f.name}}`;
+    if (key in all) continue;
+    const v = fromColumn(f, row[f.name]);
+    const str = v == null ? "" : Array.isArray(v) ? String(v[0] ?? "") : typeof v === "object" ? JSON.stringify(v) : String(v);
+    all[key] = NONESCAPE_TYPES.includes(f.type) ? str : escapeHtml(str);
+  }
+  let subject = template.subject, body = template.body;
+  for (const [k, v] of Object.entries(all)) { subject = subject.split(k).join(v); body = body.split(k).join(v); }
+  return { subject, body: LAYOUT.replace("{{CONTENT}}", body) };
+}