tinywebui 0.1.0

package/src/routes/mcp.js

@@ -0,0 +1,59 @@
+import { json, readJson, UPLOAD_LIMIT } from '../http.js';
+import { LockedError } from '../config/config.js';
+import { fingerprint } from '../access/policy.js';
+import { actor } from '../access/auth_gate.js';
+import { toolList } from './settings.js';
+import { logger } from '../log.js';
+import { FEATURE } from '../../public/shared/features.js';
+
+const log = logger('mcp');
+
+export function mcpRoutes({ auditMcp, config, hub, source, swapHub }) {
+
+  /** Writes mcp.json (audited), then reconnects. A locked or invalid file is the caller's error. */
+  const saveAndReconnect = async (res, text, auth) => {
+    let servers;
+    try {
+      const before = fingerprint(config(), source.loadMcpServers());
+      servers = source.saveMcpFile(text);
+      auditMcp(actor(auth), before);
+    } catch (err) {
+      json(res, err instanceof LockedError ? 409 : 400, { error: err.message });
+      return false;
+    }
+    await swapHub(servers);
+    log.info(`reloaded: ${hub().tools.length} tool(s)`);
+    return true;
+  };
+
+  return [
+    // mcp.json can hold server credentials (env, headers): admins only.
+    { method: 'GET', path: /^\/api\/mcp$/, feature: FEATURE.MCP, handle: ({ res }) =>
+      json(res, 200, { path: source.mcpPath(), text: source.readMcpFile(), locked: source.mcpLocked }) },
+
+    { method: 'POST', path: /^\/api\/mcp$/, feature: FEATURE.MCP, handle: async ({ req, res, auth }) => {
+      const { text } = await readJson(req, UPLOAD_LIMIT);
+      if (!await saveAndReconnect(res, text, auth)) return undefined;
+      return json(res, 200, { tools: toolList(hub()), mcpErrors: hub().errors });
+    } },
+
+    // Disabling a server tears its connection down rather than filtering its
+    // tools out client-side: an unwanted server is one fewer child process or
+    // open connection, not just one the model happens not to be offered.
+    { method: 'POST', path: /^\/api\/mcp\/servers\/([^/]+)\/toggle$/, feature: FEATURE.MCP, handle: async ({ req, res, auth, params: [rawName] }) => {
+      const name = decodeURIComponent(rawName);
+      const { disabled } = await readJson(req);
+      let servers;
+      try {
+        const parsed = JSON.parse(source.readMcpFile());
+        servers = parsed.mcpServers || parsed;
+      } catch (err) {
+        return json(res, 500, { error: `mcp.json is not valid JSON: ${err.message}` });
+      }
+      if (!servers[name]) return json(res, 404, { error: `no such server "${name}"` });
+      servers[name] = { ...servers[name], disabled: Boolean(disabled) };
+      if (!await saveAndReconnect(res, JSON.stringify({ mcpServers: servers }, null, 2), auth)) return undefined;
+      return json(res, 200, { ...hub().inventory(config().disabledTools), disabledTools: config().disabledTools || [] });
+    } }
+  ];
+}

package/src/routes/settings.js

@@ -0,0 +1,101 @@
+import { json, readJson } from '../http.js';
+import { isClosed, enabledEntries, publicEntry } from '../config/models.js';
+import { modelsFor } from '../access/policy.js';
+import { audit } from '../audit.js';
+import { setOverride } from '../config/approval.js';
+import { actor } from '../access/auth_gate.js';
+import { FEATURE } from '../../public/shared/features.js';
+
+export const toolList = (hub) => hub.tools.map((t) => ({
+  name: t.function.name,
+  description: t.function.description,
+  parameters: t.function.parameters
+}));
+
+export function settingsRoutes({ config, configFor, hub, saveConfig, toolsView }) {
+  // The provider's model list, cached per endpoint for a few minutes:
+  // OpenRouter's list is large and the picker is opened far more often than
+  // the catalogue changes.
+  let modelCache = null;
+  const listModels = async () => {
+    const cfg = config();
+    const key = `${cfg.baseUrl}|${Boolean(cfg.apiKey)}`;
+    if (modelCache?.key === key && Date.now() - modelCache.at < 5 * 60_000) return modelCache.value;
+    let value;
+    try {
+      const r = await fetch(`${cfg.baseUrl}/models`, {
+        headers: cfg.apiKey ? { authorization: `Bearer ${cfg.apiKey}` } : {},
+        signal: AbortSignal.timeout(8000)
+      });
+      if (!r.ok) throw new Error(`${r.status} from ${cfg.baseUrl}/models`);
+      const body = await r.json();
+      const rows = Array.isArray(body?.data) ? body.data : Array.isArray(body?.models) ? body.models : [];
+      const models = rows
+        .map((m) => ({ id: m.id || m.name, name: m.name && m.name !== m.id ? m.name : null }))
+        .filter((m) => typeof m.id === 'string' && m.id)
+        .sort((a, b) => a.id.localeCompare(b.id));
+      value = { supported: models.length > 0, models };
+    } catch (err) {
+      value = { supported: false, models: [], error: err.message };
+    }
+    modelCache = { key, at: Date.now(), value };
+    return value;
+  };
+
+  return [
+    { method: 'GET', path: /^\/api\/config$/, feature: null, handle: ({ res, auth }) => json(res, 200, {
+      ...configFor(auth),
+      tools: toolList(hub()),
+      mcpErrors: hub().errors
+    }) },
+
+    { method: 'POST', path: /^\/api\/config$/, feature: FEATURE.SETTINGS, handle: async ({ req, res, auth }) => {
+      saveConfig(await readJson(req), actor(auth));
+      audit('admin.config_changed', { by: auth.userId ?? null });
+      return json(res, 200, configFor(auth));
+    } },
+
+    // The provider's own model list, for the composer's model picker. Not
+    // every OpenAI-compatible endpoint serves /models, so a failure is an
+    // answer too: the picker falls back to typing an id.
+    { method: 'GET', path: /^\/api\/models$/, feature: FEATURE.MODEL_PICKER, handle: async ({ res, auth }) => {
+      const cfg = config();
+      const allowed = modelsFor(cfg, auth.role);
+      // A catalog is the whole list: its labels, never the provider's ids.
+      if (isClosed(cfg)) {
+        const entries = enabledEntries(cfg).filter((e) => allowed === '*' || allowed.includes(e.id));
+        return json(res, 200, { supported: true, restricted: true, catalog: true, models: entries.map(publicEntry) });
+      }
+      const all = await listModels();
+      if (allowed === '*') return json(res, 200, all);
+      // A fixed catalog: only those ids, named from the provider list when
+      // it knows them, listed even when it does not.
+      const byId = new Map(all.models.map((m) => [m.id, m]));
+      return json(res, 200, { supported: true, restricted: true, models: allowed.map((id) => byId.get(id) || { id, name: null }) });
+    } },
+
+    // The grouped view behind the tools panel: built-ins, and every MCP
+    // server's tools under it with that server's connection health.
+    { method: 'GET', path: /^\/api\/tools$/, feature: FEATURE.TOOLS, handle: ({ res }) => json(res, 200, toolsView()) },
+
+    // Per-tool approval override from the settings panel: 'ask', 'auto', or
+    // 'default' to fall back to the global toolApproval mode.
+    { method: 'POST', path: /^\/api\/tools\/approval$/, feature: FEATURE.TOOLS, handle: async ({ req, res, auth }) => {
+      const { name, policy } = await readJson(req);
+      if (!name || !['ask', 'auto', 'default'].includes(policy)) {
+        return json(res, 400, { error: 'name and policy (ask | auto | default) are required' });
+      }
+      saveConfig(setOverride(config(), name, policy), actor(auth));
+      return json(res, 200, toolsView());
+    } },
+
+    { method: 'POST', path: /^\/api\/tools\/toggle$/, feature: FEATURE.TOOLS, handle: async ({ req, res, auth }) => {
+      const { name, disabled } = await readJson(req);
+      if (!name) return json(res, 400, { error: 'name is required' });
+      const set = new Set(config().disabledTools || []);
+      if (disabled) set.add(name); else set.delete(name);
+      saveConfig({ disabledTools: [...set] }, actor(auth));
+      return json(res, 200, toolsView());
+    } }
+  ];
+}

package/src/server.js

@@ -0,0 +1,397 @@
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { watch, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { createConfigSource, LockedError, configProblems } from './config/config.js';
+import { McpHub } from './mcp.js';
+import { isClosed, findEntry } from './config/models.js';
+import { Store, SCHEMA_VERSION } from './store/index.js';
+import { fingerprint, featuresFor, modelsFor } from './access/policy.js';
+import { hashPassword, applyAccessPolicy } from './access/auth.js';
+import { audit } from './audit.js';
+import { logger } from './log.js';
+import { resolveAuth, OWNER_ID } from './access/auth_gate.js';
+import { json, HttpError, SECURITY_HEADERS, crossSite, serveStatic } from './http.js';
+import { expandToolDef, callExpand } from './tools/context_tool.js';
+import { documentToolDef, callReadDocument } from './tools/document_tool.js';
+import { askToolDef, callAskUser } from './tools/ask_tool.js';
+import { chatSearchToolDef, callSearchChats } from './tools/chat_search_tool.js';
+import { taskToolDef, callManageTasks } from './tools/task_tool.js';
+import { automationToolDef, manageAutomation } from './automations/automation.js';
+import { overrideFor } from './config/approval.js';
+import { Retrieval } from './retrieval/retrieval.js';
+import { loadEmbedder, resolveRetrieval, defaultModelsDir } from './retrieval/embedding.js';
+import { createRuns } from './chat/runs.js';
+import { createScheduler } from './automations/scheduler.js';
+import { authRoutes } from './routes/auth.js';
+import { settingsRoutes } from './routes/settings.js';
+import { mcpRoutes } from './routes/mcp.js';
+import { libraryRoutes } from './routes/library.js';
+import { automationRoutes } from './routes/automations.js';
+import { documentRoutes } from './routes/documents.js';
+import { chatRoutes } from './routes/chats.js';
+import { adminRoutes } from './routes/admin.js';
+import { EVENT } from '../public/shared/events.js';
+import { FEATURE } from '../public/shared/features.js';
+
+const log = logger('server');
+
+const VERSION = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+/**
+ * Every API route, with the feature it needs (null: any signed-in caller, or
+ * anyone for the pre-auth routes the auth gate lets through). Dispatch and
+ * permission are the same table, so a route cannot ship without a decision
+ * about who may use it. First match wins.
+ */
+function routeTable(app) {
+  // What route groups may ask for. Each group's signature names the part it
+  // uses; config, hub and passwordHash change at runtime, so they are read
+  // through accessors rather than captured.
+  const deps = {
+    store: app.store, runs: app.runs, scheduler: app.scheduler, retrieval: app.retrieval,
+    source: app.source, version: app.version,
+    config: () => app.cfg, hub: () => app.hub, passwordHash: () => app.passwordHash,
+    saveConfig: (patch, by) => app.saveConfig(patch, by), refreshConfig: () => app.refreshConfig(),
+    auditMcp: (by, before) => app.auditMcp(by, before), swapHub: (servers) => app.swapHub(servers),
+    multiUser: () => app.multiUser(), modelFor: (userId, role) => app.modelFor(userId, role),
+    toolsFor: (features) => app.toolsFor(features), toolsView: () => app.toolsView(), configFor: (auth) => app.configFor(auth)
+  };
+  return [
+    ...authRoutes(deps), ...settingsRoutes(deps), ...mcpRoutes(deps), ...libraryRoutes(deps),
+    ...automationRoutes(deps), ...documentRoutes(deps), ...chatRoutes(deps), ...adminRoutes(deps)
+  ];
+}
+
+// Handlers only read their dependencies when called, so a stub lists the table.
+export const API_ROUTES = routeTable({}).map((r) => [r.method, r.path, r.feature]);
+
+// Fields a non-admin never sees: credentials, and where the deployment's
+// trust boundary sits.
+const ADMIN_ONLY_FIELDS = /^(apiKey|authPassword|sessionSecret|google|baseUrl|trusted|adminEmails|models$)/;
+
+/**
+ * Starts an instance. Everything but port/host is optional and passed to
+ * createConfigSource: `config` (keys set here win and are locked in the UI),
+ * `configFile` (a path, or false for none), `mcpServers`, `mcpFile`, `dbPath`.
+ */
+export async function start({ port = 7777, host = '127.0.0.1', ...sourceOpts } = {}) {
+  const source = createConfigSource(sourceOpts);
+  const initial = source.load();
+  const problems = configProblems(initial);
+  if (problems.length) throw new Error(problems.join('\n'));
+
+  const store = new Store(source.dbPath(initial), { migrate: initial.autoMigrate !== false });
+  // Runs live in this process, so nothing from before it can still be waiting.
+  store.chats.expireQuestions();
+  if (store.migratedFrom !== null && store.migratedFrom < SCHEMA_VERSION) {
+    log.info(`migrated database from schema ${store.migratedFrom} to ${SCHEMA_VERSION}`);
+  }
+  if (initial.authMode === 'trusted-header') applyAccessPolicy(store, initial);
+
+  // The embedding bundle loads now, so a problem with it stops startup with a
+  // clear message instead of surfacing on the first search -- except under
+  // 'auto', where a model that simply isn't installed means lexical.
+  let resolved;
+  try {
+    const load = sourceOpts.embedder ? async () => sourceOpts.embedder : loadEmbedder;
+    resolved = await resolveRetrieval(initial.retrieval, defaultModelsDir(source.path()), load);
+  } catch (err) { store.close(); throw err; }
+  const { embedder } = resolved;
+  if (resolved.fallback) log.warn(`retrieval: lexical only -- ${resolved.fallback}`);
+  else if (embedder) log.info(`retrieval: ${resolved.mode} with ${embedder.spec?.repoId || initial.retrieval.model} (${embedder.dim} dims)`);
+
+  if (initial.authMode === 'single') store.users.ensureOwner(OWNER_ID);
+
+  /**
+   * What every part of the server shares. `cfg` and `hub` are replaced, not
+   * mutated, when settings are saved or files reload, so read them from here
+   * at use time rather than holding on to them.
+   */
+  const app = {
+    version: VERSION,
+    source,
+    store,
+    retrieval: new Retrieval(store, { ...initial.retrieval, mode: resolved.mode }, embedder),
+    cfg: initial,
+    hub: null,
+    // 'single': the stored hash, or one made in memory from $TINYWEBUI_PASSWORD
+    // (handy for containers). validateConfig already refused a plaintext one.
+    passwordHash: initial.authMode === 'single' ? initial.authPassword || hashPassword(process.env.TINYWEBUI_PASSWORD) : null,
+
+    // Every UI/API change lands in config.json (source.save) and is audited:
+    // who, which keys, the new values (none of these keys are secrets), and the
+    // config fingerprint before and after, to line up with a git diff.
+    saveConfig(patch, by) {
+      const before = fingerprint(app.cfg, source.loadMcpServers());
+      app.cfg = source.save(patch);
+      audit('config.changed', { by: by ?? 'local', keys: Object.keys(patch), values: patch, before, after: fingerprint(app.cfg, source.loadMcpServers()) });
+      return app.cfg;
+    },
+    /** Re-reads the config after something other than saveConfig wrote the file. */
+    refreshConfig() {
+      app.cfg = source.load();
+    },
+    auditMcp: (by, before) => audit('mcp.changed', { by: by ?? 'local', before, after: fingerprint(app.cfg, source.loadMcpServers()) }),
+
+    multiUser: () => app.cfg.authMode === 'trusted-header',
+
+    /**
+     * The model a person's turns use. Tiers 1-2: the configured model. Tier 3:
+     * their own pick if their role still allows it, else the configured model
+     * if allowed, else the first model their role allows.
+     */
+    modelFor(userId, role) {
+      const { cfg } = app;
+      // With a catalog, everything is an entry id; a provider id (as the
+      // default `model` may be) is resolved to its entry.
+      const known = (m) => (isClosed(cfg) ? findEntry(cfg, m)?.id : m);
+      const fallback = known(cfg.model) || cfg.model;
+      if (cfg.authMode !== 'trusted-header' || !userId) return fallback;
+      const allowed = modelsFor(cfg, role);
+      const ok = (m) => m && (allowed === '*' || allowed.includes(m));
+      const pref = known(store.users.getPrefs(userId).model);
+      if (ok(pref)) return pref;
+      if (ok(fallback)) return fallback;
+      // First of the role's models still enabled (a parked one never runs).
+      return allowed.map(known).find(Boolean) || fallback;
+    },
+
+    /** The tools a turn gets: what is switched on, minus manage_automation for
+     * anyone whose role has no automations. */
+    toolsFor: (features) => app.hub.activeTools(app.cfg.disabledTools)
+      .filter((t) => features.has(FEATURE.AUTOMATIONS) || t.function.name !== 'manage_automation'),
+
+    /** A stored owner's features: null (tiers 1-2) is the one person. */
+    ownerFeatures: (userId) => featuresFor(app.cfg, userId ? store.users.get(userId)?.role : null),
+
+    /** The tools panel payload: inventory plus each tool's approval state. */
+    toolsView() {
+      const { cfg, hub } = app;
+      const inv = hub.inventory(cfg.disabledTools);
+      const mark = (t) => ({ ...t, approval: overrideFor(cfg, t.name) });
+      return {
+        // Built-ins never ask, so they carry no approval state to show.
+        internal: inv.internal,
+        servers: inv.servers.map((s) => ({ ...s, tools: s.tools.map(mark) })),
+        disabledTools: cfg.disabledTools || [],
+        toolApproval: cfg.toolApproval
+      };
+    },
+
+    configFor(auth) {
+      const pub = source.public(app.cfg);
+      if (auth.features.has(FEATURE.SETTINGS)) return pub;
+      const out = {};
+      for (const [k, v] of Object.entries(pub)) if (!ADMIN_ONLY_FIELDS.test(k)) out[k] = v;
+      return { ...out, readOnly: true };
+    },
+
+    /** Replaces the hub wholesale: the old one's child processes are shut
+     * down after the new one is up, so a rename cannot leave an orphan. */
+    swapHub(servers) {
+      // Recorded now, not once connected: the file watcher fires 300 ms after
+      // our own save, and a slow connect would make that echo look like an
+      // outside edit and start a second swap.
+      mcpText = source.readMcpFile();
+      // One swap at a time: two in flight would both close the same old hub
+      // and leave the first new one, and its child processes, running.
+      const run = swapping.then(async () => {
+        if (stopping) return;
+        const old = app.hub;
+        app.hub = await connectHub(servers);
+        await old.close();
+      });
+      swapping = run.catch(() => {});
+      return run;
+    },
+
+    onRunIdle: (chatId) => app.scheduler.drain(chatId)
+  };
+  app.runs = createRuns(app);
+  app.scheduler = createScheduler(app);
+  const { retrieval, runs, scheduler } = app;
+
+  // The built-in tools are ours, not an MCP server's, but the model should not
+  // be able to tell: they are registered onto the same hub and called the same way.
+  const connectHub = async (servers) =>
+    (await new McpHub(servers).connect())
+      .registerLocal(expandToolDef(), (args, ctx) => callExpand(args, { ...ctx, store }), { readOnly: true })
+      .registerLocal(documentToolDef(), (args, ctx) => callReadDocument(args, { ...ctx, store, retrieval }), { readOnly: true })
+      .registerLocal(chatSearchToolDef(), (args, ctx) => callSearchChats(args, { ...ctx, store, retrieval }), { readOnly: true })
+      // Changes nothing, so it never waits for approval; never alongside
+      // other calls, so a question cannot race a write it is asking about.
+      .registerLocal(askToolDef(), callAskUser, { readOnly: true, idempotent: false, executionMode: 'sequential' })
+      .registerLocal(taskToolDef(), (args, ctx) => callManageTasks(args, {
+        ...ctx, store, onChange: () => runs.get(ctx.chatId)?.emit({ type: EVENT.TASKS, tasks: store.chats.visibleTasks(ctx.chatId) })
+      }), { executionMode: 'sequential' })
+      .registerLocal(automationToolDef(), (args, ctx) => {
+        const out = manageAutomation(args, { ...ctx, store, triggerAutomation: scheduler.trigger });
+        scheduler.arm();
+        return out;
+      });
+
+  app.hub = await connectHub(source.loadMcpServers());
+  // What mcp.json said when the hub was last (re)built, so a reload can tell
+  // a real edit from the echo of the UI's own save.
+  let mcpText = source.readMcpFile();
+  // The hub swap in progress, if any, and whether shutdown has begun.
+  let swapping = Promise.resolve();
+  let stopping = false;
+  const serversOf = (text) => { try { const p = JSON.parse(text); return p.mcpServers || p; } catch { return {}; } };
+
+  log.info(`config: ${source.path() || '(in code, no file)'}`);
+  log.info(`mcp:    ${source.mcpPath() || '(in code)'}`);
+  log.info(`db:     ${source.dbPath(app.cfg)}`);
+  log.info(`model:  ${app.cfg.model} via ${app.cfg.baseUrl}`);
+  log.info(`tools:  ${app.hub.tools.length} from ${app.hub.clients.size} MCP server(s)`);
+  // Repeated after the banner, grouped, so it is the last thing a first run shows.
+  const offFor = Map.groupBy(app.hub.install, ([, need]) => need.url);
+  for (const [url, entries] of offFor) {
+    log.warn(`${entries.map(([name]) => name).join(', ')} off until ${entries[0][1].name} is installed: ${url}`);
+  }
+  log.info(`policy: ${fingerprint(app.cfg, source.loadMcpServers())} (fingerprint)`);
+
+  const routes = routeTable(app);
+
+  const server = createServer(async (req, res) => {
+    try {
+      for (const [k, v] of Object.entries(SECURITY_HEADERS)) res.setHeader(k, v);
+      const url = new URL(req.url || '/', 'http://x');
+      const { pathname } = url;
+      if (crossSite(req, app.cfg)) {
+        audit('request.cross_site_rejected', { method: req.method, path: pathname });
+        return json(res, 403, { error: 'cross-site request refused' });
+      }
+      // Probes for orchestrators: no auth, nothing sensitive. /healthz says
+      // the process answers; /readyz that it can serve (database reachable),
+      // and which build and config it serves.
+      if (req.method === 'GET' && pathname === '/healthz') return json(res, 200, { ok: true });
+      if (req.method === 'GET' && pathname === '/readyz') {
+        let dbOk = false;
+        try { dbOk = store.ping(); } catch { /* not ready */ }
+        return json(res, dbOk ? 200 : 503, { ready: dbOk, version: VERSION, fingerprint: fingerprint(app.cfg, source.loadMcpServers()) });
+      }
+      const auth = resolveAuth(req, pathname, app.cfg, store);
+      if (auth.notFound) return json(res, 404, { error: 'not found' });
+      if (auth.unauthorized) return json(res, 401, { error: 'unauthorized' });
+      if (auth.disabled) return json(res, 403, { error: 'disabled' });
+      if (auth.pending) return json(res, 403, { error: 'pending_approval' });
+
+      if (!pathname.startsWith('/api/')) return serveStatic(req, res);
+      for (const route of routes) {
+        if (route.method !== req.method) continue;
+        const match = route.path.exec(pathname);
+        if (!match) continue;
+        if (route.feature && !auth.features.has(route.feature)) return json(res, 403, { error: 'feature_disabled', feature: route.feature });
+        return await route.handle({ req, res, auth, url, params: match.slice(1) });
+      }
+      return json(res, 404, { error: 'not found' });
+    } catch (err) {
+      if (err instanceof HttpError && err.status === 413) req.resume?.();
+      if (!res.headersSent) json(res, err instanceof HttpError ? err.status : err instanceof LockedError ? 409 : 500, { error: err.message });
+      else res.end();
+    }
+  });
+
+  await new Promise((resolve) => server.listen(port, host, resolve));
+  scheduler.arm();
+  log.info(`http://${host}:${port}`);
+  // Anything stored before dense retrieval was on (or under another model)
+  // is embedded in the background; document queries fill in on demand too.
+  retrieval.backfill((msg) => log.info(`retrieval: ${msg}`))
+    .catch((err) => log.error(`retrieval backfill failed: ${err.message}`));
+
+  /**
+   * Re-reads config.json and mcp.json after a hand or agent edit. All or
+   * nothing: a file that fails to parse or validate is reported and the
+   * running config stays exactly as it was. tinywebui.config.js is code and
+   * is only read at startup, as is authMode (switching it live would strand
+   * sessions and half the auth state).
+   */
+  async function reloadFromFiles(reason) {
+    let next, servers, text;
+    try {
+      next = source.load();
+      text = source.readMcpFile();
+      const parsed = JSON.parse(text);
+      servers = parsed.mcpServers || parsed;
+      for (const [name, spec] of Object.entries(servers)) {
+        if (!spec || (!spec.command && !spec.url)) throw new Error(`mcp server "${name}" needs either "command" or "url"`);
+      }
+    } catch (err) {
+      log.warn(`reload rejected (${reason}): ${err.message}`);
+      audit('config.reload_rejected', { reason, problems: [err.message] });
+      return false;
+    }
+    const problems = configProblems(next);
+    if (next.authMode !== app.cfg.authMode) problems.push('authMode changes need a restart');
+    if (JSON.stringify(next.retrieval) !== JSON.stringify(app.cfg.retrieval)) problems.push('retrieval changes need a restart');
+    if (problems.length) {
+      log.warn(`reload rejected (${reason}):\n  ${problems.join('\n  ')}`);
+      audit('config.reload_rejected', { reason, problems });
+      return false;
+    }
+    const before = fingerprint(app.cfg, serversOf(mcpText));
+    const after = fingerprint(next, servers);
+    const mcpChanged = text !== mcpText;
+    if (before === after && !mcpChanged) return true; // our own write, or a no-op save
+    app.cfg = next;
+    if (next.authMode === 'single') app.passwordHash = next.authPassword || hashPassword(process.env.TINYWEBUI_PASSWORD);
+    if (next.authMode === 'trusted-header') applyAccessPolicy(store, next);
+    if (mcpChanged) await app.swapHub(servers);
+    scheduler.arm();
+    log.info(`reloaded (${reason}): policy ${after}`);
+    audit('config.reloaded', { reason, before, after, mcpChanged });
+    return true;
+  }
+
+  // Editors often replace a file rather than write into it, which a watch on
+  // the file itself would lose; watching the folder catches both.
+  const watchers = [];
+  let reloadTimer = null;
+  const scheduleReload = (reason) => {
+    clearTimeout(reloadTimer);
+    reloadTimer = setTimeout(() => { reloadFromFiles(reason).catch((err) => log.error(`reload failed: ${err.message}`)); }, 300);
+    reloadTimer.unref?.();
+  };
+  if (sourceOpts.watch !== false) {
+    const targets = [source.path(), source.mcpPath()].filter(Boolean);
+    for (const folder of new Set(targets.map((t) => dirname(t)))) {
+      if (!existsSync(folder)) continue;
+      const names = new Set(targets.filter((t) => dirname(t) === folder).map((t) => t.slice(folder.length + 1)));
+      try {
+        const w = watch(folder, (_, name) => { if (name && names.has(String(name))) scheduleReload('file changed'); });
+        w.unref?.();
+        watchers.push(w);
+      } catch (err) { log.error(`cannot watch ${folder}: ${err.message}`); }
+    }
+  }
+  const onHup = () => scheduleReload('SIGHUP');
+  process.on('SIGHUP', onHup);
+  server.reload = reloadFromFiles;
+
+  // Real teardown, reused two ways: on SIGINT/SIGTERM it exits the process, and
+  // as `server.shutdown()` it does not -- which is what a test harness needs.
+  const shutdown = async () => {
+    scheduler.stop();
+    clearTimeout(reloadTimer);
+    for (const w of watchers) w.close();
+    process.off('SIGHUP', onHup);
+    // A swap still connecting would otherwise finish after this and leave
+    // its servers running.
+    stopping = true;
+    await swapping;
+    await app.hub.close();
+    await Promise.allSettled([...retrieval.pending.values()]);
+    embedder?.close?.();
+    store.close();
+    await new Promise((resolve) => server.close(resolve));
+  };
+  process.on('SIGINT', () => shutdown().then(() => process.exit(0)));
+  process.on('SIGTERM', () => shutdown().then(() => process.exit(0)));
+
+  server.shutdown = shutdown;
+  return server;
+}

package/src/set-password.js

@@ -0,0 +1,32 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { createConfigSource } from './config/config.js';
+import { hashPassword } from './access/auth.js';
+
+/** Reads one line without echoing it when attached to a terminal. */
+function ask(prompt) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: process.stdin.isTTY });
+    if (process.stdin.isTTY) rl._writeToOutput = (s) => { if (s.startsWith(prompt)) rl.output.write(prompt); };
+    rl.question(prompt, (answer) => { rl.close(); if (process.stdin.isTTY) process.stdout.write('\n'); resolve(answer); });
+  });
+}
+
+/**
+ * `tinywebui set-password`: stores an scrypt hash of a new password in the
+ * config file and switches authMode to 'single'. Existing sessions are
+ * signed with sessionSecret, which is rotated so they all end here too.
+ */
+export async function setPassword() {
+  const file = createConfigSource().path();
+  if (!file) throw new Error('no config file to write to');
+  const pw = await ask('New password: ');
+  if (pw.length < 8) throw new Error('use at least 8 characters');
+  if (process.stdin.isTTY && (await ask('Repeat password: ')) !== pw) throw new Error('passwords do not match');
+  const current = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+  current.authMode = 'single';
+  current.authPassword = hashPassword(pw);
+  delete current.sessionSecret; // regenerated on next start: every old session ends
+  writeFileSync(file, JSON.stringify(current, null, 2) + '\n');
+  console.log(`[tinywebui] password set in ${file}; restart TinyWebUI to apply`);
+}