@sleep2agi/commhub-server 0.9.0-preview.13 → 0.9.0-preview.131

package/src/rest-identity.ts

@@ -0,0 +1,139 @@
+// 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.
+//
+// Production network tokens pass tokenId and resolve through resolveNodeCaller.
+// A token whose name is not `node:` (not_a_node_token, the registration token
+// before report_status) falls back to nodeAliasForToken, same as main.
+// tokenId omitted keeps the name-only shape used by the unit cases below.
+
+import { resolveNodeCaller } from "./create-node.js";
+
+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;
+  /** Set on the production path. Network tokens then ignore tokenName as authority. */
+  tokenId?: string | null;
+  /** Username resolved from the authenticated token. */
+  authenticatedUsername?: string | null;
+  /** 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;
+}
+
+/** Human dispatches use the authenticated username; node credentials represent nodes. */
+export function resolveUserTaskFromSession(username: string | null | undefined, requestedFrom: unknown): RestIdentityResult {
+  const fromSession = username?.trim() || "api";
+  const requested = typeof requestedFrom === "string" ? requestedFrom.trim() : "";
+  if (requested && requested !== fromSession) {
+    return {
+      ok: false,
+      error: "from_session_identity_mismatch",
+      message: "user token task sender must match the authenticated username",
+      tokenAlias: fromSession,
+      requestedFromSession: requested,
+    };
+  }
+  return { ok: true, fromSession };
+}
+
+export function resolveRestFromSession(input: RestIdentityInput): RestIdentityResult {
+  const requested = typeof input.requestedFrom === "string" ? input.requestedFrom.trim() : "";
+  let alias: string | null;
+  if (input.token.startsWith("ntok_") && input.tokenId) {
+    const resolved = resolveNodeCaller(input.tokenId);
+    if (resolved.ok) {
+      alias = resolved.alias;
+    } else if (resolved.reason === "not_a_node_token") { // board679-plain-ntok-rest
+      // Name is not `node:` yet. Main signs that as api, and refuses a claim.
+      // not_owner / bound_node_missing / ambiguous stay the hard reject.
+      alias = nodeAliasForToken(input.token, input.tokenName);
+    } else {
+      return {
+        ok: false,
+        error: "from_session_identity_mismatch",
+        message: "network token from_session does not match token-bound node alias",
+        tokenAlias: "",
+        requestedFromSession: requested,
+      };
+    }
+  } else {
+    alias = nodeAliasForToken(input.token, input.tokenName);
+  }
+
+  // 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" };
+  }
+
+  // Authenticated human callers are always represented by their username.
+  // Keep the unscoped development / legacy transport path separate.
+  if (!alias) {
+    const authenticatedUsername = typeof input.authenticatedUsername === "string"
+      ? input.authenticatedUsername.trim()
+      : "";
+    if (authenticatedUsername) return resolveUserTaskFromSession(authenticatedUsername, input.requestedFrom);
+    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,68 @@
+/**
+ * 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", "rules_file_capable", "skills_capable", "files_capable",
+  "logs_capable",
+] 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", "thread_id", "turn_id",
+] 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", "created_by_node_id", "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);

package/src/rest-write-network-resolution.test.ts

@@ -0,0 +1,133 @@
+// #819 — `resolveRestWriteNetworkId` 是 network-scope.ts 里唯一没有任何测试点名的
+// 导出函数。同文件的五个兄弟各有 1-2 个测试文件点名它们:
+//
+//   resolveRestNetworkScope  1        canRestWriteNetwork  1
+//   singleNetworkId          2        addNetworkScope      1
+//   getUserNetworkIds        1        resolveRestWriteNetworkId  🔴 0
+//
+// 而它决定的是**一次 REST 写入落到哪个网络**。它的 docstring 说明了一条不显然的
+// 规则:管理员的**读**作用域按设计是全局的(networkIds=null),所以它本身表达不了
+// 「这个管理员恰好只属于一个网络」;而**写**不能继承这个歧义 —— 只有在确实只有
+// 一个成员关系时才用它,0 个或 ≥2 个都必须显式指定网络。
+//
+// 🔴 这条规则的两半都要钉:
+//   - **放行那半**(admin + 恰好 1 个成员关系 → 用它)如果坏了,会退化成「管理员
+//     写任何东西都要显式带 network_id」——很吵,但**安全**,所以没人会急着修;
+//   - **收紧那半**(admin + 0 或 ≥2 → null)如果坏了,一次写入会**落到一个没被
+//     指定的网络里**,而调用方看到的是成功。
+//
+// 只写反向断言是不够的:一个「永远返回 null」的实现能通过所有「收紧」用例。
+// 所以每一条收紧断言都配了正控。
+//
+// Run: COMMHUB_DB=/tmp/819-rest-write-scope.db bun test src/rest-write-network-resolution.test.ts
+
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { db } from "./db.js";
+import { resolveRestNetworkScope, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
+
+const NET_A = "net_819_a";
+const NET_B = "net_819_b";
+const U_SINGLE = "u819_single";   // 只属于 NET_A
+const U_MULTI = "u819_multi";     // 属于 NET_A + NET_B
+const U_NONE = "u819_none";       // 一个都不属于
+const ALL_USERS = [U_SINGLE, U_MULTI, U_NONE];
+
+function cleanup() {
+  try { db.run("DELETE FROM network_members WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  for (const u of ALL_USERS) {
+    try { db.run("DELETE FROM users WHERE user_id = ?1", [u]); } catch {}
+  }
+}
+
+function seed() {
+  for (const u of ALL_USERS) {
+    db.run(
+      `INSERT INTO users (user_id, username, password_hash, role, created_at)
+       VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+      [u, u],
+    );
+  }
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET_A, U_SINGLE]);
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET_B, U_MULTI]);
+  const member = (u: string, net: string, role: string) =>
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, ?3, datetime('now'))`, [u, net, role]);
+  member(U_SINGLE, NET_A, "owner");
+  member(U_MULTI, NET_A, "member");
+  member(U_MULTI, NET_B, "owner");
+}
+
+beforeEach(() => { cleanup(); seed(); });
+afterAll(() => { cleanup(); });
+
+/** 管理员的读作用域:全局(networkIds=null),这正是歧义的来源。 */
+const ADMIN_SCOPE: RestNetworkScope = { networkIds: null };
+const scopeOf = (...ids: string[]): RestNetworkScope => ({ networkIds: ids });
+const ctx = (userId: string) => ({ userId, networkId: null });
+
+describe("#819 resolveRestWriteNetworkId — 作用域里就能确定时,直接用它", () => {
+  test("作用域恰好一个网络 → 用那一个(与是不是 admin 无关)", () => {
+    expect(resolveRestWriteNetworkId(scopeOf(NET_A), ctx(U_MULTI), false)).toBe(NET_A);
+    expect(resolveRestWriteNetworkId(scopeOf(NET_A), ctx(U_MULTI), true)).toBe(NET_A);
+  });
+
+  test("作用域两个网络 → 歧义,null(即使调用者是 admin)", () => {
+    expect(resolveRestWriteNetworkId(scopeOf(NET_A, NET_B), ctx(U_MULTI), true)).toBeNull();
+  });
+
+  // 🔴 这一条我一开始断错了,留下来当记录:我以为「作用域为空数组 → null」,
+  // 实测是 NET_A。原因是 `[]` 过不了 singleNetworkId,于是落到 admin 的成员关系
+  // 回退分支,而 U_SINGLE 恰好只有一个成员关系。
+  //
+  // 而 `networkIds: []` 在 resolveRestNetworkScope 里有确切含义:`:46` 那一行,
+  // **非 admin 请求了一个自己没有角色的网络** —— 它带着 `denied: "access denied
+  // to requested network"`。也就是说 `[]` 不是「没指定」,是「明确被拒」。
+  //
+  // 现在**没有**问题,因为那一行只对非 admin 产生(admin 在 `:42` 就提前返回
+  // networkIds:null 了),而非 admin 走到这里必然 null —— 见下一条。
+  //
+  // 但它是一个潜伏的形状:如果将来有任何路径让 admin 拿到 networkIds: [],
+  // 这次写入会**忽略那条明确的拒绝**,回退到他的单一成员关系。所以两条都钉住:
+  // 当前行为,以及那条让它安全的前提。
+  test("作用域为空数组 + admin + 恰好一个成员关系 → 回退到成员关系(当前行为,记录)", () => {
+    expect(resolveRestWriteNetworkId(scopeOf(), ctx(U_SINGLE), true)).toBe(NET_A);
+  });
+
+  test("🔴 让上一条安全的前提:空数组作用域只由非 admin 产生,而非 admin → null", () => {
+    expect(resolveRestWriteNetworkId(scopeOf(), ctx(U_SINGLE), false)).toBeNull();
+    // 前提本身也断一次:resolveRestNetworkScope 对 admin 从不产出空数组。
+    const adminScope = resolveRestNetworkScope(NET_B, ctx(U_NONE), true);
+    expect(adminScope.networkIds).toBeNull();
+  });
+});
+
+describe("#819 admin 的全局读作用域不能替写入决定网络", () => {
+  test("🔴 admin + 恰好 1 个成员关系 → 用那一个(放行那半)", () => {
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, ctx(U_SINGLE), true)).toBe(NET_A);
+  });
+
+  test("🔴 admin + 2 个成员关系 → null,必须显式指定(收紧那半)", () => {
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, ctx(U_MULTI), true)).toBeNull();
+  });
+
+  test("🔴 admin + 0 个成员关系 → null(不能因为读是全局的就随便挑一个)", () => {
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, ctx(U_NONE), true)).toBeNull();
+  });
+
+  test("非 admin + 全局作用域 → null(这种组合本身就不该发生,fail closed)", () => {
+    // 正控在上面那条「admin + 单成员 → NET_A」:如果实现改成永远 null,那条会红。
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, ctx(U_SINGLE), false)).toBeNull();
+  });
+
+  test("没有 authCtx + 全局作用域 → null", () => {
+    expect(resolveRestWriteNetworkId(ADMIN_SCOPE, null, true)).toBeNull();
+  });
+});
+
+describe("#819 作用域优先于成员关系回退", () => {
+  test("作用域说 NET_B,而该用户唯一的成员关系是 NET_A → 结果是 NET_B", () => {
+    // 归属由作用域决定,不由「他碰巧属于哪个网络」决定。
+    // 如果实现把两者的优先级搞反,这条会返回 NET_A。
+    expect(resolveRestWriteNetworkId(scopeOf(NET_B), ctx(U_SINGLE), true)).toBe(NET_B);
+  });
+});

package/src/restricted-files.ts

@@ -0,0 +1,76 @@
+// 多用户 Agent 权限 —— 受限成员与上传文件。
+// 文件按网络归属;受限成员(只看授权 Agent 的成员)在受限网络里不能凭 file_id 读网络里任意文件,
+// 也不能把自己看不见的 file_id 塞进发给授权 Agent 的任务(那等于借 Agent 的网络令牌去读)。
+import { existsSync, readFileSync } from "fs";
+import { db } from "./db.js";
+import { addAgentTimelineScope, addOwnTrafficScope, type RestNetworkScope } from "./network-scope.js";
+import { FILE_ID_REGEX, indexEntryPath, validateIndexEntry } from "./uploads.js";
+
+/**
+ * 受限成员能不能看见这个文件:只认**对方(授权 Agent / 给他发私信的人)放进来**的附件 ——
+ *   user_inbox 里发给自己的私信附件;
+ *   授权 Agent 时间线上(#563,与 /api/tasks 同一判据 addAgentTimelineScope)**别人**发出的任务的
+ *   attachments —— 时间线上看得见那条消息,就得看得见它带的图;发送方是受限成员时发送路径已校验过
+ *   他看得见这些文件,不受限的发送方本来就看得见全网文件;
+ *   时间线上任务的 reply_attachments(Agent 回复写进的);
+ *   授权 Agent 发给自己的 inbox 行的 attachments。
+ * 自己随任务带出去的 attachments **不算**:否则把任意 file_id 塞进自己的任务就能「解锁」别人的文件。
+ */
+export function restrictedMemberSeesFile(userId: string, username: string, networkId: string, fileId: string): boolean {
+  if (!FILE_ID_REGEX.test(fileId)) return false;
+  const listed = (metaJson: string | null | undefined, key: "attachments" | "reply_attachments"): boolean => {
+    if (!metaJson) return false;
+    try {
+      const list = JSON.parse(metaJson)?.[key];
+      return Array.isArray(list) && list.some((a: any) => a && typeof a === "object" && a.file_id === fileId);
+    } catch { return false; }
+  };
+  // LIKE 只做预筛(file_id 只含 [A-Za-z0-9_-],`_` 转义后逐字匹配),真正的判定在 listed() 里按键解析。
+  const needle = `%"${fileId.replace(/_/g, "\\_")}"%`;
+  for (const row of db.all<{ meta_json: string | null }>(
+    "SELECT meta_json FROM user_inbox WHERE user_id = ?1 AND network_id = ?2 AND meta_json LIKE ?3 ESCAPE '\\' LIMIT 50",
+    userId, networkId, needle,
+  )) {
+    if (listed(row.meta_json, "attachments")) return true;
+  }
+  const scope: RestNetworkScope = { networkId, networkIds: null, agentRestriction: { userId, username, networkIds: [networkId] } };
+  const taskParams: unknown[] = [needle];
+  const taskSql = addAgentTimelineScope("SELECT from_name, to_name, meta_json FROM tasks WHERE meta_json LIKE ?1 ESCAPE '\\'", taskParams, scope, { from: "from_name", to: "to_name", fromNodeId: "from_node_id", toNodeId: "to_node_id" });
+  for (const row of db.all<{ from_name: string; to_name: string; meta_json: string | null }>(taskSql + " LIMIT 50", ...taskParams)) {
+    if (row.from_name !== username && listed(row.meta_json, "attachments")) return true;
+    if (listed(row.meta_json, "reply_attachments")) return true;
+  }
+  const inboxParams: unknown[] = [needle];
+  const inboxSql = addOwnTrafficScope("SELECT session_name, meta_json FROM inbox WHERE meta_json LIKE ?1 ESCAPE '\\'", inboxParams, scope, { from: "from_session", to: "session_name" });
+  for (const row of db.all<{ session_name: string; meta_json: string | null }>(inboxSql + " LIMIT 50", ...inboxParams)) {
+    if (row.session_name === username && listed(row.meta_json, "attachments")) return true;
+  }
+  return false;
+}
+
+/** 受限成员能不能用这个文件(下载 / 当附件转给 Agent):自己传的,或 restrictedMemberSeesFile。 */
+export function restrictedMemberCanUseFile(userId: string, username: string, networkId: string, fileId: string): boolean {
+  if (!FILE_ID_REGEX.test(fileId)) return false;
+  const path = indexEntryPath(fileId);
+  if (!path || !existsSync(path)) return false;
+  let entry: any;
+  try { entry = JSON.parse(readFileSync(path, "utf8")); } catch { return false; }
+  if (!validateIndexEntry(entry) || entry.file_id !== fileId) return false;
+  if (entry.network_id !== networkId) return false;
+  if (entry.owner_id === userId) return true;
+  return restrictedMemberSeesFile(userId, username, networkId, fileId);
+}
+
+/**
+ * 受限成员发给 Agent 的任务 / 消息里的附件:每个 file_id 都必须是他自己能用的文件。
+ * 返回第一个不合格的 file_id(调用方回 403),全部合格返回 null。
+ */
+export function restrictedMemberAttachmentsDenied(userId: string, username: string, networkId: string, raw: unknown): string | null {
+  if (!Array.isArray(raw)) return null;
+  for (const item of raw) {
+    const fileId = item && typeof item === "object" ? (item as { file_id?: unknown }).file_id : undefined;
+    if (fileId === undefined) continue;
+    if (typeof fileId !== "string" || !restrictedMemberCanUseFile(userId, username, networkId, fileId)) return String(fileId);
+  }
+  return null;
+}

package/src/retention.ts

@@ -20,6 +20,7 @@
 //   COMMHUB_DB=/tmp/test-retention.db bun test src/retention.test.ts
 
 import { db } from "./db.js";
+import { sweepNodeRequestContent, type NodeRequestSweepResult } from "./node-request-retention.js";
 
 export type RetentionConfig = {
   // High-frequency telemetry; default = 7 days.
@@ -52,6 +53,9 @@ export type SweepResult = {
     tasks: number;
     audit_log: number;
   };
+  // node_rules_requests: file bytes purged by age / after read, rows deleted
+  // after 30 days. Fixed policy (privacy, not disk) — no env opt-out.
+  nodeRequests: NodeRequestSweepResult;
   vacuum: {
     walCheckpointPagesMoved: number | null;
     incrementalFreedPages: number | null;
@@ -178,6 +182,8 @@ export function sweepRetention(cfg: RetentionConfig = readRetentionConfig()): Sw
     cfg.auditLogDays,
   );
 
+  const nodeRequests = sweepNodeRequestContent();
+
   // VACUUM:
   //   - wal_checkpoint(TRUNCATE): trims the WAL file. Works on every
   //     SQLite DB regardless of auto_vacuum setting. Useful after
@@ -191,10 +197,13 @@ export function sweepRetention(cfg: RetentionConfig = readRetentionConfig()): Sw
   //     DBs must run a one-time blocking `VACUUM` themselves (out of
   //     scope for the sweeper, which deliberately stays non-
   //     blocking).
+  //   Both are SQLite PRAGMAs; on PostgreSQL autovacuum does this job and
+  //   the two counters stay null (RFC-039 S3).
   let walCheckpointPagesMoved: number | null = null;
   let incrementalFreedPages: number | null = null;
   let errored = false;
-  try {
+  const sqliteVacuum = db.dialect === "sqlite";
+  if (sqliteVacuum) try {
     // wal_checkpoint(TRUNCATE) returns a row { busy, log, checkpointed }.
     // We expose `log` (page count moved into the main DB) for ops visibility.
     const checkpoint = db.get<{ busy: number; log: number; checkpointed: number }>(
@@ -205,7 +214,7 @@ export function sweepRetention(cfg: RetentionConfig = readRetentionConfig()): Sw
     console.log(`[commhub retention] wal_checkpoint failed: ${e?.message ?? e}`);
     errored = true;
   }
-  try {
+  if (sqliteVacuum) try {
     // incremental_vacuum is a no-op on databases not created with
     // PRAGMA auto_vacuum = INCREMENTAL. For existing prod DBs that
     // weren't, the operator would have to run a full one-time VACUUM
@@ -230,6 +239,7 @@ export function sweepRetention(cfg: RetentionConfig = readRetentionConfig()): Sw
       tasks,
       audit_log: auditLog,
     },
+    nodeRequests,
     vacuum: { walCheckpointPagesMoved, incrementalFreedPages, errored },
   };
 }
@@ -249,11 +259,13 @@ export function startRetentionSweeper(
         r.deletes.inbox +
         r.deletes.tasks +
         r.deletes.audit_log;
-      if (totalDeletes > 0 || r.vacuum.errored) {
+      const nr = r.nodeRequests;
+      if (totalDeletes > 0 || nr.purged > 0 || nr.deleted > 0 || nr.timedOut > 0 || r.vacuum.errored) {
         console.log(
           `[commhub retention] swept in ${r.durationMs}ms — ` +
             `telemetry=${r.deletes.agent_telemetry} events=${r.deletes.task_events} ` +
             `inbox=${r.deletes.inbox} tasks=${r.deletes.tasks} audit=${r.deletes.audit_log} ` +
+            `nodeReqPurged=${nr.purged} nodeReqDeleted=${nr.deleted} nodeReqTimedOut=${nr.timedOut} ` +
             `walPages=${r.vacuum.walCheckpointPagesMoved} freedPages=${r.vacuum.incrementalFreedPages}`,
         );
       }

package/src/route-callers-http.test.ts

@@ -0,0 +1,120 @@
+// GET /api/stats/routes?by=caller — per-route caller classes (token kind + User-Agent family).
+// Production serves the full GET /api/status ~2.8/s and every caller arrives as 127.0.0.1 through the
+// frp tunnel, with no access log; this breakdown is how we tell who it is. Pinned over real HTTP:
+//   - without by=caller the body is byte-for-byte what routeStats() produced before this change;
+//   - with it, each route carries callers [{class, count, bytes}] counted per class;
+//   - no token, user id, node id, username or raw User-Agent text ever reaches the output;
+//   - distinct classes per route are capped, the rest folded into "(other)";
+//   - still admin-only.
+
+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 { ROUTE_MAX_CALLERS_PER_ROUTE, ROUTE_OVERFLOW_KEY, routeStats } from "./route-timing.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-route-callers-"));
+process.env.HOME = DIR;
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+
+const PW = "RouteCallersPassw0rd!";
+const NODE_ID = "node_route_callers_probe";
+const NODE_NAME = "rc-probe-node";
+const UA_MARKER = "zz-ua-marker-41c9";
+let BASE = "";
+let hub: any = null;
+let admin = "";
+let adminId = "";
+let adminName = "";
+let member = "";
+let ntok = "";
+
+const get = (path: string, headers: Record<string, string> = {}) => fetch(`${BASE}${path}`, { headers });
+const auth = (token: string, ua?: string) => ({ Authorization: `Bearer ${token}`, ...(ua === undefined ? {} : { "User-Agent": ua }) });
+async function byCaller(): Promise<{ text: string; rows: any[] }> {
+  const res = await get("/api/stats/routes?minutes=5&by=caller", auth(admin));
+  expect(res.status).toBe(200);
+  const text = await res.text();
+  return { text, rows: JSON.parse(text).routes };
+}
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const { register, createNetworkTokenForNode } = await import("./auth.js");
+  const { db } = await import("./db.js");
+  adminName = `rc_admin_${Date.now()}`;
+  const a = register(adminName, PW);
+  admin = a.token!;
+  adminId = a.user!.user_id;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [adminId]);
+  member = register(`rc_member_${Date.now()}`, PW).token!;
+  const minted = createNetworkTokenForNode(adminId, a.network_id!, NODE_NAME, NODE_ID);
+  expect(minted.ok).toBe(true);
+  ntok = minted.token!;
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("GET /api/stats/routes?by=caller", () => {
+  test("without by=caller the body is exactly the pre-existing routeStats() output", async () => {
+    await get("/api/status", auth(admin, "node"));
+    await get("/api/status?light=1", auth(ntok, "agent-node/2.5.0-preview.88"));
+    // The stats request is recorded only after its body is built, so nothing lands between these two.
+    const expected = JSON.stringify({ ok: true, ...routeStats(5 * 60_000) });
+    const res = await get("/api/stats/routes?minutes=5", auth(admin));
+    expect(await res.text()).toBe(expected);
+    const body = JSON.parse(expected);
+    expect(Object.keys(body)).toEqual(["ok", "window_ms", "samples", "oldest_at", "routes"]);
+    for (const r of body.routes) expect(Object.keys(r)).toEqual(["route", "count", "total_ms", "avg_ms", "p95_ms", "max_ms", "bytes", "errors"]);
+  });
+
+  test("callers are counted per class: token kind + UA family", async () => {
+    const before = (await byCaller()).rows.find(r => r.route === "GET /api/status")?.callers ?? [];
+    const count = (cs: any[], cls: string) => cs.find(c => c.class === cls)?.count ?? 0;
+    for (let i = 0; i < 3; i++) expect((await get("/api/status", auth(member, "node"))).status).toBe(200);
+    await get("/api/status", auth(ntok, `agent-node/2.5.0-preview.88 (${UA_MARKER})`));
+    await get("/api/status", auth(member, `Mozilla/5.0 (X11; ${UA_MARKER}) Chrome/130.0`));
+    await get("/api/status", { "User-Agent": "curl/8.5.0" }); // anonymous → 401, still counted
+    const row = (await byCaller()).rows.find(r => r.route === "GET /api/status")!;
+    const callers = row.callers as any[];
+    expect(count(callers, "user node") - count(before, "user node")).toBe(3);
+    expect(count(callers, "node agent-node/2.5.0-preview.88") - count(before, "node agent-node/2.5.0-preview.88")).toBe(1);
+    expect(count(callers, "user browser") - count(before, "user browser")).toBe(1);
+    expect(count(callers, "anon curl/8.5.0") - count(before, "anon curl/8.5.0")).toBe(1);
+    expect(callers.reduce((n: number, c: any) => n + c.count, 0)).toBe(row.count);
+    expect(callers.reduce((n: number, c: any) => n + c.bytes, 0)).toBe(row.bytes);
+    for (const c of callers) expect(Object.keys(c)).toEqual(["class", "count", "bytes"]);
+  });
+
+  test("no token, id, username or raw User-Agent text in the output", async () => {
+    await get(`/api/status?token=${ntok}`, { "User-Agent": `${UA_MARKER}/1.0` });
+    const { text, rows } = await byCaller();
+    for (const secret of [admin, member, ntok, adminId, adminName, NODE_ID, NODE_NAME, UA_MARKER, "Mozilla", "X11", "127.0.0.1", "ntok_", "utok_"]) {
+      expect(text).not.toContain(secret);
+    }
+    const classes = rows.flatMap(r => r.callers.map((c: any) => c.class));
+    expect(classes).toContain("node other");
+    for (const cls of classes) expect(cls).toMatch(/^(\(other\)|(node|user|master|token|anon) [a-z0-9._-]+(\/[0-9A-Za-z.-]+)?)$/);
+  });
+
+  test("distinct classes per route are capped, the rest folded into (other)", async () => {
+    const n = ROUTE_MAX_CALLERS_PER_ROUTE + 5;
+    for (let i = 0; i < n; i++) await get("/api/networks", auth(member, `curl/${i}.0.0`));
+    const row = (await byCaller()).rows.find(r => r.route === "GET /api/networks")!;
+    expect(row.callers.length).toBe(ROUTE_MAX_CALLERS_PER_ROUTE);
+    expect(row.callers.at(-1).class).toBe(ROUTE_OVERFLOW_KEY);
+    expect(row.callers.reduce((s: number, c: any) => s + c.count, 0)).toBe(row.count);
+  });
+
+  test("still admin-only", async () => {
+    expect((await get("/api/stats/routes?by=caller", auth(member))).status).toBe(403);
+    expect((await get("/api/stats/routes?by=caller", auth(ntok))).status).toBe(403);
+  });
+});