getbotons 0.0.0-stage → 0.1.0

package/payload/server/src/health.ts

@@ -0,0 +1,117 @@
+import type { BrainProblem, DatabaseProblem, Health, HealthCheck, HealthDetails, OperationsBrain, OperationsHealth, ProviderInfo } from '../../shared/types.ts';
+import { buildSha, versionNumber } from '../../shared/util.ts';
+import type { Config } from './config.ts';
+import type { Engine } from './engine.ts';
+import type { ProviderRegistry } from './providers/index.ts';
+import type { Store } from './store.ts';
+
+export const SCHEDULER_STALE_INTERVALS = 3;
+
+/** SQLite's primary result codes (node:sqlite's `errcode`, extended codes included), as the owner's fixed words. */
+const SQLITE_PROBLEMS: Record<number, DatabaseProblem> = { 5: 'busy', 6: 'busy', 8: 'read-only', 10: 'io-error', 11: 'corrupt', 13: 'disk-full', 14: 'cannot-open', 26: 'corrupt' };
+
+/** What a failed database check says about where to look, as a fixed word. */
+export function databaseProblem(err: unknown): DatabaseProblem {
+  const code = (err as { errcode?: unknown })?.errcode;
+  return (typeof code === 'number' && SQLITE_PROBLEMS[code & 0xff]) || 'other';
+}
+
+function brainProblem(p: ProviderInfo): BrainProblem | null {
+  if (p.available) return null;
+  if (!p.installed) return 'not-installed';
+  if (p.loggedIn === false) return 'signed-out';
+  return 'unavailable';
+}
+
+/** A brain for the owner's view: its states and times, a version number only if one is found, and none of the CLI's text. */
+export function ownerBrain(p: ProviderInfo, usageLimitUntil: string | null = null): OperationsBrain {
+  return {
+    id: p.id,
+    label: p.label,
+    available: p.available,
+    installed: p.installed,
+    loggedIn: p.loggedIn,
+    version: versionNumber(p.version),
+    problem: brainProblem(p),
+    lastSuccessAt: p.lastSuccessAt,
+    lastErrorAt: p.lastError?.at ?? null,
+    usageLimitUntil,
+    readiness: p.readiness,
+  };
+}
+
+/** Whether this server can do its job, not just answer. */
+export class HealthMonitor {
+  #cfg: Config;
+  #store: Store;
+  #engine: Engine;
+  #providers: ProviderRegistry;
+  #startedAt = Date.now();
+  #lastTickAt: number | null = null;
+
+  constructor(deps: { cfg: Config; store: Store; engine: Engine; providers: ProviderRegistry }) {
+    this.#cfg = deps.cfg;
+    this.#store = deps.store;
+    this.#engine = deps.engine;
+    this.#providers = deps.providers;
+  }
+
+  schedulerTicked(at = Date.now()): void {
+    this.#lastTickAt = at;
+  }
+
+  async check(): Promise<Required<Health>> {
+    return (await this.#check()).health;
+  }
+
+  /** The same checks for Settings → Health: fixed words for what failed, never error text, paths or CLI output. */
+  async owner(usageLimitUntil: (providerId: string) => string | null = () => null): Promise<OperationsHealth> {
+    const { health, databaseProblem: problem } = await this.#check();
+    const { details } = health;
+    return {
+      ok: health.ok,
+      build: buildSha(health.build),
+      failing: health.failing,
+      details: {
+        database: { ok: details.database.ok, problem: details.database.ok ? null : problem },
+        scheduler: details.scheduler,
+        providers: details.providers.map((p) => ownerBrain(p, usageLimitUntil(p.id))),
+        draining: details.draining,
+      },
+    };
+  }
+
+  async #check(): Promise<{ health: Required<Health>; databaseProblem: DatabaseProblem | null }> {
+    const now = Date.now();
+    const { problem, ...database } = this.#database();
+    const intervalMs = this.#cfg.schedulerIntervalMs;
+    const scheduler = {
+      ok: now - (this.#lastTickAt ?? this.#startedAt) <= SCHEDULER_STALE_INTERVALS * intervalMs,
+      lastTickAt: this.#lastTickAt === null ? null : new Date(this.#lastTickAt).toISOString(),
+      intervalMs,
+    };
+    let providers: ProviderInfo[] = [];
+    let providersOk = false;
+    try {
+      providers = await this.#providers.infos();
+      providersOk = providers.some((p) => p.available);
+    } catch {}
+    const draining = this.#engine.draining;
+    const failing: HealthCheck[] = [];
+    if (!database.ok) failing.push('database');
+    if (!scheduler.ok) failing.push('scheduler');
+    if (!providersOk) failing.push('providers');
+    if (draining) failing.push('draining');
+    const details: HealthDetails = { database, scheduler, providers, draining };
+    return { health: { ok: failing.length === 0, build: this.#cfg.build, failing, details }, databaseProblem: problem };
+  }
+
+  #database(): HealthDetails['database'] & { problem: DatabaseProblem | null } {
+    try {
+      this.#store.db.prepare('select count(*) as n from bots').get();
+      return { ok: true, error: null, problem: null };
+    } catch (err) {
+      return { ok: false, error: (err as Error).message, problem: databaseProblem(err) };
+    }
+  }
+}

package/payload/server/src/held-dir.ts

@@ -0,0 +1,96 @@
+import { closeSync, constants, mkdirSync, openSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/*
+ * Folders held open, so a path under one is looked up from the folder itself, not again from the root. Server code
+ * that reads or writes a Workspace Boton's files runs outside its sandbox, while the Boton can rename and relink anything
+ * in its workspace: checking a path and then using it again would follow a folder swapped for a link in between.
+ * Linux names an open folder's entries as /proc/self/fd/<fd>/<name>, so each step opens one name in a folder already
+ * open, never through a link. Imports Node builtins only (the `botons` CLI loads it).
+ */
+
+/**
+ * Whether this system can look up a name in an open folder (Linux's /proc/self/fd). Without it nothing here works:
+ * a folder looked up again by its path is what a swap between two steps redirects, so there is no fallback to that.
+ */
+export let heldLookups: boolean = (() => {
+  try {
+    return process.platform === 'linux' && statSync('/proc/self/fd').isDirectory();
+  } catch {
+    return false;
+  }
+})();
+
+/** Tests only (set in code, never from a setting): as on a system without lookups in an open folder. */
+export function useHeldLookups(on: boolean): void {
+  heldLookups = on;
+}
+
+export class NoHeldLookups extends Error {
+  constructor() {
+    super('this system cannot look up a name in an open folder (Linux /proc/self/fd), so Botons does not touch files a Boton could swap meanwhile');
+  }
+}
+
+export interface HeldDir {
+  fd: number;
+  /** Where it was when opened; only for messages. */
+  path: string;
+}
+
+/** The path that names the open folder `dir` itself. */
+export function heldPath(dir: HeldDir): string {
+  if (!heldLookups) throw new NoHeldLookups();
+  return `/proc/self/fd/${dir.fd}`;
+}
+
+export class LinkInTheWay extends Error {}
+
+const DIR_FLAGS = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+
+/** The path that names `name` in the open folder `dir`. */
+export function under(dir: HeldDir, name: string): string {
+  if (!name || name === '.' || name === '..' || name.includes('/') || name.includes('\0')) throw new Error(`not a single name: ${name}`);
+  return `${heldPath(dir)}/${name}`;
+}
+
+/** Opens the folder at `path` (links followed: the caller trusts it, as the server's own setting). */
+export function holdDir(path: string): HeldDir {
+  return { fd: openSync(path, constants.O_RDONLY | constants.O_DIRECTORY), path };
+}
+
+/**
+ * Opens the folder `parts` beneath `root`, one name at a time, refusing a link anywhere on the way (LinkInTheWay). With
+ * `create`, missing folders are made. The caller closes what it returns unless it is `root` itself (no `parts`).
+ */
+export function holdBeneath(root: HeldDir, parts: string[], create = false): HeldDir {
+  let cur = root;
+  try {
+    for (const name of parts) {
+      const at = under(cur, name);
+      let fd: number;
+      try {
+        fd = openSync(at, DIR_FLAGS);
+      } catch (e) {
+        const code = (e as NodeJS.ErrnoException).code;
+        if (code === 'ENOENT' && create) {
+          try {
+            mkdirSync(at);
+          } catch (m) {
+            if ((m as NodeJS.ErrnoException).code !== 'EEXIST') throw m;
+          }
+          fd = openSync(at, DIR_FLAGS);
+        } else throw e;
+      }
+      if (cur !== root) closeSync(cur.fd);
+      cur = { fd, path: join(cur.path, name) };
+    }
+    return cur;
+  } catch (e) {
+    if (cur !== root) closeSync(cur.fd);
+    const code = (e as NodeJS.ErrnoException).code;
+    // O_NOFOLLOW on a link: ELOOP; O_DIRECTORY on a link it didn't follow, or on a file: ENOTDIR.
+    if (code === 'ELOOP' || code === 'ENOTDIR') throw new LinkInTheWay(`${join(root.path, ...parts)} is not a folder of its own: a link or file is in the way`);
+    throw e;
+  }
+}

package/payload/server/src/hooks.ts

@@ -0,0 +1,141 @@
+import type { Routine, RoutineRun, WebhookRunStatus } from '../../shared/types.ts';
+import { earlierName } from '../../shared/legacy-names.mjs';
+import type { Config } from './config.ts';
+import type { Engine } from './engine.ts';
+import type { Ctx, Router } from './http.ts';
+import { log } from './log.ts';
+import { HttpError, type Store } from './store.ts';
+import { orNull } from './util.ts';
+import { DeliveryError, deliveryId, deliveryKeys, freshnessProblem, handshake, matchesFilter, parseDelivery, safeEqual, shownHeaders, signatureProblem } from './webhooks.ts';
+
+const WAIT_DEFAULT_S = 300;
+const WAIT_MAX_S = 1800;
+/** `?wait` on the public listener is cut to this: an open request is a held socket on the internet. */
+export const PUBLIC_WAIT_MAX_S = 30;
+
+/** `?timeout=<seconds>` for webhook waits, clamped to 1..`max`; junk falls back to the default. */
+export function waitSeconds(raw: string | null, max: number): number {
+  const n = raw === null || raw.trim() === '' ? NaN : Number(raw);
+  return Number.isFinite(n) ? Math.min(Math.max(n, 1), max) : Math.min(WAIT_DEFAULT_S, max);
+}
+
+function givenKey(c: Ctx): string {
+  const auth = c.req.headers.authorization ?? '';
+  return (auth.toLowerCase().startsWith('bearer ') ? auth.slice(7).trim() : '') || String(c.req.headers['x-boton-key'] ?? c.req.headers[earlierName('x-boton-key')!] ?? '') || c.url.searchParams.get('key') || '';
+}
+
+export function addHookRoutes(r: Router, deps: { cfg: Config; store: Store; engine: Engine }): Router {
+  const { cfg, store, engine } = deps;
+
+  /** 202 with the queued run (a redelivery's: 200), or with ?wait=1 its result once it has one. */
+  const answerRun = async (c: Ctx, routine: Routine, run: RoutineRun, callerGone: AbortSignal, extra: { duplicate?: true } = {}) => {
+    const location = `${routine.webhook!.url}/runs/${encodeURIComponent(run.id)}`;
+    const pending = (r: RoutineRun, status: number) => {
+      c.res.setHeader('location', location);
+      c.json(status, { ok: true, runId: r.id, status: r.status, ...extra });
+    };
+    const wait = ['1', 'true', 'yes'].includes(c.url.searchParams.get('wait') ?? '');
+    if (!wait) return pending(run, extra.duplicate ? 200 : 202);
+    c.req.socket.setTimeout(0);
+    const viaPublic = cfg.hooks.port !== null && c.req.socket.localPort === cfg.hooks.port;
+    const done = await engine.waitForRun(run, waitSeconds(c.url.searchParams.get('timeout'), viaPublic ? PUBLIC_WAIT_MAX_S : WAIT_MAX_S) * 1000, callerGone);
+    if (callerGone.aborted) return;
+    if (engine.closing.aborted && (done.status === 'queued' || done.status === 'running')) {
+      c.res.setHeader('location', location);
+      c.res.setHeader('retry-after', '30');
+      return c.json(503, {
+        ok: false,
+        runId: done.id,
+        status: done.status,
+        error: 'The server is restarting before this run finished. It runs (or is marked interrupted) when the server is back: check the run at the Location.',
+        ...extra,
+      });
+    }
+    // Gone: the run was deleted with its routine or Boton while waiting.
+    const gone = !store.findRun(done.id);
+    if (!gone && (done.status === 'queued' || done.status === 'running')) return pending(done, 202);
+    c.json(gone ? 410 : 200, { ok: done.status === 'succeeded', runId: done.id, status: done.status, reply: done.reply, error: done.error, ...extra });
+  };
+
+  // A generic routine takes its key; the others take only their sender's signature.
+  r.on('POST', '/hooks/routines/:id', async (c) => {
+    // On res, not req: req's 'close' fires as soon as its body has been read.
+    const callerGone = new AbortController();
+    c.res.once('close', () => callerGone.abort());
+    const routine = orNull(() => store.getRoutine(c.params.id));
+    const secrets = routine?.webhook ? store.webhookSecrets(routine.id) : null;
+    if (!routine?.webhook || !secrets) throw new HttpError(401, 'Unknown routine or bad key');
+    const { source } = routine.webhook;
+    const headers = c.req.headers;
+    if (source === 'generic') {
+      const given = givenKey(c);
+      if (!given || !safeEqual(given, secrets.key)) throw new HttpError(401, 'Unknown routine or bad key');
+    }
+    const bytes = await c.rawBytes();
+    // A signed sender's signature covers the exact bytes, so a forged delivery is refused before anything parses them.
+    if (source !== 'generic') {
+      const bad = signatureProblem(source, secrets, headers, bytes);
+      if (bad) throw new HttpError(401, bad);
+    }
+    let delivery: ReturnType<typeof parseDelivery>;
+    try {
+      delivery = parseDelivery(bytes, headers['content-type']);
+    } catch (err) {
+      if (err instanceof DeliveryError) throw new HttpError(400, err.message);
+      throw err;
+    }
+    if (source !== 'generic') {
+      const stale = freshnessProblem(source, delivery.json);
+      if (stale) throw new HttpError(401, stale);
+    }
+    const answer = handshake(source, headers, delivery.json);
+    if (answer) return c.json(200, answer);
+
+    // A redelivery within a day gets the run the first one started, unless that run failed or was skipped.
+    const id = deliveryId(source, headers, delivery.json);
+    const keys = deliveryKeys(source, id, bytes);
+    const earlier = keys.map((k) => store.findDelivery(routine.id, k)).find((r) => r !== null) ?? null;
+    if (earlier) {
+      // A failed run the owner retried: the redelivery gets the retry.
+      const first = store.findRun(earlier);
+      const run = first && store.latestRetry(first);
+      if (!run) return c.json(200, { ok: true, runId: earlier, status: null, duplicate: true });
+      if (run.status !== 'failed' && run.status !== 'skipped') return answerRun(c, routine, run, callerGone.signal, { duplicate: true });
+      log.info('webhook redelivery of a run that did not succeed: running it again', { routineId: routine.id, runId: run.id, status: run.status });
+    }
+    // A Slack retry with no event_id can't be matched to its first try, which probably started a run.
+    if (source === 'slack' && id === null && headers['x-slack-retry-num'] !== undefined) return c.json(200, { ok: true, skipped: true, reason: 'Slack retry' });
+    if (!routine.enabled) throw new HttpError(409, 'Routine is paused');
+    if (routine.webhook.filter && !matchesFilter(routine.webhook.filter, headers, delivery.json)) {
+      return c.json(200, { ok: true, skipped: true, reason: 'Filtered out' });
+    }
+    const run = engine.triggerRoutine(routine.id, 'webhook', delivery.payload, shownHeaders(headers));
+    for (const k of keys) store.recordDelivery(routine.id, k, run.id);
+    return answerRun(c, routine, run, callerGone.signal);
+  });
+
+  // Takes the routine's key whatever its sender.
+  r.on('GET', '/hooks/routines/:id/runs/:runId', (c) => {
+    const secrets = store.webhookSecrets(c.params.id);
+    const given = givenKey(c);
+    if (!secrets || !given || !safeEqual(given, secrets.key)) throw new HttpError(401, 'Unknown routine or bad key');
+    const run = store.findRun(c.params.runId);
+    if (!run || run.routineId !== c.params.id) throw new HttpError(404, `No run ${c.params.runId} of this routine`);
+    return {
+      ok: run.status === 'succeeded',
+      runId: run.id,
+      status: run.status,
+      trigger: run.trigger,
+      reply: run.reply,
+      error: run.error,
+      startedAt: run.startedAt,
+      finishedAt: run.finishedAt,
+      attempts: run.attempts,
+      retriedAs: run.meta?.retriedAs ?? null,
+      cancelled: !!run.meta?.cancelled,
+      timedOut: !!run.meta?.timedOut,
+    } satisfies WebhookRunStatus;
+  });
+
+  return r;
+}

package/payload/server/src/http.ts

@@ -0,0 +1,207 @@
+import { serverCommand } from './install-type.ts';
+import { createReadStream, existsSync, statSync } from 'node:fs';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { isIP } from 'node:net';
+import { extname, join, normalize } from 'node:path';
+import type { Principal, RouteAccess } from './auth.ts';
+import { log } from './log.ts';
+import { HttpError } from './store.ts';
+import { inside, orNull } from './util.ts';
+
+export interface Ctx {
+  req: IncomingMessage;
+  res: ServerResponse;
+  url: URL;
+  params: Record<string, string>;
+  /** Null for a public route called without a token, and on /hooks. */
+  principal: Principal | null;
+  /** At most 1 MB (or the route's own maxBody), else 413. */
+  rawBytes(): Promise<Buffer>;
+  /** JSON. With `strictUtf8`, bytes that aren't UTF-8 are a 400 rather than read as U+FFFD. */
+  body<T = any>(opts?: { strictUtf8?: boolean }): Promise<T>;
+  json(status: number, body: unknown): void;
+}
+
+type Handler = (ctx: Ctx) => unknown | Promise<unknown>;
+
+const MAX_BODY = 1024 * 1024;
+
+export class Router {
+  #routes: { method: string; parts: string[]; handler: Handler; access: RouteAccess; maxBody: number }[] = [];
+
+  /** By default only paired devices may call it, with a body of at most 1 MB. */
+  on(method: string, path: string, handler: Handler, access: RouteAccess = {}, opts: { maxBody?: number } = {}): this {
+    this.#routes.push({ method, parts: path.split('/').filter(Boolean), handler, access, maxBody: opts.maxBody ?? MAX_BODY });
+    return this;
+  }
+
+  match(method: string, pathname: string): { handler: Handler; params: Record<string, string>; access: RouteAccess; maxBody: number } | null | 'method' {
+    const segs = pathname.split('/').filter(Boolean);
+    let pathMatched = false;
+    for (const r of this.#routes) {
+      if (r.parts.length !== segs.length) continue;
+      const params: Record<string, string> = {};
+      let ok = true;
+      for (let i = 0; i < segs.length; i++) {
+        if (r.parts[i].startsWith(':')) {
+          const value = safeDecode(segs[i]);
+          if (value === null) throw new HttpError(400, 'Malformed URL encoding');
+          params[r.parts[i].slice(1)] = value;
+        } else if (r.parts[i] !== segs[i]) {
+          ok = false;
+          break;
+        }
+      }
+      if (!ok) continue;
+      pathMatched = true;
+      if (r.method === method) return { handler: r.handler, params, access: r.access, maxBody: r.maxBody };
+    }
+    return pathMatched ? 'method' : null;
+  }
+}
+
+export const safeDecode = (s: string): string | null => orNull(() => decodeURIComponent(s));
+
+export function sendJson(res: ServerResponse, status: number, body: unknown, headers: Record<string, string> = {}) {
+  if (res.writableEnded || res.destroyed) return;
+  // Too late to change the status (say, a stream failed midway): just finish the response.
+  if (res.headersSent) return void res.end();
+  const data = JSON.stringify(body);
+  res.writeHead(status, { ...headers, 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+  res.end(data);
+}
+
+export function makeCtx(req: IncomingMessage, res: ServerResponse, url: URL, params: Record<string, string>, principal: Principal | null, maxBody = MAX_BODY): Ctx {
+  let raw: Promise<Buffer> | null = null;
+  const rawBytes = () =>
+    (raw ??= new Promise<Buffer>((resolve, reject) => {
+      let size = 0;
+      const chunks: Buffer[] = [];
+      req.on('data', (c: Buffer) => {
+        size += c.length;
+        if (size > maxBody) {
+          reject(new HttpError(413, 'Request body too large'));
+          req.destroy();
+          return;
+        }
+        chunks.push(c);
+      });
+      req.on('end', () => resolve(Buffer.concat(chunks)));
+      // The caller hung up (or a request timeout cut it off): not a server error.
+      const incomplete = () => new HttpError(400, 'Request body incomplete');
+      req.on('error', (err) => reject(req.complete ? err : incomplete()));
+      req.on('close', () => {
+        if (!req.complete) reject(incomplete());
+      });
+    }));
+  return {
+    req,
+    res,
+    url,
+    params,
+    principal,
+    rawBytes,
+    async body(opts: { strictUtf8?: boolean } = {}) {
+      const bytes = await rawBytes();
+      let text: string;
+      if (!opts.strictUtf8) text = bytes.toString('utf8');
+      else {
+        try {
+          text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(bytes);
+        } catch {
+          throw new HttpError(400, 'Body must be UTF-8 text');
+        }
+      }
+      if (!text.trim()) return {};
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        throw new HttpError(400, 'Body must be valid JSON');
+      }
+      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) throw new HttpError(400, 'Body must be a JSON object');
+      return parsed as any;
+    },
+    json: (status, body) => sendJson(res, status, body),
+  };
+}
+
+const RAW_UPLOAD = /^\/api\/bots\/[^/]+\/uploads$/;
+
+/**
+ * Browser-safety checks, a second line behind auth: the Host check blocks DNS
+ * rebinding, the rest drive-by requests from other sites. Mutations need a
+ * Content-Type that forces a CORS preflight: exactly application/json
+ * (`text/plain; x=application/json` is not it), or octet-stream for an upload.
+ */
+export function guardRequest(req: IncomingMessage, url: URL, allowedHosts: Set<string>, publicOrigins: ReadonlySet<string> = new Set()): string | null {
+  const host = (req.headers.host ?? '').replace(/:\d+$/, '').replace(/^\[|\]$/g, '').toLowerCase();
+  if (!host || (!isIP(host) && !allowedHosts.has(host))) return `Host "${host}" is not allowed. Set BOTONS_ALLOWED_HOSTS to permit it.`;
+  const origin = req.headers.origin;
+  if (origin && origin !== 'null') {
+    try {
+      const parsed = new URL(origin);
+      const configured = parsed.origin !== 'null' && origin.toLowerCase() === parsed.origin.toLowerCase() && publicOrigins.has(parsed.origin.toLowerCase());
+      if (!configured && parsed.host.toLowerCase() !== (req.headers.host ?? '').toLowerCase()) return 'Cross-origin requests are not allowed';
+    } catch {
+      return 'Bad Origin header';
+    }
+  }
+  const mutating = req.method !== 'GET' && req.method !== 'HEAD' && req.method !== 'OPTIONS';
+  if (mutating && url.pathname.startsWith('/api/')) {
+    if (origin === 'null') return 'Requests from an opaque origin (Origin: null) are not allowed';
+    const site = req.headers['sec-fetch-site'];
+    if (site !== undefined && site !== 'same-origin') return 'Cross-site requests are not allowed';
+    const type = (req.headers['content-type'] ?? '').split(';', 1)[0].trim().toLowerCase();
+    const upload = req.method === 'POST' && RAW_UPLOAD.test(url.pathname) && type === 'application/octet-stream';
+    if (!upload && type !== 'application/json') return 'API requests must use Content-Type: application/json';
+  }
+  return null;
+}
+
+const TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.ico': 'image/x-icon',
+  '.json': 'application/json',
+  '.webmanifest': 'application/manifest+json',
+  '.woff2': 'font/woff2',
+};
+
+/**
+ * The owner's app is never shown inside another page (CSP frame-ancestors, and X-Frame-Options for browsers without
+ * it): no site can lay it under its own and steer the owner's clicks onto an approval. A generated file's preview is
+ * served by the API with its own policy (PREVIEW_CSP in files.ts), never from here.
+ */
+export const APP_FRAMING = { 'content-security-policy': "frame-ancestors 'none'", 'x-frame-options': 'DENY' } as const;
+
+/** `rel`: the decoded request path. */
+export function serveStatic(root: string, rel: string, res: ServerResponse): void {
+  if (!existsSync(join(root, 'index.html'))) {
+    res.writeHead(503, { 'content-type': 'text/html; charset=utf-8', ...APP_FRAMING });
+    res.end(`<h1>Botons</h1><p>The web app is not built yet. Run <code>${serverCommand('repair')}</code>.</p>`);
+    return;
+  }
+  const file = normalize(join(root, rel));
+  let target = inside(root, file) && existsSync(file) && statSync(file).isFile() ? file : null;
+  if (!target) {
+    if (extname(rel)) return void res.writeHead(404, APP_FRAMING).end('Not found');
+    target = join(root, 'index.html'); // SPA fallback
+    rel = '/index.html';
+  }
+  const immutable = rel.startsWith('/assets/');
+  res.writeHead(200, {
+    'content-type': TYPES[extname(target)] ?? 'application/octet-stream',
+    'cache-control': immutable ? 'public, max-age=31536000, immutable' : 'no-cache',
+    ...APP_FRAMING,
+  });
+  createReadStream(target)
+    .on('error', (err) => {
+      log.error(`could not read ${target}`, { err });
+      res.destroy();
+    })
+    .pipe(res);
+}