@sleep2agi/commhub-server 0.9.0-preview.90 → 0.9.0-preview.92

package/src/departments.ts

@@ -11,6 +11,7 @@
 // 只有空部门(没有子部门、没有成员)能删;负责人必须是本网络成员;人离开网络后,作为负责人的引用读出来是 null。
 
 import { db, logAudit } from "./db.js";
+import { deleteDepartmentGrants, deleteDepartmentGrantsForNetwork } from "./department-heads.js";
 
 try { db.exec("ALTER TABLE network_members ADD COLUMN department_id TEXT"); } catch {}
 db.exec(`
@@ -210,7 +211,11 @@ export function deleteDepartment(networkId: string, id: string): Ok<{ deleted: s
   const children = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM network_departments WHERE network_id = ?1 AND parent_id = ?2", networkId, id)?.n ?? 0;
   const members = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM network_members WHERE network_id = ?1 AND department_id = ?2", networkId, id)?.n ?? 0;
   if (children || members) return { ...fail(409, "department_not_empty"), children, members };
-  db.run("DELETE FROM network_departments WHERE network_id = ?1 AND department_id = ?2", [networkId, id]);
+  // RFC-040:部门的项目授权(network_department_project_grants)和部门同一事务删掉。
+  db.transaction(() => {
+    db.run("DELETE FROM network_departments WHERE network_id = ?1 AND department_id = ?2", [networkId, id]);
+    deleteDepartmentGrants(networkId, id);
+  });
   return { ok: true, deleted: id };
 }
 
@@ -226,6 +231,7 @@ export function setMemberDepartment(networkId: string, userId: string, departmen
 /** 网络删掉时一起清(和项目授权同一时机调用)。 */
 export function deleteDepartmentsForNetwork(networkId: string): void {
   db.run("DELETE FROM network_departments WHERE network_id = ?1", [networkId]);
+  deleteDepartmentGrantsForNetwork(networkId);
 }
 
 export function auditDepartment(user: { user_id: string; username: string }, action: string, networkId: string, detail: string): void {

package/src/mcp-context-cost-http.test.ts

@@ -0,0 +1,117 @@
+// #476(#469 MCP 审计的最后一项)—— Hub MCP 面的上下文成本。
+//
+// 钉住:
+//   1. tools/list 的总字节有上限(TOOLS_LIST_MAX_BYTES):描述 / 参数说明不能悄悄长回去。每个工具也有上限,
+//      单条工具描述有上限。要加新工具 / 新说明,改这里的数字 —— 改的时候就会被看见。
+//   2. requirements_events 不带 requirement_id(全网动态)默认 50 条、从新到旧、next_cursor 翻更早的;
+//      带 requirement_id 的单卡调用不变(默认 200);REST /api/requirements/events 不变(默认 200,App 用它)。
+//   3. requirements_events 参数严格:不认识的参数 → -32602,列出能用的参数。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/mcp-context-cost-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { register } from "./auth.js";
+import { registerTools } from "./tools.js";
+
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("mcp-context-cost requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+/**
+ * tools/list 整份 JSON 的字节上限。#476 之前(main,含 #475)74 个工具 76,824 B;修剪后 71,399 B。
+ * 上限留 ~1.1 KB 余量;加工具或加说明超过它,就在这里改数字并在 PR 里说为什么。
+ */
+const TOOLS_LIST_MAX_BYTES = 72_500;
+/** 单个工具(名字 + 描述 + 输入 schema)的上限;最大的是 report_status(节点心跳,~8.4 KB 的遥测结构)。 */
+const TOOL_MAX_BYTES = 9_000;
+/** 单条工具描述的上限(说明写进参数的 describe,或者拆短)。 */
+const DESCRIPTION_MAX_BYTES = 1_000;
+const NETWORK_EVENTS = 80;
+
+let server: any;
+let base = "";
+let token = "", netId = "";
+let close: () => Promise<void>;
+let client: Client;
+const call = async (name: string, args: Record<string, unknown>) => {
+  const r: any = await client.callTool({ name, arguments: args });
+  const text = String(r.content?.[0]?.text ?? "");
+  return r.isError ? { mcpError: true, text } : { ...JSON.parse(text), _bytes: Buffer.byteLength(text, "utf8") };
+};
+let busyId = "";
+
+beforeAll(async () => {
+  const u = register(`ctx_${Date.now()}`, "CtxCost123!", undefined, "seed");
+  token = u.token!; netId = u.network_id!;
+  const s = new McpServer({ name: "ctx", version: "1" });
+  registerTools(s, undefined, null, u.user!.user_id, u.user!.username, false, "tok_user");
+  client = new Client({ name: "ctx-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await s.connect(st);
+  await client.connect(ct);
+  close = async () => { await client.close(); await s.close(); };
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+  // 一张卡上 60 条评论(单卡调用要能拿到 > 50 条),再加 20 张卡各一条
+  const busy = await call("requirements_create", { network_id: netId, name: "busy task" });
+  busyId = busy.requirement.id;
+  for (let i = 0; i < 60; i++) expect((await call("requirements_comment", { network_id: netId, id: busyId, text: `进展 ${i}:这一步完成了` })).ok).toBe(true);
+  for (let i = 0; i < NETWORK_EVENTS - 60; i++) {
+    const r = await call("requirements_create", { network_id: netId, name: `task ${i}` });
+    await call("requirements_comment", { network_id: netId, id: r.requirement.id, text: "已开始" });
+  }
+}, 120_000);
+afterAll(async () => { await close?.(); server?.stop?.(true); });
+
+describe("#476 tools/list size", () => {
+  test("total, per tool and per description stay under their ceilings", async () => {
+    const { tools } = await client.listTools();
+    const total = Buffer.byteLength(JSON.stringify({ tools }), "utf8");
+    const sizes = tools.map((t: any) => ({ name: t.name, all: Buffer.byteLength(JSON.stringify(t)), desc: Buffer.byteLength(t.description ?? "") }));
+    sizes.sort((a, b) => b.all - a.all);
+    console.log(`tools/list: ${tools.length} tools, ${total} B; largest ${sizes.slice(0, 3).map(x => `${x.name}=${x.all}`).join(", ")}`);
+    expect(total).toBeLessThanOrEqual(TOOLS_LIST_MAX_BYTES);
+    for (const x of sizes) {
+      expect(x.all, x.name).toBeLessThanOrEqual(TOOL_MAX_BYTES);
+      expect(x.desc, x.name).toBeLessThanOrEqual(DESCRIPTION_MAX_BYTES);
+    }
+  });
+});
+
+describe("#476 requirements_events defaults", () => {
+  test("network-wide: 50 newest by default, next_cursor pages older events", async () => {
+    const p1 = await call("requirements_events", { network_id: netId });
+    expect(p1.events.length).toBe(50);
+    expect(typeof p1.next_cursor).toBe("string");
+    const times = p1.events.map((e: any) => e.at ?? e.created_at);
+    expect([...times].sort().reverse()).toEqual(times);
+    const p2 = await call("requirements_events", { network_id: netId, cursor: p1.next_cursor });
+    const ids = new Set([...p1.events, ...p2.events].map((e: any) => e.id));
+    expect(ids.size).toBe(p1.events.length + p2.events.length);
+    console.log(`network events page of 50: ${p1._bytes} B`);
+    expect(p1._bytes).toBeLessThan(25_000);
+  });
+
+  test("an explicit limit still wins; one task's timeline keeps its old default (200)", async () => {
+    expect((await call("requirements_events", { network_id: netId, limit: 70 })).events.length).toBe(70);
+    const one = await call("requirements_events", { network_id: netId, requirement_id: busyId });
+    expect(one.events.filter((e: any) => e.kind === "comment").length).toBe(60);
+  });
+
+  test("REST GET /api/requirements/events is unchanged (default 200)", async () => {
+    const res = await fetch(`${base}/api/requirements/events?network_id=${netId}`, { headers: { Authorization: `Bearer ${token}` } });
+    const body = await res.json() as any;
+    expect(res.status).toBe(200);
+    expect(body.events.length).toBeGreaterThan(50);
+  });
+
+  test("unknown parameters → -32602 listing the valid ones", async () => {
+    const r = await call("requirements_events", { network_id: netId, task_id: busyId });
+    expect(r.mcpError).toBe(true);
+    expect(r.text).toContain("-32602");
+    expect(r.text).toContain("unknown parameter(s): task_id; valid parameters: network_id, requirement_id, since, limit, cursor");
+  });
+});

package/src/network-token-membership-http.test.ts

@@ -0,0 +1,139 @@
+// #488 —— 网络令牌只在它的用户还是这个网络的成员时有效(RFC-041 §1)。
+//
+// 以前:被移出网络的成员留下的节点令牌照样解析 —— MCP 每个工具都拒(not a member),REST 读却拿得到整个网络
+// (GET /api/status 返回全部名册)。受限成员的令牌本来就在 resolveToken 被拒,但 401 只写 unauthorized。
+//
+// 钉住:
+//   (i)   非成员的网络令牌:每个 REST GET 与 /mcp 都 401,reason = not_network_member(下面 GETS 是逐条探过的读路径)。
+//   (ii)  removeNetworkMember 在同一个事务里吊销这个人在该网络的令牌(revoked_at),别的网络的令牌不动。
+//   (iii) 受限成员的节点令牌:401 带 reason = node_owner_restricted + hint;不认识的令牌只有 unauthorized。
+//   成员的节点令牌、不受限的情况与以前完全一样。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/network-token-membership-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { addNetworkMember, createNetworkTokenForNode, createNetwork, register, removeNetworkMember } from "./auth.js";
+import { replaceAgentGrants } from "./agent-access.js";
+import { db } from "./db.js";
+
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("network-token-membership requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+const stamp = Date.now();
+const PW = "TokenMember123!";
+const OTHER = `other-${stamp}`; // 网络里别人的 Agent —— 出现在响应里 = 读到了不该读的
+let server: any, base = "", net = "", net2 = "", taskId = "";
+const tok: Record<string, string> = {};
+const ids: Record<string, string> = {};
+
+const get = (t: string, path: string) =>
+  fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${t}` } })
+    .then(async (r) => ({ status: r.status, text: await r.text() }));
+const mcp = (t: string, name: string, args: Record<string, unknown>) =>
+  fetch(`${base}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${t}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  }).then(async (r) => ({ status: r.status, text: await r.text() }));
+
+// 拿网络令牌能调的 REST GET 读路径(server.ts 里 restScope 之后的每个 GET,加上之前自己解析令牌的 /api/auth/me、/api/networks)。
+const GETS = () => [
+  "/api/auth/me", "/api/networks",
+  `/api/status?network_id=${net}`, `/api/status?light=1`, "/api/servers", "/api/server/unknown/health", "/api/server/unknown/agents",
+  "/api/messages", "/api/messages?scope=user", "/api/stats", "/api/stats/sse", "/api/stats/routes", "/api/server-logs", "/api/audit-log",
+  "/api/task_events", "/api/nodes", `/api/nodes/${ids.other}/config`, "/api/node-create-requests", "/api/host-supervisors",
+  `/api/task/${taskId}`, "/api/tasks", "/api/completions", "/api/dm/threads", "/api/requirements",
+];
+
+beforeAll(async () => {
+  const boss = register(`tm_boss_${stamp}`, PW); net = boss.network_id!; ids.boss = boss.user!.user_id; tok.bossUser = boss.token!;
+  for (const k of ["exm", "rem", "mia", "stay"]) {
+    const u = register(`tm_${k}_${stamp}`, PW); ids[k] = u.user!.user_id;
+    expect(addNetworkMember(net, ids[k], "member", ids.boss, { agentAccess: "all" }).ok).toBe(true);
+    const t = createNetworkTokenForNode(ids[k], net, `${k}-${stamp}`, `n_tm_${k}_${stamp}`);
+    expect(t.ok).toBe(true);
+    tok[k] = t.token!;
+  }
+  // rem 在另一个网络里也有令牌 —— 被移出 net 时那枚不能被一起吊销。
+  const n2 = createNetwork(ids.rem, `tm-net2-${stamp}`); expect(n2.ok).toBe(true); net2 = n2.network_id!;
+  const t2 = createNetworkTokenForNode(ids.rem, net2, `rem2-${stamp}`, `n_tm_rem2_${stamp}`); tok.rem2 = t2.token!;
+
+  ids.other = `n_tm_other_${stamp}`;
+  db.run("INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id) VALUES (?1, ?2, ?2, ?3, ?4)", [ids.other, OTHER, net, ids.boss]);
+  db.run("INSERT INTO sessions (resume_id, alias, status, node_id, network_id, server) VALUES (?1, ?2, 'idle', ?3, ?4, 'unknown')", [`r_${ids.other}`, OTHER, ids.other, net]);
+  taskId = `task_tm_${stamp}`;
+  db.run("INSERT INTO tasks (task_id, from_name, to_name, to_node_id, content, status, network_id) VALUES (?1, 'boss', ?2, ?3, 'secret plan', 'pending', ?4)", [taskId, OTHER, ids.other, net]);
+
+  // exm:老数据 —— 成员行没了,令牌还在(移出前的版本不吊销)。rem:走真实的 removeNetworkMember。
+  db.run("DELETE FROM network_members WHERE network_id = ?1 AND user_id = ?2", [net, ids.exm]);
+  expect(removeNetworkMember(net, ids.rem).ok).toBe(true);
+  // mia:铸完令牌后被收窄成只看授权的 Agent。
+  expect(replaceAgentGrants({ networkId: net, userId: ids.mia, grants: [], agentAccess: "granted", actorUserId: ids.boss }).ok).toBe(true);
+
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 60_000);
+afterAll(() => { server?.stop?.(true); });
+
+describe("#488 (i) a network token whose user left the network", () => {
+  test("every REST GET read is 401 not_network_member and leaks nothing", async () => {
+    const leaks: string[] = [];
+    for (const path of GETS()) {
+      const r = await get(tok.exm, path);
+      if (r.status !== 401 || r.text.includes(OTHER) || r.text.includes("secret plan")) leaks.push(`${path} → ${r.status}`);
+      else expect(JSON.parse(r.text).reason).toBe("not_network_member");
+    }
+    expect(leaks).toEqual([]);
+  });
+
+  test("/mcp is 401 too, with the reason", async () => {
+    const r = await mcp(tok.exm, "get_all_status", {});
+    expect(r.status).toBe(401);
+    expect(JSON.parse(r.text).reason).toBe("not_network_member");
+    expect(JSON.parse(r.text).hint).toContain("no longer a member");
+  });
+});
+
+describe("#488 (ii) removeNetworkMember revokes the member's tokens for that network", () => {
+  test("revoked_at is set for that network only, and the token is rejected", async () => {
+    const rows = db.all<{ network_id: string; revoked_at: string | null }>("SELECT network_id, revoked_at FROM api_tokens WHERE user_id = ?1 AND network_id IS NOT NULL", ids.rem);
+    expect(rows.filter((r) => r.network_id === net).length).toBeGreaterThan(0);
+    expect(rows.filter((r) => r.network_id === net).every((r) => !!r.revoked_at)).toBe(true);
+    expect(rows.filter((r) => r.network_id === net2).every((r) => !r.revoked_at)).toBe(true);
+    expect((await get(tok.rem, `/api/status?network_id=${net}`)).status).toBe(401);
+    expect((await get(tok.rem2, "/api/status")).status).toBe(200);
+  });
+});
+
+describe("#488 (iii) a restricted owner's node token says why it is refused", () => {
+  test("401 with reason node_owner_restricted + hint on REST and /mcp", async () => {
+    for (const r of [await get(tok.mia, "/api/status"), await mcp(tok.mia, "report_status", { resume_id: "r", alias: `mia-${stamp}`, status: "idle" })]) {
+      expect(r.status).toBe(401);
+      const body = JSON.parse(r.text);
+      expect(body.reason).toBe("node_owner_restricted");
+      expect(body.hint).toContain("Agent access");
+    }
+    const me = await get(tok.mia, "/api/auth/me");
+    expect(me.status).toBe(401);
+    expect(JSON.parse(me.text).reason).toBe("node_owner_restricted");
+  });
+
+  test("an unknown token gets no reason (nothing to explain, nothing leaked)", async () => {
+    const r = await get("ntok_doesnotexist", "/api/status");
+    expect(r.status).toBe(401);
+    expect(JSON.parse(r.text)).toEqual({ error: "unauthorized" });
+  });
+});
+
+describe("#488 unchanged for members", () => {
+  test("an all-access member's node token reads and heartbeats as before", async () => {
+    const st = await get(tok.stay, `/api/status?network_id=${net}`);
+    expect(st.status).toBe(200);
+    expect(st.text).toContain(OTHER);
+    const hb = await mcp(tok.stay, "report_status", { resume_id: `r_stay_${stamp}`, alias: `stay-${stamp}`, status: "idle" });
+    expect(hb.status).toBe(200);
+    expect(hb.text).toContain('\\"ok\\":true');
+    expect((await get(tok.bossUser, `/api/task/${taskId}`)).status).toBe(200);
+  });
+});

package/src/node-permissions-http.test.ts

@@ -0,0 +1,258 @@
+// RFC-041 第一阶段(#487)—— 节点自己的权限:先记录、后执行。全部经真实 HTTP 入口(bootServer + fetch REST / /mcp / SSE)。
+//
+// 钉住:
+//   1. log(默认):正常模式的节点「本来会被拒」的写照常放行,只按 (节点, 路由, 原因, 小时) 合并记一行。
+//   2. 显式模式不看开关、立刻生效:只读写什么都拒、回复 / 心跳照常;受限只看只改派给它的卡,广播 / 订阅别人的推送都拒。
+//   3. enforce:同一组请求按规则拒(node_permission_denied + reason + hint),含只有人能做的事(human_only)。
+//   4. off:不判也不记(显式模式仍生效)。
+//   5. 改模式:节点主人 / 网络 owner、admin 能;别的成员 403、节点令牌 403、不在网络里 404。
+//   6. 报表:owner/admin 看到过去 7 天每个节点「本来会拦」的计数;成员 / 节点令牌 403。
+//   7. 每个注册的 MCP 工具都归了类(新工具忘了归类会红)。8. 记录有上限、会清理。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/node-permissions-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { addNetworkMember, createNetworkTokenForNode, register } from "./auth.js";
+import { replaceTaskGrants } from "./task-access.js";
+import { db } from "./db.js";
+import { NODE_TOOL_CLASS, pruneNodePermissionLog, __resetNodePermissionLogStateForTest } from "./node-permissions.js";
+import { registerTools } from "./tools.js";
+
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("node-permissions requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+const stamp = Date.now();
+const PW = "NodePerm123!";
+let server: any, base = "", net = "";
+const user: Record<string, { id: string; token: string }> = {};
+const node: Record<string, { id: string; alias: string; token: string; tokenId: string }> = {};
+const card: Record<string, string> = {};
+
+async function call(token: string, method: string, path: string, body?: unknown) {
+  const r = await fetch(`${base}${path}`, {
+    method, headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await r.text();
+  let json: any = null; try { json = JSON.parse(text); } catch {}
+  return { status: r.status, body: json, text };
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const r = await fetch(`${base}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const text = await r.text();
+  const data = text.split("\n").find((l) => l.startsWith("data: "));
+  const msg = JSON.parse(data ? data.slice(6) : text);
+  const inner = msg.result?.content?.[0]?.text;
+  try { return JSON.parse(inner); } catch { return { raw: inner ?? msg }; }
+}
+const sse = async (token: string, path: string) => {
+  const ac = new AbortController();
+  const r = await fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${token}` }, signal: ac.signal });
+  const status = r.status;
+  const body = status === 200 ? null : await r.json().catch(() => null);
+  ac.abort();
+  return { status, body };
+};
+const logRows = (nodeId: string) => db.all<{ route: string; reason: string; hits: number | string }>(
+  "SELECT route, reason, hits FROM node_permission_log WHERE network_id = ?1 AND node_id = ?2 ORDER BY route, reason", net, nodeId);
+const hitsOf = (nodeId: string, route: string, reason: string) =>
+  Number(logRows(nodeId).find((r) => r.route === route && r.reason === reason)?.hits ?? 0);
+const attrsRev = (nodeId: string) => Number(db.get<{ r: number | string | null }>("SELECT attrs_revision AS r FROM nodes WHERE node_id = ?1", nodeId)?.r ?? 0);
+const setMode = (nodeKey: string, mode: string) => db.run("UPDATE nodes SET permission_mode = ?1 WHERE node_id = ?2", [mode, node[nodeKey].id]);
+const newCard = async (name: string, extra: Record<string, unknown> = {}) => {
+  const r = await call(user.boss.token, "POST", "/api/requirements", { name, network_id: net, ...extra });
+  expect(r.status).toBe(201);
+  return r.body.requirement.id as string;
+};
+
+beforeAll(async () => {
+  const boss = register(`np_boss_${stamp}`, PW); net = boss.network_id!; user.boss = { id: boss.user!.user_id, token: boss.token! };
+  for (const k of ["sco", "mem", "out"]) {
+    const u = register(`np_${k}_${stamp}`, PW); user[k] = { id: u.user!.user_id, token: u.token! };
+    if (k !== "out") expect(addNetworkMember(net, user[k].id, "member", user.boss.id, { agentAccess: "all" }).ok).toBe(true);
+  }
+  // sco:只看相关任务的成员(task_access=scoped)—— 他的节点在正常模式下会碰到「主人看不见」的卡。
+  expect(replaceTaskGrants({ networkId: net, userId: user.sco.id, taskAccess: "scoped", actorUserId: user.boss.id }).ok).toBe(true);
+  for (const [key, owner] of [["nN", "boss"], ["nR", "boss"], ["nRO", "boss"], ["nS", "sco"], ["other", "boss"]] as const) {
+    const alias = `${key.toLowerCase()}-${stamp}`, id = `n_np_${key.toLowerCase()}_${stamp}`;
+    const t = createNetworkTokenForNode(user[owner].id, net, alias, id);
+    expect(t.ok).toBe(true);
+    node[key] = { id, alias, token: t.token!, tokenId: t.token_id! };
+    db.run("INSERT INTO sessions (resume_id, alias, status, node_id, network_id) VALUES (?1, ?2, 'idle', ?3, ?4)", [`r_${id}`, alias, id, net]);
+  }
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+  card.assigned = await newCard("assigned to nR", { agent_owner: { kind: "node", id: node.nR.id } });
+  card.child = await newCard("child of assigned", { parent_id: card.assigned });
+  card.boss = await newCard("boss only");
+  card.scoPart = await newCard("sco participates", { participants: [{ kind: "user", id: user.sco.id }] });
+  setMode("nR", "restricted");
+  setMode("nRO", "readonly");
+}, 60_000);
+afterEach(() => { delete process.env.COMMHUB_NODE_PERMISSIONS; });
+afterAll(() => { server?.stop?.(true); });
+
+describe("log (default): never blocks a normal node, records would-be denials", () => {
+  test("a write beyond the owner's visibility goes through and is logged once per hour, hits merged", async () => {
+    const route = "PATCH /api/requirements/:id";
+    const before = hitsOf(node.nS.id, route, "beyond_owner_visibility");
+    expect((await call(node.nS.token, "PATCH", `/api/requirements/${card.boss}`, { description: "via scoped owner's node" })).status).toBe(200);
+    expect((await call(node.nS.token, "PATCH", `/api/requirements/${card.boss}`, { description: "again" })).status).toBe(200);
+    expect(hitsOf(node.nS.id, route, "beyond_owner_visibility")).toBe(before + 2);
+    expect(logRows(node.nS.id).filter((r) => r.route === route).length).toBe(1);
+  });
+
+  test("a list read that includes cards the owner cannot see is returned in full and logged", async () => {
+    const r = await call(node.nS.token, "GET", `/api/requirements?network_id=${net}`);
+    expect(r.status).toBe(200);
+    expect(r.body.requirements.map((x: any) => x.id)).toContain(card.boss);
+    expect(hitsOf(node.nS.id, "GET /api/requirements", "beyond_owner_visibility")).toBeGreaterThan(0);
+  });
+
+  test("human-only actions are logged, not blocked by this layer", async () => {
+    const r = await call(node.nN.token, "PUT", `/api/nodes/${node.other.id}/attrs`, { display_name: "renamed by a node", base_attrs_revision: attrsRev(node.other.id) });
+    expect(r.status).toBe(200);
+    expect(hitsOf(node.nN.id, "PUT /api/nodes/:id/attrs", "human_only")).toBe(1);
+    const p = await mcp(node.nN.token, "projects_create", { network_id: net, name: `p-${stamp}` });
+    expect(p.error).not.toBe("node_permission_denied");
+    expect(hitsOf(node.nN.id, "mcp:projects_create", "human_only")).toBe(1);
+  });
+
+  test("an all-access owner's normal node does its usual work with zero log rows", async () => {
+    expect((await mcp(node.nN.token, "send_task", { alias: node.other.alias, task: "hello" })).ok).toBe(true);
+    expect((await call(node.nN.token, "PATCH", `/api/requirements/${card.boss}`, { column: "doing" })).status).toBe(200);
+    expect(logRows(node.nN.id).filter((r) => r.reason !== "human_only")).toEqual([]);
+  });
+});
+
+describe("explicit modes are enforced immediately (even under log)", () => {
+  test("read-only: writes and dispatch refused with a hint; heartbeat, replies and reads still work", async () => {
+    const w = await call(node.nRO.token, "PATCH", `/api/requirements/${card.boss}`, { description: "nope" });
+    expect(w.status).toBe(403);
+    expect(w.body).toMatchObject({ error: "node_permission_denied", reason: "mode_readonly" });
+    expect(w.body.hint).toContain("read-only");
+    expect((await mcp(node.nRO.token, "send_task", { alias: node.other.alias, task: "x" })).reason).toBe("mode_readonly");
+    expect((await call(node.nRO.token, "POST", "/api/task", { alias: node.other.alias, task: "x", network_id: net })).body.reason).toBe("mode_readonly");
+    expect((await mcp(node.nRO.token, "report_status", { resume_id: `r_${node.nRO.id}`, alias: node.nRO.alias, status: "idle" })).ok).toBe(true);
+    const t = await mcp(node.nN.token, "send_task", { alias: node.nRO.alias, task: "please answer" });
+    const reply = await mcp(node.nRO.token, "send_reply", { in_reply_to: t.task_id ?? t.message_id, text: "done", status: "replied" });
+    expect(reply.ok).not.toBe(false);
+    expect((await call(node.nRO.token, "GET", `/api/requirements?network_id=${net}`)).status).toBe(200);
+  });
+
+  test("restricted: sees and edits only cards assigned to it (and their subtasks)", async () => {
+    const list = await call(node.nR.token, "GET", `/api/requirements?network_id=${net}`);
+    expect(list.body.requirements.map((x: any) => x.id).sort()).toEqual([card.assigned, card.child].sort());
+    expect((await call(node.nR.token, "GET", `/api/requirements/${card.boss}`)).status).toBe(404);
+    expect((await call(node.nR.token, "PATCH", `/api/requirements/${card.assigned}`, { column: "doing" })).status).toBe(200);
+    expect((await call(node.nR.token, "PATCH", `/api/requirements/${card.child}`, { column: "doing" })).status).toBe(200);
+    expect((await call(node.nR.token, "POST", `/api/requirements/${card.assigned}/comments`, { text: "progress" })).status).toBe(201);
+    const mine = await call(node.nR.token, "POST", "/api/requirements", { name: "mine", network_id: net, agent_owner: { kind: "node", id: node.nR.id } });
+    expect(mine.status).toBe(201);
+    const notMine = await call(node.nR.token, "POST", "/api/requirements", { name: "not mine", network_id: net });
+    expect(notMine.status).toBe(403);
+    expect(notMine.body.reason).toBe("mode_restricted_not_assigned");
+    const viaMcp = await mcp(node.nR.token, "requirements_list", { network_id: net });
+    expect((viaMcp.requirements ?? []).map((x: any) => x.id)).not.toContain(card.boss);
+  });
+
+  test("restricted: no broadcast, no network stream, no other session's stream; its own stream works", async () => {
+    expect((await mcp(node.nR.token, "broadcast", { message: "hi all" })).reason).toBe("mode_restricted_not_assigned");
+    expect((await call(node.nR.token, "POST", "/api/broadcast", { message: "hi", network_id: net })).body.reason).toBe("mode_restricted_not_assigned");
+    expect((await sse(node.nR.token, `/events/network/${net}`)).status).toBe(403);
+    expect((await sse(node.nR.token, `/events/${encodeURIComponent(node.other.alias)}?network_id=${net}`)).status).toBe(403);
+    expect((await sse(node.nR.token, `/events/${encodeURIComponent(node.nR.alias)}?network_id=${net}`)).status).toBe(200);
+  });
+});
+
+describe("enforce", () => {
+  test("the same requests that were only logged are refused with node_permission_denied", async () => {
+    process.env.COMMHUB_NODE_PERMISSIONS = "enforce";
+    // 主人看不见的卡:与不存在同一个 404(按主人的可见范围读)。
+    expect((await call(node.nS.token, "PATCH", `/api/requirements/${card.boss}`, { description: "now refused" })).status).toBe(404);
+    // 主人看得见(他是参与人)但改不了的卡:node_permission_denied。
+    const w = await call(node.nS.token, "PATCH", `/api/requirements/${card.scoPart}`, { description: "now refused" });
+    expect(w.status).toBe(403);
+    expect(w.body).toMatchObject({ error: "node_permission_denied", reason: "beyond_owner_visibility" });
+    const list = await call(node.nS.token, "GET", `/api/requirements?network_id=${net}`);
+    expect(list.body.requirements.map((x: any) => x.id)).not.toContain(card.boss);
+  });
+
+  test("human-only actions are denied (REST and MCP); a node can still write its own attrs", async () => {
+    process.env.COMMHUB_NODE_PERMISSIONS = "enforce";
+    const r = await call(node.nN.token, "PUT", `/api/nodes/${node.other.id}/attrs`, { display_name: "nope", base_attrs_revision: attrsRev(node.other.id) });
+    expect(r.status).toBe(403);
+    expect(r.body.reason).toBe("human_only");
+    expect((await mcp(node.nN.token, "projects_create", { network_id: net, name: `q-${stamp}` })).reason).toBe("human_only");
+    expect((await call(node.nN.token, "PUT", `/api/nodes/${node.nN.id}/attrs`, { display_name: "me", base_attrs_revision: attrsRev(node.nN.id) })).status).toBe(200);
+    expect((await mcp(node.nN.token, "send_task", { alias: node.other.alias, task: "still fine" })).ok).toBe(true);
+  });
+
+  test("off: nothing is evaluated or logged for normal nodes; explicit modes still apply", async () => {
+    process.env.COMMHUB_NODE_PERMISSIONS = "off";
+    const before = JSON.stringify(logRows(node.nS.id));
+    expect((await call(node.nS.token, "PATCH", `/api/requirements/${card.boss}`, { description: "off" })).status).toBe(200);
+    expect(JSON.stringify(logRows(node.nS.id))).toBe(before);
+    expect((await call(node.nRO.token, "PATCH", `/api/requirements/${card.boss}`, { description: "still read-only" })).status).toBe(403);
+  });
+});
+
+describe("PUT /api/nodes/:id/permission-mode", () => {
+  test("owner and network owner/admin can set it and it applies on the next request; others cannot", async () => {
+    expect((await call(user.boss.token, "PUT", `/api/nodes/${node.nN.id}/permission-mode`, { mode: "readonly" })).body).toMatchObject({ ok: true, permission_mode: "readonly", previous: "normal" });
+    expect((await call(node.nN.token, "PATCH", `/api/requirements/${card.boss}`, { description: "mode flip" })).body.reason).toBe("mode_readonly");
+    expect((await call(user.boss.token, "PUT", `/api/nodes/${node.nN.id}/permission-mode`, { mode: "normal" })).status).toBe(200);
+    expect((await call(node.nN.token, "PATCH", `/api/requirements/${card.boss}`, { description: "mode flip" })).status).toBe(200);
+    expect((await call(user.sco.token, "PUT", `/api/nodes/${node.nS.id}/permission-mode`, { mode: "restricted" })).status).toBe(200); // sco 是 nS 的主人
+    expect((await call(user.sco.token, "PUT", `/api/nodes/${node.nS.id}/permission-mode`, { mode: "normal" })).status).toBe(200);
+    expect((await call(user.mem.token, "PUT", `/api/nodes/${node.nN.id}/permission-mode`, { mode: "readonly" })).status).toBe(403);
+    expect((await call(node.nN.token, "PUT", `/api/nodes/${node.nN.id}/permission-mode`, { mode: "normal" })).body.error).toBe("user_token_required");
+    expect((await call(user.out.token, "PUT", `/api/nodes/${node.nN.id}/permission-mode`, { mode: "readonly" })).status).toBe(404);
+    expect((await call(user.boss.token, "PUT", `/api/nodes/${node.nN.id}/permission-mode`, { mode: "admin" })).status).toBe(400);
+    expect(db.get<{ n: number | string }>("SELECT COUNT(*) AS n FROM audit_log WHERE action = 'node_permission_mode_changed' AND target_id = ?1", node.nN.id)!.n).toBeTruthy();
+  });
+});
+
+describe("GET /api/networks/:id/node-permission-report", () => {
+  test("owner sees would-have-blocked counts per node; members and node tokens are refused", async () => {
+    const r = await call(user.boss.token, "GET", `/api/networks/${net}/node-permission-report`);
+    expect(r.status).toBe(200);
+    const nS = r.body.nodes.find((n: any) => n.node_id === node.nS.id);
+    expect(nS.by_reason.beyond_owner_visibility).toBeGreaterThanOrEqual(2);
+    expect(nS.alias).toBe(node.nS.alias);
+    expect(r.body.total).toBe(r.body.nodes.reduce((n: number, e: any) => n + e.total, 0));
+    expect((await call(user.mem.token, "GET", `/api/networks/${net}/node-permission-report`)).status).toBe(403);
+    expect((await call(node.nN.token, "GET", `/api/networks/${net}/node-permission-report`)).status).toBe(403);
+    expect((await call(user.boss.token, "GET", `/api/networks/${net}/node-permission-report?since=${encodeURIComponent(new Date(Date.now() + 3_600_000).toISOString())}`)).body.total).toBe(0);
+  });
+});
+
+describe("bookkeeping", () => {
+  test("every MCP tool a node can call has a permission class", async () => {
+    const s = new McpServer({ name: "np", version: "1" });
+    registerTools(s, undefined, net, user.boss.id, node.nN.alias, true, node.nN.tokenId);
+    const client = new Client({ name: "np-client", version: "1" });
+    const [ct, st] = InMemoryTransport.createLinkedPair();
+    await s.connect(st); await client.connect(ct);
+    const names = (await client.listTools()).tools.map((t) => t.name);
+    await client.close(); await s.close();
+    expect(names.length).toBeGreaterThan(50);
+    expect(names.filter((n) => !NODE_TOOL_CLASS[n])).toEqual([]);
+  });
+
+  test("log rows older than the retention window are pruned", () => {
+    const old = new Date(Date.now() - 40 * 86_400_000).toISOString().slice(0, 13);
+    db.run("INSERT INTO node_permission_log (network_id, node_id, route, reason, hour, hits) VALUES (?1, ?2, 'old', 'human_only', ?3, 5)", [net, node.nN.id, old]);
+    pruneNodePermissionLog();
+    __resetNodePermissionLogStateForTest();
+    expect(db.get("SELECT 1 AS hit FROM node_permission_log WHERE route = 'old'")).toBeFalsy();
+  });
+});