@sleep2agi/commhub-server 0.9.0-preview.27 → 0.9.0-preview.29

package/src/rest-explicit-columns-http.test.ts

@@ -0,0 +1,149 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  AUDIT_LOG_REST_COLUMNS,
+  COMPLETION_REST_COLUMNS,
+  NETWORK_REST_COLUMNS,
+  SESSION_REST_COLUMNS,
+  TASK_EVENT_REST_COLUMNS,
+  TASK_REST_COLUMNS,
+  SCHEDULED_TASK_STORAGE_COLUMNS,
+} from "./rest-projections.js";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-rest-columns-"));
+process.env.COMMHUB_DB ||= join(PRIVATE_DB_DIR, "hub.db");
+
+let db: typeof import("./db.js").db;
+let server: ReturnType<typeof Bun.serve>;
+let base = "";
+let token = "";
+let networkId = "";
+
+const INTERNAL_SENTINEL = "future_internal_only";
+const sortedKeys = (value: Record<string, unknown>): string[] => Object.keys(value).sort();
+const sorted = (values: readonly string[]): string[] => [...values].sort();
+
+async function api(path: string): Promise<any> {
+  const response = await fetch(`${base}${path}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  expect(response.status).toBe(200);
+  return response.json();
+}
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { register } = await import("./auth.js");
+  const auth = register(`rest_shape_${Date.now()}`, "RestShape-Strong-1!", undefined, "rest-shape");
+  expect(auth.ok).toBe(true);
+  token = auth.token!;
+  networkId = auth.network_id!;
+
+  // Simulate future migrations. Any REST SELECT * silently broadcasts these
+  // columns; every endpoint below must keep them private without needing a
+  // code change when the table grows.
+  for (const table of ["networks", "sessions", "audit_log", "task_events", "tasks", "completions", "scheduled_tasks"]) {
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${INTERNAL_SENTINEL} TEXT`);
+  }
+
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, agent, model, network_id, external_schedules)
+     VALUES ('resume-rest-shape', 'rest-shape-node', 'idle', 'agent-node:codex', 'gpt-shape', ?1, ?2)`,
+    [networkId, JSON.stringify({ observed_at: "2026-08-10T02:00:00.000Z", schedules: [] })],
+  );
+  db.run(
+    `INSERT INTO tasks (task_id, from_name, to_name, status, content, priority, network_id, parent_task_id, meta_json)
+     VALUES ('task-rest-shape', 'sender', 'rest-shape-node', 'delivered', 'shape', 'normal', ?1, 'parent-shape', '{"attachment":true}')`,
+    [networkId],
+  );
+  db.run(
+    `INSERT INTO task_events (task_id, from_status, to_status, actor, detail, network_id)
+     VALUES ('task-rest-shape', 'created', 'delivered', 'shape-test', 'shape', ?1)`,
+    [networkId],
+  );
+  db.run(
+    `INSERT INTO completions (id, session_name, task, result, network_id)
+     VALUES ('completion-rest-shape', 'rest-shape-node', 'shape', 'done', ?1)`,
+    [networkId],
+  );
+  db.run(
+    `INSERT INTO audit_log (user_id, username, action, target_type, target_id, detail, ip, network_id)
+     VALUES ((SELECT owner_id FROM networks WHERE network_id = ?1), 'shape-user', 'shape_action', 'shape', 'shape-id', 'shape', '127.0.0.1', ?1)`,
+    [networkId],
+  );
+  db.run(
+    `INSERT INTO scheduled_tasks
+       (schedule_id, network_id, created_by, name, target_node_id, target_alias,
+        task_content, schedule_type, schedule_json, timezone, next_run_at)
+     VALUES ('schedule-rest-shape', ?1, 'private-user-id', 'shape schedule',
+             'node-rest-shape', 'rest-shape-node', 'shape task', 'interval',
+             '{"type":"interval","every_seconds":3600}', 'UTC', '2099-01-01T00:00:00.000Z')`,
+    [networkId],
+  );
+
+  const mod = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+});
+
+afterAll(() => {
+  try { server?.stop(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("#311 REST response projections are stable across future ALTER TABLE", () => {
+  test("network list and detail preserve their existing public keys", async () => {
+    const list = await api("/api/networks");
+    const row = list.networks.find((item: any) => item.network_id === networkId);
+    expect(sortedKeys(row)).toEqual(sorted([...NETWORK_REST_COLUMNS, "member_role", "name"]));
+    expect(row[INTERNAL_SENTINEL]).toBeUndefined();
+
+    const detail = await api(`/api/networks/${networkId}`);
+    expect(sortedKeys(detail.network)).toEqual(sorted(NETWORK_REST_COLUMNS));
+    expect(detail.network[INTERNAL_SENTINEL]).toBeUndefined();
+  });
+
+  test("full status preserves telemetry compatibility without storage drift", async () => {
+    const body = await api(`/api/status?network_id=${networkId}`);
+    const row = body.sessions.find((item: any) => item.alias === "rest-shape-node");
+    expect(sortedKeys(row)).toEqual(sorted([...SESSION_REST_COLUMNS, "runtime", "host", "process_telemetry"]));
+    expect(row[INTERNAL_SENTINEL]).toBeUndefined();
+    expect(row.external_schedules).toEqual({ observed_at: "2026-08-10T02:00:00.000Z", schedules: [] });
+  });
+
+  test("task list and task detail expose the same explicit contract", async () => {
+    const list = await api(`/api/tasks?network_id=${networkId}&task_id=task-rest-shape&skip_stats=1`);
+    expect(sortedKeys(list.tasks[0])).toEqual(sorted(TASK_REST_COLUMNS));
+    expect(list.tasks[0][INTERNAL_SENTINEL]).toBeUndefined();
+
+    const detail = await api(`/api/tasks/task-rest-shape?network_id=${networkId}`);
+    expect(sortedKeys(detail.task)).toEqual(sorted(TASK_REST_COLUMNS));
+    expect(detail.task[INTERNAL_SENTINEL]).toBeUndefined();
+  });
+
+  test("audit, task-event, and completion rows are explicit", async () => {
+    const audit = await api("/api/audit-log?action=shape_action");
+    expect(sortedKeys(audit.logs[0])).toEqual(sorted(AUDIT_LOG_REST_COLUMNS));
+    expect(audit.logs[0][INTERNAL_SENTINEL]).toBeUndefined();
+
+    const events = await api(`/api/task_events?network_id=${networkId}&task_id=task-rest-shape`);
+    expect(sortedKeys(events.events[0])).toEqual(sorted(TASK_EVENT_REST_COLUMNS));
+    expect(events.events[0][INTERNAL_SENTINEL]).toBeUndefined();
+
+    const completions = await api(`/api/completions?network_id=${networkId}&since=2000-01-01T00:00:00.000Z`);
+    expect(sortedKeys(completions.completions[0])).toEqual(sorted(COMPLETION_REST_COLUMNS));
+    expect(completions.completions[0][INTERNAL_SENTINEL]).toBeUndefined();
+  });
+
+  test("scheduled-task decoding keeps storage-only identity and JSON private", async () => {
+    const body = await api(`/api/scheduled-tasks?network_id=${networkId}`);
+    const row = body.schedules.find((item: any) => item.schedule_id === "schedule-rest-shape");
+    const publicColumns = SCHEDULED_TASK_STORAGE_COLUMNS.filter((key) => key !== "created_by" && key !== "schedule_json");
+    expect(sortedKeys(row)).toEqual(sorted([...publicColumns, "schedule"]));
+    expect(row.created_by).toBeUndefined();
+    expect(row.schedule_json).toBeUndefined();
+    expect(row[INTERNAL_SENTINEL]).toBeUndefined();
+  });
+});

package/src/rest-identity.test.ts

@@ -0,0 +1,120 @@
+// REST from_session identity binding.
+//
+// Run: COMMHUB_DB=/tmp/rest-identity-test.db bun test src/rest-identity.test.ts
+// (COMMHUB_DB must be set explicitly — unset defaults to the production DB.)
+//
+// Assertion discipline: results are compared with toEqual against the whole
+// object, so a widened accepted-set fails instead of silently passing.
+
+import { describe, expect, test } from "bun:test";
+import { nodeAliasForToken, resolveRestFromSession } from "./rest-identity.js";
+
+const NTOK = "ntok_abc123";
+const UTOK = "utok_abc123";
+
+describe("REST from_session identity binding", () => {
+  test("node token claiming another node's alias is refused", () => {
+    expect(resolveRestFromSession({
+      token: NTOK,
+      tokenName: "node:通信IM牛",
+      requestedFrom: "通信龙",
+    })).toEqual({
+      ok: false,
+      error: "from_session_identity_mismatch",
+      message: "network token from_session does not match token-bound node alias",
+      tokenAlias: "通信IM牛",
+      requestedFromSession: "通信龙",
+    });
+  });
+
+  test("node token omitting from is bound to its own alias, not 'api'", () => {
+    expect(resolveRestFromSession({
+      token: NTOK,
+      tokenName: "node:通信IM牛",
+      requestedFrom: undefined,
+    })).toEqual({ ok: true, fromSession: "通信IM牛" });
+  });
+
+  test("node token claiming its own alias is accepted", () => {
+    expect(resolveRestFromSession({
+      token: NTOK,
+      tokenName: "node:通信IM牛",
+      requestedFrom: "通信IM牛",
+    })).toEqual({ ok: true, fromSession: "通信IM牛" });
+  });
+
+  test("whitespace padding does not defeat the comparison", () => {
+    expect(resolveRestFromSession({
+      token: NTOK,
+      tokenName: "node:通信IM牛",
+      requestedFrom: "  通信IM牛  ",
+    })).toEqual({ ok: true, fromSession: "通信IM牛" });
+  });
+
+  // The Dashboard posts as its logged-in user; this path must not change.
+  test("user token keeps the previous behaviour", () => {
+    expect(resolveRestFromSession({
+      token: UTOK,
+      tokenName: "dashboard",
+      requestedFrom: "admin",
+    })).toEqual({ ok: true, fromSession: "admin" });
+  });
+
+  test("user token with no from still defaults to 'api'", () => {
+    expect(resolveRestFromSession({
+      token: UTOK,
+      tokenName: null,
+      requestedFrom: undefined,
+    })).toEqual({ ok: true, fromSession: "api" });
+  });
+
+  // A non-string `from` must not be coerced into an identity.
+  test("non-string from is not treated as a claim", () => {
+    expect(resolveRestFromSession({
+      token: NTOK,
+      tokenName: "node:通信IM牛",
+      requestedFrom: { toString: () => "通信龙" },
+    })).toEqual({ ok: true, fromSession: "通信IM牛" });
+  });
+
+  // A network-bound token we cannot resolve to an alias must not be able to
+  // call itself anything. Found by independent review of this change.
+  describe("ntok_ with an unresolvable alias fails closed", () => {
+    for (const tokenName of ["node:", "node:   ", "dashboard", null, undefined]) {
+      test(`claim is refused when tokenName is ${JSON.stringify(tokenName)}`, () => {
+        expect(resolveRestFromSession({
+          token: NTOK,
+          tokenName,
+          requestedFrom: "通信龙",
+        })).toEqual({
+          ok: false,
+          error: "from_session_identity_mismatch",
+          message: "network token has no resolvable node alias and may not claim a from_session",
+          tokenAlias: "",
+          requestedFromSession: "通信龙",
+        });
+      });
+    }
+
+    test("no claim at all still resolves to 'api'", () => {
+      expect(resolveRestFromSession({
+        token: NTOK,
+        tokenName: "node:",
+        requestedFrom: undefined,
+      })).toEqual({ ok: true, fromSession: "api" });
+    });
+  });
+
+  describe("nodeAliasForToken", () => {
+    test("only ntok_ + node: prefix yields an alias", () => {
+      expect(nodeAliasForToken(NTOK, "node:X")).toBe("X");
+      // A user token whose name merely looks node-shaped must not bind.
+      expect(nodeAliasForToken(UTOK, "node:X")).toBeNull();
+      // A node token whose name is not node-scoped must not bind.
+      expect(nodeAliasForToken(NTOK, "dashboard")).toBeNull();
+      expect(nodeAliasForToken(NTOK, null)).toBeNull();
+      // `node:` with nothing after it is not an identity.
+      expect(nodeAliasForToken(NTOK, "node:   ")).toBeNull();
+    });
+  });
+});

package/src/rest-identity.ts

@@ -0,0 +1,93 @@
+// REST from_session identity binding.
+//
+// Both transports resolve the same `api_tokens` row through resolveToken, and
+// auth.ts already states the invariant:
+//
+//   "Network-bound node tokens are an identity boundary: they must not spoof
+//    another node via from_session."
+//
+// tools.ts enforced it for MCP (defaultFrom + fromIdentityMismatchReply).
+// POST /api/task did not — it took `body.from` verbatim, so any node holding
+// its own ntok_ could claim another node's alias. That value is stored on the
+// task row and, once sender labels reach the copresence TUIs, rendered to a
+// human as an attribution.
+//
+// This is the same decision expressed as a pure function so every credential
+// kind is a directly constructible test input rather than a hand-assembled
+// Request (the #503 convention in this codebase).
+
+export interface RestIdentityInput {
+  /** Raw bearer token, only its prefix matters (`ntok_` = network-bound). */
+  token: string;
+  /** `api_tokens.name`; for node tokens it is `node:<alias>`. */
+  tokenName: string | null | undefined;
+  /** Caller-supplied `body.from`. */
+  requestedFrom: unknown;
+}
+
+export type RestIdentityResult =
+  | { ok: true; fromSession: string }
+  | {
+      ok: false;
+      error: "from_session_identity_mismatch";
+      message: string;
+      tokenAlias: string;
+      requestedFromSession: string;
+    };
+
+/** Alias a token is bound to, or null when it is not node-scoped. */
+export function nodeAliasForToken(token: string, tokenName: string | null | undefined): string | null {
+  if (!token.startsWith("ntok_")) return null;
+  if (typeof tokenName !== "string" || !tokenName.startsWith("node:")) return null;
+  const alias = tokenName.slice("node:".length).trim();
+  return alias || null;
+}
+
+export function resolveRestFromSession(input: RestIdentityInput): RestIdentityResult {
+  const alias = nodeAliasForToken(input.token, input.tokenName);
+  const requested = typeof input.requestedFrom === "string" ? input.requestedFrom.trim() : "";
+
+  // A network-bound token whose name we cannot resolve to an alias (`node:`,
+  // `node:   `, or a name that was never node-scoped) is the degenerate case.
+  // We know it IS a node credential; we just cannot tell WHICH node. Letting it
+  // claim anything is the worst available option, so refuse the claim outright
+  // rather than falling through to the unbound path.
+  //
+  // Production always writes `node:${nodeName}`, so this costs nothing real —
+  // but "we couldn't identify you, so you may call yourself anything" is
+  // exactly the fail-open shape this change exists to remove.
+  if (!alias && input.token.startsWith("ntok_")) {
+    if (requested) {
+      return {
+        ok: false,
+        error: "from_session_identity_mismatch",
+        message: "network token has no resolvable node alias and may not claim a from_session",
+        tokenAlias: "",
+        requestedFromSession: requested,
+      };
+    }
+    return { ok: true, fromSession: "api" };
+  }
+
+  // Not a node token: unchanged behaviour. The Dashboard legitimately posts as
+  // its logged-in user; tightening that is a separate change with its own
+  // compatibility surface.
+  if (!alias) {
+    return { ok: true, fromSession: requested || "api" };
+  }
+
+  // Node token claiming somebody else — refuse rather than silently rewrite,
+  // so a misconfigured caller is visible instead of quietly relabelled.
+  if (requested && requested !== alias) {
+    return {
+      ok: false,
+      error: "from_session_identity_mismatch",
+      message: "network token from_session does not match token-bound node alias",
+      tokenAlias: alias,
+      requestedFromSession: requested,
+    };
+  }
+
+  // Node token, no claim or a matching one: bind to the token's own alias.
+  return { ok: true, fromSession: alias };
+}

package/src/rest-projections.ts

@@ -0,0 +1,67 @@
+/**
+ * Stable REST row projections.
+ *
+ * These lists deliberately mirror the fields already exposed by the public
+ * endpoints before #311.  Keeping them in one place makes the wire contract
+ * independent from future ALTER TABLE migrations: adding a storage-only
+ * column must never silently add a REST response key.
+ */
+export const NETWORK_REST_COLUMNS = [
+  "network_id", "network_name", "owner_id", "description", "settings",
+  "created_at", "updated_at", "visibility", "max_members",
+] as const;
+
+export const SESSION_REST_COLUMNS = [
+  "resume_id", "alias", "tmux_name", "server", "ip", "hostname", "agent",
+  "project_dir", "version", "status", "task", "output", "progress", "score",
+  "cpu_load_1min", "cpu_cores", "mem_total_gb", "mem_used_gb", "mem_avail_gb",
+  "disk_total_gb", "disk_used_gb", "disk_avail_gb", "process_rss_bytes",
+  "process_rss_mb", "process_cpu_pct", "process_uptime_seconds",
+  "process_in_flight_count", "network_id", "registered_at", "updated_at",
+  "node_id", "session_id", "config_path", "channels", "last_seen_at", "model",
+  "external_schedules",
+] as const;
+
+export const AUDIT_LOG_REST_COLUMNS = [
+  "id", "user_id", "username", "action", "target_type", "target_id", "detail",
+  "ip", "network_id", "created_at",
+] as const;
+
+export const TASK_EVENT_REST_COLUMNS = [
+  "id", "task_id", "from_status", "to_status", "event_type", "actor", "detail",
+  "created_at", "network_id",
+] as const;
+
+export const TASK_REST_COLUMNS = [
+  "task_id", "from_node_id", "from_name", "to_node_id", "to_name", "priority",
+  "status", "content", "result", "in_reply_to", "requires_response", "scope",
+  "created_at", "delivered_at", "started_at", "runtime_submitted_at", "consumed_at", "completed_at", "expires_at",
+  "network_id", "parent_task_id", "meta_json",
+] as const;
+
+export const COMPLETION_REST_COLUMNS = [
+  "id", "session_name", "task", "result", "artifacts", "score",
+  "duration_minutes", "network_id", "completed_at",
+] as const;
+
+// Storage projection for scheduled-task rows. `created_by` and
+// `schedule_json` are intentionally selected for server-side auth/decoding,
+// then removed by decodeRow before the REST response is serialized.
+export const SCHEDULED_TASK_STORAGE_COLUMNS = [
+  "schedule_id", "network_id", "created_by", "name", "target_node_id",
+  "target_alias", "task_content", "priority", "schedule_type", "schedule_json",
+  "timezone", "overlap_policy", "misfire_policy", "status", "next_run_at",
+  "last_run_at", "revision", "created_at", "updated_at",
+] as const;
+
+export function sqlColumns(columns: readonly string[], qualifier?: string): string {
+  return columns.map((column) => qualifier ? `${qualifier}.${column}` : column).join(", ");
+}
+
+export const NETWORK_REST_SELECT = sqlColumns(NETWORK_REST_COLUMNS);
+export const SESSION_REST_SELECT = sqlColumns(SESSION_REST_COLUMNS);
+export const AUDIT_LOG_REST_SELECT = sqlColumns(AUDIT_LOG_REST_COLUMNS);
+export const TASK_EVENT_REST_SELECT = sqlColumns(TASK_EVENT_REST_COLUMNS);
+export const TASK_REST_SELECT = sqlColumns(TASK_REST_COLUMNS);
+export const COMPLETION_REST_SELECT = sqlColumns(COMPLETION_REST_COLUMNS);
+export const SCHEDULED_TASK_STORAGE_SELECT = sqlColumns(SCHEDULED_TASK_STORAGE_COLUMNS);