codebase-onboarder 0.1.0

package/server/apiSearch.js

@@ -0,0 +1,253 @@
+// POST /api/search — runs a TF-IDF query against the index built at scan
+// time. The work that used to live here (re-listing the tree, re-reading
+// every file, parsing its tokens) now lives in `searchIndex.js`, which
+// `apiScan.js` invokes once when the scan finishes. What is left in this
+// module is the request shape: validate, look up the session, score, send.
+//
+// The pure scoring functions (`buildTfIdfIndex` for one-off in-memory
+// indexes used by tests, and `searchIndex` for the score-and-snippet pass)
+// are still exported so the front end and tests can construct indexes
+// directly when they need to.
+//
+// There are two ways through, and which one a query takes is the point:
+// `searchIndex` answers a query of bare words the forgiving way it always
+// did — partial matches, ranked by TF-IDF — while `searchDocuments` parses
+// the shared query language (`shared/search/query.js`, the same module the
+// palette uses) and enforces anything the person actually decided: filters,
+// phrases, regexes, the case toggle. A half-remembered name should still find
+// the file; `ext:js -vendor` should not be negotiated with.
+
+import { getSession } from './sessions.js';
+import { sendError, sendJSON } from './http.js';
+import {
+  isAdvanced, lineOfIndex, matchesPathFilters, parseQuery, queryIsEmpty,
+  scoreContent, scorePath, snippetAt,
+} from '../shared/search/query.js';
+
+export function buildTfIdfIndex(documents) {
+  // documents: [{ path, content }]
+  const index = new Map();
+  const docCounts = new Map();
+  let totalDocs = 0;
+
+  for (const doc of documents) {
+    if (!doc.content || typeof doc.content !== 'string') continue;
+    const tokens = doc.content.toLowerCase().split(/\W+/).filter((t) => t.length > 1);
+    if (!tokens.length) continue;
+    totalDocs++;
+
+    const tf = new Map();
+    for (const t of tokens) {
+      tf.set(t, (tf.get(t) || 0) + 1);
+    }
+    for (const t of tf.keys()) {
+      docCounts.set(t, (docCounts.get(t) || 0) + 1);
+    }
+    index.set(doc.path, { tf, content: doc.content, tokenCount: tokens.length });
+  }
+
+  return { index, docCounts, totalDocs };
+}
+
+export function searchIndex(indexData, queryString, limit = 10) {
+  if (!indexData || !queryString) return [];
+  const terms = queryString.toLowerCase().split(/\s+/).filter((t) => t.length > 0);
+  if (!terms.length) return [];
+
+  const { index, docCounts, totalDocs } = indexData;
+  if (!totalDocs) return [];
+
+  const idf = new Map();
+  for (const t of terms) {
+    const df = docCounts.get(t) || 0;
+    idf.set(t, df === 0 ? 0 : Math.log(1 + totalDocs / df));
+  }
+
+  const results = [];
+  for (const [docPath, data] of index.entries()) {
+    let score = 0;
+    let matchCount = 0;
+    for (const t of terms) {
+      const tf = data.tf.get(t) || 0;
+      if (tf > 0) {
+        matchCount++;
+        // Normalized TF * IDF
+        score += (tf / Math.sqrt(data.tokenCount)) * (idf.get(t) || 1);
+      }
+    }
+
+    if (score > 0) {
+      // Find best snippet
+      const lowerContent = data.content.toLowerCase();
+      let bestIdx = -1;
+      for (const t of terms) {
+        const idx = lowerContent.indexOf(t);
+        if (idx !== -1 && (bestIdx === -1 || idx < bestIdx)) {
+          bestIdx = idx;
+        }
+      }
+
+      let snippet = '';
+      let line = 1;
+      if (bestIdx !== -1) {
+        const linesBefore = data.content.slice(0, bestIdx).split('\n');
+        line = linesBefore.length;
+        const allLines = data.content.split('\n');
+        const targetLine = (allLines[line - 1] || '').trim();
+        snippet = targetLine.length > 120 ? targetLine.slice(0, 117) + '…' : targetLine;
+      }
+
+      results.push({
+        path: docPath,
+        score: score * (matchCount / terms.length), // Boost docs containing all terms
+        snippet,
+        line,
+      });
+    }
+  }
+
+  results.sort((a, b) => b.score - a.score);
+  return results.slice(0, limit);
+}
+
+// The strict pass: filters are gates, not hints, and every term has to land.
+// Ranking is positional — `scorePath` and `scoreContent` reward the file whose
+// name matches and the file where the word appears early — because a query with
+// a regex or a filter in it is a person who knows what they want, and does not
+// need the corpus statistics of `searchIndex` second-guessing them.
+function strictSearch(indexData, parsed) {
+  // `kind:` is a statement about symbols, and content cannot answer it. A query
+  // that is *only* a kind filter is answered by the palette's symbol pass and
+  // by nothing here, which is the honest result rather than "every file".
+  const kindOnly = parsed.kinds.length > 0
+    && !parsed.terms.length && !parsed.phrases.length && !parsed.regex;
+
+  const results = [];
+  for (const [docPath, doc] of indexData.index.entries()) {
+    if (kindOnly) break;
+    if (!matchesPathFilters(parsed, docPath)) continue;
+
+    const pathScore = scorePath(parsed, docPath);
+    const content = scoreContent(parsed, doc.content);
+    if (!pathScore && !content.score) continue;
+
+    const at = content.index;
+    results.push({
+      path: docPath,
+      score: pathScore + content.score,
+      line: at >= 0 ? lineOfIndex(doc.content, at) : 1,
+      snippet: snippetAt(doc.content, at >= 0 ? at : 0),
+    });
+  }
+
+  results.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+  return results;
+}
+
+// What the index could not read, in the shape the palette can say out loud —
+// "searched 127 files, 3 skipped" beats a mystery file that never turns up.
+function indexStats(indexData) {
+  const skipped = indexData && indexData.skipped;
+  if (!skipped) return null;
+  return { bytes: indexData.totalBytes ?? 0, skipped: { ...skipped }, cap: indexData.cap ?? null };
+}
+
+// The serializable half of a parsed query. `parsed.regex` is a RegExp and would
+// go over the wire as `{}`, so the pattern travels as the text it was typed as.
+function querySummary(parsed) {
+  return {
+    terms: parsed.terms,
+    phrases: parsed.phrases,
+    negatives: parsed.negatives,
+    exts: parsed.exts,
+    paths: parsed.paths,
+    kinds: parsed.kinds,
+    isTest: parsed.isTest,
+    isSource: parsed.isSource,
+    regex: parsed.regexSource ? `/${parsed.regexSource}/${parsed.regexFlags}` : null,
+    caseSensitive: parsed.caseSensitive,
+    advanced: isAdvanced(parsed),
+  };
+}
+
+// The one entry point the route uses, kept separate from `searchIndex` so the
+// forgiving ranking that shipped first survives intact: a query of bare words
+// is still answered by that function, partial matches and all. Only a query the
+// person made decisions in — a filter, a phrase, a regex, the case toggle —
+// goes down the strict path, where those decisions are enforced.
+export function searchDocuments(indexData, rawQuery, options = {}) {
+  const limit = Number.isFinite(options.limit) ? Math.max(1, Math.floor(options.limit)) : 15;
+  const parsed = parseQuery(rawQuery, { caseSensitive: !!options.caseSensitive });
+  const advanced = isAdvanced(parsed);
+  const base = {
+    results: [],
+    total: 0,
+    indexed: indexData?.totalDocs ?? 0,
+    capped: false,
+    advanced,
+    query: querySummary(parsed),
+    error: parsed.error,
+    stats: indexStats(indexData),
+  };
+
+  if (!indexData || !indexData.totalDocs) return base;
+  if (queryIsEmpty(parsed)) return base;
+  // A pattern that would not compile is the whole answer. Reporting "no
+  // results" instead would send someone hunting for a file sitting right there.
+  if (parsed.error) return base;
+
+  if (!advanced) {
+    const ranked = searchIndex(indexData, parsed.terms.join(' '), limit);
+    return { ...base, results: ranked, total: ranked.length, capped: ranked.length >= limit };
+  }
+
+  const all = strictSearch(indexData, parsed);
+  return {
+    ...base,
+    results: all.slice(0, limit),
+    total: all.length,
+    capped: all.length > limit,
+  };
+}
+
+export async function handleSearch(res, body) {
+  const { scanId, query, limit = 15, caseSensitive = false } = body || {};
+  if (!scanId) return sendError(res, 400, 'Missing scanId.');
+  const session = getSession(scanId);
+  if (!session) return sendError(res, 404, 'Scan not found.');
+
+  const q = (query || '').trim();
+  if (!q) {
+    return sendJSON(res, 200, { results: [], total: 0, indexed: session.searchIndex?.totalDocs ?? 0 });
+  }
+
+  // No index means the scan was opened before this change shipped, or the
+  // caller is using a session that was never given a scan-time index. The
+  // honest answer is "no results" rather than rebuilding the whole thing on
+  // the request thread.
+  if (!session.searchIndex || session.searchIndex.totalDocs === 0) {
+    return sendJSON(res, 200, {
+      results: [],
+      total: 0,
+      indexed: 0,
+      note: 'Nothing was indexed for this scan.',
+    });
+  }
+
+  try {
+    const out = searchDocuments(session.searchIndex, q, { limit, caseSensitive });
+    return sendJSON(res, 200, {
+      results: out.results,
+      total: out.total,
+      indexed: out.indexed,
+      capped: out.capped,
+      advanced: out.advanced,
+      query: out.query,
+      error: out.error || null,
+      stats: out.stats || null,
+    });
+  } catch (err) {
+    return sendError(res, 500, 'Search failed: ' + err.message);
+  }
+}
+

package/server/apiSettings.js

@@ -0,0 +1,118 @@
+// The settings endpoints: read the public shape, apply a patch, rotate the key.
+//
+// All three go through `server/config.js` for validation and the atomic 0600
+// write, so the CLI wizard, `onboarder config set`, and this API can never save
+// three dialects of the same file. What lives here is only what HTTP adds:
+// status codes, the secret-handling rules (never read the key back out, show a
+// new one exactly once), and the restart hint — the running server bound its
+// socket at boot, so a host/port change is real but not yet in effect.
+
+import {
+  DEFAULT_SETTINGS, generateAccessKey, normalizeSettings, publicSettings,
+  readSettings, updateSettings, writeSettings, configPath,
+} from './config.js';
+import { sendError, sendJSON } from './http.js';
+import { tunnelStatus } from './tunnel.js';
+
+// Where this request's settings live. The router's config object carries the
+// path when the server was booted with one; tests and a bare `createServer()`
+// get the defaults-in-memory view instead of somebody's home directory.
+function settingsFile(config) {
+  return config?.configPath || null;
+}
+
+async function currentSettings(config) {
+  if (typeof config?.getSettings === 'function') return config.getSettings();
+  const file = settingsFile(config);
+  if (file) return readSettings(file);
+  return { ...DEFAULT_SETTINGS, account: { ...DEFAULT_SETTINGS.account }, tunnel: { ...DEFAULT_SETTINGS.tunnel } };
+}
+
+// The public body every read returns: settings with the secret masked, plus
+// the connection picture (URLs, tunnel status) the drawer and CLI both render.
+async function publicBody(config) {
+  const settings = await currentSettings(config);
+  return {
+    settings: publicSettings(settings),
+    configFile: settingsFile(config) || configPath(),
+    node: process.version,
+    tunnels: tunnelStatus(settings),
+  };
+}
+
+export async function handleGetSettings(req, res, config) {
+  try {
+    sendJSON(res, 200, await publicBody(config));
+  } catch (err) {
+    sendError(res, 500, err.message || 'The settings could not be read.');
+  }
+}
+
+// Which changes the running server cannot absorb. Auth, domain, and tunnel
+// flags are read live from disk on each request; the bind is a socket that
+// already exists.
+function restartRequired(config, next) {
+  const boot = config?.boot;
+  if (!boot) return [];
+  const changed = [];
+  if (next.host !== boot.host) changed.push('host');
+  if (next.port !== boot.port) changed.push('port');
+  return changed;
+}
+
+export async function handleUpdateSettings(res, body, config) {
+  const file = settingsFile(config);
+  if (!file) {
+    return sendError(res, 400, 'This server was started without a config file, so there is nothing to save to.');
+  }
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return sendError(res, 400, 'Send a JSON object of settings to change.');
+  }
+  // Only known keys may be patched — a typo like "ports" must be a loud 400,
+  // not a silently ignored write that the UI then claims it saved.
+  const allowed = new Set(['mode', 'host', 'port', 'domain', 'autoOpen', 'account', 'tunnel']);
+  const unknown = Object.keys(body).filter((k) => k !== 'accessKey' && !allowed.has(k));
+  if (unknown.length) {
+    return sendError(res, 400, `Unknown setting${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}.`);
+  }
+  if ('accessKey' in body) {
+    return sendError(res, 400, 'The access key is rotated, not patched — POST /api/settings/access-key.');
+  }
+  try {
+    const next = await updateSettings(body, file);
+    sendJSON(res, 200, {
+      settings: publicSettings(next),
+      restartRequired: restartRequired(config, next),
+    });
+  } catch (err) {
+    sendError(res, 400, err.message || 'Those settings did not validate.');
+  }
+}
+
+// Rotation returns the new key in the clear, once. It is never in a GET after
+// that — `hasAccessKey`/`accessKeyMasked` are all the readback there is. The
+// person copies it from this response into the devices that need it.
+export async function handleRotateAccessKey(res, config) {
+  const file = settingsFile(config);
+  if (!file) {
+    return sendError(res, 400, 'This server was started without a config file, so there is nothing to save to.');
+  }
+  try {
+    const accessKey = generateAccessKey();
+    const current = await currentSettings(config);
+    const next = await writeSettings({ ...current, accessKey }, file);
+    sendJSON(res, 200, {
+      accessKey,
+      settings: publicSettings(next),
+      note: 'Shown once. Update every device that connects remotely; the old key is dead.',
+    });
+  } catch (err) {
+    sendError(res, 400, err.message || 'The key could not be rotated.');
+  }
+}
+
+// Kept exported for the tests: a patch that survives normalizeSettings is the
+// same patch the wizard and the API would both accept.
+export function validatePatch(patch) {
+  return normalizeSettings({ ...DEFAULT_SETTINGS, ...patch });
+}

package/server/apiTools.js

@@ -0,0 +1,90 @@
+// GET /api/tools  — which analyzers this machine can run, for the engines panel.
+// POST /api/tools/run — run the available analyzers against a live scan and
+// return the normalized findings.
+//
+// The scan id is a capability the same way it is for `/api/file`: it names a
+// root the person chose, and the analyzers are run inside that root and nowhere
+// else. `tools.js` spawns with argument arrays and hard timeouts, so a crafted
+// path becomes an argument and a hung tool becomes a failed pass, not a stuck
+// server.
+
+import { sendError, sendJSON } from './http.js';
+import { getSession } from './sessions.js';
+import { runExternalAnalysis, toolsStatus } from './tools/scan.js';
+import { installTool, isInstalling, plansFor } from './tools/install.js';
+import { TOOL_DEFS } from './tools/registry.js';
+
+const KNOWN_TOOLS = new Set(TOOL_DEFS.map((d) => d.id));
+
+export function handleToolsStatus(res) {
+  sendJSON(res, 200, { tools: toolsStatus() });
+}
+
+export async function handleToolsRun(res, body) {
+  const { scanId, kinds, tools, options } = body || {};
+  if (!scanId) return sendError(res, 400, 'Missing scanId.');
+  const session = getSession(scanId);
+  if (!session) return sendError(res, 404, 'That scan is gone. Rescan the repo.');
+
+  // `kinds` narrows by purpose, `tools` to named engines. An unknown value is a
+  // typo the caller would rather hear about than have silently ignored.
+  let kindFilter = null;
+  if (Array.isArray(kinds) && kinds.length) {
+    const ok = kinds.filter((k) => k === 'security' || k === 'dead-code');
+    if (!ok.length) return sendError(res, 400, 'kinds must be "security" and/or "dead-code".');
+    kindFilter = ok;
+  }
+  let toolFilter = null;
+  if (Array.isArray(tools) && tools.length) {
+    toolFilter = tools.map((t) => String(t));
+  }
+
+  // `options` is the per-engine GUI form. Validation happens against the
+  // registry schema inside the run — the handler just passes it along.
+  const report = await runExternalAnalysis(session.root, {
+    kinds: kindFilter, tools: toolFilter, options,
+  });
+  return sendJSON(res, 200, report);
+}
+
+// POST /api/tools/install — install a missing engine, streaming progress.
+//
+// This is the one endpoint that changes the machine, so it is worth spelling
+// out why that is safe enough for a local, self-hosted app:
+//
+//   * The route is a POST, which the router's same-origin gate already
+//     refuses for any page that is not Onboarder's own — a foreign tab cannot
+//     drive it.
+//   * `tool` must name a registry entry; the install plans are fixed data in
+//     `tools/install.js`, spawned as argument arrays. Nothing from the
+//     request body ever becomes part of a command line.
+//   * The stream is SSE in the same `data:`-framed shape the explain proxy
+//     uses, so the front end reads install progress exactly like AI output.
+export async function handleToolsInstall(res, body) {
+  const tool = String(body?.tool || '');
+  if (!KNOWN_TOOLS.has(tool)) {
+    return sendError(res, 400, `Unknown tool "${tool}". Known: ${[...KNOWN_TOOLS].join(', ')}.`);
+  }
+  if (!plansFor(tool).length) {
+    return sendError(res, 400, `Onboarder has no install plan for ${tool} on ${process.platform}.`);
+  }
+  if (isInstalling(tool)) {
+    return sendError(res, 409, `${tool} is already being installed.`);
+  }
+
+  res.writeHead(200, {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-cache',
+    connection: 'keep-alive',
+  });
+  const send = (event) => {
+    try { res.write('data: ' + JSON.stringify(event) + '\n\n'); } catch { /* client went away */ }
+  };
+
+  try {
+    await installTool(tool, send);
+  } catch (err) {
+    send({ type: 'done', ok: false, error: err.message || 'The install failed.' });
+  }
+  res.end();
+}

package/server/config.js

@@ -0,0 +1,227 @@
+// Durable, user-scoped settings for the CLI/server. This file deliberately does
+// not know about HTTP: the CLI and the settings API use the same validation and
+// write path so a browser can change a setting without inventing a second schema.
+
+import { promises as fs } from 'node:fs';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+
+export const CONFIG_VERSION = 1;
+export const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+export const DEFAULT_SETTINGS = Object.freeze({
+  version: CONFIG_VERSION,
+  mode: 'local',
+  host: '127.0.0.1',
+  port: 4310,
+  domain: '',
+  accessKey: '',
+  // Whether `onboarder start` opens the app in a browser once it is listening.
+  // Off in the schema so `npm start` from a checkout stays quiet; the setup
+  // wizard offers to turn it on, which is where the people who want it are.
+  autoOpen: false,
+  account: Object.freeze({ name: '', email: '', provider: 'openai-compatible', baseUrl: '', model: '' }),
+  tunnel: Object.freeze({ cloudflare: false, tailscale: false }),
+});
+
+export function configHome(env = process.env) {
+  if (env.XDG_CONFIG_HOME) return path.resolve(env.XDG_CONFIG_HOME, 'onboarder');
+  return path.join(os.homedir(), '.config', 'onboarder');
+}
+
+export function configPath(env = process.env) {
+  // An explicit override first: the CLI's --config flag and the test suite both
+  // need a config file that is not the one in the person's home directory.
+  if (env.ONBOARDER_CONFIG) return path.resolve(env.ONBOARDER_CONFIG);
+  return path.join(configHome(env), 'config.json');
+}
+
+export function isLoopbackHost(host) {
+  return LOOPBACK_HOSTS.has(String(host || '').trim().toLowerCase());
+}
+
+function cleanString(value, max = 240) {
+  return String(value ?? '').trim().slice(0, max);
+}
+
+function normalizePort(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Port must be a whole number from 1 to 65535.');
+  return port;
+}
+
+function normalizeDomain(value) {
+  const domain = cleanString(value).toLowerCase();
+  if (!domain) return '';
+  if (domain.length > 253 || domain.includes('/') || domain.includes('\\') || domain.includes(' ') || domain.includes('@') || domain.startsWith('.')) {
+    throw new Error('Domain must be a hostname such as map.example.com.');
+  }
+  return domain;
+}
+
+function normalizeAccount(value = {}) {
+  return {
+    name: cleanString(value.name, 80),
+    email: cleanString(value.email, 160),
+    provider: cleanString(value.provider || 'openai-compatible', 80),
+    baseUrl: cleanString(value.baseUrl, 500),
+    model: cleanString(value.model, 160),
+  };
+}
+
+function normalizeTunnel(value = {}) {
+  return { cloudflare: Boolean(value.cloudflare), tailscale: Boolean(value.tailscale) };
+}
+
+export function normalizeSettings(value = {}) {
+  const mode = value.mode === 'self-hosted' ? 'self-hosted' : 'local';
+  const host = cleanString(value.host || DEFAULT_SETTINGS.host, 120);
+  const settings = {
+    version: CONFIG_VERSION,
+    mode,
+    host,
+    port: normalizePort(value.port ?? DEFAULT_SETTINGS.port),
+    domain: normalizeDomain(value.domain),
+    accessKey: cleanString(value.accessKey, 256),
+    autoOpen: value.autoOpen === undefined ? DEFAULT_SETTINGS.autoOpen : Boolean(value.autoOpen),
+    account: normalizeAccount(value.account),
+    tunnel: normalizeTunnel(value.tunnel),
+  };
+  if (!host) throw new Error('Host cannot be empty.');
+  if (settings.mode === 'local' && !isLoopbackHost(settings.host)) {
+    throw new Error('Local mode only binds to 127.0.0.1, localhost, or ::1. Choose self-hosted mode for a network bind.');
+  }
+  if (settings.mode === 'self-hosted' && !isLoopbackHost(settings.host) && !settings.domain) {
+    throw new Error('A self-hosted network bind needs a domain (or keep the server on loopback behind a tunnel).');
+  }
+  return settings;
+}
+
+export function generateAccessKey() {
+  return `ob_${randomBytes(32).toString('base64url')}`;
+}
+
+// Every URL a person might reach this server through, derived from the settings
+// so the CLI banner, the settings drawer, and `onboarder config` never disagree
+// about what to print.
+export function serverUrls(value = DEFAULT_SETTINGS) {
+  const settings = normalizeSettings(value);
+  const urls = { local: `http://localhost:${settings.port}` };
+  if (!isLoopbackHost(settings.host)) {
+    urls.network = settings.host === '0.0.0.0' || settings.host === '::'
+      ? `http://<this-machine>:${settings.port} (every interface)`
+      : `http://${settings.host}:${settings.port}`;
+  }
+  if (settings.domain) urls.domain = `https://${settings.domain}`;
+  return urls;
+}
+
+// The key, safe to print in a list: enough to recognize it, not enough to use it.
+export function maskAccessKey(key) {
+  const value = String(key || '');
+  if (value.length <= 8) return value ? '…' : '';
+  return `${value.slice(0, 6)}…${value.slice(-4)}`;
+}
+
+export function publicSettings(value = DEFAULT_SETTINGS) {
+  const settings = normalizeSettings(value);
+  return {
+    version: settings.version,
+    mode: settings.mode,
+    host: settings.host,
+    port: settings.port,
+    domain: settings.domain,
+    autoOpen: settings.autoOpen,
+    hasAccessKey: Boolean(settings.accessKey),
+    accessKeyMasked: maskAccessKey(settings.accessKey),
+    account: settings.account,
+    tunnel: settings.tunnel,
+    urls: serverUrls(settings),
+    security: {
+      remoteAuth: settings.mode === 'self-hosted',
+      loopback: isLoopbackHost(settings.host),
+    },
+  };
+}
+
+// Hostnames the rebinding guard should accept beyond loopback: the configured
+// domain, and a non-loopback bind address itself. A loopback-only local server
+// gets an empty list, which is exactly the old behavior.
+//
+// Enabled tunnels add wildcard suffixes: a Cloudflare quick tunnel's name is
+// random (https://<something>.trycloudflare.com) and a Tailscale machine name
+// belongs to the tailnet, so neither can be configured ahead of time. This is
+// safe because it can only widen Host acceptance in self-hosted mode, where
+// every API call already needs the access key — the guard's job there is
+// keeping drive-by traffic off the static files, not authentication.
+export function allowedHosts(value = DEFAULT_SETTINGS) {
+  const settings = normalizeSettings(value);
+  const hosts = new Set();
+  if (settings.domain) hosts.add(settings.domain);
+  if (!isLoopbackHost(settings.host)) hosts.add(settings.host.toLowerCase());
+  if (settings.tunnel.cloudflare) hosts.add('*.trycloudflare.com');
+  if (settings.tunnel.tailscale) hosts.add('*.ts.net');
+  return [...hosts];
+}
+
+export function accessKeysMatch(expected, actual) {
+  const a = Buffer.from(String(expected || ''));
+  const b = Buffer.from(String(actual || ''));
+  return a.length > 0 && a.length === b.length && timingSafeEqual(a, b);
+}
+
+export function bearerToken(req) {
+  const value = String(req.headers?.authorization || '');
+  const match = value.match(/^Bearer\s+(.+)$/i);
+  return match ? match[1].trim() : '';
+}
+
+export function authReason(req, settings = DEFAULT_SETTINGS) {
+  const normalized = normalizeSettings(settings);
+  if (normalized.mode !== 'self-hosted') return null;
+  if (!normalized.accessKey) return 'Self-hosted mode has no access key configured.';
+  const token = bearerToken(req);
+  if (!accessKeysMatch(normalized.accessKey, token)) return 'A valid access key is required.';
+  return null;
+}
+
+// Has a config ever been written? The wizard asks this to decide between
+// "start from the defaults" and "start from what you already have".
+export async function configExists(file = configPath()) {
+  try {
+    await fs.access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+
+export async function readSettings(file = configPath()) {
+  try {
+    const raw = await fs.readFile(file, 'utf8');
+    return normalizeSettings(JSON.parse(raw));
+  } catch (err) {
+    if (err.code === 'ENOENT') return { ...DEFAULT_SETTINGS, account: { ...DEFAULT_SETTINGS.account }, tunnel: { ...DEFAULT_SETTINGS.tunnel } };
+    if (err instanceof SyntaxError) throw new Error(`Config is not valid JSON: ${file}`);
+    throw err;
+  }
+}
+
+export async function writeSettings(value, file = configPath()) {
+  const settings = normalizeSettings(value);
+  const dir = path.dirname(file);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  const body = JSON.stringify(settings, null, 2) + '\n';
+  await fs.writeFile(temp, body, { encoding: 'utf8', mode: 0o600 });
+  await fs.rename(temp, file);
+  await fs.chmod(file, 0o600);
+  return settings;
+}
+
+export async function updateSettings(patch = {}, file = configPath()) {
+  const current = await readSettings(file);
+  const next = normalizeSettings({ ...current, ...patch, account: { ...current.account, ...(patch.account || {}) }, tunnel: { ...current.tunnel, ...(patch.tunnel || {}) } });
+  return writeSettings(next, file);
+}