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

package/src/server.ts

@@ -5,6 +5,7 @@ import { statusAliasResolverRead } from "./status-alias-resolver.js";
 import { readNodeHealth } from "./node-health-store.js";
 import { assertNodeHealthy, degradedLayers } from "./node-health-guard.js";
 import { auditDepartment, createDepartment, deleteDepartment, listDepartments, setMemberDepartment, updateDepartment } from "./departments.js";
+import { DEPARTMENT_SCOPE_DENIED, departmentLeaders, departmentSubtree, headScope, listDepartmentProjectGrants, managedDepartmentIds, membersIn, replaceDepartmentProjectGrants } from "./department-heads.js";
 import { redactMessageRow } from "./redact-tokens.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { parseDbTimestampMs } from "./db-timestamp.js";
@@ -26,7 +27,7 @@ import { canMessageAgent, isAgentRestricted, listAgentGrants, listGroupGrants, g
 import { validateAvatarUrl } from "./avatar-validate.js";
 import { narrowTags, parseStoredTags, validateScalarAttr } from "./node-attrs-validate.js";
 import { daemonDefaultWorkdirRoot } from "./create-node-validate.js";
-import { register, login, resolveToken, isExpiredSessionToken, sessionIdleDays, listSessions, revokeSession, revokeOtherSessions, getUserNetworks, getUserAllNetworks, createNetwork, deleteNetwork, adminDeleteEmptyNetwork, renameNetwork, changePassword, issueUserToken, listTokens, createToken, revokeToken, getNetworkMembers, getNetworkHumans, getUserNetworkRole, addNetworkMember, adminCreateUser, listUsersWithMemberships, updateMemberRole, removeNetworkMember, createInvite, joinByInvite, createNetworkTokenForNode, type AuthUser } from "./auth.js";
+import { register, login, resolveToken, tokenRejection, isExpiredSessionToken, sessionIdleDays, listSessions, revokeSession, revokeOtherSessions, getUserNetworks, getUserAllNetworks, createNetwork, deleteNetwork, adminDeleteEmptyNetwork, renameNetwork, changePassword, issueUserToken, listTokens, createToken, revokeToken, getNetworkMembers, getNetworkHumans, getUserNetworkRole, addNetworkMember, adminCreateUser, listUsersWithMemberships, updateMemberRole, removeNetworkMember, createInvite, joinByInvite, createNetworkTokenForNode, type AuthUser } from "./auth.js";
 import { abortRename, cleanupCommittedRenameSessions, commitRename, prepareRename, resolveCanonicalAlias } from "./rename.js";
 import { sharedSendDedup, buildDuplicateSendPayload } from "./send_dedup.js";
 import { clientRequestIdFromMeta, idempotentTaskId, idempotentTaskMatches, type StoredIdempotentTask } from "./task-idempotency.js";
@@ -224,7 +225,8 @@ function requireAuth(req: Request, options: RequestTokenOptions = {}): Response
     return null;
   }
 
-  return Response.json({ error: "unauthorized" }, { status: 401 });
+  // #488 —— 令牌存在但因主人的成员身份被拒:说清楚为什么(reason + hint),节点日志里一眼看懂为什么掉线。
+  return Response.json({ error: "unauthorized", ...(tokenRejection(token) ?? {}) }, { status: 401 });
 }
 
 function getClientIP(req: Request, server?: any): string {
@@ -324,7 +326,7 @@ function requireAdminAuth(req: Request): Response | null {
   const token = requestToken(req);
   if (!token) return Response.json({ ok: false, error: "auth required" }, { status: 401 });
   const resolved = resolveToken(token);
-  if (!resolved) return Response.json({ ok: false, error: "invalid token" }, { status: 401 });
+  if (!resolved) return Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 });
   if (!isHubAdminCredential(resolved)) return Response.json({ ok: false, error: "admin required" }, { status: 403 });
   return null;
 }
@@ -1277,11 +1279,13 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");
       if (!token) return withCors(req, Response.json({ ok: false, error: "token required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       // 节点令牌:user 仍是签发它的用户(旧 agent-node 靠它打日志),但只列它绑定的那个网络,
       // 并用 credential 说清楚这是一个节点身份 —— user.role 不是这个调用者的权限。
       const allNetworks = getUserAllNetworks(resolved.user.user_id);
-      const networks = resolved.networkId ? allNetworks.filter((n: any) => n.network_id === resolved.networkId) : allNetworks;
+      // RFC-040:managed_department_ids = 我负责的部门 + 全部下级(空 = 不是负责人;viewer 恒空;节点令牌不是人,恒空)。
+      const networks = (resolved.networkId ? allNetworks.filter((n: any) => n.network_id === resolved.networkId) : allNetworks)
+        .map((n: any) => ({ ...n, managed_department_ids: resolved.networkId ? [] : managedDepartmentIds(n.network_id, resolved.user.user_id) }));
       const credential = resolved.networkId
         ? { kind: "node", network_id: resolved.networkId, node_alias: resolved.tokenName?.startsWith("node:") ? resolved.tokenName.slice(5) : null, acts_as_owner: false }
         : { kind: "user" };
@@ -1292,7 +1296,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "");
       if (!token) return withCors(req, Response.json({ ok: false, error: "token required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       try {
         const body = await req.json() as any;
@@ -1317,7 +1321,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "");
       if (!token) return withCors(req, Response.json({ ok: false, error: "token required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       try {
         const body = await req.json() as any;
@@ -1339,7 +1343,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       try {
         const body = await req.json() as any;
@@ -1359,7 +1363,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       try {
         const body = await req.json() as any;
         if (!body.network_id || !body.old_alias || !body.new_alias) {
@@ -1378,7 +1382,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       try {
         const body = await req.json() as any;
         if (!body.txn_id) return withCors(req, Response.json({ ok: false, error: "txn_id required" }, { status: 400 }));
@@ -1395,7 +1399,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       try {
         const body = await req.json() as any;
         if (!body.txn_id) return withCors(req, Response.json({ ok: false, error: "txn_id required" }, { status: 400 }));
@@ -1413,7 +1417,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       const tokens = listTokens(resolved.user.user_id);
       return withCors(req, Response.json({ ok: true, tokens }));
@@ -1423,7 +1427,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       try {
         const body = await req.json() as any;
@@ -1440,7 +1444,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       const result = revokeToken(resolved.user.user_id, tokenDeleteMatch[1]);
       if (result.ok) logAudit(resolved.user.user_id, resolved.user.username, "token_revoked", "token", tokenDeleteMatch[1]);
@@ -1453,7 +1457,7 @@ return Bun.serve({
       const token = requestToken(req, { allowQueryToken: false });
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       const sessions = listSessions(resolved.user.user_id, resolved.tokenId);
       return withCors(req, Response.json({ ok: true, sessions, current_token_id: resolved.tokenId, idle_timeout_days: sessionIdleDays() }));
@@ -1463,7 +1467,7 @@ return Bun.serve({
       const token = requestToken(req, { allowQueryToken: false });
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       // 当前令牌必须是一次登录会话,否则「保留当前这个」无从说起(API 令牌调用会把所有会话都撤掉)。
       const current = resolved.tokenId ? listSessions(resolved.user.user_id, resolved.tokenId).find((x) => x.is_current) : undefined;
@@ -1478,7 +1482,7 @@ return Bun.serve({
       const token = requestToken(req, { allowQueryToken: false });
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       const targetId = decodeURIComponent(sessionDeleteMatch[1]);
       const result = revokeSession(resolved.user.user_id, targetId);
@@ -1492,7 +1496,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");
       if (!token) return withCors(req, Response.json({ ok: false, error: "token required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       // V3.13: ntok_ can only see its bound network; utok_ sees all member networks
       if (resolved.networkId) {
         // ntok_ — only return the bound network
@@ -1522,7 +1526,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");
       if (!token) return withCors(req, Response.json({ ok: false, error: "token required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       try {
         const body = await req.json() as any;
@@ -1722,25 +1726,76 @@ return Bun.serve({
     }
 
     // ── 组织架构(board #419):部门 + 成员所在部门。读:网络任何成员 / 本网络的节点令牌 / Hub 管理员;
-    // 写:网络 owner / admin、Hub 管理员(节点令牌不能写)。规则在 departments.ts。 ──
+    // 写:网络 owner / admin、Hub 管理员(节点令牌不能写)。规则在 departments.ts。
+    // RFC-040(#455)部门负责人:每次请求按 leader_user_id 现算「我负责的部门 + 全部下级」(department-heads.ts),
+    // 在这棵子树里也能写;越出子树 → 403 department_scope_denied(固定一个错误)。不是负责人的成员与以前逐字节相同。 ──
     const deptMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/departments(?:\/([^/]+))?$/);
     const memberDeptMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/members\/([^/]+)\/department$/);
-    if (deptMatch || memberDeptMatch) {
+    const deptSubMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/departments\/([^/]+)\/(project-grants|nodes)$/);
+    if (deptMatch || memberDeptMatch || deptSubMatch) {
       const token = requestToken(req, { allowQueryToken: false });
       const resolved = token ? resolveToken(token) : null;
       if (!resolved) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
-      const netId = decodeURIComponent((deptMatch ?? memberDeptMatch)![1]);
+      const netId = decodeURIComponent((deptMatch ?? memberDeptMatch ?? deptSubMatch)![1]);
       if (resolved.networkId && resolved.networkId !== netId) return withCors(req, Response.json({ ok: false, error: "not a member of this network" }, { status: 403 }));
       const hubAdmin = isHubAdminCredential(resolved);
       const role = resolved.networkId ? null : getUserNetworkRole(resolved.user.user_id, netId);
       if (!hubAdmin && !role && !resolved.networkId) return withCors(req, Response.json({ ok: false, error: "not a member of this network" }, { status: 403 }));
       if (!db.get("SELECT 1 AS x FROM networks WHERE network_id = ?1", netId)) return withCors(req, Response.json({ ok: false, error: "network_not_found" }, { status: 404 }));
+      const canManage = hubAdmin || (!resolved.networkId && (role === "owner" || role === "admin"));
+      // 负责人范围:只算人(节点令牌不是人);owner / admin 本来全管,不必算。viewer 在 headScope 里恒为空。
+      const head = canManage || resolved.networkId ? { managed: new Set<string>(), strict: new Set<string>() } : headScope(netId, resolved.user.user_id);
+      const isHead = head.managed.size > 0;
+      const scopeDenied = () => withCors(req, Response.json({ ok: false, error: DEPARTMENT_SCOPE_DENIED }, { status: 403 }));
       if (deptMatch && !deptMatch[2] && req.method === "GET") {
-        return withCors(req, Response.json({ ok: true, network_id: netId, ...listDepartments(netId) }));
+        const listed = listDepartments(netId);
+        // viewer_can:manage = 能改名 / 移动 / 删除 / 换负责人;create_child = 能在它下面建子部门。
+        // project_grants(部门项目授权)只给 owner / admin:项目 id 不对只看相关任务的成员公开。
+        const departments = listed.departments.map((d) => ({ ...d, viewer_can: { manage: canManage || head.strict.has(d.id), create_child: canManage || head.managed.has(d.id) } }));
+        return withCors(req, Response.json({ ok: true, network_id: netId, departments, members: listed.members, ...(canManage ? { project_grants: listDepartmentProjectGrants(netId) } : {}) }));
+      }
+      if (deptSubMatch) {
+        const deptId = decodeURIComponent(deptSubMatch[2]);
+        const subtree = departmentSubtree(netId, deptId);
+        if (!subtree.size) return withCors(req, Response.json({ ok: false, error: "department_not_found" }, { status: 404 }));
+        if (deptSubMatch[3] === "nodes") {
+          // 本部门(含下级)成员拥有的节点:只读的状态与健康(RFC-040 Q3 —— 能管人 ≠ 能用 / 能管他的 Agent)。
+          if (req.method !== "GET") return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
+          if (!canManage && !head.managed.has(deptId)) return scopeDenied();
+          const owners = membersIn(netId, subtree);
+          const rows = db.all<{ node_id: string; alias: string | null; display_name: string | null; owner_user_id: string | null }>(
+            "SELECT node_id, alias, display_name, owner_user_id FROM nodes WHERE network_id = ?1 AND owner_user_id IS NOT NULL ORDER BY alias, node_id", netId,
+          ).filter((n) => owners.has(n.owner_user_id!));
+          const nodes = rows.map((n) => {
+            const session = db.get<{ status: string | null; last_seen_at: string | null }>(
+              "SELECT status, last_seen_at FROM sessions WHERE node_id = ?1 AND network_id = ?2 ORDER BY last_seen_at DESC LIMIT 1", n.node_id, netId,
+            );
+            const h = n.alias ? readNodeHealth(netId, n.alias) : null;
+            return {
+              node_id: n.node_id, alias: n.alias, display_name: n.display_name, owner_user_id: n.owner_user_id,
+              status: session?.status ?? "offline", last_seen_at: session?.last_seen_at ?? null,
+              health: h?.health ?? null, degraded: degradedLayers(h?.health).map((l) => ({ layer: l.layer, label: l.label, reason: l.reason })),
+            };
+          });
+          return withCors(req, Response.json({ ok: true, network_id: netId, department_id: deptId, nodes }));
+        }
+        // 部门项目授权:只有 owner / admin(和按人授权一样)。
+        if (!canManage) return withCors(req, Response.json({ ok: false, error: "owner/admin required" }, { status: 403 }));
+        if (req.method === "GET") {
+          return withCors(req, Response.json({ ok: true, network_id: netId, department_id: deptId, project_grants: listDepartmentProjectGrants(netId, deptId).map(({ project_id, can_edit }) => ({ project_id, can_edit })) }));
+        }
+        if (req.method !== "PUT") return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
+        let grantBody: Record<string, unknown> = {};
+        try { const b = await req.json(); grantBody = b && typeof b === "object" && !Array.isArray(b) ? b as Record<string, unknown> : {}; } catch { return withCors(req, Response.json({ ok: false, error: "invalid JSON" }, { status: 400 })); }
+        const r = replaceDepartmentProjectGrants(netId, deptId, grantBody.project_grants, resolved.user.user_id);
+        if (!r.ok) return withCors(req, Response.json({ ok: false, error: r.error, ...(r.detail ? { detail: r.detail } : {}) }, { status: r.status }));
+        auditDepartment(resolved.user, "department_project_grants_set", netId, JSON.stringify({ id: deptId, project_grants: r.project_grants }));
+        // 子树里的人看见的卡变了:断开实时流让它按新权限重连。
+        for (const uid of membersIn(netId, subtree)) closeUserStreamsInNetwork(netId, uid);
+        return withCors(req, Response.json({ ok: true, network_id: netId, department_id: deptId, project_grants: r.project_grants }));
       }
-      const canManage = hubAdmin || (!resolved.networkId && (role === "owner" || role === "admin"));
       if (!["POST", "PATCH", "PUT", "DELETE"].includes(req.method)) return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
-      if (!canManage) return withCors(req, Response.json({ ok: false, error: "owner/admin required" }, { status: 403 }));
+      if (!canManage && !isHead) return withCors(req, Response.json({ ok: false, error: "owner/admin required" }, { status: 403 }));
       let body: Record<string, unknown> = {};
       if (req.method !== "DELETE") {
         try { const b = await req.json(); body = b && typeof b === "object" && !Array.isArray(b) ? b as Record<string, unknown> : {}; } catch { return withCors(req, Response.json({ ok: false, error: "invalid JSON" }, { status: 400 })); }
@@ -1749,27 +1804,66 @@ return Bun.serve({
         const { status, ...rest } = r;
         return withCors(req, Response.json(rest, { status: r.ok ? okStatus : status ?? 400 }));
       };
+      // 负责人的写:只在本部门子树里。部门 / 上级不存在的情况交给 departments.ts 回原来的 404 / 400。
+      const exists = (id: unknown) => typeof id === "string" && departmentSubtree(netId, id).size > 0;
+      const blank = (v: unknown) => v === undefined || v === null || v === "";
+      const inManaged = (id: unknown) => typeof id === "string" && head.managed.has(id);
+      const leaderOk = (v: unknown) => blank(v) || (typeof v === "string" && membersIn(netId, head.managed).has(v));
+      const via = canManage ? "admin" : "leader";
+      // 组织架构变了,负责人们的「本部门」跟着变:断开他们(和被调动的人)的实时流,按新权限重连。
+      const leadersBefore = departmentLeaders(netId);
+      const kick = (extra: string[] = []) => { for (const uid of new Set([...leadersBefore, ...departmentLeaders(netId), ...extra])) closeUserStreamsInNetwork(netId, uid); };
       if (memberDeptMatch) {
         if (req.method !== "PUT") return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
         const targetUid = decodeURIComponent(memberDeptMatch[2]);
+        if (!canManage) {
+          // 调动只在子树内:人原来在本部门(含下级),目标也在本部门。调进 / 调出(含「未分配」)归管理员。
+          const current = db.get<{ department_id: string | null }>("SELECT department_id FROM network_members WHERE network_id = ?1 AND user_id = ?2", netId, targetUid);
+          if (current && (!inManaged(current.department_id) || (!inManaged(body.department_id) && (blank(body.department_id) || exists(body.department_id))))) return scopeDenied();
+        }
         const r = setMemberDepartment(netId, targetUid, body.department_id);
-        if (r.ok) auditDepartment(resolved.user, "member_department_set", netId, `${targetUid} → ${r.department_id ?? "(unassigned)"}`);
+        if (r.ok) {
+          auditDepartment(resolved.user, "member_department_set", netId, `${targetUid} → ${r.department_id ?? "(unassigned)"}${via === "leader" ? " via=leader" : ""}`);
+          kick([targetUid]);
+        }
         return reply(r);
       }
       const deptId = deptMatch![2] ? decodeURIComponent(deptMatch![2]) : null;
+      const tag = (detail: Record<string, unknown>) => JSON.stringify(via === "leader" ? { ...detail, via } : detail);
       if (!deptId && req.method === "POST") {
+        if (!canManage) {
+          // 只能建在本部门(含下级)下面;建顶层部门归管理员。新部门的负责人必须是本部门成员。
+          if (blank(body.parent_id) || (exists(body.parent_id) && !inManaged(body.parent_id))) return scopeDenied();
+          if (!leaderOk(body.leader_user_id)) return scopeDenied();
+        }
         const r = createDepartment(netId, resolved.user.user_id, body);
-        if (r.ok) auditDepartment(resolved.user, "department_created", netId, JSON.stringify({ id: r.department.id, name: r.department.name, parent_id: r.department.parent_id }));
+        if (r.ok) {
+          auditDepartment(resolved.user, "department_created", netId, tag({ id: r.department.id, name: r.department.name, parent_id: r.department.parent_id }));
+          kick();
+        }
         return reply(r, 201);
       }
       if (deptId && req.method === "PATCH") {
+        if (!canManage && exists(deptId)) {
+          // 自己负责的那个部门(名字 / 上级 / 负责人)归上一级负责人或管理员;下级部门只能在子树里挪。
+          if (!head.strict.has(deptId)) return scopeDenied();
+          if (body.parent_id !== undefined && (blank(body.parent_id) || (exists(body.parent_id) && !inManaged(body.parent_id)))) return scopeDenied();
+          if (body.leader_user_id !== undefined && !leaderOk(body.leader_user_id)) return scopeDenied();
+        }
         const r = updateDepartment(netId, deptId, body);
-        if (r.ok) auditDepartment(resolved.user, "department_updated", netId, JSON.stringify({ id: deptId, ...body }));
+        if (r.ok) {
+          auditDepartment(resolved.user, "department_updated", netId, tag({ id: deptId, ...body }));
+          kick();
+        }
         return reply(r);
       }
       if (deptId && req.method === "DELETE") {
+        if (!canManage && exists(deptId) && !head.strict.has(deptId)) return scopeDenied();
         const r = deleteDepartment(netId, deptId);
-        if (r.ok) auditDepartment(resolved.user, "department_deleted", netId, deptId);
+        if (r.ok) {
+          auditDepartment(resolved.user, "department_deleted", netId, via === "leader" ? `${deptId} via=leader` : deptId);
+          kick();
+        }
         return reply(r as { ok: boolean; status?: number } & Record<string, unknown>);
       }
       return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
@@ -1781,7 +1875,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       const netId = membersMatch[1];
       const targetUid = membersMatch[2];
@@ -1833,7 +1927,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       const netId = url.pathname.split("/")[3];
       const callerRole = getUserNetworkRole(resolved.user.user_id, netId);
@@ -1850,7 +1944,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       const body = await req.json() as any;
       const result = joinByInvite(body.invite_code, resolved.user.user_id);
@@ -1908,7 +2002,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       const networkId = netDetailMatch[1];
       const network = db.get<any>(`SELECT ${NETWORK_REST_SELECT} FROM networks WHERE network_id = ?1`, networkId);
       if (!network) return withCors(req, Response.json({ ok: false, error: "network not found" }, { status: 404 }));
@@ -1940,7 +2034,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       // Hub 管理员删别人的网络:同一个资源、同一个动词,只是换一条判据 —— 只允许空网络
       // (计数见 auth.ts adminDeleteEmptyNetwork)。owner 自己删仍走下面原来的路径,行为不变。
@@ -1964,7 +2058,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       try {
         const body = await req.json() as any;
@@ -3634,7 +3728,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       if (!isHubAdminCredential(resolved)) return withCors(req, Response.json({ ok: false, error: "admin only" }, { status: 403 }));
       const limit = Math.min(Number(url.searchParams.get("limit")) || 200, LOG_RING_CAP);
       const since = url.searchParams.get("since"); // ISO timestamp; only return logs newer
@@ -3650,7 +3744,7 @@ return Bun.serve({
       const token = req.headers.get("Authorization")?.replace("Bearer ", "") || url.searchParams.get("token");
       if (!token) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
       const resolved = resolveToken(token);
-      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token" }, { status: 401 }));
+      if (!resolved) return withCors(req, Response.json({ ok: false, error: "invalid token", ...(tokenRejection(token) ?? {}) }, { status: 401 }));
       // 审计日志是账号的记录;节点令牌不能读签发者(常是管理员)的审计日志。
       if (isNodeCredential(resolved)) return userTokenRequired(req);
       const limit = Math.min(Number(url.searchParams.get("limit")) || 50, 200);

package/src/task-access.ts

@@ -7,10 +7,13 @@
 //               能改:负责人是我 / 我建的 / 项目授权 can_edit;能删:负责人是我 / 我建的;不能管项目。
 //               viewer 只看 ④,什么都不能改。
 // owner/admin 角色与 Hub 管理员不看这一列。节点令牌(Agent)不经过这里 —— 规则原样不动。
+// RFC-040(#455)再加两个来源,和上面的取并集、只加不减:部门项目授权(授权给我的部门或它的上级 ⇒ 同按人授权),
+// 负责人权力(我负责的部门子树里的卡:可看 / 可改 / 可删;viewer 当负责人不算)。见 department-heads.ts。
 //
 // 判定是 fail-closed 的:task_access 只有字面 'all' 才放开;role 只有 owner/admin 才豁免。
 
 import { db } from "./db.js";
+import { deleteDepartmentGrantsForProject, departmentGrantsForMember, headCardsFor, isDepartmentCard, type DepartmentCards } from "./department-heads.js";
 
 // ── 表结构(放在这里而不是 db.ts:db.ts 每多一行,文档里钉着的行号就漂一次) ──
 // ALTER 的 DEFAULT 'all' 让**升级前已有的**成员行全部落在旧语义 —— 升级不收窄任何人;新成员按下面的
@@ -96,7 +99,7 @@ export function listProjectGrants(networkId: string, userId: string): ProjectGra
 const likeEscape = (s: string) => s.replace(/[\\%_]/g, (c) => `\\${c}`);
 export const userRefPattern = (userId: string) => `%${likeEscape(`"kind":"user","id":"${userId}"`)}%`;
 
-type CardRow = { network_id: string; owner_json: string | null; participants_json: string | null; created_by: string | null; created_by_json: string | null; project_id: string | null };
+type CardRow = { network_id: string; owner_json: string | null; participants_json: string | null; created_by: string | null; created_by_json: string | null; project_id: string | null; agent_owner_json?: string | null };
 const refIs = (json: string | null, userId: string) => !!json && json.includes(`"kind":"user","id":"${userId}"`);
 const ownsCard = (row: CardRow, userId: string) => refIs(row.owner_json, userId);
 const createdCard = (row: CardRow, userId: string) => refIs(row.created_by_json, userId) || (!row.created_by_json && row.created_by === userId);
@@ -111,6 +114,18 @@ function projectGrant(networkId: string, userId: string, projectId: string | nul
   return row ? { project_id: projectId, can_edit: row.can_edit === 1 } : null;
 }
 
+/** 部门项目授权(RFC-040):null = 部门没授权这个项目;否则 = can_edit。 */
+function departmentGrant(networkId: string, userId: string, projectId: string | null): boolean | null {
+  if (!projectId) return null;
+  const grants = departmentGrantsForMember(networkId, userId);
+  return grants.has(projectId) ? grants.get(projectId)! : null;
+}
+/** 这张卡是不是我负责的部门(含下级)的卡。 */
+function headOf(userId: string, row: CardRow): boolean {
+  const cards = headCardsFor(row.network_id, userId);
+  return !!cards && isDepartmentCard(cards, row);
+}
+
 export type TaskCaller = { userId: string } | null;
 
 /** 看得见这张卡吗。caller=null(节点令牌 / 管理员 / 旧的全局令牌)恒为 true。 */
@@ -119,8 +134,9 @@ export function canSeeTask(caller: TaskCaller, row: CardRow): boolean {
   const m = memberRow(caller.userId, row.network_id);
   if (!scopedRow(m)) return true;
   if (projectGrant(row.network_id, caller.userId, row.project_id)) return true;
+  if (departmentGrant(row.network_id, caller.userId, row.project_id) !== null) return true;
   if (m?.member_role === "viewer") return false;
-  return ownsCard(row, caller.userId) || createdCard(row, caller.userId) || participates(row, caller.userId);
+  return ownsCard(row, caller.userId) || createdCard(row, caller.userId) || participates(row, caller.userId) || headOf(caller.userId, row);
 }
 
 /** 能改这张卡吗(PATCH / 勾子任务)。只对看得见的卡调用。 */
@@ -130,7 +146,23 @@ export function canEditTask(caller: TaskCaller, row: CardRow): boolean {
   if (!scopedRow(m)) return true;
   if (m?.member_role === "viewer") return false;
   if (ownsCard(row, caller.userId) || createdCard(row, caller.userId)) return true;
-  return projectGrant(row.network_id, caller.userId, row.project_id)?.can_edit === true;
+  if (projectGrant(row.network_id, caller.userId, row.project_id)?.can_edit === true) return true;
+  return departmentGrant(row.network_id, caller.userId, row.project_id) === true || headOf(caller.userId, row);
+}
+
+/**
+ * 这次能改,是不是**只**因为负责人身份(没有自己的 / 按人或部门授权的来源)。这种时候负责人只能把卡交给本部门的人
+ * (RFC-040 §1:改负责人只能改成本部门成员 / 其 Agent / 自己),返回本部门的人和节点;否则 null(不加限制)。
+ */
+export function headOnlyEditScope(caller: TaskCaller, row: CardRow): DepartmentCards | null {
+  if (!caller) return null;
+  const m = memberRow(caller.userId, row.network_id);
+  if (!scopedRow(m) || m?.member_role === "viewer") return null;
+  if (ownsCard(row, caller.userId) || createdCard(row, caller.userId)) return null;
+  if (projectGrant(row.network_id, caller.userId, row.project_id)?.can_edit === true) return null;
+  if (departmentGrant(row.network_id, caller.userId, row.project_id) === true) return null;
+  const cards = headCardsFor(row.network_id, caller.userId);
+  return cards && isDepartmentCard(cards, row) ? cards : null;
 }
 
 /**
@@ -159,7 +191,15 @@ export function canDeleteTask(caller: TaskCaller, row: CardRow): boolean {
   const m = memberRow(caller.userId, row.network_id);
   if (!scopedRow(m)) return true;
   if (m?.member_role === "viewer") return false;
-  return ownsCard(row, caller.userId) || createdCard(row, caller.userId);
+  return ownsCard(row, caller.userId) || createdCard(row, caller.userId) || headOf(caller.userId, row);
+}
+
+/** 这次能删只因为负责人身份(RFC-040 Q4:记 requirement_deleted_by_leader + 私信卡的负责人)。 */
+export function deletesAsHeadOnly(caller: TaskCaller, row: CardRow): boolean {
+  if (!caller) return false;
+  const m = memberRow(caller.userId, row.network_id);
+  if (!scopedRow(m) || m?.member_role === "viewer") return false;
+  return !ownsCard(row, caller.userId) && !createdCard(row, caller.userId) && headOf(caller.userId, row);
 }
 
 /**
@@ -170,14 +210,16 @@ export function canDeleteTask(caller: TaskCaller, row: CardRow): boolean {
 export type TaskPermissions = { edit: boolean; delete: boolean; edit_fields?: readonly string[] };
 export function taskPermissionsResolver(caller: TaskCaller): (row: CardRow) => TaskPermissions | null {
   if (!caller) return () => null;
-  const cache = new Map<string, { scoped: boolean; viewer: boolean; grants: Map<string, boolean> }>();
+  const cache = new Map<string, { scoped: boolean; viewer: boolean; grants: Map<string, boolean>; deptGrants: Map<string, boolean>; head: DepartmentCards | null }>();
   const ctxFor = (networkId: string) => {
     let c = cache.get(networkId);
     if (!c) {
       const m = memberRow(caller.userId, networkId);
       const scoped = scopedRow(m);
+      const viewer = m?.member_role === "viewer";
       const grants = new Map<string, boolean>(scoped ? listProjectGrants(networkId, caller.userId).map((g) => [g.project_id, g.can_edit] as [string, boolean]) : []);
-      cache.set(networkId, c = { scoped, viewer: m?.member_role === "viewer", grants });
+      const deptGrants = scoped ? departmentGrantsForMember(networkId, caller.userId) : new Map<string, boolean>();
+      cache.set(networkId, c = { scoped, viewer, grants, deptGrants, head: scoped && !viewer ? headCardsFor(networkId, caller.userId) : null });
     }
     return c;
   };
@@ -185,8 +227,9 @@ export function taskPermissionsResolver(caller: TaskCaller): (row: CardRow) => T
     const c = ctxFor(row.network_id);
     if (!c.scoped) return null;
     if (c.viewer) return { edit: false, delete: false };
-    const mine = ownsCard(row, caller.userId) || createdCard(row, caller.userId);
-    const edit = mine || (row.project_id ? c.grants.get(row.project_id) === true : false);
+    const head = !!c.head && isDepartmentCard(c.head, row);
+    const mine = ownsCard(row, caller.userId) || createdCard(row, caller.userId) || head;
+    const edit = mine || (row.project_id ? c.grants.get(row.project_id) === true || c.deptGrants.get(row.project_id) === true : false);
     if (!edit && participates(row, caller.userId)) return { edit, delete: mine, edit_fields: PARTICIPANT_EDIT_FIELDS };
     return { edit, delete: mine };
   };
@@ -199,6 +242,7 @@ export function taskPermissionsResolver(caller: TaskCaller): (row: CardRow) => T
 export function projectUseResolver(caller: TaskCaller, networkId: string): (projectId: string) => boolean {
   if (!caller || !isTaskScoped(caller.userId, networkId)) return () => true;
   const editable = new Set(listProjectGrants(networkId, caller.userId).filter((g) => g.can_edit).map((g) => g.project_id));
+  for (const [projectId, canEdit] of departmentGrantsForMember(networkId, caller.userId)) if (canEdit) editable.add(projectId);
   return (projectId) => editable.has(projectId);
 }
 
@@ -206,7 +250,7 @@ export function projectUseResolver(caller: TaskCaller, networkId: string): (proj
 export function canUseProject(caller: TaskCaller, networkId: string, projectId: string | null): boolean {
   if (!caller || !projectId) return true;
   if (!isTaskScoped(caller.userId, networkId)) return true;
-  return projectGrant(networkId, caller.userId, projectId)?.can_edit === true;
+  return projectGrant(networkId, caller.userId, projectId)?.can_edit === true || departmentGrant(networkId, caller.userId, projectId) === true;
 }
 
 /**
@@ -232,6 +276,16 @@ export function addTaskVisibilityScope(sql: string, params: unknown[], caller: T
     parts.push(`(network_id IN (${ph(members)}) AND (${mine} OR ${granted}))`);
   }
   if (viewers.length) parts.push(`(network_id IN (${ph(viewers)}) AND ${granted})`);
+  // RFC-040:部门项目授权(viewer 也有,和按人授权一样只给「看」)+ 负责人本部门的卡(viewer 没有)。只加析取项。
+  for (const s of scoped) {
+    const extra: string[] = [];
+    const deptProjects = [...departmentGrantsForMember(s.networkId, caller.userId).keys()];
+    if (deptProjects.length) extra.push(`project_id IN (${ph(deptProjects)})`);
+    const head = s.viewer ? null : headCardsFor(s.networkId, caller.userId);
+    if (head?.users.size) extra.push(`owner_json IN (${ph([...head.users].map((id) => JSON.stringify({ kind: "user", id })))})`);
+    if (head?.nodes.size) extra.push(`agent_owner_json IN (${ph([...head.nodes].map((id) => JSON.stringify({ kind: "node", id })))})`);
+    if (extra.length) parts.push(`(network_id = ?${params.push(s.networkId)} AND (${extra.join(" OR ")}))`);
+  }
   return `${sql} AND (${parts.join(" OR ")})`;
 }
 
@@ -240,7 +294,10 @@ export function addProjectVisibilityScope(sql: string, params: unknown[], caller
   if (!caller || !isTaskScoped(caller.userId, networkId)) return sql;
   const uid = params.push(caller.userId);
   const net = params.push(networkId);
-  return `${sql} AND project_id IN (SELECT project_id FROM network_member_project_grants WHERE user_id = ?${uid} AND network_id = ?${net})`;
+  const personal = `project_id IN (SELECT project_id FROM network_member_project_grants WHERE user_id = ?${uid} AND network_id = ?${net})`;
+  const deptProjects = [...departmentGrantsForMember(networkId, caller.userId).keys()];
+  if (!deptProjects.length) return `${sql} AND ${personal}`;
+  return `${sql} AND (${personal} OR project_id IN (${deptProjects.map((id) => `?${params.push(id)}`).join(", ")}))`;
 }
 
 export type ReplaceTaskGrantsResult =
@@ -302,6 +359,7 @@ export function deleteTaskGrantsForMember(networkId: string, userId: string): vo
 }
 export function deleteTaskGrantsForProject(projectId: string): void {
   db.run("DELETE FROM network_member_project_grants WHERE project_id = ?1", [projectId]);
+  deleteDepartmentGrantsForProject(projectId);
 }
 
 // 被拒的写入审计限频:同一 (用户, 卡) 每小时最多记一条,别让重试刷爆审计表。