getbotons 0.0.0-stage → 0.1.0

package/payload/server/src/backup.ts

@@ -0,0 +1,382 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, closeSync, lstatSync, constants, copyFileSync, existsSync, fstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import type { BackupStatus, BackupSummary } from '../../shared/types.ts';
+import { join, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { DB_FILE } from '../../shared/legacy-names.mjs';
+
+export const KEEP_BACKUPS = 14;
+
+/** The timer backs up daily, so a newest backup older than two days means it stopped. */
+export const BACKUP_STALE_MS = 2 * 86_400_000;
+
+/** How many of the newest backups the owner's status lists. */
+export const BACKUPS_LISTED = KEEP_BACKUPS;
+
+/** The folders of BOTONS_HOME archived besides the database (not run/, nor backups/). browser/ holds each Boton's browser profile. */
+export const ARCHIVED_FOLDERS: readonly string[] = ['workspaces', 'shared', 'templates', 'browser'];
+
+/**
+ * Left out of a browser profile: Chromium's lock links (a restore refuses links, and they name the old process) and
+ * its caches and its own home folder, which it rebuilds. Cookies and site storage stay. An owner's handover profile
+ * (browser/<boton>/handover) is never archived: it holds what the owner typed, and is deleted as the handover ends.
+ */
+const BROWSER_EXCLUDES = ['browser/*/handover', 'browser/*/home', 'browser/*/profile/Singleton*', 'browser/*/profile/*Cache*', 'browser/*/profile/Default/*Cache*', 'browser/*/profile/Default/Service Worker', 'browser/*/profile/Crashpad'];
+
+/** A backup folder's name is its UTC time, so names sort oldest first. */
+const BACKUP_NAME = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z$/;
+
+/** What a backup that died part-way leaves behind; group 1 is when it started. */
+const PARTIAL_NAME = /^(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z)\.partial$/;
+
+export const stamp = (d: Date = new Date()): string => d.toISOString().replace(/[:.]/g, '-');
+
+/** Backups hold chat history and webhook keys. */
+function privateDir(dir: string): string {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  return dir;
+}
+
+interface BackupManifest {
+  createdAt: string;
+  schemaVersion: number;
+  counts: Record<string, number>;
+  workspaces: boolean;
+  folders?: string[];
+  tarWarning?: string;
+  workspacesError?: string;
+}
+
+export interface BackupResult {
+  dir: string;
+  manifest: BackupManifest;
+  removed: string[];
+}
+
+/** The database file in a data folder or a backup: botons.db, or its deprecated name until the upgrade renames it (shared/legacy-names.mjs). */
+export function dbFileIn(dir: string): string {
+  const now = join(dir, 'botons.db');
+  if (existsSync(now)) return now;
+  const old = join(dir, DB_FILE);
+  return existsSync(old) ? old : now;
+}
+
+const lstatOrNull = (p: string) => {
+  try {
+    return lstatSync(p);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Back up `home` into backups/<time>/ (named only once complete), then keep the newest KEEP_BACKUPS.
+ * If tar fails the database copy is still kept, and nothing is pruned so older backups with workspaces stay.
+ */
+export function backup(opts: { home: string; now?: Date }): BackupResult {
+  const now = opts.now ?? new Date();
+  const dbPath = dbFileIn(opts.home);
+  if (!existsSync(dbPath)) throw new Error(`No database at ${dbPath}`);
+  const backupsDir = privateDir(join(opts.home, 'backups'));
+  const dir = join(backupsDir, stamp(now));
+  if (existsSync(dir)) throw new Error(`${dir} already exists`);
+  const partial = `${dir}.partial`;
+  rmSync(partial, { recursive: true, force: true });
+  privateDir(partial);
+
+  let manifest: BackupManifest;
+  try {
+    const snapshot = join(partial, 'botons.db');
+    const db = new DatabaseSync(dbPath, { readOnly: true });
+    try {
+      db.exec('pragma busy_timeout = 5000');
+      // A consistent single-file copy (VACUUM INTO reads one snapshot, WAL included), safe while the server writes.
+      db.prepare('vacuum into ?').run(snapshot);
+    } finally {
+      db.close();
+    }
+    chmodSync(snapshot, 0o600);
+    manifest = { createdAt: now.toISOString(), ...inspectSnapshot(snapshot), workspaces: false };
+
+    const folders = ARCHIVED_FOLDERS.filter((f) => existsSync(join(opts.home, f)));
+    if (folders.length) {
+      const archive = join(partial, 'workspaces.tar.gz');
+      // --ignore-failed-read: skip what this user cannot read (a Boton's chmod 000, a root-owned folder a container left).
+      const excludes = folders.includes('browser') ? BROWSER_EXCLUDES.map((e) => `--exclude=${e}`) : [];
+      const tar = spawnSync('tar', ['--ignore-failed-read', ...excludes, '-czf', archive, '-C', opts.home, ...folders], { encoding: 'utf8' });
+      const stderr = (tar.stderr ?? '').trim();
+      // GNU tar exits 1 when a file changed while it was read; the archive is still good.
+      if (!tar.error && (tar.status === 0 || tar.status === 1) && existsSync(archive)) {
+        chmodSync(archive, 0o600);
+        manifest.workspaces = true;
+        manifest.folders = folders;
+        if (stderr) manifest.tarWarning = stderr;
+      } else {
+        rmSync(archive, { force: true });
+        manifest.workspacesError = tar.error
+          ? `Could not run tar: ${tar.error.message}`
+          : `tar failed (${tar.status === null ? `signal ${tar.signal}` : `exit ${tar.status}`})${stderr ? `: ${stderr}` : ''}`;
+      }
+    }
+
+    writeFileSync(join(partial, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+    renameSync(partial, dir);
+  } catch (err) {
+    rmSync(partial, { recursive: true, force: true });
+    throw err;
+  }
+  if (manifest.workspacesError) return { dir, manifest, removed: [] };
+
+  // Only names this code makes are deleted: other files in backups/ always stay.
+  const all = listBackups(backupsDir);
+  const removed = all.slice(0, Math.max(0, all.length - KEEP_BACKUPS));
+  for (const n of removed) rmSync(join(backupsDir, n), { recursive: true, force: true });
+  // A younger partial backup may still be running.
+  const dayAgo = stamp(new Date(now.getTime() - 86_400_000));
+  for (const n of readdirSync(backupsDir)) {
+    const started = PARTIAL_NAME.exec(n)?.[1];
+    if (started && started < dayAgo) rmSync(join(backupsDir, n), { recursive: true, force: true });
+  }
+  return { dir, manifest, removed };
+}
+
+function inspectSnapshot(file: string): { schemaVersion: number; counts: Record<string, number> } {
+  const db = new DatabaseSync(file, { readOnly: true });
+  try {
+    const problems = db.prepare('pragma integrity_check').all().map((r) => String(r.integrity_check));
+    if (problems.join() !== 'ok') throw new Error(`The snapshot failed integrity_check: ${problems.slice(0, 5).join('; ')}`);
+    const tables = db.prepare("select name from sqlite_master where type = 'table' and name not like 'sqlite_%' order by name").all();
+    const counts: Record<string, number> = {};
+    for (const { name } of tables) counts[String(name)] = Number(db.prepare(`select count(*) as n from "${name}"`).get()!.n);
+    return { schemaVersion: Number(db.prepare('pragma user_version').get()!.user_version), counts };
+  } finally {
+    db.close();
+  }
+}
+
+/** When a backup folder's name says it was made, or NaN when the name is not a real UTC time (2026-99-99T…). */
+export function backupTime(name: string): number {
+  if (!BACKUP_NAME.test(name)) return Number.NaN;
+  const at = Date.parse(name.replace(/T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/, 'T$1:$2:$3.$4Z'));
+  // Date.parse rolls some impossible dates over (02-30 → 03-02); a real stamp prints back to the same name.
+  return Number.isFinite(at) && stamp(new Date(at)) === name ? at : Number.NaN;
+}
+
+/** The largest manifest.json the owner's view reads; the backup command writes a few KiB. */
+export const MANIFEST_MAX_BYTES = 256 * 1024;
+
+const ISO_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+/**
+ * A backup folder's manifest, or null when it is missing, not a regular file (a FIFO, a device, a symlink), larger
+ * than MANIFEST_MAX_BYTES or not JSON. Opens without following a link and without blocking, then checks the open
+ * file itself, so a swap between the check and the read cannot make it block or read something else.
+ */
+export function readManifest(file: string): Partial<BackupManifest> | null {
+  let fd: number;
+  try {
+    fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  } catch {
+    return null;
+  }
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile() || st.size > MANIFEST_MAX_BYTES) return null;
+    // Read at most one byte past the limit: the file may grow after fstat.
+    const buf = Buffer.alloc(MANIFEST_MAX_BYTES + 1);
+    let n = 0;
+    while (n < buf.length) {
+      const got = readSync(fd, buf, n, buf.length - n, n);
+      if (got === 0) break;
+      n += got;
+    }
+    if (n > MANIFEST_MAX_BYTES) return null;
+    const parsed: unknown = JSON.parse(buf.subarray(0, n).toString('utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Partial<BackupManifest>) : null;
+  } catch {
+    return null;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** The manifest's createdAt when it is a canonical UTC time, else the folder name's: never the manifest's own text. */
+function createdAt(manifest: Partial<BackupManifest>, name: string): string {
+  const m = manifest.createdAt;
+  if (typeof m === 'string' && ISO_TIME.test(m)) {
+    const at = Date.parse(m);
+    if (Number.isFinite(at) && new Date(at).toISOString() === m) return m;
+  }
+  return new Date(backupTime(name)).toISOString();
+}
+
+/**
+ * What the owner sees of the backups: names, times, schema versions and whether workspaces were archived. Reads
+ * only manifests, and never returns a path or a manifest's error text (tar's messages name files). Never throws:
+ * when the backups folder cannot be listed (not a folder, no permission, removed while read) it says only that.
+ */
+export function backupStatus(opts: { backupsDir: string; dbExists: boolean; now?: number }): BackupStatus {
+  const now = opts.now ?? Date.now();
+  const base = { keep: KEEP_BACKUPS, staleAfterHours: BACKUP_STALE_MS / 3_600_000 };
+  let entries: { name: string; dir: boolean }[];
+  try {
+    entries = readdirSync(opts.backupsDir, { withFileTypes: true }).map((e) => ({ name: e.name, dir: e.isDirectory() }));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      return { ...base, backups: [], total: 0, stale: true, partial: 0, unreadable: true };
+    }
+    entries = [];
+  }
+  // Real folders only: a symlink or file named like a backup is not one this code made.
+  const names = entries
+    .filter((e) => e.dir && Number.isFinite(backupTime(e.name)))
+    .map((e) => e.name)
+    .sort();
+  const backups = names
+    .slice(-BACKUPS_LISTED)
+    .reverse()
+    .map((name): BackupSummary => {
+      const manifest = readManifest(join(opts.backupsDir, name, 'manifest.json')) ?? {};
+      return {
+        name,
+        createdAt: createdAt(manifest, name),
+        schemaVersion: typeof manifest.schemaVersion === 'number' && Number.isSafeInteger(manifest.schemaVersion) ? manifest.schemaVersion : null,
+        workspaces: manifest.workspaces === true,
+        workspacesFailed: typeof manifest.workspacesError === 'string',
+      };
+    });
+  const newest = names.at(-1);
+  return {
+    ...base,
+    backups,
+    total: names.length,
+    stale: newest ? now - backupTime(newest) > BACKUP_STALE_MS : opts.dbExists,
+    partial: entries.filter((e) => PARTIAL_NAME.test(e.name)).length,
+    unreadable: false,
+  };
+}
+
+export function listBackups(backupsDir: string): string[] {
+  if (!existsSync(backupsDir)) return [];
+  return readdirSync(backupsDir)
+    .filter((n) => Number.isFinite(backupTime(n)))
+    .sort();
+}
+
+/** What a restore puts back besides botons.db: the folders a backup archives, and the database's own side files. */
+const RESTORED = ['botons.db', 'botons.db-wal', 'botons.db-shm', ...ARCHIVED_FOLDERS];
+/** Set aside too: the database under its deprecated name (shared/legacy-names.mjs), so only the restored one is left. */
+const SET_ASIDE = [...RESTORED, DB_FILE, `${DB_FILE}-wal`, `${DB_FILE}-shm`];
+
+export interface RestorePlan {
+  /** The backup folder. */
+  from: string;
+  schemaVersion: number;
+  workspaces: boolean;
+  /** The backup's database file (botons.db, or its deprecated name in a backup made before the rename). */
+  db: string;
+  /** What is in `home` now and gets moved to `setAside`. */
+  moves: string[];
+  setAside: string;
+}
+
+/**
+ * Whether a restore by this code takes a backup at `version`: its own schema, or the one before (upgraded at the next
+ * start). The restore command, the rehearsal and the owner's view all decide it here.
+ */
+export function restorable(version: number, maxSchema: number): 'ok' | 'newer' | 'older' {
+  if (version > maxSchema) return 'newer';
+  return version >= maxSchema - 1 && version > 0 ? 'ok' : 'older';
+}
+
+/** The schema versions a restore by this code takes, oldest first. */
+export const restorableSchemas = (maxSchema: number): number[] => [maxSchema - 1, maxSchema].filter((v) => v > 0);
+
+/** A backup by folder name (in <home>/backups), "latest", or a path. Throws if it is not a usable backup. */
+export function planRestore(opts: { home: string; backup: string; now?: Date; maxSchema: number }): RestorePlan {
+  const backupsDir = join(opts.home, 'backups');
+  let from: string;
+  if (opts.backup === 'latest') {
+    const newest = listBackups(backupsDir).at(-1);
+    if (!newest) throw new Error(`There is no backup in ${backupsDir}.`);
+    from = join(backupsDir, newest);
+  } else from = BACKUP_NAME.test(opts.backup) ? join(backupsDir, opts.backup) : resolve(opts.backup);
+  const db = dbFileIn(from);
+  if (!existsSync(db)) throw new Error(`${from} is not a backup: it has no botons.db.`);
+  const { schemaVersion } = inspectSnapshot(db);
+  const compat = restorable(schemaVersion, opts.maxSchema);
+  if (compat === 'newer') {
+    throw new Error(`The backup's database is at schema version ${schemaVersion}, newer than this code's ${opts.maxSchema}. Restore it with the release that made it.`);
+  }
+  if (compat === 'older') throw new Error(`Schema version ${schemaVersion} cannot be upgraded by this code; use a compatible release first.`);
+  const archive = join(from, 'workspaces.tar.gz');
+  const workspaces = existsSync(archive);
+  if (workspaces) {
+    // Read through once before anything moves, and unpack nothing but the folders a backup archives.
+    const list = spawnSync('tar', ['-tzf', archive], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+    if (list.error || list.status !== 0) throw new Error(`${archive} cannot be read: ${list.error?.message ?? (list.stderr || `exit ${list.status}`).trim()}`);
+    // Reject links and special files: their targets can cross isolation boundaries even when member names do not.
+    const types = spawnSync('tar', ['-tvzf', archive], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, env: { ...process.env, LC_ALL: 'C' } });
+    if (types.error || types.status !== 0 || types.stdout.split('\n').some((line) => line && !['-', 'd'].includes(line[0]))) {
+      throw new Error(`${archive} contains links or special files; restore only regular files and directories.`);
+    }
+    const stray = list.stdout.split('\n').find((m) => m && !ARCHIVED_FOLDERS.some((f) => m === f || m.startsWith(`${f}/`)));
+    if (stray !== undefined || /(^|\/)\.\.(\/|$)/m.test(list.stdout)) throw new Error(`${archive} holds ${stray ?? 'a ".." path'}, which a Botons backup never does.`);
+  }
+  return {
+    from,
+    schemaVersion,
+    workspaces,
+    db,
+    moves: SET_ASIDE.filter((f) => existsSync(join(opts.home, f))),
+    setAside: join(opts.home, `before-restore-${stamp(opts.now)}`),
+  };
+}
+
+/**
+ * Restore a backup into `home`, which no server may be using (the caller holds its lock). Nothing is deleted: what is
+ * there now moves to plan.setAside first. If the restore fails part-way, what it unpacked is removed and the set-aside
+ * state is moved back.
+ */
+export function restore(home: string, plan: RestorePlan): void {
+  if (existsSync(plan.setAside)) throw new Error(`${plan.setAside} already exists`);
+  // Prepare everything before moving originals. Restrictive archive permissions or failed extraction cannot
+  // strand the active database, and installed paths can be rolled back with renames rather than recursive removal.
+  const staging = mkdtempSync(join(home, '.restore-'));
+  const present = SET_ASIDE.filter((f) => lstatOrNull(join(home, f)));
+  const moved: string[] = [];
+  const installed: string[] = [];
+  let recoveryIncomplete = false;
+  try {
+    copyFileSync(plan.db, join(staging, 'botons.db'));
+    chmodSync(join(staging, 'botons.db'), 0o600);
+    if (plan.workspaces) {
+      const tar = spawnSync('tar', ['-xzf', join(plan.from, 'workspaces.tar.gz'), '-C', staging, '--no-same-owner'], { encoding: 'utf8' });
+      if (tar.error || tar.status !== 0) throw new Error(`Unpacking workspaces.tar.gz failed: ${tar.error?.message ?? (tar.stderr || `exit ${tar.status}`).trim()}`);
+    }
+    // A data folder with nothing in it yet (a new machine) has nothing to set aside.
+    if (present.length) privateDir(plan.setAside);
+    for (const f of present) {
+      renameSync(join(home, f), join(plan.setAside, f));
+      moved.push(f);
+    }
+    for (const f of RESTORED) if (existsSync(join(staging, f))) {
+      renameSync(join(staging, f), join(home, f));
+      installed.push(f);
+    }
+  } catch (err) {
+    try {
+      for (const f of installed) renameSync(join(home, f), join(staging, f));
+      for (const f of moved) renameSync(join(plan.setAside, f), join(home, f));
+      if (existsSync(plan.setAside)) rmSync(plan.setAside, { recursive: true });
+    } catch (rollback) {
+      recoveryIncomplete = true;
+      throw new Error(`Restore failed: ${(err as Error).message}. Recovery incomplete: ${(rollback as Error).message}. Preserve ${plan.setAside} and ${staging} for manual recovery; do not start the server.`);
+    }
+    throw new Error(`Restore failed; original state preserved. ${(err as Error).message}`);
+  } finally {
+    // A hostile mode on an extracted directory can prevent cleanup. Keep the private staging folder for inspection.
+    try { if (!recoveryIncomplete) rmSync(staging, { recursive: true, force: true }); } catch {}
+  }
+}

package/payload/server/src/brain-login.ts

@@ -0,0 +1,75 @@
+import { cliHomesEnv, prepareCliHomes } from './cli-homes.ts';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { agentEnv } from './providers/process.ts';
+import { HttpError } from './store.ts';
+
+export interface BrainLoginState { state: 'idle' | 'waiting' | 'finished' | 'cancelled' | 'timed-out' | 'fallback'; url: string | null; code: string | null }
+/** Only the fixed device verification address and code leave this class. Raw CLI output is never logged. */
+export class BrainLogin {
+  #child: ChildProcess | null = null;
+  #timer: ReturnType<typeof setTimeout> | null = null;
+  #view: BrainLoginState = { state: 'idle', url: null, code: null };
+  view(): BrainLoginState { return { ...this.#view }; }
+  private bin: string;
+  private readonly timeoutMs: number;
+  private readonly schedule: (callback: () => void, delay: number) => ReturnType<typeof setTimeout>;
+  constructor(bin = 'codex', timeoutMs = 10 * 60_000, schedule: (callback: () => void, delay: number) => ReturnType<typeof setTimeout> = setTimeout) { this.bin = bin; this.timeoutMs = timeoutMs; this.schedule = schedule; }
+  setBin(bin: string): void {
+    if (this.#child) throw new HttpError(409, 'Cancel sign-in before updating.');
+    this.bin = bin;
+  }
+  start(): BrainLoginState {
+    if (this.#child) throw new HttpError(409, 'A sign-in is already running. Cancel it first.');
+    this.#view = { state: 'waiting', url: null, code: null };
+    prepareCliHomes();
+    const child = spawn(this.bin, ['login', '--device-auth'], { env: { ...agentEnv({ NO_COLOR: '1' }), ...cliHomesEnv(process.env, true) }, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+    this.#child = child;
+    let pending = '';
+    const read = (chunk: Buffer) => {
+      if (this.#child !== child || this.#view.state !== 'waiting') return;
+      // Bounded transient parsing buffer, discarded after each line; never returned in errors.
+      pending = (pending + chunk.toString()).replace(/\x1b\[[0-9;]*m/g, '').slice(-2048);
+      const lines = pending.split(/\r?\n/);
+      pending = lines.pop() ?? '';
+      for (const line of lines) {
+        if (/https:\/\/auth\.openai\.com\/codex\/device(?:\s|$)/.test(line)) this.#view.url = 'https://auth.openai.com/codex/device';
+        const code = line.trim().match(/^([A-Z0-9]{4}-[A-Z0-9]{5}|[A-Z0-9]{4}-[A-Z0-9]{4})$/);
+        if (code) this.#view.code = code[1];
+      }
+    };
+    child.stdout!.on('data', read);
+    child.stderr!.on('data', read);
+    child.once('error', () => finish('fallback'));
+    child.once('close', (code) => finish(code === 0 ? 'finished' : 'fallback'));
+    const finish = (state: BrainLoginState['state']) => {
+      if (this.#child !== child) return;
+      this.#child = null;
+      this.#killGroup(child);
+      if (this.#timer) clearTimeout(this.#timer);
+      this.#timer = null;
+      child.stdout?.removeListener('data', read);
+      child.stderr?.removeListener('data', read);
+      pending = '';
+      this.#view = { state, url: null, code: null };
+    };
+    this.#timer = this.schedule(() => { this.cancel(); this.#view.state = 'timed-out'; }, this.timeoutMs);
+    this.#timer.unref();
+    return this.view();
+  }
+  #killGroup(child: ChildProcess): void {
+    // A configured launcher may spawn the actual CLI. Neither may finish login after cancellation.
+    if (!child.pid) return;
+    try { process.kill(-child.pid, 'SIGKILL'); } catch { /* The group may already have exited. */ }
+  }
+  cancel(): BrainLoginState {
+    const child = this.#child;
+    this.#child = null;
+    child?.stdout?.removeAllListeners('data');
+    child?.stderr?.removeAllListeners('data');
+    if (child) this.#killGroup(child);
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = null;
+    this.#view = { state: 'cancelled', url: null, code: null };
+    return this.view();
+  }
+}

package/payload/server/src/browser-cert.ts

@@ -0,0 +1,67 @@
+import { createHash, generateKeyPairSync, randomBytes, sign } from 'node:crypto';
+
+/*
+ * The certificate the owner's handover browser is shown for every HTTPS site: made here, with a new P-256 key, for
+ * one handover. That Chromium is told to trust exactly this key (--ignore-certificate-errors-spki-list) and no other
+ * certificate changes for it, so its proxy (browser-proxy.ts, `intercept`) can end each HTTPS tunnel itself, see
+ * every request inside (its method above all) and decide on it, then send it on to the site over TLS that the proxy
+ * verifies against the system's roots. The key never leaves this process; nothing else trusts it.
+ */
+
+const der = (tag: number, body: Buffer): Buffer => {
+  const n = body.length;
+  const len = n < 0x80 ? Buffer.from([n]) : n < 0x100 ? Buffer.from([0x81, n]) : Buffer.from([0x82, n >> 8, n & 0xff]);
+  return Buffer.concat([Buffer.from([tag]), len, body]);
+};
+const seq = (...parts: Buffer[]) => der(0x30, Buffer.concat(parts));
+const oid = (dotted: string): Buffer => {
+  const [a, b, ...rest] = dotted.split('.').map(Number);
+  const out = [a * 40 + b];
+  for (const v of rest) {
+    const bytes = [v & 0x7f];
+    for (let x = v >> 7; x > 0; x >>= 7) bytes.unshift((x & 0x7f) | 0x80);
+    out.push(...bytes);
+  }
+  return der(0x06, Buffer.from(out));
+};
+const utcTime = (d: Date) => der(0x17, Buffer.from(`${d.toISOString().slice(2, 19).replace(/[-:T]/g, '')}Z`, 'ascii'));
+const name = (cn: string) => seq(der(0x31, seq(oid('2.5.4.3'), der(0x0c, Buffer.from(cn, 'utf8')))));
+const ECDSA_SHA256 = seq(oid('1.2.840.10045.4.3.2'));
+
+export interface InterceptCert {
+  key: string;
+  cert: string;
+  /** SHA-256 of the key's SubjectPublicKeyInfo, base64: what Chromium is told to trust. */
+  spki: string;
+}
+
+/** A new key and a self-signed certificate for it, valid from a day ago for two days. */
+export function interceptCert(now = new Date()): InterceptCert {
+  const { privateKey, publicKey } = generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+  const spkiDer = publicKey.export({ type: 'spki', format: 'der' });
+  const randomSerial = randomBytes(16);
+  // DER integers need minimal signed encoding; keep this positive and nonzero.
+  let first = 0;
+  while (first < randomSerial.length - 1 && randomSerial[first] === 0) first++;
+  let serial = randomSerial.subarray(first);
+  if (serial.length === 1 && serial[0] === 0) serial = Buffer.from([1]);
+  else if (serial[0] & 0x80) serial = Buffer.concat([Buffer.from([0]), serial]);
+  const subject = name('Botons handover');
+  const tbs = seq(
+    der(0xa0, der(0x02, Buffer.from([2]))),
+    der(0x02, serial),
+    ECDSA_SHA256,
+    subject,
+    seq(utcTime(new Date(now.getTime() - 86_400_000)), utcTime(new Date(now.getTime() + 86_400_000))),
+    subject,
+    spkiDer,
+  );
+  const signature = sign('sha256', tbs, { key: privateKey, dsaEncoding: 'der' });
+  const certDer = seq(tbs, ECDSA_SHA256, der(0x03, Buffer.concat([Buffer.from([0]), signature])));
+  const pem = `-----BEGIN CERTIFICATE-----\n${certDer.toString('base64').replace(/.{64}/g, '$&\n').replace(/\n?$/, '\n')}-----END CERTIFICATE-----\n`;
+  return {
+    key: privateKey.export({ type: 'pkcs8', format: 'pem' }) as string,
+    cert: pem,
+    spki: createHash('sha256').update(spkiDer).digest('base64'),
+  };
+}

package/payload/server/src/browser-handoff.ts

@@ -0,0 +1,119 @@
+import { type BrowserHandoff, type HandoffEvent, handBackNote, handoffOpen, handoffReason, handoffStep, handoffWaiting, requestHandoff } from '../../shared/handoff.ts';
+import type { Message } from '../../shared/types.ts';
+import { log } from './log.ts';
+import type { PushRequest } from './notify.ts';
+import { HttpError, type Store } from './store.ts';
+import { nowIso } from './util.ts';
+
+/*
+ * The handoff cards (shared/handoff.ts) as the server keeps them: a `browser.handoff` chat event whose meta holds the
+ * record, changed only through Store.setHandoff (from one state to the next), so the chat updates live. browser.ts
+ * says when the owner takes the browser over and when that ends; this says what the card and the Boton make of it.
+ * Nothing here opens or drives a browser, and nothing here sees what the owner does in it.
+ */
+
+export interface HandoffDeps {
+  store: Store;
+  /** A push for the owner (Notifier.push), best effort. */
+  push?: (req: PushRequest) => Promise<unknown>;
+  /** Starts the Boton's turn on its pending messages. */
+  wake: (botId: string) => void;
+}
+
+const handoffOf = (m: Message): BrowserHandoff | null => (m.meta?.kind === 'browser.handoff' ? (m.meta.browserHandoff ?? null) : null);
+
+export class BrowserHandoffs {
+  #deps: HandoffDeps;
+
+  constructor(deps: HandoffDeps) {
+    this.#deps = deps;
+  }
+
+  /** The step `e` on card `m`, if it can happen from where it stands now (another change got there first: null). */
+  #step(m: Message, e: HandoffEvent): Message | null {
+    const h = handoffOf(m);
+    if (!h) return null;
+    const next = handoffStep(h, e);
+    return next ? this.#deps.store.setHandoff(m.id, h.state, next) : null;
+  }
+
+  /** The Boton's open handoff (requested and waiting, or taken), if any. Requests past their expiry found on the way are closed. */
+  open(botId: string): Message | null {
+    const now = nowIso();
+    let found: Message | null = null;
+    for (const m of this.#deps.store.openHandoffs(botId)) {
+      const h = handoffOf(m)!;
+      if (!handoffOpen(h, now)) this.#step(m, { type: 'close', at: now, why: 'nobody took it in time' });
+      else found ??= m;
+    }
+    return found;
+  }
+
+  /**
+   * The Boton asks (browser_handoff, from its running turn). `url` is where its browser is (origin and path only);
+   * `takenBy` names the device when the owner already has the browser, so the card starts taken. A second ask while
+   * one waits replaces it (the newer reason is the one that counts); one already taken is answered with that one.
+   */
+  request(botId: string, rawReason: unknown, url: string | null, takenBy: string | null): { message: Message; already: 'taken' | null } {
+    const reason = handoffReason(rawReason);
+    if (typeof reason !== 'string') throw new HttpError(400, reason.why);
+    const now = nowIso();
+    const current = this.open(botId);
+    if (current && handoffOf(current)!.state === 'taken') return { message: current, already: 'taken' };
+    if (current) this.#step(current, { type: 'close', at: now, why: 'the Boton asked again' });
+    const store = this.#deps.store;
+    const bot = store.getBot(botId);
+    let message = store.addMessage(botId, 'event', `Your turn in ${bot.name}'s browser: ${reason}`, { kind: 'browser.handoff', browserHandoff: requestHandoff(reason, url, new Date()) });
+    if (takenBy) message = this.#step(message, { type: 'take', at: nowIso(), by: takenBy }) ?? message;
+    log.info('browser handoff requested', { botId, handoffId: message.id, taken: !!takenBy || undefined });
+    if (!takenBy) {
+      void this.#deps
+        .push?.({ bot: { id: bot.id, name: bot.name }, reason: 'approval', detail: `Your turn in ${bot.name}'s browser: ${reason}`, generic: `Your turn in ${bot.name}'s browser.`, priority: 'high' })
+        ?.catch((err) => log.warn('could not push a browser handoff', { botId, err }));
+    }
+    return { message, already: null };
+  }
+
+  /** The owner took the browser over (from the card, the chat header or Settings): a waiting request is taken. */
+  taken(botId: string, by: string): void {
+    const m = this.open(botId);
+    if (m && handoffWaiting(handoffOf(m)!, nowIso())) this.#step(m, { type: 'take', at: nowIso(), by });
+  }
+
+  /**
+   * The handover ended (`how`: `finished` when the owner handed it back): a taken handoff is handed back, with where the
+   * page is (origin and path only), and the Boton is woken with a note saying so. False if there was none.
+   */
+  handedBack(botId: string, page: string | null, how: string): boolean {
+    const m = this.open(botId);
+    if (!m || handoffOf(m)!.state !== 'taken') return false;
+    const done = this.#step(m, { type: 'hand-back', at: nowIso(), page, how });
+    if (!done) return false;
+    const store = this.#deps.store;
+    if (!store.hasBot(botId)) return true;
+    const note = handBackNote(store.getSettings().ownerName, handoffOf(done)!);
+    store.addMessage(botId, 'user', note, { kind: 'browser.handed_back', handoffId: m.id }, true);
+    log.info('browser handoff handed back', { botId, handoffId: m.id, how });
+    this.#deps.wake(botId);
+    return true;
+  }
+
+  /** The Boton's browser was turned off (or the Boton is going): a request still waiting can't be taken any more. */
+  closeWaiting(botId: string, why: string): void {
+    const m = this.open(botId);
+    if (m && handoffOf(m)!.state === 'requested') this.#step(m, { type: 'close', at: nowIso(), why });
+  }
+
+  /**
+   * At start: a handover never outlives the server, so a handoff still taken was handed back by the stop (each Boton is
+   * told), and requests past their expiry are closed.
+   */
+  recover(): void {
+    const now = nowIso();
+    for (const m of this.#deps.store.openHandoffs(null)) {
+      const h = handoffOf(m)!;
+      if (h.state === 'taken') this.handedBack(m.botId, null, 'the server restarted');
+      else if (!handoffWaiting(h, now)) this.#step(m, { type: 'close', at: now, why: 'nobody took it in time' });
+    }
+  }
+}