@sleep2agi/commhub-server 0.9.0-preview.21 → 0.9.0-preview.22

package/README.md

@@ -7,7 +7,7 @@
 
 CommHub: MCP Streamable HTTP + SSE push + REST API for an AI agent network. Single-process Bun server, SQLite-backed, zero config when launched through `anet`.
 
-The supported path is to install the `anet` CLI (`@sleep2agi/agent-network`, currently v2.2.10 at v0.10.11) and run `anet hub start`, which wires up the port, default admin account, recovery admin `utok_`, and local config for you.
+The supported path is to install the `anet` CLI (`@sleep2agi/agent-network`) and run `anet hub start`, which wires up the port, default admin account, recovery admin `utok_`, and local config for you.
 
 ## Quick start (verified)
 

package/bin/commhub.ts

@@ -54,5 +54,9 @@ Examples:
   }
 }
 
-// Load the server
-import("../src/index.js");
+// Load the server module (side-effect-free since the #438 corrective:
+// importing binds nothing) and start the hub EXPLICITLY. Never rely on
+// import side effects or import.meta.main here — this bin is a dynamic
+// importer, where import.meta.main is false inside the module.
+const { startHub } = await import("../src/server.js");
+startHub();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.21",
+  "version": "0.9.0-preview.22",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
   "type": "module",
   "main": "src/index.ts",

package/src/api-host-supervisors-fallback.test.ts

@@ -27,8 +27,10 @@ import { register, login, createNetwork } from "./auth.js";
 import { db } from "./db.js";
 
 const SERVER_DB = mkdtempSync(join(tmpdir(), "anet-hs-fallback-db-")) + "/commhub.db";
-const PORT = 18000 + Math.floor(Math.random() * 1000);
-const BASE = `http://127.0.0.1:${PORT}`;
+// #438 corrective: private bootServer({ port: 0 }) instance (see
+// uploads-http.test.ts for rationale).
+let BASE = "";
+let server: any = null;
 
 // Three users:
 //   soloUser    — single accessible network (fallback should work)
@@ -41,7 +43,6 @@ let soloDaemonAlias = "";
 
 beforeAll(async () => {
   process.env.COMMHUB_DB = SERVER_DB;
-  process.env.PORT = String(PORT);
   process.env.HOST = "127.0.0.1";
 
   const suffix = `${Date.now()}_${Math.floor(Math.random() * 1000)}`;
@@ -53,6 +54,12 @@ beforeAll(async () => {
   // case a false-negative for our fix contract.
   const seed = register(`seed_admin_${suffix}`, password, undefined, "seed");
   if (!seed.ok || !seed.token) throw new Error("seed admin failed: " + JSON.stringify(seed));
+  // "First registered user is auto-admin" only holds when this suite has
+  // the DB to itself. In an aggregate run another suite registers first,
+  // the seed lands as a plain user, and paths 7/8 silently test the
+  // wrong role. Promote explicitly — resolveToken reads users.role at
+  // request time, so promotion after token issuance is effective.
+  db.run("UPDATE users SET role = 'admin' WHERE username = ?1", [`seed_admin_${suffix}`]);
   // Save the admin token so path 7 can hit /api/host-supervisors as an
   // admin directly (通信龙 review point 1: verify admin+no-query goes 400
   // explicitly, not only implicitly via seed_admin's shadow presence).
@@ -108,8 +115,10 @@ beforeAll(async () => {
     userIdForToken: login(`multi_${suffix}`, password).user!.user_id,
   });
 
-  // Import triggers Bun.serve at module load — this IS the server start.
-  await import("./index.js");
+  // server.ts is side-effect-free to import; boot a private instance.
+  const { bootServer } = await import("./server.js");
+  server = bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${server.port}`;
   await new Promise((r) => setTimeout(r, 100));
 });
 
@@ -145,6 +154,7 @@ function seedHostSupervisorDaemon(opts: {
 }
 
 afterAll(() => {
+  try { server?.stop?.(true); } catch {}
   try { rmSync(SERVER_DB, { recursive: true, force: true }); } catch {}
 });
 

package/src/avatar-validate.test.ts

@@ -0,0 +1,113 @@
+// #462 — unit tests for the avatar_url XSS boundary (avatar-validate.ts).
+//
+// The validator's whole job is to keep hostile values out of a dashboard
+// <img src>; every rejection case here is a concrete injection shape.
+// Live-gate check: replace validateAvatarUrl with `return { ok: true,
+// value: String(raw) }` and the javascript:/data:/control-char tests go
+// red.
+
+import { describe, expect, test } from "bun:test";
+import { MAX_AVATAR_URL_LENGTH, validateAvatarUrl } from "./avatar-validate";
+
+describe("#462 validateAvatarUrl", () => {
+  test("accepts plain https URL", () => {
+    const r = validateAvatarUrl("https://cdn.example.com/a/b.png");
+    expect(r).toEqual({ ok: true, value: "https://cdn.example.com/a/b.png" });
+  });
+
+  test("accepts http URL and trims surrounding whitespace", () => {
+    const r = validateAvatarUrl("  http://example.com/x.jpg  ");
+    expect(r).toEqual({ ok: true, value: "http://example.com/x.jpg" });
+  });
+
+  test("accepts URL with query string", () => {
+    const r = validateAvatarUrl("https://example.com/img?size=64&v=2");
+    expect(r.ok).toBe(true);
+  });
+
+  test("null / undefined / empty / whitespace-only → clear (value null)", () => {
+    expect(validateAvatarUrl(null)).toEqual({ ok: true, value: null });
+    expect(validateAvatarUrl(undefined)).toEqual({ ok: true, value: null });
+    expect(validateAvatarUrl("")).toEqual({ ok: true, value: null });
+    expect(validateAvatarUrl("   ")).toEqual({ ok: true, value: null });
+  });
+
+  test("rejects non-string types", () => {
+    expect(validateAvatarUrl(42).ok).toBe(false);
+    expect(validateAvatarUrl({ url: "https://x" }).ok).toBe(false);
+    expect(validateAvatarUrl(["https://x"]).ok).toBe(false);
+    expect(validateAvatarUrl(true).ok).toBe(false);
+  });
+
+  test("rejects javascript: pseudo-protocol", () => {
+    expect(validateAvatarUrl("javascript:alert(1)").ok).toBe(false);
+    expect(validateAvatarUrl("JavaScript:alert(1)").ok).toBe(false);
+    expect(validateAvatarUrl("JAVASCRIPT:alert(document.cookie)").ok).toBe(false);
+  });
+
+  test("rejects javascript: smuggled via embedded tab/newline (URL() would strip them)", () => {
+    expect(validateAvatarUrl("java\tscript:alert(1)").ok).toBe(false);
+    expect(validateAvatarUrl("java\nscript:alert(1)").ok).toBe(false);
+    expect(validateAvatarUrl("java\rscript:alert(1)").ok).toBe(false);
+  });
+
+  test("rejects data: / vbscript: / file: / blob: and other non-http protocols", () => {
+    expect(validateAvatarUrl("data:text/html,<script>alert(1)</script>").ok).toBe(false);
+    expect(validateAvatarUrl("data:image/png;base64,iVBORw0KGgo=").ok).toBe(false);
+    expect(validateAvatarUrl("vbscript:msgbox(1)").ok).toBe(false);
+    expect(validateAvatarUrl("file:///etc/passwd").ok).toBe(false);
+    expect(validateAvatarUrl("blob:https://example.com/uuid").ok).toBe(false);
+    expect(validateAvatarUrl("ftp://example.com/a.png").ok).toBe(false);
+  });
+
+  test("rejects relative / protocol-relative / non-URL strings", () => {
+    expect(validateAvatarUrl("/avatars/1.png").ok).toBe(false);
+    expect(validateAvatarUrl("//cdn.example.com/1.png").ok).toBe(false);
+    expect(validateAvatarUrl("not a url").ok).toBe(false);
+    expect(validateAvatarUrl("example.com/x.png").ok).toBe(false);
+  });
+
+  test("rejects embedded whitespace and control characters", () => {
+    expect(validateAvatarUrl("https://example.com/a b.png").ok).toBe(false);
+    expect(validateAvatarUrl("https://example.com/a\u0000.png").ok).toBe(false);
+    expect(validateAvatarUrl("https://example.com/a\u009f.png").ok).toBe(false);
+  });
+
+  test("normalizes to parsed.href: markup-hostile chars come out percent-encoded (finding 3)", () => {
+    const r1 = validateAvatarUrl('https://example.com/a"b.png');
+    expect(r1).toEqual({ ok: true, value: "https://example.com/a%22b.png" });
+    const r2 = validateAvatarUrl("https://example.com/</script><script>.png");
+    expect(r2.ok).toBe(true);
+    if (r2.ok) {
+      expect(r2.value).not.toContain("<");
+      expect(r2.value).not.toContain(">");
+    }
+    const r3 = validateAvatarUrl("https://example.com/a`b.png");
+    expect(r3.ok).toBe(true);
+    if (r3.ok) expect(r3.value).not.toContain("`");
+  });
+
+  test("rejects values whose href still carries attribute-breaking chars (single quote)", () => {
+    // WHATWG URL leaves ' un-encoded in the PATH component — href alone
+    // doesn't neutralize it there, so the validator must refuse.
+    expect(validateAvatarUrl("https://example.com/a'b.png").ok).toBe(false);
+    // In the QUERY component ' IS percent-encoded by href → accepted,
+    // but the stored value must carry no raw quote.
+    const q = validateAvatarUrl("https://example.com/x.png?a='1'");
+    expect(q.ok).toBe(true);
+    if (q.ok) expect(q.value).not.toContain("'");
+  });
+
+  test("rejects URLs with embedded credentials (userinfo)", () => {
+    expect(validateAvatarUrl("https://user:pass@example.com/a.png").ok).toBe(false);
+    expect(validateAvatarUrl("https://user@example.com/a.png").ok).toBe(false);
+    expect(validateAvatarUrl("http://:secret@example.com/a.png").ok).toBe(false);
+  });
+
+  test("enforces the length cap", () => {
+    const base = "https://example.com/";
+    const ok = base + "a".repeat(MAX_AVATAR_URL_LENGTH - base.length);
+    expect(validateAvatarUrl(ok).ok).toBe(true);
+    expect(validateAvatarUrl(ok + "a").ok).toBe(false);
+  });
+});

package/src/avatar-validate.ts

@@ -0,0 +1,69 @@
+// #462 — validator for the user-set custom avatar URL (nodes.avatar_url).
+//
+// The value ends up in an <img src> on every dashboard client, so this is
+// an XSS trust boundary: protocol MUST be http/https (rejects javascript:,
+// data:, vbscript:, file:, blob:, …), no whitespace/control characters,
+// bounded length. Pure function, unit-tested in avatar-validate.test.ts.
+
+export const MAX_AVATAR_URL_LENGTH = 2048;
+
+export type AvatarValidation =
+  | { ok: true; value: string | null }
+  | { ok: false; reason: string };
+
+/**
+ * Normalize + validate an untrusted avatar_url patch value.
+ *
+ *   null / undefined / "" / whitespace-only  → { ok, value: null }  (clear)
+ *   valid absolute http(s) URL               → { ok, value: trimmed }
+ *   anything else                            → { ok: false, reason }
+ */
+export function validateAvatarUrl(raw: unknown): AvatarValidation {
+  if (raw === null || raw === undefined) return { ok: true, value: null };
+  if (typeof raw !== "string") {
+    return { ok: false, reason: "avatar_url must be a string or null" };
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return { ok: true, value: null };
+  if (trimmed.length > MAX_AVATAR_URL_LENGTH) {
+    return { ok: false, reason: `avatar_url must be ≤ ${MAX_AVATAR_URL_LENGTH} chars` };
+  }
+  // Reject embedded whitespace + C0/C1 control chars outright. URL()
+  // silently strips some of these (e.g. tabs/newlines), which would let
+  // "java\tscript:" style payloads normalize into a hostile protocol —
+  // so this check must run BEFORE parsing, on the raw trimmed string.
+  if (/[\u0000-\u001f\u007f-\u009f\s]/.test(trimmed)) {
+    return { ok: false, reason: "avatar_url must not contain whitespace or control characters" };
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return { ok: false, reason: "avatar_url must be an absolute URL" };
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return { ok: false, reason: "avatar_url protocol must be http or https" };
+  }
+  // Embedded credentials (https://user:pass@host/…) would be persisted,
+  // leaked to the avatar host on every render, and can spoof the visible
+  // origin in UIs. Reject outright rather than silently stripping — the
+  // caller should know their input carried secrets (通信龙 review round-2
+  // follow-up).
+  if (parsed.username || parsed.password) {
+    return { ok: false, reason: "avatar_url must not contain credentials (userinfo)" };
+  }
+  // Persist the NORMALIZED href, not the raw input: href percent-encodes
+  // markup-hostile characters (" < > ` → %22 %3C %3E %60), so what lands
+  // in the DB is already safe to interpolate into an <img src> attribute.
+  // The dashboard renderer lives in a different package this repo cannot
+  // audit — the server must not bet on it escaping (审查修复 per 通信龙
+  // #461/#462 review, finding 3).
+  const normalized = parsed.href;
+  // Belt-and-braces: reject anything href does NOT encode that could
+  // still break out of an attribute context (WHATWG URL leaves ' and \
+  // untouched in some positions).
+  if (/["'<>\\`]/.test(normalized)) {
+    return { ok: false, reason: "avatar_url contains characters not allowed in a URL" };
+  }
+  return { ok: true, value: normalized };
+}

package/src/boot-side-effect.test.ts

@@ -0,0 +1,124 @@
+// #438 corrective — regression gate for the two boot-path failure modes:
+//
+//   1. import side effect: `import("./server.js")` must NOT bind any port.
+//      Pre-corrective (7fa3ad35, when this module was still index.ts with
+//      module-level `export const server = bootServer()`) this fails:
+//      witnessed-red showed the probe port EADDRINUSE right after import.
+//      The run-entry shim src/index.ts is the ONLY module whose import
+//      boots — by design, documented there — and is deliberately not
+//      imported anywhere in the test suite.
+//   2. silent no-op double start: `startHub()` is single-shot and must
+//      REJECT a second call observably — "I thought I started it but
+//      nothing happened" is the same failure family as the
+//      import.meta.main incident (#438 review).
+//
+// Test order inside this file matters: the no-side-effect probe must run
+// BEFORE anything calls startHub in this process. bun executes tests in
+// declaration order, and no other suite calls startHub.
+
+import { describe, expect, test } from "bun:test";
+
+const PROBE_PORT = 18500 + Math.floor(Math.random() * 500);
+
+describe("#438 corrective — importing server.ts is side-effect-free", () => {
+  test("importing server.js binds nothing (probe port stays free)", async () => {
+    // Pin the module's default PORT to the probe so that IF an import
+    // side effect ever regresses, it binds exactly the port we probe.
+    process.env.PORT = process.env.PORT || String(PROBE_PORT);
+    const probe = Number(process.env.PORT) || PROBE_PORT;
+    await import("./server.js");
+    // If import had booted a server, this bind would throw EADDRINUSE.
+    let listener: any = null;
+    expect(() => {
+      listener = Bun.listen({ hostname: "127.0.0.1", port: probe, socket: { data() {} } });
+    }).not.toThrow();
+    listener?.stop?.(true);
+  });
+});
+
+describe("#476 — import alone must let the process exit", () => {
+  test("a subprocess that only imports server.js exits by itself (no module-level timers hold the loop)", () => {
+    // Witnessed-red: pre-#476 (main 541a80aa) this child is killed by the
+    // timeout with a non-zero exit — two module-level setIntervals
+    // (rate-limit sweep + DB-writing task patrol) held the event loop
+    // after a bare import. Post-#476 both live inside startHub, so the
+    // child exits 0 on its own. Runs in a subprocess because the parent
+    // test process has its own handles and can't observe loop-emptiness.
+    const child = Bun.spawnSync({
+      cmd: ["bun", "-e", 'await import("./src/server.js");'],
+      cwd: `${import.meta.dir}/..`,
+      env: { ...process.env, COMMHUB_DB: process.env.COMMHUB_DB || "/tmp/anet-476-probe.db" },
+      timeout: 10_000,
+    });
+    expect(child.exitCode).toBe(0);
+  }, 15_000);
+
+  test("the moved task patrol actually FIRES under startHub (not just registered-looking)", () => {
+    // Fake-gate guard for the #476 move: stub patrolExpiredTasks to a
+    // no-op (or forget to register it in startHub) and this goes red.
+    // Runs in a subprocess because startHub is single-shot per process
+    // and the patrol period is shrunk via env for observability.
+    const script = `
+      process.env.COMMHUB_TASK_PATROL_MS = "100";
+      const { startHub } = await import("./src/server.js");
+      const { db } = await import("./src/db.js");
+      const hub = startHub({ port: 0, hostname: "127.0.0.1" });
+      db.run("DELETE FROM tasks WHERE task_id = 't476_patrol'");
+      db.run("INSERT INTO tasks (task_id, from_name, to_name, priority, status, content, created_at, expires_at) " +
+             "VALUES ('t476_patrol', 'a', 'b', 'normal', 'delivered', 'x', datetime('now'), datetime('now', '-1 minute'))");
+      await new Promise((r) => setTimeout(r, 600));
+      const row = db.get("SELECT status FROM tasks WHERE task_id = 't476_patrol'");
+      console.log("PATROL_RESULT:" + (row ? row.status : "missing"));
+      db.run("DELETE FROM tasks WHERE task_id = 't476_patrol'");
+      hub.stop(true);
+      process.exit(0);
+    `;
+    const child = Bun.spawnSync({
+      cmd: ["bun", "-e", script],
+      cwd: `${import.meta.dir}/..`,
+      env: { ...process.env, COMMHUB_DB: process.env.COMMHUB_DB || "/tmp/anet-476-patrol.db" },
+      timeout: 15_000,
+    });
+    const out = new TextDecoder().decode(child.stdout);
+    expect(out).toContain("PATROL_RESULT:expired");
+  }, 20_000);
+});
+
+describe("#438 corrective — startHub is explicit, single-shot, observable", () => {
+  test("startHub boots a live hub; second call throws with first boot's coordinates; bootServer stays available", async () => {
+    const { startHub, bootServer, getStartedHub } = await import("./server.js") as any;
+    expect(getStartedHub()).toBeNull();
+
+    const hub = startHub({ port: 0, hostname: "127.0.0.1" });
+    try {
+      expect(hub.port).toBeGreaterThan(0);
+      expect(getStartedHub()?.server).toBe(hub);
+
+      // Really listening — the production liveness probe, not just a
+      // non-null handle.
+      const health = await fetch(`http://127.0.0.1:${hub.port}/health`);
+      expect(health.status).toBe(200);
+      expect(((await health.json()) as any).ok).toBe(true);
+
+      // Second call must be an OBSERVABLE rejection, not a silent no-op,
+      // and must tell the caller where the first boot lives.
+      let thrown: Error | null = null;
+      try {
+        startHub({ port: 0 });
+      } catch (e: any) {
+        thrown = e;
+      }
+      expect(thrown).not.toBeNull();
+      expect(String(thrown!.message)).toContain("single-shot");
+      expect(String(thrown!.message)).toContain(String(hub.port));
+
+      // Throwaway instances stay available after startHub.
+      const extra = bootServer({ port: 0, hostname: "127.0.0.1" });
+      expect(extra.port).toBeGreaterThan(0);
+      expect(extra.port).not.toBe(hub.port);
+      extra.stop(true);
+    } finally {
+      hub.stop(true);
+    }
+  });
+});

package/src/db.ts

@@ -338,6 +338,16 @@ try {
   if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
 }
 
+// #462 — user-set custom avatar (nullable http/https image URL). Pure
+// display attribute: deliberately NOT part of the RFC-024 config-apply
+// pipeline (nothing for agent-node to consume, no revision/ack). Written
+// only via PUT /api/nodes/:ref/avatar which validates the URL shape.
+try {
+  db.exec(`ALTER TABLE nodes ADD COLUMN avatar_url TEXT`);
+} catch (e: any) {
+  if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+}
+
 // RFC-027 §2 — stop/delete request envelope. Mirrors
 // node_create_requests structure so the daemon-side pull/ack pattern
 // is symmetric with create_node. action='stop'|'delete' picks which

package/src/health-redaction.test.ts

@@ -0,0 +1,176 @@
+// #473 — /health information-leak redaction.
+//
+// Public-hub audit (通信龙, 2026-07-30) showed anonymous GET /health
+// returning the full SSE key breakdown: `{networkId}:{alias}` for every
+// live connection — network id + all 95 agent aliases on the audited
+// hub. The fix keeps /health anonymous (HARD CONSTRAINT: the central
+// watchdog curls it every minute; auth here would blind it) but strips
+// the per-key detail down to aggregate counts; the detail moved behind
+// auth at GET /api/stats/sse (master token or admin only).
+//
+// Witnessed-red: on pre-fix main (8c11edf5) the "no leak" test below is
+// red — the /health body contains the connected alias and network id.
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register } from "./auth.js";
+import { db } from "./db.js";
+
+const SERVER_DB = mkdtempSync(join(tmpdir(), "anet-health-red-db-")) + "/commhub.db";
+
+let BASE = "";
+let server: any = null;
+let sseReader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+
+let userToken = "";
+let userNetworkId = "";
+let userName = "";
+let adminToken = "";
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB = process.env.COMMHUB_DB || SERVER_DB;
+  process.env.HOST = "127.0.0.1";
+
+  const suffix = `${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+  const pw = "BootstrapPw123Aa!";
+
+  // Burn a seed registration first so our member is NOT auto-admin (the
+  // "first registered user → admin" rule only bites when this suite owns
+  // the DB; per-file runs need this guard). We set roles explicitly below.
+  register(`health_seed_${suffix}`, pw, undefined, "seed");
+
+  userName = `health_user_${suffix}`;
+  const r = register(userName, pw, undefined, "seed");
+  if (!r.ok || !r.token) throw new Error("register failed: " + JSON.stringify(r));
+  userToken = r.token;
+  userNetworkId = r.network_id ?? "";
+  if (!userNetworkId) throw new Error("no network for user");
+  // Pin to plain member — defend against any residual auto-admin.
+  db.run("UPDATE users SET role = 'user' WHERE username = ?1", [userName]);
+
+  const adminName = `health_admin_${suffix}`;
+  const a = register(adminName, pw, undefined, "seed");
+  if (!a.ok || !a.token) throw new Error("admin register failed: " + JSON.stringify(a));
+  adminToken = a.token;
+  // Explicit promotion — "first registered user is auto-admin" does not
+  // hold in aggregate runs (see api-host-supervisors-fallback.test.ts).
+  db.run("UPDATE users SET role = 'admin' WHERE username = ?1", [adminName]);
+
+  const { bootServer } = await import("./server.js");
+  server = bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${server.port}`;
+
+  // Open a real SSE connection so the stats have a key that WOULD leak:
+  // the dashboard-user channel (sessionName === own username, Path 3
+  // gate 4a) registers `${networkId}:${username}` in the clients map.
+  const res = await fetch(`${BASE}/events/${encodeURIComponent(userName)}?network_id=${userNetworkId}`, {
+    headers: { Authorization: `Bearer ${userToken}` },
+  });
+  if (res.status !== 200) throw new Error("SSE subscribe failed: " + res.status);
+  sseReader = res.body!.getReader();
+  await sseReader.read(); // consume the connected frame → registration done
+});
+
+afterAll(() => {
+  try { sseReader?.cancel(); } catch {}
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(SERVER_DB, { recursive: true, force: true }); } catch {}
+});
+
+describe("#473 anonymous /health — watchdog contract intact, no topology leak", () => {
+  test("stays anonymous 200 with parseable aggregates (watchdog judge: curl -sf gets 2xx)", async () => {
+    const res = await fetch(`${BASE}/health`);
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.ok).toBe(true);
+    expect(typeof body.version).toBe("string");
+    expect(typeof body.sessions_count).toBe("number");
+    expect(typeof body.sse_connections).toBe("number");
+    expect(body.sse_connections).toBeGreaterThanOrEqual(1);
+  });
+
+  test("CLI count source stays truthful: health.sse_connections == /api/stats/sse total (no fake 0)", async () => {
+    // The CLI's `anet doctor` line reads health.sse_connections now
+    // (was Object.keys(sse_sessions).length). This pins that aggregate to
+    // the same number the auth-gated detail endpoint reports — so a live
+    // hub with N connections shows N, never the "0 active" regression the
+    // review caught. There is exactly one live SSE connection in setup.
+    const health = await (await fetch(`${BASE}/health`)).json() as any;
+    const detail = await (await fetch(`${BASE}/api/stats/sse`, { headers: { Authorization: `Bearer ${adminToken}` } })).json() as any;
+    expect(health.sse_connections).toBe(detail.total);
+    expect(health.sse_connections).toBeGreaterThanOrEqual(1);
+  });
+
+  test("does NOT expose SSE key detail: no sse_sessions field, no alias, no network id", async () => {
+    const res = await fetch(`${BASE}/health`);
+    const text = await res.text();
+    const body = JSON.parse(text);
+    expect("sse_sessions" in body).toBe(false);
+    // The live connection's identifying strings must not appear anywhere
+    // in the anonymous body.
+    expect(text).not.toContain(userName);
+    expect(text).not.toContain(userNetworkId);
+  });
+});
+
+describe("#473 GET /api/stats/sse — detail survives, behind ops auth", () => {
+  test("anonymous → 401", async () => {
+    const res = await fetch(`${BASE}/api/stats/sse`);
+    expect(res.status).toBe(401);
+  });
+
+  test("regular member token → 403 (detail spans every network)", async () => {
+    const res = await fetch(`${BASE}/api/stats/sse`, { headers: { Authorization: `Bearer ${userToken}` } });
+    expect(res.status).toBe(403);
+  });
+
+  test("admin → 200 with the full key breakdown (ops capability preserved)", async () => {
+    const res = await fetch(`${BASE}/api/stats/sse`, { headers: { Authorization: `Bearer ${adminToken}` } });
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.ok).toBe(true);
+    expect(typeof body.total).toBe("number");
+    expect(body.sessions[`${userNetworkId}:${userName}`]).toBeGreaterThanOrEqual(1);
+  });
+
+  test("legacy master token → 200 (ops path — restAuth null, isLegacyAuthToken)", () => {
+    // COMMHUB_AUTH_TOKEN is captured at module import, so this path needs
+    // a fresh process with the env set before boot (aggregate order can't
+    // guarantee this file imports server.ts first). Subprocess, like the
+    // patrol test. Reviewer flagged this path had code but no test.
+    const script = `
+      process.env.COMMHUB_AUTH_TOKEN = "master-secret-xyz";
+      const { startHub } = await import("./src/server.js");
+      const hub = startHub({ port: 0, hostname: "127.0.0.1" });
+      const base = "http://127.0.0.1:" + hub.port;
+      const anon = await fetch(base + "/api/stats/sse");
+      const master = await fetch(base + "/api/stats/sse", { headers: { Authorization: "Bearer master-secret-xyz" } });
+      const health = await fetch(base + "/health");
+      const hb = await health.json();
+      console.log("RESULT:" + JSON.stringify({
+        anon: anon.status,
+        master: master.status,
+        masterOk: (await master.json()).ok,
+        healthHasSseSessions: "sse_sessions" in hb,
+      }));
+      hub.stop(true);
+      process.exit(0);
+    `;
+    const child = Bun.spawnSync({
+      cmd: ["bun", "-e", script],
+      cwd: `${import.meta.dir}/..`,
+      env: { ...process.env, COMMHUB_DB: process.env.COMMHUB_DB || "/tmp/anet-473-master.db" },
+      timeout: 15_000,
+    });
+    const out = new TextDecoder().decode(child.stdout);
+    const m = out.match(/RESULT:(\{.*\})/);
+    expect(m).not.toBeNull();
+    const r = JSON.parse(m![1]);
+    expect(r.anon).toBe(401);        // token configured → anonymous rejected
+    expect(r.master).toBe(200);      // legacy master token → ops access
+    expect(r.masterOk).toBe(true);
+    expect(r.healthHasSseSessions).toBe(false); // /health still redacted with a token set
+  }, 20_000);
+});