@lifeaitools/clauth 1.31.1 → 2.0.1

package/cli/supervisor-ui.test.js

@@ -2,11 +2,447 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
+import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
 
+import { dashboardHtml } from './commands/serve.js';
+
 const here = path.dirname(fileURLToPath(import.meta.url));
 const serveSource = fs.readFileSync(path.join(here, 'commands', 'serve.js'), 'utf8');
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Functional harness
+//
+// The dashboard JS ships inside a served HTML template, so there is nothing to
+// import. This harness renders the real page with dashboardHtml(), lifts its
+// script into a vm realm with a stub DOM + stub fetch, and then calls the real
+// controller seams (runSupervisorSurface, addService, submitWriteUnlock, …)
+// with simulated inputs — per the global UI functional-harness rule. No pixels,
+// no browser automation: assertions are on state, command and payload.
+//
+// The requirement these tests encode: a dashboard button IS the human being
+// present. On an unlocked vault a click must proceed with no password prompt.
+// The prompt exists only for a genuinely locked vault.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function makeElement(id) {
+  const classes = new Set();
+  return {
+    id,
+    value: '',
+    textContent: '',
+    innerHTML: '',
+    className: '',
+    title: '',
+    disabled: false,
+    dataset: {},
+    style: {},
+    scrollHeight: 0,
+    scrollTop: 0,
+    clientHeight: 0,
+    classList: {
+      add: (c) => classes.add(c),
+      remove: (c) => classes.delete(c),
+      toggle: (c, on) => (on ? classes.add(c) : classes.delete(c)),
+      contains: (c) => classes.has(c),
+    },
+    addEventListener() {},
+    removeEventListener() {},
+    appendChild() {},
+    focus() {},
+    click() {},
+    querySelectorAll: () => [],
+  };
+}
+
+function bootDashboard({ initWriteToken = null, route } = {}) {
+  const html = dashboardHtml(53999, [], false, initWriteToken);
+  const start = html.indexOf('<script>');
+  const end = html.lastIndexOf('</script>');
+  assert.ok(start !== -1 && end > start, 'dashboard HTML must contain exactly one script block');
+  const script = html.slice(start + '<script>'.length, end);
+
+  const elements = new Map();
+  const fetchCalls = [];
+  const confirmCalls = [];
+
+  const sandbox = {
+    console: { log() {}, warn() {}, error() {} },
+    JSON,
+    Date,
+    Math,
+    setTimeout: () => 0,
+    clearTimeout: () => {},
+    setInterval: () => 0,
+    clearInterval: () => {},
+    localStorage: { getItem: () => null, setItem() {}, removeItem() {} },
+    navigator: { clipboard: { writeText: async () => {} } },
+    confirm: (msg) => { confirmCalls.push(msg); return true; },
+    alert: () => {},
+    document: {
+      getElementById(id) {
+        if (!elements.has(id)) elements.set(id, makeElement(id));
+        return elements.get(id);
+      },
+      createElement: (tag) => makeElement(tag),
+      querySelectorAll: () => [],
+      addEventListener() {},
+      body: makeElement('body'),
+    },
+    async fetch(url, options) {
+      const opts = options || {};
+      fetchCalls.push({ url: String(url), options: opts });
+      const body = route ? route(String(url), opts) : null;
+      // Default: vault reports itself locked, so boot() lands on the lock
+      // screen and issues no follow-up requests. Keeps the realm deterministic.
+      const json = body !== null && body !== undefined ? body : { locked: true, hard_locked: false };
+      return {
+        ok: true,
+        status: 200,
+        json: async () => json,
+        text: async () => JSON.stringify(json),
+      };
+    },
+  };
+  sandbox.location = { href: '', reload() {} };
+  sandbox.open = () => {};
+
+  vm.createContext(sandbox);
+  sandbox.window = sandbox;
+  sandbox.globalThis = sandbox;
+  vm.runInContext(script, sandbox, { filename: 'dashboard.js' });
+
+  return {
+    ctx: sandbox,
+    elements,
+    fetchCalls,
+    confirmCalls,
+    el: (id) => sandbox.document.getElementById(id),
+    /** Requests that actually carried write authority — i.e. real writes. */
+    writeCalls: () =>
+      fetchCalls.filter((c) => c.options.headers && c.options.headers['X-Clauth-Write-Token']),
+    tokenAcquisitions: () => fetchCalls.filter((c) => c.url.endsWith('/write-token')),
+    authCalls: () => fetchCalls.filter((c) => c.url.endsWith('/auth')),
+    settle: () => new Promise((r) => setImmediate(r)),
+  };
+}
+
+const SURFACE_ID = 'factory-test-plugin:primary';
+const ACTIONS_PATH = '/v1/surfaces/' + encodeURIComponent(SURFACE_ID) + '/actions';
+
+/** Vault unlocked: /write-token always hands back a current token. */
+function unlockedRoute(url, options) {
+  if (url.endsWith('/write-token')) return { ok: true, write_token: 'wt-fresh' };
+  if (url.includes('/v1/surfaces/') && url.includes('/actions')) {
+    return { operationId: 'op-42', resulting_state: { state: 'started', ok: true } };
+  }
+  if (url.endsWith('/add-service')) return { ok: true };
+  if (url.endsWith('/ping')) return { locked: true, hard_locked: false };
+  return {};
+}
+
+/** Vault genuinely locked: /write-token refuses, /auth can still unlock it. */
+function lockedRoute(url, options) {
+  if (url.endsWith('/write-token')) return { error: 'vault_locked', locked: true };
+  if (url.endsWith('/auth')) return { write_token: 'wt-after-password' };
+  if (url.includes('/v1/surfaces/') && url.includes('/actions')) {
+    return { operationId: 'op-43', resulting_state: { state: 'started', ok: true } };
+  }
+  if (url.endsWith('/add-service')) return { ok: true };
+  if (url.endsWith('/ping')) return { locked: true, hard_locked: false };
+  return {};
+}
+
+// ── 1. The requirement: a button on an unlocked vault just works ─────────────
+
+test('unlocked vault, page holds no token: the action proceeds with NO password prompt', async () => {
+  // This is the --pw / boot.key auto-unlock case — the page never saw the lock
+  // screen, so dashboardHtml() injected no token. Dave's reported flow.
+  const h = bootDashboard({ initWriteToken: null, route: unlockedRoute });
+  await h.settle();
+
+  await h.ctx.runSupervisorSurface(SURFACE_ID, 'restart');
+  await h.settle();
+
+  assert.notEqual(h.el('write-unlock-overlay').style.display, 'flex', 'no password modal may open');
+  assert.equal(h.ctx.hasPendingWriteAction(), false, 'nothing may be parked');
+  assert.deepEqual(h.authCalls(), [], 'no password round-trip may occur');
+
+  const writes = h.writeCalls();
+  assert.equal(writes.length, 1, 'the action must fire, once');
+  assert.ok(writes[0].url.endsWith(ACTIONS_PATH), 'got ' + writes[0].url);
+  assert.equal(writes[0].options.headers['X-Clauth-Write-Token'], 'wt-fresh');
+  assert.deepEqual(JSON.parse(writes[0].options.body), { action: 'restart' });
+});
+
+test('unlocked vault, page holds a STALE token: the write uses a freshly acquired one', async () => {
+  // The literal defect: the server write session has a 10-minute TTL while a
+  // dashboard tab stays open for hours, so the page kept sending a token the
+  // daemon had already expired and writeGuard answered 403 "write token
+  // required". Acquiring per action makes that unreachable.
+  const h = bootDashboard({ initWriteToken: 'wt-expired-hours-ago', route: unlockedRoute });
+  await h.settle();
+
+  await h.ctx.runSupervisorSurface(SURFACE_ID, 'stop');
+  await h.settle();
+
+  const writes = h.writeCalls();
+  assert.equal(writes.length, 1);
+  assert.equal(
+    writes[0].options.headers['X-Clauth-Write-Token'],
+    'wt-fresh',
+    'must send the refreshed token, never the stale page-load one',
+  );
+  assert.equal(h.tokenAcquisitions().length, 1, 'exactly one token acquisition per action');
+  assert.notEqual(h.el('write-unlock-overlay').style.display, 'flex');
+});
+
+test('Add Service on an unlocked vault creates the service with no prompt', async () => {
+  const h = bootDashboard({ initWriteToken: null, route: unlockedRoute });
+  await h.settle();
+
+  h.el('add-name').value = 'my-new-service';
+  h.el('add-label').value = 'My New Service';
+  h.el('add-description').value = '';
+  h.el('add-project').value = '';
+  h.el('add-type').value = 'token';
+
+  await h.ctx.addService();
+  await h.settle();
+
+  assert.notEqual(h.el('write-unlock-overlay').style.display, 'flex', 'no modal for Add Service');
+  assert.deepEqual(h.authCalls(), [], 'no password round-trip');
+
+  const writes = h.writeCalls();
+  assert.equal(writes.length, 1, 'Add Service must fire exactly once');
+  assert.ok(writes[0].url.endsWith('/add-service'), 'got ' + writes[0].url);
+  assert.equal(writes[0].options.method, 'POST');
+  assert.equal(writes[0].options.headers['X-Clauth-Write-Token'], 'wt-fresh');
+  assert.deepEqual(JSON.parse(writes[0].options.body), {
+    name: 'my-new-service',
+    key_type: 'token',
+    label: 'My New Service',
+  });
+  assert.match(h.el('add-msg').textContent, /my-new-service created/);
+});
+
+test('every write action reaches the acquire path, not just the two under test', async () => {
+  // Spot-check the breadth of the choke point: each of these is a distinct
+  // call site that previously threw its own opaque string.
+  for (const [name, args] of [
+    ['rescanSupervisorPlugins', []],
+    ['deleteService', ['some-service']],
+    ['toggleService', ['some-service']],
+    ['submitMount', []],
+    ['deleteMount', ['some-mount']],
+  ]) {
+    const h = bootDashboard({ initWriteToken: null, route: unlockedRoute });
+    await h.settle();
+    // submitMount reads two inputs and returns early when either is blank.
+    h.el('mount-name').value = 'm';
+    h.el('mount-path').value = 'C:/tmp';
+    h.el('badge-some-service').classList.add('on');
+
+    await h.ctx[name](...args);
+    await h.settle();
+
+    assert.equal(h.tokenAcquisitions().length, 1, name + ' must acquire write access');
+    assert.notEqual(h.el('write-unlock-overlay').style.display, 'flex', name + ' must not prompt');
+    assert.equal(h.ctx.hasPendingWriteAction(), false, name + ' must not park');
+  }
+});
+
+// ── 2. Locked-vault fallback — the only case that may prompt ─────────────────
+
+test('genuinely locked vault: the action parks, prompts, and performs no write', async () => {
+  const h = bootDashboard({ initWriteToken: null, route: lockedRoute });
+  await h.settle();
+
+  await h.ctx.runSupervisorSurface(SURFACE_ID, 'restart');
+  await h.settle();
+
+  assert.equal(h.el('write-unlock-overlay').style.display, 'flex', 'locked vault must prompt');
+  assert.equal(h.ctx.hasPendingWriteAction(), true);
+  assert.equal(h.ctx.pendingWriteActionName(), 'runSupervisorSurface');
+  assert.deepEqual(h.writeCalls(), [], 'no write may be attempted against a locked vault');
+});
+
+test('locked vault: after the password unlock the parked action fires exactly once', async () => {
+  const h = bootDashboard({ initWriteToken: null, route: lockedRoute });
+  await h.settle();
+
+  await h.ctx.runSupervisorSurface(SURFACE_ID, 'restart');
+  await h.settle();
+  assert.deepEqual(h.writeCalls(), []);
+
+  h.el('write-unlock-input').value = 'correct-horse';
+  await h.ctx.submitWriteUnlock();
+  await h.settle();
+
+  const writes = h.writeCalls();
+  assert.equal(writes.length, 1, 'exactly once — not zero, not twice');
+  assert.ok(writes[0].url.endsWith(ACTIONS_PATH), 'got ' + writes[0].url);
+  assert.deepEqual(JSON.parse(writes[0].options.body), { action: 'restart' }, 'arguments preserved');
+  assert.equal(h.ctx.hasPendingWriteAction(), false, 'park consumed');
+  assert.equal(h.el('write-unlock-overlay').style.display, 'none', 'modal closed');
+});
+
+test('locked vault: cancelling clears the parked action, and no write fires later', async () => {
+  const h = bootDashboard({ initWriteToken: null, route: lockedRoute });
+  await h.settle();
+
+  await h.ctx.runSupervisorSurface(SURFACE_ID, 'stop');
+  await h.settle();
+  assert.equal(h.ctx.hasPendingWriteAction(), true);
+
+  h.ctx.closeWriteUnlockModal();
+  assert.equal(h.ctx.hasPendingWriteAction(), false, 'cancel must disarm the parked write');
+  assert.deepEqual(h.writeCalls(), []);
+
+  h.ctx.unlockWrites();
+  h.el('write-unlock-input').value = 'correct-horse';
+  await h.ctx.submitWriteUnlock();
+  await h.settle();
+
+  assert.deepEqual(h.writeCalls(), [], 'a cancelled action must never fire, then or later');
+});
+
+// ── 3. Registry completeness — the guard against a per-call-site regression ──
+
+/**
+ * The reviewed write-action surface. Hand-maintained on purpose: growing it
+ * must be a decision someone made, not a number that drifts upward. A floor
+ * like `callers.size >= 15` cannot do this job — on a passing run the two
+ * set-differences below already force callers.size === registered.size, so a
+ * floor only ever catches the registry SHRINKING.
+ */
+const EXPECTED_WRITE_ACTIONS = [
+  'addService',
+  'changePassword',
+  'deleteMount',
+  'deleteService',
+  'enrollMachine',
+  'rescanSupervisorPlugins',
+  'rotateKey',
+  'runSupervisorSurface',
+  'saveKey',
+  'saveLabel',
+  'saveProject',
+  'setExpiry',
+  'submitMount',
+  'toggleService',
+  'wizSubmitCfToken',
+];
+
+function registeredWriteActions(source) {
+  const literal = source.match(/const WRITE_ACTIONS = \[([\s\S]*?)\];/);
+  assert.ok(literal, 'WRITE_ACTIONS registry must exist in the dashboard script');
+  return new Set([...literal[1].matchAll(/"([A-Za-z0-9_$]+)"/g)].map((m) => m[1]));
+}
+
+/**
+ * Every top-level dashboard function whose body calls writeHeaders().
+ *
+ * Recognises const/let/var function-expression and arrow bindings as well as
+ * function declarations. Without that, converting a write action to
+ * `const foo = async () => {…}` would attribute its writeHeaders() call to the
+ * PRECEDING declaration — and when that neighbour is itself registered, the
+ * call silently lands on an already-present name and this test passes on a
+ * genuinely unguarded action.
+ *
+ * Comment lines are skipped: prose mentioning writeHeaders() is not a call
+ * site, and counting it as one produced a false "bypasses the choke point"
+ * failure the first time a doc comment landed after a function declaration.
+ */
+function writeHeaderCallers(source) {
+  const callers = new Set();
+  let current = null;
+  for (const line of source.split(/\r?\n/)) {
+    const decl = line.match(/^(?:async\s+)?function\s+([A-Za-z0-9_$]+)\s*\(/);
+    const bound = line.match(
+      /^(?:const|let|var)\s+([A-Za-z0-9_$]+)\s*=\s*(?:async\s*)?(?:function\b|\(|[A-Za-z0-9_$]+\s*=>)/,
+    );
+    if (decl) current = decl[1];
+    else if (bound) current = bound[1];
+
+    const code = line.trim();
+    if (code.startsWith('//') || code.startsWith('*') || code.startsWith('/*')) continue;
+    if (line.includes('writeHeaders(') && current && current !== 'writeHeaders') {
+      callers.add(current);
+    }
+  }
+  return callers;
+}
+
+test('WRITE_ACTIONS matches the reviewed write-action surface exactly', () => {
+  const registered = [...registeredWriteActions(serveSource)].sort();
+  assert.deepEqual(
+    registered,
+    EXPECTED_WRITE_ACTIONS,
+    'WRITE_ACTIONS changed — update EXPECTED_WRITE_ACTIONS deliberately, and confirm the new action is a function declaration',
+  );
+});
+
+test('WRITE_ACTIONS covers every function that calls writeHeaders()', () => {
+  const registered = registeredWriteActions(serveSource);
+  const callers = writeHeaderCallers(serveSource);
+
+  const unguarded = [...callers].filter((n) => !registered.has(n));
+  assert.deepEqual(unguarded, [], 'these write actions bypass the choke point: ' + unguarded.join(', '));
+
+  const stale = [...registered].filter((n) => !callers.has(n));
+  assert.deepEqual(stale, [], 'these registry entries no longer write: ' + stale.join(', '));
+
+  assert.equal(callers.size, registered.size);
+});
+
+test('every registered write action is actually wrapped at install time', () => {
+  const h = bootDashboard({ initWriteToken: 'wt-preexisting', route: unlockedRoute });
+  const registered = [...registeredWriteActions(serveSource)];
+
+  const notWrapped = registered.filter((name) => h.ctx[name]?.__writeGuarded !== true);
+  assert.deepEqual(
+    notWrapped,
+    [],
+    'registered but not guarded in the live realm (a const/arrow binding cannot be guarded): ' + notWrapped.join(', '),
+  );
+  assert.equal(registered.length, EXPECTED_WRITE_ACTIONS.length);
+});
+
+test('installWriteAccessGuards throws on a registered name that cannot be guarded', () => {
+  assert.match(serveSource, /clauth write-guard install failed/);
+  assert.doesNotMatch(
+    serveSource,
+    /if \(typeof fn !== "function" \|\| fn\.__writeGuarded\) continue;/,
+    'the old silent-skip guard must not come back',
+  );
+});
+
+test('the write-access choke point is a single mechanism, not per-call-site guards', () => {
+  const parkSites = [...serveSource.matchAll(/pendingWriteAction = \{/g)];
+  assert.equal(parkSites.length, 1, 'exactly one place may park a write action');
+  const acquireSites = [...serveSource.matchAll(/BASE \+ "\/write-token"/g)];
+  assert.equal(acquireSites.length, 1, 'exactly one place may acquire write access');
+  assert.match(serveSource, /function installWriteAccessGuards\(/);
+});
+
+// ── 4. Server contract: the gate stays, the prompt goes ──────────────────────
+
+test('POST /write-token refuses a locked vault and never weakens the write gate', () => {
+  assert.match(serveSource, /reqPath === "\/write-token"/, 'the acquire route must exist');
+  assert.match(
+    serveSource,
+    /reqPath === "\/write-token"\)\s*\{\s*\n\s*if \(!password\) \{/,
+    'a locked vault must be refused before any token is minted',
+  );
+  // writeGuard is what makes a page-driven write distinguishable from a blind
+  // remote POST arriving through the cloudflared tunnel as loopback. It stays.
+  assert.match(serveSource, /function writeGuard\(req, res\) \{[\s\S]*?validateWriteToken\(req, writeSession\)/);
+  assert.match(serveSource, /if \(!isLocal\) \{[\s\S]*?strike\(res, 403/, 'non-loopback must stay hard-rejected');
+});
+
+// ── Pre-existing coverage — lifecycle actions and receipt feedback ───────────
+
 test('clauth supervisor UI exposes every lifecycle action and receipt feedback', () => {
   for (const action of ['start', 'stop', 'restart', 'reconcile', 'test', 'promote', 'rollback']) {
     assert.match(serveSource, new RegExp('"' + action + '"'));

package/cli/watchdog-registry.js

@@ -178,7 +178,30 @@ export function readWatchdogEvents(limit = 100) {
   }
 }
 
-export function restartWatchdogService(id) {
+async function verifyRestartHealth(service) {
+  if (!service.health?.url) return { ok: true, health_status: "not_configured" };
+
+  const attempts = Number(service.health.readyAttempts || 20);
+  const delayMs = Number(service.health.readyDelayMs || 250);
+  let observed;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    observed = await evaluateWatchdogService(service);
+    if (observed.status === "healthy") {
+      return { ok: true, health_status: observed.status, health_http_status: observed.httpStatus, attempts: attempt };
+    }
+    if (attempt < attempts) await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+  return {
+    ok: false,
+    error: "restart_health_unreachable",
+    health_status: observed?.status || "unknown",
+    health_http_status: observed?.httpStatus,
+    health_error: observed?.error,
+    attempts,
+  };
+}
+
+export async function restartWatchdogService(id) {
   const service = loadRegistry().services.find((candidate) => candidate.id === id);
   if (!service) return { ok: false, error: "service_not_registered" };
   if (!service.restart) return { ok: false, error: "restart_not_configured" };
@@ -192,18 +215,23 @@ export function restartWatchdogService(id) {
     encoding: "utf8",
     timeout: Number(service.restart.timeoutMs || 30000),
   });
+  const health = result.status === 0 ? await verifyRestartHealth(service) : { ok: false, health_status: "not_checked" };
   const event = {
     kind: "restart",
     service_id: id,
     status: result.status,
+    health_status: health.health_status,
+    health_http_status: health.health_http_status,
+    health_error: health.health_error,
     error: result.error ? result.error.message : undefined,
   };
   appendEvent(event);
   return {
-    ok: result.status === 0,
+    ok: result.status === 0 && health.ok,
     status: result.status,
     stdout: result.stdout,
     stderr: result.stderr,
     error: result.error ? result.error.message : undefined,
+    ...health,
   };
 }

package/cli/watchdog-registry.test.js

@@ -13,12 +13,12 @@ import {
   validateWatchdogService,
 } from "./watchdog-registry.js";
 
-function withTempRegistry(fn) {
+async function withTempRegistry(fn) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-watchdog-"));
   const old = process.env.CLAUTH_WATCHDOG_DIR;
   process.env.CLAUTH_WATCHDOG_DIR = dir;
   try {
-    return fn(dir);
+    return await fn(dir);
   } finally {
     if (old === undefined) delete process.env.CLAUTH_WATCHDOG_DIR;
     else process.env.CLAUTH_WATCHDOG_DIR = old;
@@ -78,12 +78,35 @@ test("registerWatchdogManifest upserts services by id", () => withTempRegistry((
   assert.equal(registry.services.find((service) => service.id === "codeflow").label, "CodeFlow Updated");
 }));
 
-test("restartWatchdogService rejects missing and unapproved services", () => withTempRegistry(() => {
-  assert.deepEqual(restartWatchdogService("missing"), { ok: false, error: "service_not_registered" });
+test("restartWatchdogService rejects missing and unapproved services", async () => withTempRegistry(async () => {
+  assert.deepEqual(await restartWatchdogService("missing"), { ok: false, error: "service_not_registered" });
   registerWatchdogManifest({
     services: [
       { id: "dev-center", label: "Dev Center", kind: "process", restart: { cmd: "node", args: ["--version"] } },
     ],
   });
-  assert.deepEqual(restartWatchdogService("dev-center"), { ok: false, error: "approval_required" });
+  assert.deepEqual(await restartWatchdogService("dev-center"), { ok: false, error: "approval_required" });
+}));
+
+test("restartWatchdogService requires registered health after launching", async () => withTempRegistry(async () => {
+  registerWatchdogManifest({
+    services: [{
+      id: "health-gated",
+      label: "Health gated",
+      kind: "http",
+      health: { url: "http://127.0.0.1:3109/health", readyAttempts: 2, readyDelayMs: 0 },
+      restart: { cmd: process.execPath, args: ["--version"] },
+      approvalRequired: false,
+    }],
+  });
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () => ({ ok: false, status: 503 });
+  try {
+    const result = await restartWatchdogService("health-gated");
+    assert.equal(result.ok, false);
+    assert.equal(result.error, "restart_health_unreachable");
+    assert.equal(result.health_status, "degraded");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
 }));