@lifeaitools/clauth 2.1.1 → 2.10.1

package/cli/http/components/service-crud-component.js

@@ -0,0 +1,288 @@
+// cli/http/components/service-crud-component.js
+// The Service+WebDAV CRUD component: dynamic-segment vault-credential
+// routes (GET /get/:service and /v/:service -- raw credential reads,
+// POST /rename|/delete|/toggle|/rotate|/set-expiry|/set/:service --
+// mutations) plus DELETE /webdav/mounts/:name. These are the
+// dynamic-segment siblings of the exact-path service routes already
+// migrated earlier this session (/add-service, /update-service,
+// /generate-token, GET /webdav/config, POST /webdav/mounts -- those
+// stay as flat registerReadOnlyRoute/registerWriteRoute calls in
+// serve.js for now, a reasonable interim state since the registry
+// mechanism itself already satisfies "not a raw if-chain").
+//
+// Every dynamic segment here uses ctx.registerPatternRoute, including
+// /rotate/:service and /set-expiry/:service which originally used
+// reqPath.startsWith()/reqPath.slice() instead of a capture regex --
+// rewritten to a /^\/rotate\/(.+)$/-style regex with match[1] instead
+// of a slice (identical semantics: the original slice took everything
+// after the prefix, so does a "(.+)$" capture group), for uniformity
+// with every other route here.
+import { deriveToken } from "../../fingerprint.js";
+import * as api from "../../api.js";
+import { operation } from "../../supervisor-registry.js";
+import { readBody } from "../request-utils.js";
+import { invalidateServiceStatusCache, getCachedServiceStatus } from "../../services/service-status.js";
+import { writeCredentialWithRecovery } from "../../recovery.js";
+import * as webdavService from "../../webdav-service.js";
+import { removeMount as webdavRemoveMount } from "../../webdav-config.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const UNKNOWN_SERVICE_THRESHOLD = 2;
+const LOG_FILE = path.join(os.tmpdir(), "clauth-serve.log");
+
+export function registerServiceCrudRoutes(ctx) {
+  ctx.registerPatternRoute("DELETE", /^\/webdav\/mounts\/(.+)$/, async (req, res, match, url) => {
+      if (ctx.writeGuard(req, res)) return;
+      const mountName = decodeURIComponent(match[1]);
+      const result = webdavRemoveMount(mountName);
+      if (result.error) {
+        operation("webdav.mount_remove", { name: mountName }, null, { ok: false, error: result.error });
+        res.writeHead(404, { "Content-Type": "application/json", ...ctx.CORS }); return res.end(JSON.stringify(result));
+      }
+      webdavService.shutdown();
+      operation("webdav.mount_remove", { name: mountName }, null, { ok: true });
+      return ctx.ok(res, result);
+  });
+  // GET /get/:service
+  ctx.registerPatternRoute("GET", /^\/get\/([a-zA-Z0-9_-]+)$/, async (req, res, match, url) => {
+      if (!ctx.password) return ctx.noBrowserJson(res, 401, { error: "Vault is locked", locked: true });
+      const service = match[1].toLowerCase();
+      const callerIp = req.socket.remoteAddress || "unknown";
+
+      if (ctx.whitelist && !ctx.whitelist.includes(service)) {
+        return ctx.strikeNoBrowser(res, 403, `Service '${service}' not in whitelist`);
+      }
+
+      try {
+        const { token, timestamp } = deriveToken(ctx.password, ctx.machineHash);
+        const result = await api.retrieve(ctx.password, ctx.machineHash, token, timestamp, service);
+
+        if (result.error) {
+          // Caller-side retrieval misses are not auth attacks. Do not burn the
+          // failure budget or make /ping look locked just because a script used
+          // stale metadata or walked disabled services.
+          const clientError = ctx.retrievalClientError(result.error);
+          if (clientError) {
+            const misses = ctx.logRetrievalClientError(clientError.logType, service, callerIp);
+
+            if (misses >= UNKNOWN_SERVICE_THRESHOLD) {
+              // Return the list of enabled service names so the caller can self-correct.
+              try {
+                const { token: lst, timestamp: lsts } = deriveToken(ctx.password, ctx.machineHash);
+                const statusResult = await getCachedServiceStatus({ password: ctx.password, machineHash: ctx.machineHash, token: lst, timestamp: lsts, whitelist: ctx.whitelist });
+                const available = (statusResult.services || [])
+                  .filter(s => s.enabled !== false)
+                  .filter(s => !ctx.whitelist || ctx.whitelist.includes(s.name.toLowerCase()))
+                  .map(s => s.name.toLowerCase());
+                return ctx.noBrowserJson(res, clientError.code, { error: clientError.jsonError, service, available });
+              } catch {
+                // If status call fails, still return 404 without the list
+              }
+            }
+
+            return ctx.noBrowserJson(res, clientError.code, {
+              error: clientError.jsonError,
+              service,
+              hint: "Use GET /knowledge or /list-services before fetching a raw service",
+            });
+          }
+
+          // Real errors (wrong token, vault locked, etc.) still burn the failure budget.
+          return ctx.strikeNoBrowser(res, 502, result.error);
+        }
+
+        // Success — clear the unknown-service miss counter for this IP.
+        ctx.unknownServiceStrikes.delete(callerIp);
+        return ctx.noBrowserJson(res, 200, { service, value: result.value, key_type: result.key_type });
+      } catch (err) {
+        return ctx.strikeNoBrowser(res, 502, err.message);
+      }
+  });
+  // GET /v/:service — plain-text credential value (shorter than /get/:service + python3 pipe)
+  ctx.registerPatternRoute("GET", /^\/v\/([a-zA-Z0-9_-]+)$/, async (req, res, match, url) => {
+      if (!ctx.password) {
+        return ctx.noBrowserText(res, 403, "locked");
+      }
+      const service = match[1].toLowerCase();
+      const callerIp = req.socket.remoteAddress || "unknown";
+
+      if (ctx.whitelist && !ctx.whitelist.includes(service)) {
+        return ctx.noBrowserText(res, 403, "not allowed");
+      }
+
+      try {
+        const { token, timestamp } = deriveToken(ctx.password, ctx.machineHash);
+        const result = await api.retrieve(ctx.password, ctx.machineHash, token, timestamp, service);
+
+        if (result.error) {
+          const clientError = ctx.retrievalClientError(result.error);
+          if (clientError) {
+            ctx.logRetrievalClientError(clientError.logType, service, callerIp);
+            return ctx.noBrowserText(res, clientError.code, clientError.text);
+          }
+          // A backend/DB error surfaced in the body is NOT a client auth failure — no strike.
+          const backendKind = api.classifyServerReason(result.error);
+          if (backendKind) {
+            try { fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] [BACKEND ${backendKind}] /v/${service} retrieve — backend unreachable, no strike: ${result.error}\n`); } catch {}
+            return ctx.noBrowserText(res, 503, `vault backend unavailable (${backendKind})`);
+          }
+          return ctx.strikeNoBrowser(res, 502, result.error);
+        }
+
+        ctx.unknownServiceStrikes.delete(callerIp);
+        return ctx.noBrowserText(res, 200, result.value);
+      } catch (err) {
+        // Timeout / network / 5xx / rate-limit: the vault never answered. Report
+        // it as a backend outage, not a credential failure — never strike.
+        const backendKind = api.classifyBackendError(err);
+        if (backendKind) {
+          try { fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] [BACKEND ${backendKind}] /v/${service} retrieve — ${err.detail || err.message}\n`); } catch {}
+          return ctx.noBrowserText(res, 503, `vault backend unavailable (${backendKind})`);
+        }
+        return ctx.strikeNoBrowser(res, 502, err.message);
+      }
+  });
+  // POST /rename/:service — rename a service
+  ctx.registerPatternRoute("POST", /^\/rename\/([a-zA-Z0-9_-]+)$/, async (req, res, match, url) => {
+      if (ctx.writeGuard(req, res)) return;
+      const service = match[1].toLowerCase();
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "Invalid JSON body" }));
+      }
+      const newName = (body.new_name || "").trim().toLowerCase();
+      if (!newName || !/^[a-z0-9_-]+$/.test(newName)) {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "Invalid name — use lowercase letters, numbers, hyphens, underscores" }));
+      }
+      try {
+        const { token, timestamp } = deriveToken(ctx.password, ctx.machineHash);
+        const result = await api.updateService(ctx.password, ctx.machineHash, token, timestamp, service, { name: newName, label: newName });
+        if (result.error) {
+          operation("service.rename", { service, new_name: newName }, null, { ok: false, error: result.error });
+          return ctx.strike(res, 502, result.error);
+        }
+        invalidateServiceStatusCache(ctx.machineHash);
+        operation("service.rename", { service, new_name: newName }, null, { ok: true });
+        return ctx.ok(res, { ok: true, old_name: service, new_name: newName });
+      } catch (err) {
+        operation("service.rename", { service, new_name: newName }, null, { ok: false, error: err.message });
+        return ctx.strike(res, 502, err.message);
+      }
+  });
+  // POST /delete/:service — remove a service entirely
+  ctx.registerPatternRoute("POST", /^\/delete\/([a-zA-Z0-9_-]+)$/, async (req, res, match, url) => {
+      if (ctx.writeGuard(req, res)) return;
+      const service = match[1].toLowerCase();
+      try {
+        const { token, timestamp } = deriveToken(ctx.password, ctx.machineHash);
+        const result = await api.removeService(ctx.password, ctx.machineHash, token, timestamp, service, `CONFIRM REMOVE ${service.toUpperCase()}`);
+        if (result.error) {
+          operation("service.delete", { service }, null, { ok: false, error: result.error });
+          return ctx.strike(res, 502, result.error);
+        }
+        invalidateServiceStatusCache(ctx.machineHash);
+        operation("service.delete", { service }, null, { ok: true });
+        return ctx.ok(res, { ok: true, deleted: service });
+      } catch (err) {
+        operation("service.delete", { service }, null, { ok: false, error: err.message });
+        return ctx.strike(res, 502, err.message);
+      }
+  });
+  // POST /toggle/:service — enable or disable a service
+  ctx.registerPatternRoute("POST", /^\/toggle\/([a-zA-Z0-9_-]+)$/, async (req, res, match, url) => {
+      if (ctx.writeGuard(req, res)) return;
+      const service = match[1].toLowerCase();
+
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "Invalid JSON body" }));
+      }
+
+      const { enabled } = body;
+      if (typeof enabled !== "boolean") {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "enabled must be boolean" }));
+      }
+
+      try {
+        const { token, timestamp } = deriveToken(ctx.password, ctx.machineHash);
+        const result = await api.enable(ctx.password, ctx.machineHash, token, timestamp, service, enabled);
+        if (result.error) {
+          operation("service.toggle", { service, enabled }, null, { ok: false, error: result.error });
+          return ctx.strike(res, 502, result.error);
+        }
+        invalidateServiceStatusCache(ctx.machineHash);
+        operation("service.toggle", { service, enabled }, null, { ok: true });
+        return ctx.ok(res, { ok: true, service, enabled });
+      } catch (err) {
+        operation("service.toggle", { service, enabled }, null, { ok: false, error: err.message });
+        return ctx.strike(res, 502, err.message);
+      }
+  });
+  // ── Key Rotation Endpoints ──────────────────────────────────
+  // POST /rotate/:service — manually trigger rotation for a service
+  ctx.registerPatternRoute("POST", /^\/rotate\/(.+)$/, async (req, res, match, url) => {
+      if (ctx.writeGuard(req, res)) return;
+      const service = decodeURIComponent(match[1]);
+      if (!service) {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "Service name required" }));
+      }
+      const result = await ctx.rotationEngine.rotateService(service);
+      operation("service.rotate", { service }, null, { ok: !result?.error, error: result?.error });
+      return ctx.ok(res, result);
+  });
+  // POST /set-expiry/:service — set expiry date for a service
+  ctx.registerPatternRoute("POST", /^\/set-expiry\/(.+)$/, async (req, res, match, url) => {
+      if (ctx.writeGuard(req, res)) return;
+      const service = decodeURIComponent(match[1]);
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "Invalid JSON body" }));
+      }
+      ctx.rotationEngine.setExpiry(service, body.expires_at, body.rotation_days);
+      operation("service.set_expiry", { service }, null, { ok: true, expires_at: body.expires_at, rotation_days: body.rotation_days });
+      return ctx.ok(res, { ok: true, service, expires_at: body.expires_at });
+  });
+  // POST /set/:service — write a new key value into vault
+  ctx.registerPatternRoute("POST", /^\/set\/([a-zA-Z0-9_-]+)$/, async (req, res, match, url) => {
+      if (ctx.writeGuard(req, res)) return;
+      const service = match[1].toLowerCase();
+
+      if (ctx.whitelist && !ctx.whitelist.includes(service)) {
+        return ctx.strike(res, 403, `Service '${service}' not in whitelist`);
+      }
+
+      let body;
+      try { body = await readBody(req); } catch {
+        return ctx.strike(res, 400, "Invalid JSON body");
+      }
+
+      const value = body.value;
+      if (!value || typeof value !== "string" || !value.trim()) {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "value is required" }));
+      }
+
+      try {
+        // NEVER log `value` — it is the secret being written.
+        const { result, snapshot, normalized } = await writeCredentialWithRecovery({ password: ctx.password, machineHash: ctx.machineHash, service, value, logFile: LOG_FILE });
+        if (result.error) {
+          operation("service.set", { service }, null, { ok: false, error: result.error });
+          return ctx.strike(res, 502, result.error);
+        }
+        invalidateServiceStatusCache(ctx.machineHash);
+        operation("service.set", { service }, null, { ok: true, normalized });
+        return ctx.ok(res, { ok: true, service, recovery_snapshot: !!snapshot?.ok, normalized });
+      } catch (err) {
+        operation("service.set", { service }, null, { ok: false, error: err.message });
+        return ctx.strike(res, 502, err.message);
+      }
+  });
+}

package/cli/http/components/supervisor-component.js

@@ -0,0 +1,104 @@
+// cli/http/components/supervisor-component.js
+// The Supervisor-write component: plugin rescan/enable/disable/test/
+// promote, surface health probe + surface actions, and tunnel-route
+// CRUD -- all gated by hasSupervisorWrite() (the supervisor's own
+// write-token, a THIRD distinct guard from lockedGuard/writeGuard and
+// from the ops plane's bearer token), except /v1/surfaces/health which
+// is deliberately guard-free (read-only health sweep, run whenever the
+// dashboard tab regains focus -- gating it would prompt for a vault
+// unlock just to look at the tab). GET /v1/operations/:id is also
+// guard-free (a read of the supervisor's own event log).
+//
+// hasSupervisorWrite/rejectSupervisorWrite/supervisorLogDto stay defined
+// in serve.js (closure state: writeSession/isSupervisorPort/port, and
+// supervisorLogDto's own helper functions) and are passed via ctx as
+// plain function references -- same avoid-circular-import reasoning as
+// every other component this session.
+import {
+  discoverPlugins,
+  setPluginEnabled,
+  runPluginAction,
+  probeAllSurfaceHealth,
+  runSurfaceAction,
+  addTunnelRoute,
+  removeTunnelRoute,
+  supervisorHealth,
+  readSupervisorEvents,
+} from "../../supervisor-registry.js";
+import { readBody } from "../request-utils.js";
+
+// Returns an async (req, res, method, reqPath, url) => void handler. The
+// caller's contract: after awaiting it, check res.writableEnded -- every
+// branch below that matches a route always ends the response before
+// returning (ok()/res.end()/noBrowserJson-shaped calls), exactly as the
+// original if-chain did, so that flag is a reliable "did this handle the
+// request" signal with zero change to the extracted control flow.
+export function registerSupervisorRoutes(ctx) {
+  return async function handleSupervisorRoute(req, res, method, reqPath, url) {
+    if (method === "POST" && reqPath === "/v1/plugins/rescan") {
+      if (!ctx.hasSupervisorWrite(req)) return ctx.rejectSupervisorWrite(res);
+      return ctx.ok(res, discoverPlugins());
+    }
+
+    const pluginEnableMatch = reqPath.match(/^\/v1\/plugins\/([^/]+)\/(enable|disable|test|promote)$/);
+    if (method === "POST" && pluginEnableMatch) {
+      if (!ctx.hasSupervisorWrite(req)) return ctx.rejectSupervisorWrite(res);
+      const pluginId = decodeURIComponent(pluginEnableMatch[1]);
+      const op = pluginEnableMatch[2];
+      const result = op === "enable"
+        ? setPluginEnabled(pluginId, true)
+        : op === "disable"
+          ? setPluginEnabled(pluginId, false)
+          : runPluginAction(pluginId, op);
+      res.writeHead(result.error ? 400 : 200, { "Content-Type": "application/json", ...ctx.CORS });
+      return res.end(JSON.stringify(result));
+    }
+
+    // POST /v1/surfaces/health — read-only health sweep over every surface.
+    // Deliberately NOT behind ctx.hasSupervisorWrite(): it cannot start, stop or
+    // restart anything, and it is what the dashboard runs when the window
+    // regains focus. Gating it would make simply looking at the tab prompt for
+    // a vault unlock.
+    if (method === "POST" && reqPath === "/v1/surfaces/health") {
+      const result = await probeAllSurfaceHealth();
+      return ctx.ok(res, result);
+    }
+
+    const surfaceActionMatch = reqPath.match(/^\/v1\/surfaces\/([^/]+)\/actions$/);
+    if (method === "POST" && surfaceActionMatch) {
+      if (!ctx.hasSupervisorWrite(req)) return ctx.rejectSupervisorWrite(res);
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "Invalid JSON" }));
+      }
+      const result = runSurfaceAction(decodeURIComponent(surfaceActionMatch[1]), body?.action || "reconcile");
+      res.writeHead(result.error ? 400 : 200, { "Content-Type": "application/json", ...ctx.CORS });
+      return res.end(JSON.stringify(result));
+    }
+
+    const tunnelRoutesMatch = reqPath.match(/^\/v1\/tunnels\/([^/]+)\/routes$/);
+    if (method === "POST" && tunnelRoutesMatch) {
+      if (!ctx.hasSupervisorWrite(req)) return ctx.rejectSupervisorWrite(res);
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "Invalid JSON" }));
+      }
+      return ctx.ok(res, addTunnelRoute(decodeURIComponent(tunnelRoutesMatch[1]), body, "localhost"));
+    }
+
+    const tunnelRouteDeleteMatch = reqPath.match(/^\/v1\/tunnels\/([^/]+)\/routes\/([^/]+)$/);
+    if (method === "DELETE" && tunnelRouteDeleteMatch) {
+      if (!ctx.hasSupervisorWrite(req)) return ctx.rejectSupervisorWrite(res);
+      return ctx.ok(res, removeTunnelRoute(decodeURIComponent(tunnelRouteDeleteMatch[1]), decodeURIComponent(tunnelRouteDeleteMatch[2]), "localhost"));
+    }
+
+    if (method === "GET" && reqPath.startsWith("/v1/operations/")) {
+      const id = decodeURIComponent(reqPath.split("/").pop());
+      const operation = (supervisorHealth(), readSupervisorEvents(500)).find((event) => event.operationId === id);
+      res.writeHead(operation ? 200 : 404, { "Content-Type": "application/json", ...ctx.CORS });
+      return res.end(JSON.stringify(operation ? ctx.supervisorLogDto(operation) : { error: "operation_not_found" }));
+    }
+  };
+}

package/cli/http/components/system-component.js

@@ -0,0 +1,184 @@
+// cli/http/components/system-component.js
+// The System component: daemon self-lifecycle -- restart (spawn a fresh
+// process, exit self), shutdown-ui (user-initiated shutdown, clears
+// boot.key so the watchdog won't auto-unlock on the next start), and
+// make-live (blue-green promotion: a staged instance stops the current
+// live daemon, spawns itself onto the live port, waits for it to answer,
+// then exits). All three ultimately call process.exit() -- this is the
+// daemon managing its own process lifecycle, registered via dependency
+// injection like every other component (ctx exposes the createServer
+// closure state these handlers read: port/password/whitelist/isStaged/
+// tunnelHostname, plus removePid/removeStagedPid/getBootKeyPath, which
+// stay in serve.js to avoid a circular import back into this file).
+import { operation } from "../../supervisor-registry.js";
+import { readBody } from "../request-utils.js";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+
+const LIVE_PORT = 52437;
+const LOG_FILE = path.join(os.tmpdir(), "clauth-serve.log");
+const CLI_ENTRY_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../index.js");
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+
+export function registerSystemRoutes(ctx) {
+  // POST /restart — spawn fresh process then exit (keeps boot.key, vault stays unlocked).
+  // Optional body { pull: true } runs `git pull` + `npm install` in the repo
+  // root FIRST, synchronously, before respawning — so the dashboard's
+  // Restart button can offer "just restart" vs "pull latest + reinstall,
+  // then restart" without a second route. Synchronous is deliberate: the
+  // daemon is about to restart anyway (a real outage either way), and a
+  // dashboard-triggered git pull is a rare, explicit, single-operator action
+  // -- not a case that needs to stay responsive to other traffic mid-pull.
+  ctx.registerWriteRoute("POST", "/restart", async (req, res) => {
+      let body = {};
+      try { body = await readBody(req); } catch {}
+      const pullLatest = !!body.pull;
+
+      if (pullLatest) {
+        const { execSync } = await import("node:child_process");
+        try {
+          const gitOut = execSync("git pull", { cwd: REPO_ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+          try { fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] Restart: git pull —\n${gitOut}\n`); } catch {}
+          const npmOut = execSync("npm install", { cwd: REPO_ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+          try { fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] Restart: npm install —\n${npmOut}\n`); } catch {}
+        } catch (err) {
+          const detail = (err.stdout || "") + (err.stderr || err.message || "");
+          operation("daemon.restart_pull_failed", { port: ctx.port }, null, { ok: false, error: detail });
+          try { fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] Restart: pull/install FAILED —\n${detail}\n`); } catch {}
+          res.writeHead(500, { "Content-Type": "application/json", ...ctx.CORS });
+          return res.end(JSON.stringify({ error: "git pull / npm install failed — daemon NOT restarted", detail }));
+        }
+      }
+
+      operation("daemon.restart_requested", { port: ctx.port, pulled: pullLatest }, null, { ok: true });
+      ctx.ok(res, { ok: true, message: pullLatest ? "pulled latest, restarting" : "restarting" });
+      const { spawn } = await import("child_process");
+      const cliEntry = CLI_ENTRY_PATH;
+      const childArgs = [cliEntry, "serve", "start", "--port", String(ctx.port)];
+      if (ctx.password) childArgs.push("--pw", ctx.password);
+      if (ctx.whitelist) childArgs.push("--services", ctx.whitelist.join(","));
+      if (ctx.tunnelHostname) childArgs.push("--tunnel", ctx.tunnelHostname);
+      const out = fs.openSync(LOG_FILE, "a");
+      const child = spawn(process.execPath, childArgs, {
+        detached: true,
+        stdio: ["ignore", out, out],
+        env: { ...process.env, __CLAUTH_DAEMON: "1" },
+        windowsHide: true,
+      });
+      child.unref();
+      ctx.stopTunnel();
+      ctx.removePid();
+      setTimeout(() => process.exit(0), 300);
+      return;
+  });
+  ctx.registerWriteRoute("POST", "/shutdown-ui", async (req, res) => {
+      operation("daemon.shutdown_ui", { port: ctx.port }, null, { ok: true });
+      ctx.stopTunnel();
+      // Clear boot.key so watchdog can't auto-unlock on restart
+      const bootKeyPath = ctx.getBootKeyPath();
+      if (bootKeyPath) {
+        try { fs.unlinkSync(bootKeyPath); } catch {}
+      }
+      ctx.ok(res, { ok: true, message: "shutting down (user-initiated, boot.key cleared)" });
+      const logLine = `[${new Date().toISOString()}] User-initiated shutdown via UI — boot.key cleared\n`;
+      try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
+      ctx.removePid();
+      setTimeout(() => process.exit(0), 100);
+      return;
+  });
+  // GET|POST /shutdown — programmatic daemon stop, keeps boot.key (accepts GET
+  // too: older scripts and curl default to GET). Also the cross-process call
+  // /make-live's own promotion flow makes against the CURRENT live daemon.
+  const shutdownHandler = async (req, res) => {
+      operation("daemon.shutdown", { port: ctx.port }, null, { ok: true });
+      ctx.stopTunnel();
+      ctx.ok(res, { ok: true, message: "shutting down" });
+      ctx.removePid();
+      setTimeout(() => process.exit(0), 100);
+      return;
+  };
+  ctx.registerWriteRoute("GET", "/shutdown", shutdownHandler);
+  ctx.registerWriteRoute("POST", "/shutdown", shutdownHandler);
+
+  ctx.registerWriteRoute("POST", "/make-live", async (req, res) => {
+      if (!ctx.isStaged) {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "Not a staged instance" }));
+      }
+      const logLine = `[${new Date().toISOString()}] Make-live: promoting staged (port ${ctx.port}) to live (port ${LIVE_PORT})\n`;
+      try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
+
+      // Stop the current live daemon if running
+      try { await fetch(`http://127.0.0.1:${LIVE_PORT}/shutdown`); } catch {}
+
+      // Wait for port to be released (Windows is slow to release sockets)
+      let portFree = false;
+      for (let i = 0; i < 10; i++) {
+        await new Promise(r => setTimeout(r, 1000));
+        try {
+          await fetch(`http://127.0.0.1:${LIVE_PORT}/ping`);
+          // Still responding — not dead yet
+        } catch {
+          portFree = true;
+          break;
+        }
+      }
+      if (!portFree) {
+        const errLog = `[${new Date().toISOString()}] Make-live: live daemon on port ${LIVE_PORT} failed to stop within 10s\n`;
+        try { fs.appendFileSync(LOG_FILE, errLog); } catch {}
+      }
+
+      // Stop tunnel on this instance (will restart on new port)
+      ctx.stopTunnel();
+
+      // Clean up staged PID file
+      ctx.removeStagedPid();
+
+      // Spawn a new daemon on the live port with same credentials
+      const { spawn } = await import("child_process");
+      const cliEntry = CLI_ENTRY_PATH;
+      const childArgs = [cliEntry, "serve", "start", "--port", String(LIVE_PORT)];
+      if (ctx.password) childArgs.push("--pw", ctx.password);
+      if (ctx.whitelist) childArgs.push("--services", ctx.whitelist.join(","));
+      if (ctx.tunnelHostname) childArgs.push("--tunnel", ctx.tunnelHostname);
+
+      const out = fs.openSync(LOG_FILE, "a");
+      const childEnv = { ...process.env, __CLAUTH_DAEMON: "1" };
+      delete childEnv.__CLAUTH_STAGED;  // Clear staged flag — child is live
+      const child = spawn(process.execPath, childArgs, {
+        detached: true,
+        stdio: ["ignore", out, out],
+        env: childEnv,
+        windowsHide: true,
+      });
+      child.unref();
+
+      // Wait for new live daemon to be reachable
+      let promoted = false;
+      for (let i = 0; i < 8; i++) {
+        await new Promise(r => setTimeout(r, 1000));
+        try {
+          const resp = await fetch(`http://127.0.0.1:${LIVE_PORT}/ping`);
+          if (resp.ok) { promoted = true; break; }
+        } catch {}
+      }
+
+      if (promoted) {
+        const okLog = `[${new Date().toISOString()}] Make-live: promoted to live on port ${LIVE_PORT}\n`;
+        try { fs.appendFileSync(LOG_FILE, okLog); } catch {}
+        operation("daemon.make_live", { from_port: ctx.port, live_port: LIVE_PORT }, null, { ok: true });
+        ctx.ok(res, { ok: true, message: "promoted to live", live_port: LIVE_PORT });
+      } else {
+        const failLog = `[${new Date().toISOString()}] Make-live: new daemon failed to start on port ${LIVE_PORT}\n`;
+        try { fs.appendFileSync(LOG_FILE, failLog); } catch {}
+        operation("daemon.make_live", { from_port: ctx.port, live_port: LIVE_PORT }, null, { ok: false, error: "new daemon failed to start" });
+        ctx.ok(res, { ok: false, error: "New daemon failed to start on live port — check log" });
+      }
+
+      // Self-terminate after response is sent
+      setTimeout(() => process.exit(0), 500);
+      return;
+  });
+}