@sleep2agi/commhub-server 0.9.0-preview.89 → 0.9.0-preview.91

package/src/department-heads.ts

@@ -0,0 +1,226 @@
+// 部门负责人权限(RFC-040,看板 #455)—— 组织架构 v2。
+//
+// 负责人 = 本部门子树的「小管理员」。不新增角色、不存展开结果:每次请求按 network_departments.leader_user_id 现算
+// 「我负责的部门 ∪ 它们的全部下级」,撤掉负责人,权限当场消失。viewer 当负责人不获得任何东西(viewer 永远只读)。
+// 只加不减:这里给出的东西(负责人看 / 改 / 删本部门的卡、部门项目授权)在 task-access.ts 里和已有来源取并集,
+// 从不改写按人授权、task_access、参与人。节点令牌(Agent)不经过这里。
+//
+// 「本部门的卡」按卡的负责人判:owner 是本部门成员,或 agent_owner 的 owner_user_id 是本部门成员 ——
+// 不按创建者 / 参与人(否则谁都能把卡「挂」进别的部门)。
+//
+// 新表只增(network_department_project_grants):项目授权给部门 D ⇒ D 及其下级部门的成员都获得(行存在 = 可看,
+// can_edit=1 = 可改)。旧代码不读它,回滚安全。递归在 JS 里算(部门 ≤ 500),不依赖 WITH RECURSIVE 的方言差异。
+
+import { db } from "./db.js";
+
+db.exec(`
+  CREATE TABLE IF NOT EXISTS network_department_project_grants (
+    network_id    TEXT NOT NULL,
+    department_id TEXT NOT NULL,
+    project_id    TEXT NOT NULL,
+    can_edit      INTEGER NOT NULL DEFAULT 0,
+    created_by    TEXT,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (network_id, department_id, project_id)
+  );
+  CREATE INDEX IF NOT EXISTS idx_dept_project_grants_project ON network_department_project_grants(project_id);
+`);
+
+export const DEPARTMENT_SCOPE_DENIED = "department_scope_denied";
+
+type TreeRow = { department_id: string; parent_id: string | null; leader_user_id: string | null };
+type Tree = { parent: Map<string, string | null>; children: Map<string, string[]>; rows: TreeRow[] };
+
+function tree(networkId: string): Tree {
+  const rows = db.all<TreeRow>("SELECT department_id, parent_id, leader_user_id FROM network_departments WHERE network_id = ?1 ORDER BY sort, created_at, department_id", networkId);
+  const parent = new Map<string, string | null>();
+  const children = new Map<string, string[]>();
+  for (const r of rows) parent.set(r.department_id, r.parent_id);
+  for (const r of rows) {
+    if (r.parent_id === null || !parent.has(r.parent_id)) continue;
+    const list = children.get(r.parent_id) ?? [];
+    list.push(r.department_id);
+    children.set(r.parent_id, list);
+  }
+  return { parent, children, rows };
+}
+
+function collect(t: Tree, root: string, into: Set<string>): void {
+  const stack = [root];
+  while (stack.length) {
+    const id = stack.pop()!;
+    if (into.has(id)) continue;
+    into.add(id);
+    for (const c of t.children.get(id) ?? []) stack.push(c);
+  }
+}
+
+/** deptId 和它的全部下级(部门不存在 → 空集)。 */
+export function departmentSubtree(networkId: string, deptId: string): Set<string> {
+  const t = tree(networkId);
+  const out = new Set<string>();
+  if (t.parent.has(deptId)) collect(t, deptId, out);
+  return out;
+}
+
+/** deptId 和它的全部上级(从自己往上;部门不存在 → 空)。 */
+function ancestorsAndSelf(t: Tree, deptId: string): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  let cur: string | null | undefined = deptId;
+  while (cur && t.parent.has(cur) && !seen.has(cur)) {
+    seen.add(cur);
+    out.push(cur);
+    cur = t.parent.get(cur);
+  }
+  return out;
+}
+
+/** 能当负责人的成员:本网络成员、不是 viewer。(网络角色 owner / admin 本来就全管,这里也照算,无害。) */
+function eligibleLeader(networkId: string, userId: string): boolean {
+  const row = db.get<{ role: string | null }>("SELECT role FROM network_members WHERE network_id = ?1 AND user_id = ?2", networkId, userId);
+  return !!row && row.role !== "viewer";
+}
+
+export type HeadScope = {
+  /** 我负责的部门 ∪ 它们的全部下级(含我负责的那几个本身)。 */
+  managed: Set<string>;
+  /** 我能改名 / 移动 / 删除 / 换负责人的部门:我负责的部门的严格下级(自己负责的那个归上一级或管理员)。 */
+  strict: Set<string>;
+};
+const EMPTY: HeadScope = { managed: new Set(), strict: new Set() };
+
+export function headScope(networkId: string, userId: string | null | undefined): HeadScope {
+  if (!userId || !networkId) return EMPTY;
+  if (!db.get("SELECT 1 AS x FROM network_departments WHERE network_id = ?1 AND leader_user_id = ?2", networkId, userId)) return EMPTY;
+  if (!eligibleLeader(networkId, userId)) return EMPTY;
+  const t = tree(networkId);
+  const managed = new Set<string>();
+  const strict = new Set<string>();
+  for (const r of t.rows) {
+    if (r.leader_user_id !== userId) continue;
+    collect(t, r.department_id, managed);
+    for (const c of t.children.get(r.department_id) ?? []) collect(t, c, strict);
+  }
+  return { managed, strict };
+}
+
+/** /api/auth/me 的 managed_department_ids:按部门树的顺序。 */
+export function managedDepartmentIds(networkId: string, userId: string): string[] {
+  const { managed } = headScope(networkId, userId);
+  if (!managed.size) return [];
+  return tree(networkId).rows.map((r) => r.department_id).filter((id) => managed.has(id));
+}
+
+/** 部门集合里的成员(department_id 落在集合里)。 */
+export function membersIn(networkId: string, departments: ReadonlySet<string>): Set<string> {
+  if (!departments.size) return new Set();
+  const rows = db.all<{ user_id: string; department_id: string | null }>("SELECT user_id, department_id FROM network_members WHERE network_id = ?1 AND department_id IS NOT NULL", networkId);
+  return new Set(rows.filter((r) => departments.has(r.department_id!)).map((r) => r.user_id));
+}
+
+/** 这些成员拥有的节点(nodes.owner_user_id)。 */
+export function nodesOwnedBy(networkId: string, userIds: ReadonlySet<string>): Set<string> {
+  if (!userIds.size) return new Set();
+  const rows = db.all<{ node_id: string; owner_user_id: string | null }>("SELECT node_id, owner_user_id FROM nodes WHERE network_id = ?1 AND owner_user_id IS NOT NULL", networkId);
+  return new Set(rows.filter((r) => userIds.has(r.owner_user_id!)).map((r) => r.node_id));
+}
+
+/** 卡的负责人 / 负责 Agent 落在这组成员 / 节点里吗(「本部门的卡」)。 */
+export type DepartmentCards = { users: Set<string>; nodes: Set<string> };
+export function departmentCardsFor(networkId: string, departments: ReadonlySet<string>): DepartmentCards {
+  const users = membersIn(networkId, departments);
+  return { users, nodes: nodesOwnedBy(networkId, users) };
+}
+const refId = (json: string | null, kind: "user" | "node"): string | null => {
+  if (!json) return null;
+  try {
+    const ref = JSON.parse(json) as { kind?: unknown; id?: unknown };
+    return ref && ref.kind === kind && typeof ref.id === "string" ? ref.id : null;
+  } catch { return null; }
+};
+export function isDepartmentCard(scope: DepartmentCards, row: { owner_json: string | null; agent_owner_json?: string | null }): boolean {
+  const owner = refId(row.owner_json, "user");
+  if (owner && scope.users.has(owner)) return true;
+  const agent = refId(row.agent_owner_json ?? null, "node");
+  return !!agent && scope.nodes.has(agent);
+}
+
+/** 负责人对这张卡的权力:卡是我负责的部门(含下级)的卡。 */
+export function headCardsFor(networkId: string, userId: string): DepartmentCards | null {
+  const { managed } = headScope(networkId, userId);
+  return managed.size ? departmentCardsFor(networkId, managed) : null;
+}
+
+// ── 部门项目授权 ──
+
+export type DepartmentProjectGrant = { department_id: string; project_id: string; can_edit: boolean };
+
+/** 这个成员从部门(自己的部门 + 全部上级)得到的项目授权:project_id → can_edit(多条取「能改」)。 */
+export function departmentGrantsForMember(networkId: string, userId: string): Map<string, boolean> {
+  const out = new Map<string, boolean>();
+  const dept = db.get<{ department_id: string | null }>("SELECT department_id FROM network_members WHERE network_id = ?1 AND user_id = ?2", networkId, userId)?.department_id;
+  if (!dept) return out;
+  const chain = ancestorsAndSelf(tree(networkId), dept);
+  if (!chain.length) return out;
+  const rows = db.all<{ department_id: string; project_id: string; can_edit: number }>("SELECT department_id, project_id, can_edit FROM network_department_project_grants WHERE network_id = ?1", networkId);
+  const inChain = new Set(chain);
+  for (const r of rows) if (inChain.has(r.department_id)) out.set(r.project_id, out.get(r.project_id) === true || r.can_edit === 1);
+  return out;
+}
+
+export function listDepartmentProjectGrants(networkId: string, departmentId?: string): DepartmentProjectGrant[] {
+  const rows = departmentId === undefined
+    ? db.all<{ department_id: string; project_id: string; can_edit: number }>("SELECT department_id, project_id, can_edit FROM network_department_project_grants WHERE network_id = ?1 ORDER BY department_id, project_id", networkId)
+    : db.all<{ department_id: string; project_id: string; can_edit: number }>("SELECT department_id, project_id, can_edit FROM network_department_project_grants WHERE network_id = ?1 AND department_id = ?2 ORDER BY project_id", networkId, departmentId);
+  return rows.map((r) => ({ department_id: r.department_id, project_id: r.project_id, can_edit: r.can_edit === 1 }));
+}
+
+const MAX_DEPARTMENT_GRANTS = 500;
+export type ReplaceDepartmentGrantsResult =
+  | { ok: true; project_grants: Array<{ project_id: string; can_edit: boolean }> }
+  | { ok: false; status: number; error: string; detail?: unknown };
+
+/** 整体替换一个部门的项目授权。项目必须是本网络的;任何一条不合格 ⇒ 整批不写。 */
+export function replaceDepartmentProjectGrants(networkId: string, departmentId: string, grants: unknown, actorUserId: string): ReplaceDepartmentGrantsResult {
+  if (!db.get("SELECT 1 AS x FROM network_departments WHERE network_id = ?1 AND department_id = ?2", networkId, departmentId)) return { ok: false, status: 404, error: "department_not_found" };
+  if (!Array.isArray(grants)) return { ok: false, status: 400, error: "project_grants_must_be_array" };
+  if (grants.length > MAX_DEPARTMENT_GRANTS) return { ok: false, status: 400, error: "too_many_grants", detail: { limit: MAX_DEPARTMENT_GRANTS } };
+  const rows: Array<{ project_id: string; can_edit: number }> = [];
+  const seen = new Set<string>();
+  for (const [index, raw] of grants.entries()) {
+    const item = typeof raw === "string" ? { project_id: raw } : (raw && typeof raw === "object" && !Array.isArray(raw) ? raw as { project_id?: unknown; can_edit?: unknown } : {});
+    const projectId = typeof item.project_id === "string" ? item.project_id.trim() : "";
+    if (!projectId) return { ok: false, status: 400, error: "project_grant_needs_project_id", detail: { index } };
+    if (item.can_edit !== undefined && typeof item.can_edit !== "boolean") return { ok: false, status: 400, error: "can_edit_must_be_boolean", detail: { index } };
+    if (!db.get("SELECT 1 AS x FROM requirement_projects WHERE project_id = ?1 AND network_id = ?2", projectId, networkId)) {
+      return { ok: false, status: 400, error: "project_not_in_network", detail: { index, project_id: projectId } };
+    }
+    if (seen.has(projectId)) continue;
+    seen.add(projectId);
+    rows.push({ project_id: projectId, can_edit: item.can_edit === true ? 1 : 0 });
+  }
+  db.transaction(() => {
+    db.run("DELETE FROM network_department_project_grants WHERE network_id = ?1 AND department_id = ?2", [networkId, departmentId]);
+    for (const r of rows) {
+      db.run("INSERT INTO network_department_project_grants (network_id, department_id, project_id, can_edit, created_by) VALUES (?1, ?2, ?3, ?4, ?5)",
+        [networkId, departmentId, r.project_id, r.can_edit, actorUserId]);
+    }
+  });
+  return { ok: true, project_grants: listDepartmentProjectGrants(networkId, departmentId).map(({ project_id, can_edit }) => ({ project_id, can_edit })) };
+}
+
+export function deleteDepartmentGrants(networkId: string, departmentId: string): void {
+  db.run("DELETE FROM network_department_project_grants WHERE network_id = ?1 AND department_id = ?2", [networkId, departmentId]);
+}
+export function deleteDepartmentGrantsForNetwork(networkId: string): void {
+  db.run("DELETE FROM network_department_project_grants WHERE network_id = ?1", [networkId]);
+}
+export function deleteDepartmentGrantsForProject(projectId: string): void {
+  db.run("DELETE FROM network_department_project_grants WHERE project_id = ?1", [projectId]);
+}
+
+/** 当前所有(有效的)负责人:组织架构变了,这些人的「本部门」可能跟着变。 */
+export function departmentLeaders(networkId: string): string[] {
+  return db.all<{ leader_user_id: string }>("SELECT DISTINCT leader_user_id FROM network_departments WHERE network_id = ?1 AND leader_user_id IS NOT NULL", networkId).map((r) => r.leader_user_id);
+}

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/observer-avatar-http.test.ts

@@ -159,8 +159,8 @@ describe("#461 GET /events/network/:id — auth", () => {
   test("membership removal revokes observer access — ntok exploit repro (通信龙 review finding 1)", async () => {
     // Exact repro of the review's exploit: add user C to network A, mint
     // an ntok BOUND to A, remove C from A — the same live ntok must lose
-    // the stream. network_members IS the revocation mechanism because
-    // removeNetworkMember does not revoke the user's tokens; the old
+    // the stream. (Before #488 network_members was the only revocation
+    // mechanism — removeNetworkMember did not revoke tokens; the old
     // `!role && authCtx.networkId !== observedNetId` OR-form let the
     // token's network binding bypass the membership check (utok would
     // not catch this: its authCtx.networkId is null, so only ntok
@@ -182,10 +182,12 @@ describe("#461 GET /events/network/:id — auth", () => {
 
     const removed = removeNetworkMember(memberNetworkId, outsiderUserId);
     expect(removed.ok).toBe(true);
-    // The review's failing probe: /events/network/A with the still-live
-    // network-bound token → must now be 403, not 200.
+    // The review's failing probe: /events/network/A with the network-bound
+    // token → must no longer be 200. Since #488 removeNetworkMember revokes
+    // the user's tokens for that network and resolveToken rejects a
+    // non-member's network token, so the token itself is refused (401).
     const afterRemoval = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(ntok) });
-    expect(afterRemoval.status).toBe(403);
+    expect(afterRemoval.status).toBe(401);
     // utok of the removed user is denied too.
     const utokAfter = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(outsiderToken) });
     expect(utokAfter.status).toBe(403);

package/src/requirement-events.ts

@@ -56,11 +56,12 @@ export type EventCard = {
   archived: number | null;
 };
 
-export type EventKind = "created" | "changed" | "deleted";
+export type EventKind = "created" | "changed" | "deleted" | "comment";
 /**
  * field(kind = changed):column / title / priority / due / start / assignee / owner / agent_owner / participants /
  * tags / checklist_item(勾选或取消一项:{id,text,done})/ checklist(增删改条目:{total,done})/
  * description(只记字数,不存正文)/ project / parent / archived。
+ * kind = comment(#474):field 为 null,new = { text }(评论正文,≤ 4000 字),只追加,不对应任何字段的改动。
  */
 export type EventDraft = { kind: EventKind; field: string | null; old: unknown; new: unknown };
 

package/src/requirement-notify.ts

@@ -132,3 +132,34 @@ export function notifyParticipantChange(input: { before: NoticeCard; after: Noti
   if (pending.size > 5_000) for (const [k, p] of pending) if (now - p.startedAt >= COALESCE_WINDOW_MS) pending.delete(k);
   return sent;
 }
+
+/**
+ * RFC-040 Q4:部门负责人(只凭负责人身份)删了本部门的一张卡 → 私信卡的负责人。
+ * 卡没有人类负责人时,私信负责 Agent 的主人(这张卡正是因为那个 Agent 才算「本部门的卡」)。
+ * 删的人就是收件人 / 收件人已不在网络 → 不发。返回收件人(测试用),没发 → null。
+ */
+export function notifyLeaderDeleted(input: { card: NoticeCard & { agent_owner_json?: string | null }; actorUserId: string }): string | null {
+  const { card, actorUserId } = input;
+  let target = userIdOf(parse(card.owner_json));
+  if (!target) {
+    const agent = parse(card.agent_owner_json ?? null) as { kind?: unknown; id?: unknown } | null;
+    if (agent?.kind === "node" && typeof agent.id === "string") {
+      target = db.get<{ owner_user_id: string | null }>("SELECT owner_user_id FROM nodes WHERE node_id = ?1 AND network_id = ?2", agent.id, card.network_id)?.owner_user_id ?? null;
+    }
+  }
+  if (!target || target === actorUserId) return null;
+  const user = db.get<{ username: string; display_name: string | null }>("SELECT username, display_name FROM users WHERE user_id = ?1", actorUserId);
+  if (!user) return null;
+  const actorName = user.display_name?.trim() || user.username;
+  const number = card.seq ? ` #${card.seq}` : "";
+  const sent = sendNoticeDm({
+    networkId: card.network_id,
+    targetUserId: target,
+    sender: { userId: actorUserId, username: user.username },
+    title: "任务删除",
+    metaJson: JSON.stringify({ task_notice: { requirement_id: card.requirement_id, seq: card.seq ?? null, network_id: card.network_id, deleted: true } }),
+    messageId: `dm_task_${uuidv4()}`,
+    text: `${actorName}(部门负责人)删除了你负责的任务${number}「${card.title}」`,
+  });
+  return sent ? target : null;
+}