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

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";
@@ -23,10 +24,11 @@ import { restrictedMemberSeesFile, restrictedMemberAttachmentsDenied } from "./r
 import { dmParticipantSeesFile, listDmThread, listDmThreads, sendHumanDm } from "./human-dm.js";
 import { getTaskAccessMode, isTaskScoped, listProjectGrants, replaceTaskGrants, NEW_MEMBER_TASK_ACCESS } from "./task-access.js";
 import { canMessageAgent, isAgentRestricted, listAgentGrants, listGroupGrants, getAgentAccessMode, replaceAgentGrants, restrictedNetworkIds, usernameIsAgentAlias, listAgentGroups, createAgentGroup, updateAgentGroup, replaceAgentGroupMembers, deleteAgentGroup, usersGrantedGroup } from "./agent-access.js";
+import { broadcastVerdict, dispatchVerdict, humanOnlyVerdict, NODE_PERMISSION_MODES, nodeDecide, nodeIdentity, nodePermissionDeniedBody, nodePermissionsFlag, streamVerdict, writeVerdict, type NodeIdentity, type NodePermissionMode, type Verdict } from "./node-permissions.js";
 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 +226,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 {
@@ -316,6 +319,18 @@ function countNetworkUploads(networkId: string): number {
   return count;
 }
 
+// RFC-041(#487):节点令牌的一次 REST 写 / 订阅先按 node-permissions.ts 判。用户令牌 → null(不判)。
+function restNodeDenied(req: Request, restAuth: { networkId: string | null; tokenId: string | null } | null, route: string, verdictOf: (id: NodeIdentity) => Verdict): Response | null {
+  if (!restAuth?.networkId) return null;
+  const id = nodeIdentity(restAuth.tokenId, restAuth.networkId);
+  if (!id) return null;
+  const verdict = verdictOf(id);
+  return nodeDecide(id, route, verdict) ? withCors(req, Response.json(nodePermissionDeniedBody(verdict!.reason, route), { status: 403 })) : null;
+}
+/** 写别的节点 = 只有人能做;写自己 = 只看模式。 */
+const nodeTargetVerdict = (targetNodeId: string) => (id: NodeIdentity): Verdict =>
+  id.nodeId && id.nodeId === targetNodeId ? writeVerdict(id, targetNodeId) : humanOnlyVerdict(id, targetNodeId);
+
 function userTokenRequired(req: Request): Response {
   return withCors(req, Response.json({ ok: false, error: "user_token_required", message: "this endpoint acts on a user account; node tokens cannot use it" }, { status: 403 }));
 }
@@ -324,7 +339,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;
 }
@@ -1005,11 +1020,9 @@ return Bun.serve({
     //   1. legacy AUTH_TOKEN (master) → any network
     //   2/3. ntok_ / utok_ → must CURRENTLY be a member of the requested
     //        network. Membership is checked unconditionally — there is NO
-    //        token-bound-network shortcut. removeNetworkMember deletes the
-    //        membership row but does NOT revoke the user's ntok, so the
-    //        network_members lookup IS the revocation mechanism: an ntok
-    //        bound to this network whose owner was removed must lose the
-    //        stream (审查修复 per 通信龙 #461 review, finding 1).
+    //        token-bound-network shortcut (审查修复 per 通信龙 #461 review,
+    //        finding 1). Since #488 removeNetworkMember also revokes the
+    //        user's tokens and resolveToken refuses a non-member's ntok.
     const netEventsMatch = url.pathname.match(/^\/events\/network\/(.+)$/);
     if (netEventsMatch && req.method === "GET") {
       const authErr = requireAuth(req);
@@ -1026,6 +1039,8 @@ return Bun.serve({
       if (!observerRole) {
         return withCors(req, Response.json({ ok: false, error: "not a member of this network" }, { status: 403 }));
       }
+      const streamDenied = restNodeDenied(req, authCtx, "SSE /events/network/:id", (id) => streamVerdict(id, "network"));
+      if (streamDenied) return streamDenied;
       // 多用户 Agent 权限:受限成员只收到自己是一端的路由事件(自己发的 / 发给自己的),
       // 看不到网络里别人和各个 Agent 之间的流量。
       if (isAgentRestricted(authCtx.userId, observedNetId)) {
@@ -1101,6 +1116,11 @@ return Bun.serve({
         if (!session && authCtx.networkId !== scopedNetId) {
           return withCors(req, Response.json({ ok: false, error: "session not in requested network" }, { status: 403 }));
         }
+        const streamDenied = restNodeDenied(req, authCtx, "SSE /events/:session", (id) => streamVerdict(id, {
+          alias: sessionName,
+          nodeId: db.get<{ node_id: string | null }>("SELECT node_id FROM sessions WHERE alias = ?1 AND network_id = ?2", sessionName, scopedNetId)?.node_id ?? null,
+        }));
+        if (streamDenied) return streamDenied;
         return createSSEStream(sessionName, scopedNetId);
       }
 
@@ -1277,11 +1297,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 +1314,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 +1339,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 +1361,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 +1381,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 +1400,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 +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 }));
       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 +1435,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 +1445,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 +1462,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 +1475,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 +1485,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 +1500,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 +1514,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 +1544,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 +1744,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 +1822,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 +1893,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 +1945,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 +1962,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 +2020,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 +2052,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 +2076,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;
@@ -2177,6 +2289,67 @@ return Bun.serve({
     // GET  /api/dm?network_id=&with=<user_id>[&limit&before]  → 双向会话记录(新的在前)
     // GET  /api/dm/threads?network_id=                       → 每个对方一行 + 未读数
     // 已读沿用 POST /api/messages/ack(私信就是收件人 user_inbox 里的行)。
+    // ── RFC-041(#487):节点自己的权限 —— 改模式、看「本来会拦」的报表。只给人(用户令牌)。 ──
+    const permModeMatch = url.pathname.match(/^\/api\/nodes\/([^/]+)\/permission-mode$/);
+    if (permModeMatch && req.method === "PUT") {
+      if (!restAuth) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
+      if (restAuth.networkId) return userTokenRequired(req);
+      let body: any;
+      try { body = await req.json(); } catch { return withCors(req, Response.json({ ok: false, error: "invalid_json" }, { status: 400 })); }
+      const mode = body?.mode;
+      if (!NODE_PERMISSION_MODES.includes(mode)) {
+        return withCors(req, Response.json({ ok: false, error: "invalid_permission_mode", message: `mode must be one of ${NODE_PERMISSION_MODES.join(", ")}` }, { status: 400 }));
+      }
+      const nodeRef = decodeURIComponent(permModeMatch[1]);
+      const node = db.get<{ node_id: string; network_id: string | null; owner_user_id: string | null; permission_mode: string | null }>(
+        "SELECT node_id, network_id, owner_user_id, permission_mode FROM nodes WHERE node_id = ?1", nodeRef);
+      const role = node?.network_id ? getUserNetworkRole(restAuth.userId, node.network_id) : null;
+      // 看不见这个节点(不在它的网络里)与不存在同一个 404。
+      if (!node || !node.network_id || (!role && !isAdmin)) return withCors(req, Response.json({ ok: false, error: "node_not_found" }, { status: 404 }));
+      // 节点主人、网络 owner / admin、Hub 管理员能改;部门负责人和别的成员不能(RFC-041 §2.3 / §2.4)。
+      if (!isAdmin && node.owner_user_id !== restAuth.userId && role !== "owner" && role !== "admin") {
+        return withCors(req, Response.json({ ok: false, error: "permission_denied", message: "only the node's owner or a network owner/admin can change its permission mode" }, { status: 403 }));
+      }
+      const previous = (node.permission_mode || "normal") as NodePermissionMode;
+      db.run("UPDATE nodes SET permission_mode = ?1 WHERE node_id = ?2", [mode, node.node_id]);
+      logAudit(restAuth.userId, restAuth.username, "node_permission_mode_changed", "node", node.node_id, JSON.stringify({ from: previous, to: mode }), getClientIP(req), node.network_id);
+      return withCors(req, Response.json({ ok: true, node_id: node.node_id, permission_mode: mode, previous }));
+    }
+    const permReportMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/node-permission-report$/);
+    if (permReportMatch && req.method === "GET") {
+      if (!restAuth) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
+      if (restAuth.networkId) return userTokenRequired(req);
+      const networkId = decodeURIComponent(permReportMatch[1]);
+      const role = getUserNetworkRole(restAuth.userId, networkId);
+      if (!isAdmin && role !== "owner" && role !== "admin") {
+        return withCors(req, Response.json({ ok: false, error: "permission_denied", message: "network owner/admin only" }, { status: 403 }));
+      }
+      const sinceRaw = url.searchParams.get("since");
+      const sinceMs = sinceRaw ? Date.parse(sinceRaw) : Date.now() - 7 * 86_400_000;
+      if (!Number.isFinite(sinceMs)) return withCors(req, Response.json({ ok: false, error: "invalid_since" }, { status: 400 }));
+      const sinceHour = new Date(sinceMs).toISOString().slice(0, 13);
+      const rows = db.all<{ node_id: string; route: string; reason: string; hits: number | string; sample: string | null; last_hour: string }>(
+        `SELECT node_id, route, reason, SUM(hits) AS hits, MAX(sample) AS sample, MAX(hour) AS last_hour
+           FROM node_permission_log WHERE network_id = ?1 AND hour >= ?2
+          GROUP BY node_id, route, reason ORDER BY node_id, route, reason`,
+        networkId, sinceHour);
+      const byNode = new Map<string, { node_id: string; alias: string | null; permission_mode: string; total: number; by_reason: Record<string, number>; routes: Array<{ route: string; reason: string; hits: number; sample: string | null; last_hour: string }> }>();
+      for (const r of rows) {
+        let entry = byNode.get(r.node_id);
+        if (!entry) {
+          const n = db.get<{ alias: string | null; permission_mode: string | null }>("SELECT alias, permission_mode FROM nodes WHERE node_id = ?1", r.node_id);
+          entry = { node_id: r.node_id, alias: n?.alias ?? null, permission_mode: n?.permission_mode || "normal", total: 0, by_reason: {}, routes: [] };
+          byNode.set(r.node_id, entry);
+        }
+        const hits = Number(r.hits);
+        entry.total += hits;
+        entry.by_reason[r.reason] = (entry.by_reason[r.reason] ?? 0) + hits;
+        entry.routes.push({ route: r.route, reason: r.reason, hits, sample: r.sample, last_hour: r.last_hour });
+      }
+      const nodes = [...byNode.values()].sort((a, b) => b.total - a.total || a.node_id.localeCompare(b.node_id));
+      return withCors(req, Response.json({ ok: true, network_id: networkId, since: new Date(sinceMs).toISOString(), mode: nodePermissionsFlag(), total: nodes.reduce((n, e) => n + e.total, 0), nodes }));
+    }
+
     if (url.pathname === "/api/dm" || url.pathname === "/api/dm/threads") {
       if (!restAuth || !requestToken(req).startsWith("utok_")) {
         return withCors(req, Response.json({ ok: false, error: "user_token_required" }, { status: 403 }));
@@ -3096,6 +3269,11 @@ return Bun.serve({
       }
       const canonical = resolveCanonicalAlias(taskNetId, body.alias);
       const targetAlias = canonical.alias;
+      const nodeDenied = restNodeDenied(req, restAuth, "POST /api/task", (id) => dispatchVerdict(id, {
+        alias: targetAlias,
+        nodeId: db.get<{ node_id: string | null }>("SELECT node_id FROM sessions WHERE alias = ?1 AND network_id = ?2", targetAlias, taskNetId)?.node_id ?? null,
+      }));
+      if (nodeDenied) return nodeDenied;
       const target = resolveRestDeliveryTarget(targetAlias, taskNetId);
       if (target.state === "not_found") {
         return withCors(req, Response.json({
@@ -3331,6 +3509,8 @@ return Bun.serve({
       if (!canRestWriteNetwork(restAuth, restScope.networkId, isAdmin)) {
         return withCors(req, Response.json({ ok: false, error: "permission_denied" }, { status: 403 }));
       }
+      const broadcastDenied = restNodeDenied(req, restAuth, "POST /api/broadcast", broadcastVerdict);
+      if (broadcastDenied) return broadcastDenied;
       let sql = "SELECT alias, node_id, network_id FROM sessions WHERE alias IS NOT NULL";
       const params: any[] = [];
       sql = addNetworkScope(sql, params, restScope);
@@ -3634,7 +3814,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 +3830,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);
@@ -3703,6 +3883,8 @@ return Bun.serve({
       if (!canRestWriteNetwork(restAuth, nodeNetId, isAdmin)) {
         return withCors(req, Response.json({ ok: false, error: "permission_denied" }, { status: 403 }));
       }
+      const nodeWriteDenied = restNodeDenied(req, restAuth, "DELETE /api/nodes/:id", nodeTargetVerdict(node.node_id));
+      if (nodeWriteDenied) return nodeWriteDenied;
 
       db.transaction(() => {
         db.run("DELETE FROM nodes WHERE node_id = ?1", [node.node_id]);
@@ -3813,6 +3995,8 @@ return Bun.serve({
       if (!canRestWriteNetwork(restAuth, nodeNetId, isAdmin)) {
         return withCors(req, Response.json({ ok: false, error: "permission_denied" }, { status: 403 }));
       }
+      const nodeWriteDenied = restNodeDenied(req, restAuth, "PUT /api/nodes/:id/attrs", nodeTargetVerdict(node.node_id));
+      if (nodeWriteDenied) return nodeWriteDenied;
 
       // Optimistic lock BEFORE any narrowing work, so a losing writer never
       // has side effects.
@@ -3912,6 +4096,8 @@ return Bun.serve({
       if (!canRestWriteNetwork(restAuth, nodeNetId, isAdmin)) {
         return withCors(req, Response.json({ ok: false, error: "permission_denied" }, { status: 403 }));
       }
+      const nodeWriteDenied = restNodeDenied(req, restAuth, "PUT /api/nodes/:id/avatar", nodeTargetVerdict(node.node_id));
+      if (nodeWriteDenied) return nodeWriteDenied;
 
       db.run(
         "UPDATE nodes SET avatar_url = ?1, updated_at = datetime('now') WHERE node_id = ?2",
@@ -4177,7 +4363,7 @@ return Bun.serve({
                         config_path, channels, server, hostname,
                         network_id, created_at, updated_at,
                         config_snapshot, lifecycle_state, avatar_url,
-                        display_name, team, tags, attrs_revision
+                        display_name, team, tags, attrs_revision, permission_mode
                  FROM nodes WHERE 1=1`;
       const params: any[] = [];
       sql = addAgentNetworkScope(sql, params, restScope, { alias: "alias", nodeId: "node_id" });