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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.90",
+  "version": "0.9.0-preview.91",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/auth.ts

@@ -337,12 +337,18 @@ export function isExpiredSessionToken(token: string): boolean {
   return !!row;
 }
 
-export function resolveToken(token: string): { user: AuthUser; networkId: string | null; tokenName: string | null; tokenId: string | null } | null {
+export type TokenRejection = "node_owner_restricted" | "not_network_member";
+
+/** 查令牌行并判它能不能用:没有这一行 → null;有但被拒 → { rejected };能用 → { row }。 */
+function lookupToken(token: string): { row: any; rejected?: undefined } | { row?: undefined; rejected: TokenRejection } | null {
   const tHash = hashToken(token);
   const cutoff = idleCutoffOffset();
   const row = db.get<any>(
     `SELECT t.token_id, t.user_id, t.network_id, t.scope, t.name AS token_name,
-            u.username, u.display_name, u.email, u.role
+            u.username, u.display_name, u.email, u.role,
+            CASE WHEN t.network_id IS NULL THEN 1
+                 WHEN EXISTS (SELECT 1 FROM network_members nm WHERE nm.network_id = t.network_id AND nm.user_id = t.user_id) THEN 1
+                 ELSE 0 END AS is_member
      FROM api_tokens t JOIN users u ON t.user_id = u.user_id
      WHERE t.token_hash = ?1
        AND (t.expires_at IS NULL OR t.expires_at > datetime('now'))
@@ -352,10 +358,34 @@ export function resolveToken(token: string): { user: AuthUser; networkId: string
 
   if (!row) return null;
 
+  // #488 —— 网络令牌只在它的用户还是这个网络的成员时有效。被移出网络的人留下的令牌(移出前签发的、
+  // 或移出时还没自动吊销的老数据)以前照样解析:MCP 每个工具都拒,REST 读却能拿到整个网络的名册。
+  if (row.network_id && !Number(row.is_member)) return { rejected: "not_network_member" };
+
   // 多用户 Agent 权限:网络令牌(ntok_ / 邀请码令牌)的权限是「这个网络里的一切」,
   // 受限成员在受限网络里不能持有它 —— 否则拿它就绕过了授权过滤。这里是唯一的解析入口,
   // 在这里拒绝,所有 REST / MCP / SSE 路径一起生效(含升级前就签发、后来才被设为受限的令牌)。
-  if (row.network_id && isAgentRestricted(row.user_id, row.network_id)) return null;
+  if (row.network_id && isAgentRestricted(row.user_id, row.network_id)) return { rejected: "node_owner_restricted" };
+  return { row };
+}
+
+/**
+ * 令牌存在、但因为主人的网络成员身份被拒时,说清楚为什么(给 401 带上 reason / hint)。
+ * 只在调用者真的持有这枚令牌时才有输出 —— 不认识的令牌一律 null,不泄露任何东西。
+ */
+export function tokenRejection(token: string | null | undefined): { reason: TokenRejection; hint: string } | null {
+  if (!token) return null;
+  const r = lookupToken(token);
+  if (!r?.rejected) return null;
+  return r.rejected === "not_network_member"
+    ? { reason: r.rejected, hint: "this token's owner is no longer a member of its network; ask a network admin to re-invite them, then create a new token" }
+    : { reason: r.rejected, hint: "this token's owner only has access to granted Agents in this network, and network tokens need full Agent access; ask a network admin to set the owner's Agent access to all" };
+}
+
+export function resolveToken(token: string): { user: AuthUser; networkId: string | null; tokenName: string | null; tokenId: string | null } | null {
+  const found = lookupToken(token);
+  if (!found?.row) return null;
+  const row = found.row;
 
   // Update last_used(节流:见 LAST_USED_WRITE_INTERVAL_SECONDS)
   db.run(
@@ -652,9 +682,13 @@ export function removeNetworkMember(networkId: string, userId: string): { ok: bo
   const member = db.get<any>("SELECT role FROM network_members WHERE network_id = ?1 AND user_id = ?2", networkId, userId);
   if (!member) return { ok: false, error: "not a member" };
   if (member.role === "owner") return { ok: false, error: "cannot remove owner" };
-  db.run("DELETE FROM network_members WHERE network_id = ?1 AND user_id = ?2", [networkId, userId]);
-  deleteAgentGrants(networkId, userId);
-  deleteTaskGrantsForMember(networkId, userId);
+  db.transaction(() => {
+    db.run("DELETE FROM network_members WHERE network_id = ?1 AND user_id = ?2", [networkId, userId]);
+    // #488 —— 他在这个网络里的令牌(节点令牌 / 邀请码令牌)一起吊销;resolveToken 也会拒非成员的令牌,这里让库里的状态如实。
+    db.run("UPDATE api_tokens SET revoked_at = datetime('now') WHERE network_id = ?1 AND user_id = ?2 AND revoked_at IS NULL", [networkId, userId]);
+    deleteAgentGrants(networkId, userId);
+    deleteTaskGrantsForMember(networkId, userId);
+  });
   return { ok: true };
 }
 

package/src/department-heads-http.test.ts

@@ -0,0 +1,329 @@
+// RFC-040(#455)部门负责人权限 —— 逐条钉矩阵:owner / admin / 负责人 / 上级负责人 / 普通成员 / viewer(当负责人)。
+//
+// 组织架构(测试夹具,全是占位名):
+//   研发(上级负责人 parentHead)── 前端(负责人 head)── 前端一组
+//                              └─ 后端
+//   销售(无负责人)
+//   只读组(负责人是 viewer —— 不获得任何东西)
+// 成员:head 在前端,member 在前端一组(拥有节点 node_m),be 在后端,sales 在销售,viewer 在只读组,
+// allMember(task_access='all')在销售。除 allMember 外都是「只看相关任务」(scoped)。
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-dept-heads-"));
+let BASE = "";
+let hub: any = null;
+const PW = "DeptHeadsPassw0rd!xyz";
+let NET = "";
+const U: Record<string, { token: string; id: string }> = {};
+const D: Record<string, string> = {};
+const C: Record<string, string> = {};
+const P: Record<string, string> = {};
+let NODE_TOKEN = "";
+
+async function send(token: string, method: string, path: string, body?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  const text = await res.text();
+  let json: any = null;
+  try { json = JSON.parse(text); } catch {}
+  return { status: res.status, body: json };
+}
+const dept = (token: string, method: string, path = "", body?: unknown) => send(token, method, `/api/networks/${NET}/departments${path}`, body);
+const me = async (k: string) => (await send(U[k].token, "GET", "/api/auth/me")).body.networks.find((n: any) => n.network_id === NET).managed_department_ids as string[];
+const visible = async (k: string, query = "") => new Set(((await send(U[k].token, "GET", `/api/requirements?network_id=${NET}${query}`)).body.requirements as any[]).map(r => r.id));
+const card = (k: string) => C[k];
+const userRef = (k: string) => ({ kind: "user", id: U[k].id });
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`dh_owner_${Date.now()}`, PW, undefined, "Owner");
+  U.owner = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [U.owner.id]);
+  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}`;
+  const stamp = Date.now();
+  const add = async (k: string, role: string, scoped = true) => {
+    const username = `dh_${k}_${stamp}`;
+    expect((await send(U.owner.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role })).status).toBe(200);
+    const login = await send("", "POST", "/api/auth/login", { username, password: PW });
+    U[k] = { token: login.body.token, id: login.body.user.user_id };
+    if (scoped && role !== "admin") expect((await send(U.owner.token, "PUT", `/api/networks/${NET}/members/${U[k].id}/task-grants`, { task_access: "scoped" })).status).toBe(200);
+  };
+  await add("admin", "admin");
+  for (const k of ["head", "parentHead", "member", "be", "sales"]) await add(k, "member");
+  await add("viewer", "viewer");
+  await add("allMember", "member", false);
+
+  const mkDept = async (k: string, name: string, parent: string | null, leader: string | null) => {
+    const r = await dept(U.owner.token, "POST", "", { name, parent_id: parent, leader_user_id: leader ? U[leader].id : null });
+    expect(r.status).toBe(201);
+    D[k] = r.body.department.id;
+  };
+  await mkDept("rd", "研发", null, "parentHead");
+  await mkDept("fe", "前端", D.rd, "head");
+  await mkDept("fe1", "前端一组", D.fe, null);
+  await mkDept("be", "后端", D.rd, null);
+  await mkDept("sales", "销售", null, null);
+  await mkDept("ro", "只读组", null, "viewer");
+  const place = async (k: string, d: string) => expect((await send(U.owner.token, "PUT", `/api/networks/${NET}/members/${U[k].id}/department`, { department_id: D[d] })).status).toBe(200);
+  await place("head", "fe"); await place("member", "fe1"); await place("be", "be"); await place("sales", "sales"); await place("viewer", "ro"); await place("allMember", "sales");
+  await place("parentHead", "rd");
+
+  // member 拥有的节点:用 owner 建令牌,再把节点主人改成 member(scoped 成员不能自己建节点令牌)。
+  const node = createNetworkTokenForNode(U.owner.id, NET, "示例-成员节点", "node_dh_m");
+  NODE_TOKEN = node.token!;
+  db.run("UPDATE nodes SET owner_user_id = ?1 WHERE node_id = 'node_dh_m'", [U.member.id]);
+
+  for (const [k, name] of [["p1", "示例项目一"], ["p2", "示例项目二"]] as const) {
+    const r = await send(U.owner.token, "POST", `/api/requirements/projects?network_id=${NET}`, { name, network_id: NET });
+    expect(r.status).toBe(201);
+    P[k] = r.body.project.id;
+  }
+  const mkCard = async (k: string, fields: Record<string, unknown>) => {
+    const r = await send(U.owner.token, "POST", "/api/requirements", { name: `示例卡 ${k}`, network_id: NET, ...fields });
+    expect(r.status).toBe(201);
+    C[k] = r.body.requirement.id;
+  };
+  await mkCard("memberOwned", { owner: userRef("member") });
+  await mkCard("memberAgent", { agent_owner: { kind: "node", id: "node_dh_m" } });
+  await mkCard("salesOwned", { owner: userRef("sales"), project_id: P.p2 });
+  await mkCard("beOwned", { owner: userRef("be") });
+  await mkCard("salesP1", { owner: userRef("sales"), project_id: P.p1 });
+  await mkCard("toDelete", { owner: userRef("member") });
+  await mkCard("toDeleteAgent", { agent_owner: { kind: "node", id: "node_dh_m" } });
+}, 60_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("who is a head (computed per request)", () => {
+  test("/api/auth/me managed_department_ids: own departments + all sub-departments; others empty; a viewer leader gets nothing", async () => {
+    expect(new Set(await me("head"))).toEqual(new Set([D.fe, D.fe1]));
+    expect(new Set(await me("parentHead"))).toEqual(new Set([D.rd, D.fe, D.fe1, D.be]));
+    expect(await me("member")).toEqual([]);
+    expect(await me("viewer")).toEqual([]);
+    expect(await me("owner")).toEqual([]);
+    const node = await send(NODE_TOKEN, "GET", "/api/auth/me");
+    expect(node.body.networks[0].managed_department_ids).toEqual([]);
+  });
+
+  test("departments list: viewer_can per department; project_grants only for owner / admin", async () => {
+    const byId = (r: any) => new Map((r.body.departments as any[]).map(d => [d.id, d.viewer_can]));
+    const head = await dept(U.head.token, "GET");
+    const v = byId(head);
+    expect(v.get(D.fe)).toEqual({ manage: false, create_child: true }); // 自己负责的部门:不能改,能在下面建
+    expect(v.get(D.fe1)).toEqual({ manage: true, create_child: true });
+    expect(v.get(D.be)).toEqual({ manage: false, create_child: false });
+    expect("project_grants" in head.body).toBe(false);
+    expect(byId(await dept(U.parentHead.token, "GET")).get(D.fe)).toEqual({ manage: true, create_child: true });
+    expect(byId(await dept(U.member.token, "GET")).get(D.fe1)).toEqual({ manage: false, create_child: false });
+    const owner = await dept(U.owner.token, "GET");
+    expect(byId(owner).get(D.sales)).toEqual({ manage: true, create_child: true });
+    expect(Array.isArray(owner.body.project_grants)).toBe(true);
+    expect(Array.isArray((await dept(U.admin.token, "GET")).body.project_grants)).toBe(true);
+  });
+});
+
+describe("department writes: heads inside their subtree, fixed 403 outside", () => {
+  test("create: under own subtree 201; elsewhere / top level → 403 department_scope_denied; non-heads unchanged", async () => {
+    const ok = await dept(U.head.token, "POST", "", { name: "前端二组", parent_id: D.fe });
+    expect(ok.status).toBe(201);
+    D.fe2 = ok.body.department.id;
+    for (const parent of [D.be, D.rd, null]) {
+      const r = await dept(U.head.token, "POST", "", { name: "越权部门", parent_id: parent });
+      expect(r.status).toBe(403);
+      expect(r.body.error).toBe("department_scope_denied");
+    }
+    const leaderOutside = await dept(U.head.token, "POST", "", { name: "前端三组", parent_id: D.fe, leader_user_id: U.sales.id });
+    expect(leaderOutside.body.error).toBe("department_scope_denied");
+    // 普通成员 / viewer 负责人:与以前逐字节相同。
+    for (const k of ["member", "viewer"]) {
+      const r = await dept(U[k].token, "POST", "", { name: "x", parent_id: D.fe });
+      expect(r.status).toBe(403);
+      expect(r.body).toEqual({ ok: false, error: "owner/admin required" });
+    }
+  });
+
+  test("patch: own department is the parent head's; sub-departments rename / move / set leader only inside the subtree", async () => {
+    const own = await dept(U.head.token, "PATCH", `/${D.fe}`, { name: "前端改名" });
+    expect(own.status).toBe(403);
+    expect(own.body.error).toBe("department_scope_denied");
+    expect((await dept(U.parentHead.token, "PATCH", `/${D.fe}`, { name: "前端(上级改)" })).status).toBe(200);
+    expect((await dept(U.head.token, "PATCH", `/${D.fe1}`, { name: "前端一组(改)" })).status).toBe(200);
+    expect((await dept(U.head.token, "PATCH", `/${D.fe2}`, { parent_id: D.fe1 })).status).toBe(200);
+    expect((await dept(U.head.token, "PATCH", `/${D.fe2}`, { parent_id: D.be })).body.error).toBe("department_scope_denied");
+    expect((await dept(U.head.token, "PATCH", `/${D.fe2}`, { parent_id: null })).body.error).toBe("department_scope_denied");
+    expect((await dept(U.head.token, "PATCH", `/${D.be}`, { name: "后端改" })).body.error).toBe("department_scope_denied");
+    expect((await dept(U.head.token, "PATCH", `/${D.fe1}`, { leader_user_id: U.member.id })).status).toBe(200);
+    expect((await dept(U.head.token, "PATCH", `/${D.fe1}`, { leader_user_id: U.sales.id })).body.error).toBe("department_scope_denied");
+    expect((await dept(U.head.token, "PATCH", `/${D.fe1}`, { leader_user_id: null })).status).toBe(200);
+    expect((await dept(U.head.token, "PATCH", "/dept_missing", { name: "x" })).status).toBe(404);
+  });
+
+  test("delete: empty sub-department yes, outside no; the 409 not-empty rule still applies", async () => {
+    expect((await dept(U.head.token, "DELETE", `/${D.be}`)).body.error).toBe("department_scope_denied");
+    expect((await dept(U.head.token, "DELETE", `/${D.fe1}`)).status).toBe(409); // member 在里面
+    expect((await dept(U.head.token, "DELETE", `/${D.fe2}`)).status).toBe(200);
+  });
+
+  test("moving people: only from inside the subtree to inside the subtree; in / out (incl. unassigned) is admin-only", async () => {
+    const move = (k: string, who: string, to: string | null) => send(U[k].token, "PUT", `/api/networks/${NET}/members/${U[who].id}/department`, { department_id: to });
+    expect((await move("head", "member", D.fe)).status).toBe(200);
+    expect((await move("head", "member", D.fe1)).status).toBe(200);
+    expect((await move("head", "member", null)).body.error).toBe("department_scope_denied");
+    expect((await move("head", "member", D.sales)).body.error).toBe("department_scope_denied");
+    expect((await move("head", "sales", D.fe)).body.error).toBe("department_scope_denied");
+    expect((await move("member", "member", D.fe)).body).toEqual({ ok: false, error: "owner/admin required" });
+    expect((await move("admin", "sales", D.fe)).status).toBe(200);
+    expect((await move("admin", "sales", D.sales)).status).toBe(200);
+  });
+});
+
+describe("tasks: union with the existing ACL", () => {
+  test("a head sees, edits and is offered delete on the department's cards (owner or Agent owner in the subtree), nothing else", async () => {
+    const seen = await visible("head");
+    expect(seen.has(card("memberOwned"))).toBe(true);
+    expect(seen.has(card("memberAgent"))).toBe(true);
+    expect(seen.has(card("salesOwned"))).toBe(false);
+    expect(seen.has(card("beOwned"))).toBe(false);
+    expect((await send(U.head.token, "GET", `/api/requirements/${card("beOwned")}`)).status).toBe(404);
+    const row = (await send(U.head.token, "GET", `/api/requirements/${card("memberOwned")}`)).body.requirement;
+    expect(row.viewer_can).toMatchObject({ edit: true, delete: true });
+    expect((await send(U.head.token, "PATCH", `/api/requirements/${card("memberOwned")}`, { name: "示例卡(负责人改)" })).status).toBe(200);
+    const parent = await visible("parentHead");
+    expect(parent.has(card("beOwned"))).toBe(true);
+    expect(parent.has(card("memberOwned"))).toBe(true);
+    expect(parent.has(card("salesOwned"))).toBe(false);
+  });
+
+  test("a head-only edit can hand the card only to the department (or self); clearing is allowed", async () => {
+    const out = await send(U.head.token, "PATCH", `/api/requirements/${card("memberAgent")}`, { owner: userRef("sales") });
+    expect(out.status).toBe(403);
+    expect(out.body.error).toBe("department_scope_denied");
+    expect(out.body.field).toBe("owner");
+    expect((await send(U.head.token, "PATCH", `/api/requirements/${card("memberAgent")}`, { owner: userRef("member") })).status).toBe(200);
+    expect((await send(U.head.token, "PATCH", `/api/requirements/${card("memberAgent")}`, { owner: null })).status).toBe(200);
+  });
+
+  test("viewers never get head power; ordinary members see nothing new", async () => {
+    // viewer 负责「只读组」,把 sales 临时放进去:viewer 仍看不见 sales 的卡,也不能删。
+    expect((await send(U.owner.token, "PUT", `/api/networks/${NET}/members/${U.sales.id}/department`, { department_id: D.ro })).status).toBe(200);
+    expect((await visible("viewer")).has(card("salesOwned"))).toBe(false);
+    expect((await send(U.viewer.token, "DELETE", `/api/requirements/${card("salesOwned")}`)).status).not.toBe(200);
+    expect((await send(U.owner.token, "PUT", `/api/networks/${NET}/members/${U.sales.id}/department`, { department_id: D.sales })).status).toBe(200);
+    const be = await visible("be");
+    expect(be.has(card("memberOwned"))).toBe(false);
+    expect([...be].every(id => id === card("beOwned"))).toBe(true);
+  });
+
+  test("revoking a head takes effect on the very next request (no cache, no re-login)", async () => {
+    expect((await dept(U.owner.token, "PATCH", `/${D.fe}`, { leader_user_id: null })).status).toBe(200);
+    expect(await me("head")).toEqual([]);
+    expect((await visible("head")).has(card("memberOwned"))).toBe(false);
+    expect((await dept(U.head.token, "POST", "", { name: "撤了还想建", parent_id: D.fe })).body).toEqual({ ok: false, error: "owner/admin required" });
+    expect((await send(U.head.token, "PATCH", `/api/requirements/${card("memberOwned")}`, { name: "撤了还想改" })).status).toBe(404);
+    expect((await dept(U.owner.token, "PATCH", `/${D.fe}`, { leader_user_id: U.head.id })).status).toBe(200);
+    expect((await visible("head")).has(card("memberOwned"))).toBe(true);
+  });
+
+  test("union never revokes: personal project grants and task_access='all' are untouched by departments", async () => {
+    // member 有按人授权 p1(可改)。把他调来调去、设部门授权、撤负责人,都不影响这份授权。
+    expect((await send(U.owner.token, "PUT", `/api/networks/${NET}/members/${U.member.id}/task-grants`, { project_grants: [{ project_id: P.p1, can_edit: true }] })).status).toBe(200);
+    expect((await visible("member")).has(card("salesP1"))).toBe(true);
+    expect((await send(U.owner.token, "PUT", `/api/networks/${NET}/members/${U.member.id}/department`, { department_id: D.be })).status).toBe(200);
+    expect((await dept(U.owner.token, "PUT", `/${D.be}/project-grants`, { project_grants: [] })).status).toBe(200);
+    expect((await visible("member")).has(card("salesP1"))).toBe(true);
+    expect((await send(U.member.token, "PATCH", `/api/requirements/${card("salesP1")}`, { name: "按人授权可改" })).status).toBe(200);
+    expect((await send(U.owner.token, "PUT", `/api/networks/${NET}/members/${U.member.id}/department`, { department_id: D.fe1 })).status).toBe(200);
+    // task_access='all' 的老成员:看见全部,和部门无关。
+    const all = await visible("allMember");
+    for (const k of ["memberOwned", "salesOwned", "beOwned"]) expect(all.has(card(k))).toBe(true);
+    expect((await send(U.owner.token, "PUT", `/api/networks/${NET}/members/${U.member.id}/task-grants`, { project_grants: [] })).status).toBe(200);
+  });
+});
+
+describe("department project grants", () => {
+  test("owner / admin only; whole-batch validation", async () => {
+    expect((await dept(U.head.token, "GET", `/${D.rd}/project-grants`)).body).toEqual({ ok: false, error: "owner/admin required" });
+    expect((await dept(U.parentHead.token, "PUT", `/${D.rd}/project-grants`, { project_grants: [{ project_id: P.p2 }] })).status).toBe(403);
+    const bad = await dept(U.owner.token, "PUT", `/${D.rd}/project-grants`, { project_grants: [{ project_id: P.p2 }, { project_id: "proj_not_here" }] });
+    expect(bad.status).toBe(400);
+    expect(bad.body.error).toBe("project_not_in_network");
+    expect((await dept(U.owner.token, "GET", `/${D.rd}/project-grants`)).body.project_grants).toEqual([]);
+    expect((await dept(U.owner.token, "GET", "/dept_missing/project-grants")).status).toBe(404);
+  });
+
+  test("a grant to a department cascades to its sub-departments, not to siblings; can_edit decides edit", async () => {
+    expect((await visible("member")).has(card("salesOwned"))).toBe(false);
+    expect((await dept(U.admin.token, "PUT", `/${D.rd}/project-grants`, { project_grants: [{ project_id: P.p2, can_edit: false }] })).status).toBe(200);
+    expect((await visible("member")).has(card("salesOwned"))).toBe(true); // member 在 研发 › 前端 › 前端一组
+    expect((await visible("sales")).has(card("salesOwned"))).toBe(true); // 自己的卡,本来就看得见
+    expect((await send(U.member.token, "PATCH", `/api/requirements/${card("salesOwned")}`, { name: "只读授权" })).status).toBe(403);
+    expect((await dept(U.owner.token, "PUT", `/${D.rd}/project-grants`, { project_grants: [{ project_id: P.p2, can_edit: true }] })).status).toBe(200);
+    expect((await send(U.member.token, "PATCH", `/api/requirements/${card("salesOwned")}`, { name: "部门授权可改" })).status).toBe(200);
+    // 授权给 后端:前端一组的 member 拿不到。
+    expect((await dept(U.owner.token, "PUT", `/${D.rd}/project-grants`, { project_grants: [] })).status).toBe(200);
+    expect((await dept(U.owner.token, "PUT", `/${D.be}/project-grants`, { project_grants: [{ project_id: P.p2 }] })).status).toBe(200);
+    expect((await visible("member")).has(card("salesOwned"))).toBe(false);
+    expect((await visible("be")).has(card("salesOwned"))).toBe(true);
+    expect((await dept(U.owner.token, "GET")).body.project_grants).toEqual([{ department_id: D.be, project_id: P.p2, can_edit: false }]);
+    // 项目列表也跟着授权走。
+    const projects = (await send(U.be.token, "GET", `/api/requirements/projects?network_id=${NET}`)).body.projects.map((p: any) => p.id);
+    expect(projects).toContain(P.p2);
+  });
+});
+
+describe("delete by a head: audit + DM", () => {
+  test("head deletes a department card → requirement_deleted_by_leader + a DM to the card's owner (or the Agent's owner)", async () => {
+    const inbox = (uid: string) => db.all<{ content: string }>("SELECT content FROM user_inbox WHERE user_id = ?1 AND content LIKE '%部门负责人%'", uid);
+    const before = inbox(U.member.id).length;
+    expect((await send(U.head.token, "DELETE", `/api/requirements/${card("toDelete")}`)).status).toBe(200);
+    expect((await send(U.head.token, "DELETE", `/api/requirements/${card("toDeleteAgent")}`)).status).toBe(200);
+    const audits = db.all<{ action: string; target_id: string; detail: string }>("SELECT action, target_id, detail FROM audit_log WHERE action = 'requirement_deleted_by_leader' ORDER BY id");
+    expect(audits.map(a => a.target_id)).toEqual([card("toDelete"), card("toDeleteAgent")]);
+    expect(JSON.parse(audits[0].detail).notified).toBe(U.member.id);
+    expect(JSON.parse(audits[1].detail).notified).toBe(U.member.id); // Agent 的主人
+    const dms = inbox(U.member.id);
+    expect(dms.length).toBe(before + 2);
+    expect(dms.at(-1)!.content).toContain("删除了你负责的任务");
+    // 不是本部门的卡:负责人删不了(看不见 = 404)。普通成员删别人的卡照旧被拒。
+    expect((await send(U.head.token, "DELETE", `/api/requirements/${card("beOwned")}`)).status).toBe(404);
+    expect((await send(U.be.token, "DELETE", `/api/requirements/${card("salesOwned")}`)).status).toBe(403);
+  });
+});
+
+describe("department_id filter and the read-only node list", () => {
+  test("GET /api/requirements?department_id= narrows to the subtree's cards, within what the caller can see", async () => {
+    const all = await visible("owner", `&department_id=${D.fe}`);
+    expect(all.has(card("memberOwned"))).toBe(true);
+    expect(all.has(card("memberAgent"))).toBe(true);
+    expect(all.has(card("beOwned"))).toBe(false);
+    expect((await visible("owner", `&department_id=${D.rd}`)).has(card("beOwned"))).toBe(true);
+    expect((await visible("be", `&department_id=${D.rd}`)).has(card("memberOwned"))).toBe(false); // 仍受可见范围约束
+    const bad = await send(U.owner.token, "GET", `/api/requirements?network_id=${NET}&department_id=dept_missing`);
+    expect(bad.status).toBe(400);
+    expect(bad.body.error).toBe("department_not_found");
+  });
+
+  test("GET …/departments/:dept/nodes: heads (subtree) and owner/admin; read-only status + health", async () => {
+    const r = await dept(U.head.token, "GET", `/${D.fe}/nodes`);
+    expect(r.status).toBe(200);
+    expect(r.body.nodes.map((n: any) => n.node_id)).toEqual(["node_dh_m"]);
+    expect(Object.keys(r.body.nodes[0]).sort()).toEqual(["alias", "degraded", "display_name", "health", "last_seen_at", "node_id", "owner_user_id", "status"]);
+    expect((await dept(U.head.token, "GET", `/${D.be}/nodes`)).body.error).toBe("department_scope_denied");
+    expect((await dept(U.member.token, "GET", `/${D.fe}/nodes`)).body.error).toBe("department_scope_denied");
+    expect((await dept(U.owner.token, "GET", `/${D.rd}/nodes`)).body.nodes.length).toBe(1);
+    expect((await dept(U.head.token, "POST", `/${D.fe}/nodes`, {})).status).toBe(405);
+    expect((await send(NODE_TOKEN, "GET", `/api/networks/${NET}/departments/${D.fe}/nodes`)).body.error).toBe("department_scope_denied");
+  });
+});

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);
+}