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

package/src/server.ts

@@ -3,8 +3,10 @@ import { markGzipReusable, maybeGzipResponse, trimLightTask } from "./http-gzip"
 import { ifNoneMatchHits, memoStatusBody } from "./status-read-cache";
 import { statusAliasResolverRead } from "./status-alias-resolver.js";
 import { readNodeHealth } from "./node-health-store.js";
+import { wantsAllTools } from "./tool-audience.js";
 import { assertNodeHealthy, degradedLayers } from "./node-health-guard.js";
 import { auditDepartment, createDepartment, deleteDepartment, listDepartments, setMemberDepartment, updateDepartment } from "./departments.js";
+import { addManualMember, canManageGroup, createDepartmentGroup, getDepartmentGroup, groupById, groupViewerCan, isGroupMember, listGroupMembers, listVisibleGroups, readGroup, removeManualMember, renameGroup, syncDepartmentGroups } from "./department-groups.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";
@@ -22,8 +24,10 @@ import { pendingInboxCount } from "./inbox-count.js";
 import { addAgentNetworkScope, addHumanNetworkScope, addNetworkScope, addOwnTrafficScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, getUserNetworkIds, resolveRestNetworkScope, resolveRestWriteNetworkId, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { restrictedMemberSeesFile, restrictedMemberAttachmentsDenied } from "./restricted-files.js";
 import { dmParticipantSeesFile, listDmThread, listDmThreads, sendHumanDm } from "./human-dm.js";
+import { groupMemberSeesFile, groupUnreadFor, listGroupMessages, listGroupThreads, markGroupRead, memberGroup, sendGroupMessage } from "./group-messages.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";
@@ -123,7 +127,11 @@ const SERVER_VERSION = (() => {
 })();
 
 // Feature flags advertised on /health (see the /health handler). Exported for tests.
-export const HUB_HEALTH_CAPABILITIES = ["status_node_id"] as const;
+// node_permission_mode(#489):节点有 permission_mode、GET /api/nodes 每行带 viewer_can.permission_mode,
+// PUT /api/nodes/:id/permission-mode 与 GET /api/networks/:id/node-permission-report 可用(RFC-041 第一阶段)。
+// chat_groups(RFC-042,#457):部门群可用 —— …/departments/:dept/group、…/chat-groups(资料 / 成员 / 消息 / 已读)、
+// GET /api/dm/threads 的 group_threads;群对象带 viewer_can {manage, post},会话行带 last_message 预览,成员带 username / display_name。
+export const HUB_HEALTH_CAPABILITIES = ["status_node_id", "node_permission_mode", "chat_groups"] as const;
 
 // In-memory log ring buffer — last N lines streamed via /api/server-logs.
 // Wraps console.log/info/warn/error so EVERY existing log call lands here
@@ -179,12 +187,12 @@ function sweepStaleRateLimits(): void {
 }
 
 // ── Factory: 每个请求创建新的 McpServer（stateless 模式）──
-function createServer(clientIP?: string, enforceNetworkId?: string | null, enforceUserId?: string | null, callerAlias?: string | null, callerTokenIsNetwork = false, callerTokenId?: string | null): McpServer {
+function createServer(clientIP?: string, enforceNetworkId?: string | null, enforceUserId?: string | null, callerAlias?: string | null, callerTokenIsNetwork = false, callerTokenId?: string | null, includeProtocolTools = false): McpServer {
   const server = new McpServer({
     name: "commhub",
     version: "0.5.0",
   });
-  registerTools(server, clientIP, enforceNetworkId, enforceUserId, callerAlias, callerTokenIsNetwork, callerTokenId);
+  registerTools(server, clientIP, enforceNetworkId, enforceUserId, callerAlias, callerTokenIsNetwork, callerTokenId, { includeProtocol: includeProtocolTools });
   return server;
 }
 
@@ -318,6 +326,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 }));
 }
@@ -440,6 +460,10 @@ export function normalizeEntry(
 //     legacy master token still pass above, as for every other file.
 //     Files uploaded any other way never become DM-scoped, including when
 //     they are later forwarded into a DM.
+//     RFC-042 (#457, group messages): a DM-scoped file is also readable by
+//     the CURRENT members of a chat group with a message carrying it
+//     (group-messages.ts groupMemberSeesFile); the same widening applies to
+//     restricted members below. Removed members lose it immediately.
 //   - Everything else → deny (404). New uploads in production always
 //     carry a truthy owner_id (requireAuth blocks the null-owner-
 //     producing path when DEV_OPEN=off and no legacy master token is
@@ -467,12 +491,12 @@ export function authorizeFileDownload(
     // 私信文件:只看是不是这段私信里的人,与受限 / 不受限无关。
     if (entry.dmScoped) {
       if (entry.ownerId !== null && entry.ownerId === principal.userId) return true;
-      return !!fileId && dmParticipantSeesFile(principal.userId, entry.networkId, fileId);
+      return !!fileId && (dmParticipantSeesFile(principal.userId, entry.networkId, fileId) || groupMemberSeesFile(principal.userId, entry.networkId, fileId));
     }
     // 多用户 Agent 权限:受限成员只能下载自己传的,或者出现在自己与授权 Agent 往来 / 自己收件箱里的文件。
     if (!isAgentRestricted(principal.userId, entry.networkId)) return true;
     if (entry.ownerId !== null && entry.ownerId === principal.userId) return true;
-    return !!fileId && restrictedMemberSeesFile(principal.userId, principal.username, entry.networkId, fileId);
+    return !!fileId && (restrictedMemberSeesFile(principal.userId, principal.username, entry.networkId, fileId) || groupMemberSeesFile(principal.userId, entry.networkId, fileId));
   }
 
   if (principal.kind === "ntok" || principal.kind === "utok") {
@@ -979,7 +1003,8 @@ return Bun.serve({
         }
         labelRoute(req, mcpParsedBody === undefined ? "?" : mcpRouteLabel(mcpParsedBody));
       }
-      const mcpServer = createServer(clientIP, enforceNetId, authCtx?.userId || null, callerAlias, !!token?.startsWith("ntok_"), authCtx?.tokenId || null);
+      // #478:tools/list 按调用者过滤;X-Anet-Tools: all / ?tools=all 时节点令牌也列出协议工具。
+      const mcpServer = createServer(clientIP, enforceNetId, authCtx?.userId || null, callerAlias, !!token?.startsWith("ntok_"), authCtx?.tokenId || null, wantsAllTools(req, url));
       await mcpServer.connect(transport);
       const response = await transport.handleRequest(req, mcpParsedBody === undefined ? undefined : { parsedBody: mcpParsedBody });
       // Disconnect after response to prevent McpServer leak
@@ -1007,11 +1032,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);
@@ -1028,6 +1051,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)) {
@@ -1103,6 +1128,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);
       }
 
@@ -1731,7 +1761,7 @@ return Bun.serve({
     // 在这棵子树里也能写;越出子树 → 403 department_scope_denied(固定一个错误)。不是负责人的成员与以前逐字节相同。 ──
     const deptMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/departments(?:\/([^/]+))?$/);
     const memberDeptMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/members\/([^/]+)\/department$/);
-    const deptSubMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/departments\/([^/]+)\/(project-grants|nodes)$/);
+    const deptSubMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/departments\/([^/]+)\/(project-grants|nodes|group)$/);
     if (deptMatch || memberDeptMatch || deptSubMatch) {
       const token = requestToken(req, { allowQueryToken: false });
       const resolved = token ? resolveToken(token) : null;
@@ -1779,6 +1809,35 @@ return Bun.serve({
           });
           return withCors(req, Response.json({ ok: true, network_id: netId, department_id: deptId, nodes }));
         }
+        if (deptSubMatch[3] === "group") {
+          // RFC-042(#457)部门群:GET 看部门挂着的群,POST 建群。Agent(节点令牌)不进群,一律 403。
+          // 建:owner / admin / Hub 管理员,或这个部门(含上级)的负责人。读:上面这些人,和群成员;别人 → 404(不暴露有没有群)。
+          if (resolved.networkId) return withCors(req, Response.json({ ok: false, error: "humans_only" }, { status: 403 }));
+          const mayCreate = canManage || head.managed.has(deptId);
+          if (req.method === "GET") {
+            const linked = getDepartmentGroup(netId, deptId);
+            // 兜底对账(RFC-042 §4):读之前先把成员对齐,再判「是不是成员」。
+            if (linked) db.transaction(() => { syncDepartmentGroups(netId, linked.id); });
+            const group = linked ? getDepartmentGroup(netId, deptId) : null;
+            if (!group || (!mayCreate && !isGroupMember(group.id, resolved.user.user_id))) {
+              return withCors(req, Response.json({ ok: false, error: "department_group_not_found" }, { status: 404 }));
+            }
+            const viewerCan = groupViewerCan(group, isGroupMember(group.id, resolved.user.user_id), canManage, head.managed);
+            return withCors(req, Response.json({ ok: true, network_id: netId, department_id: deptId, group: { ...group, viewer_can: viewerCan }, members: listGroupMembers(group.id) }));
+          }
+          if (req.method !== "POST") return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
+          if (!mayCreate) return isHead ? scopeDenied() : withCors(req, Response.json({ ok: false, error: "owner/admin required" }, { status: 403 }));
+          let groupBody: Record<string, unknown> = {};
+          try { const t = await req.text(); const b = t ? JSON.parse(t) : {}; groupBody = 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 = createDepartmentGroup(netId, deptId, resolved.user.user_id, groupBody);
+          if (!r.ok) {
+            const { ok: _ok, status, ...rest } = r;
+            return withCors(req, Response.json({ ok: false, ...rest }, { status }));
+          }
+          auditDepartment(resolved.user, "department_group_created", netId, JSON.stringify({ id: deptId, group_id: r.group.id, members: r.members.length, ...(canManage ? {} : { via: "leader" }) }));
+          const createdCan = groupViewerCan(r.group, r.members.some((m) => m.user_id === resolved.user.user_id), canManage, head.managed);
+          return withCors(req, Response.json({ ok: true, network_id: netId, department_id: deptId, group: { ...r.group, viewer_can: createdCan }, members: r.members }, { status: 201 }));
+        }
         // 部门项目授权:只有 owner / admin(和按人授权一样)。
         if (!canManage) return withCors(req, Response.json({ ok: false, error: "owner/admin required" }, { status: 403 }));
         if (req.method === "GET") {
@@ -1869,6 +1928,108 @@ return Bun.serve({
       return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
     }
 
+    // ── RFC-042(#457):群(目前只有部门群)。
+    // GET …/chat-groups = 我在里面的群(owner / admin / Hub 管理员看到全部);GET …/chat-groups/:gid = 群资料 + 成员
+    // (群成员、owner / admin、该部门(含上级)负责人;别人 404)。建群走 POST …/departments/:dept/group。
+    // 第二个 PR:PATCH …/chat-groups/:gid {name} 改群名;POST …/chat-groups/:gid/members {user_id} 手动拉人;
+    // DELETE …/chat-groups/:gid/members/:uid 手动移人(source='department' 的人 → 409 department_member)。
+    // 管群 = owner / admin / Hub 管理员,或挂部门的群的该部门(含上级)负责人。看得见但管不了 → 403 group_manage_denied;
+    // 看不见 → 404 group_not_found(不暴露有没有群)。Agent(节点令牌)不进群,一律 403 humans_only。 ──
+    const chatGroupsMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/chat-groups(?:\/([^/]+)(?:\/(members|messages|read)(?:\/([^/]+))?)?)?$/);
+    if (chatGroupsMatch) {
+      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 }));
+      if (resolved.networkId) return withCors(req, Response.json({ ok: false, error: "humans_only" }, { status: 403 }));
+      const netId = decodeURIComponent(chatGroupsMatch[1]);
+      const hubAdmin = isHubAdminCredential(resolved);
+      const role = getUserNetworkRole(resolved.user.user_id, netId);
+      if (!hubAdmin && !role) return withCors(req, Response.json({ ok: false, error: "not a member of this network" }, { status: 403 }));
+      const canManage = hubAdmin || role === "owner" || role === "admin";
+      const gid = chatGroupsMatch[2] ? decodeURIComponent(chatGroupsMatch[2]) : null;
+      const sub = chatGroupsMatch[3];
+      const memberUid = chatGroupsMatch[4] ? decodeURIComponent(chatGroupsMatch[4]) : null;
+      // viewer 当负责人不获得任何东西(headScope 已保证);owner / admin 本来全管,不必算。
+      const managed = canManage ? new Set<string>() : headScope(netId, resolved.user.user_id).managed;
+      if (!gid) {
+        if (req.method !== "GET") return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
+        // 第三个 PR:每个群附上我的 unread / last_message_at(只对我在里面的群;管理者看到的非成员群是 0 / null —— 不让管理身份窥探消息时间)。
+        // App 补口(只增):last_message 预览(同一口径,非成员群 null)和 viewer_can {manage, post}(与写接口同一判据)。
+        // listGroupThreads 已经批量带上 last_message,整张列表固定几次查询,不逐群查。
+        const threads = new Map(listGroupThreads(netId, resolved.user.user_id).map((t) => [t.group_id, t]));
+        const groups = listVisibleGroups(netId, resolved.user.user_id, canManage).map((g) => {
+          const t = g.is_member ? threads.get(g.id) : undefined;
+          return { ...g, unread: t?.unread ?? 0, last_message_at: t?.last_at ?? null, last_message: t?.last_message ?? null, viewer_can: groupViewerCan(g, g.is_member, canManage, managed) };
+        });
+        return withCors(req, Response.json({ ok: true, network_id: netId, groups }));
+      }
+      const notFound = () => withCors(req, Response.json({ ok: false, error: "group_not_found" }, { status: 404 }));
+      // 第三个 PR(群消息):GET / POST …/:gid/messages、POST …/:gid/read。只认**当前群成员** —— owner / admin / 负责人
+      // 不是成员也读不到消息(他们看得到群资料,但消息只给群里的人);别人(含被移出的人)一律 404 group_not_found。
+      if (sub === "messages" || sub === "read") {
+        if (memberUid) return notFound();
+        const ok = (sub === "messages" && (req.method === "GET" || req.method === "POST")) || (sub === "read" && req.method === "POST");
+        if (!ok) return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
+        if (!memberGroup(netId, gid, resolved.user.user_id)) return notFound();
+        const failedMsg = (r: { status: number; error: string }) => withCors(req, Response.json({ ok: false, error: r.error }, { status: r.status }));
+        if (sub === "messages" && req.method === "GET") {
+          const page = listGroupMessages(gid, resolved.user.user_id, Number(url.searchParams.get("limit")) || 50, url.searchParams.get("before"));
+          if ("ok" in page) return failedMsg(page);
+          return withCors(req, Response.json({ ok: true, network_id: netId, group_id: gid, ...page, unread: groupUnreadFor(gid, resolved.user.user_id) }));
+        }
+        let mbody: Record<string, unknown> = {};
+        try { const t = await req.text(); const b = t ? JSON.parse(t) : {}; if (!b || typeof b !== "object" || Array.isArray(b)) throw new Error("not an object"); mbody = b as Record<string, unknown>; } catch { return withCors(req, Response.json({ ok: false, error: "invalid JSON" }, { status: 400 })); }
+        if (sub === "read") {
+          const r = markGroupRead(netId, gid, resolved.user.user_id, mbody.seq);
+          if (!r.ok) return failedMsg(r);
+          return withCors(req, Response.json({ ok: true, network_id: netId, group_id: gid, last_read_seq: r.last_read_seq, unread: r.unread }));
+        }
+        const sent = sendGroupMessage({
+          networkId: netId, groupId: gid,
+          sender: { userId: resolved.user.user_id, username: resolved.user.username },
+          message: mbody.message, attachments: mbody.attachments, clientRequestId: mbody.client_request_id,
+        });
+        if (!sent.ok) return failedMsg(sent);
+        return withCors(req, Response.json({ ok: true, network_id: netId, group_id: gid, message: sent.message, duplicate: sent.duplicate, delivered_to: sent.delivered_to }));
+      }
+      if (!sub && req.method === "GET") {
+        const got = readGroup(netId, gid, resolved.user.user_id, canManage, managed);
+        if (!got) return notFound();
+        return withCors(req, Response.json({ ok: true, network_id: netId, ...got }));
+      }
+      const allowed = (!sub && req.method === "PATCH") || (sub === "members" && !memberUid && req.method === "POST") || (sub === "members" && memberUid && req.method === "DELETE");
+      if (!allowed) return withCors(req, Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 }));
+      const group = groupById(netId, gid);
+      if (!group) return notFound();
+      if (!canManageGroup(group, canManage, managed)) {
+        return isGroupMember(gid, resolved.user.user_id)
+          ? withCors(req, Response.json({ ok: false, error: "group_manage_denied" }, { status: 403 }))
+          : notFound();
+      }
+      let body: Record<string, unknown> = {};
+      if (req.method !== "DELETE") {
+        try { const t = await req.text(); const b = t ? JSON.parse(t) : {}; 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 })); }
+      }
+      const via = canManage ? {} : { via: "leader" };
+      const failed = (r: { status: number; error: string }) => withCors(req, Response.json({ ok: false, error: r.error }, { status: r.status }));
+      if (!sub) {
+        const r = renameGroup(netId, gid, body);
+        if (!r.ok) return failed(r);
+        auditDepartment(resolved.user, "chat_group_renamed", netId, JSON.stringify({ group_id: gid, name: r.group.name, ...via }));
+        return withCors(req, Response.json({ ok: true, network_id: netId, group: { ...r.group, viewer_can: groupViewerCan(r.group, isGroupMember(gid, resolved.user.user_id), canManage, managed) } }));
+      }
+      if (!memberUid) {
+        const r = addManualMember(netId, gid, body.user_id);
+        if (!r.ok) return failed(r);
+        auditDepartment(resolved.user, "chat_group_member_added", netId, JSON.stringify({ group_id: gid, user_id: r.member.user_id, ...via }));
+        return withCors(req, Response.json({ ok: true, network_id: netId, group_id: gid, member: r.member }, { status: 201 }));
+      }
+      const r = removeManualMember(netId, gid, memberUid);
+      if (!r.ok) return failed(r);
+      auditDepartment(resolved.user, "chat_group_member_removed", netId, JSON.stringify({ group_id: gid, user_id: memberUid, ...via }));
+      return withCors(req, Response.json({ ok: true, network_id: netId, group_id: gid, removed: memberUid }));
+    }
+
     // ── V3.13: Network members + invites ──
     const membersMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/members(?:\/([^/]+))?$/);
     if (membersMatch) {
@@ -2271,6 +2432,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 }));
@@ -2297,7 +2519,8 @@ return Bun.serve({
           return withCors(req, Response.json({ ok: false, error: "not a member of this network" }, { status: 403 }));
         }
         if (url.pathname === "/api/dm/threads") {
-          return withCors(req, Response.json({ ok: true, network_id: dmNet, threads: listDmThreads(dmNet, restAuth.userId) }));
+          // group_threads(RFC-042 第三个 PR,只增字段):我在里面的群,每个带 unread / last_at / last_message 预览 —— App 私信未读角标可以一起算。
+          return withCors(req, Response.json({ ok: true, network_id: dmNet, threads: listDmThreads(dmNet, restAuth.userId), group_threads: listGroupThreads(dmNet, restAuth.userId) }));
         }
         const other = url.searchParams.get("with") ?? "";
         if (!other) return withCors(req, Response.json({ ok: false, error: "with_required" }, { status: 400 }));
@@ -3190,6 +3413,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({
@@ -3425,6 +3653,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);
@@ -3797,6 +4027,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]);
@@ -3907,6 +4139,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.
@@ -4006,6 +4240,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",
@@ -4271,7 +4507,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, owner_user_id
                  FROM nodes WHERE 1=1`;
       const params: any[] = [];
       sql = addAgentNetworkScope(sql, params, restScope, { alias: "alias", nodeId: "node_id" });
@@ -4312,6 +4548,17 @@ return Bun.serve({
         }
       })();
 
+      // RFC-041(#489):调用者能不能改这个节点的权限模式 —— 与 PUT /api/nodes/:id/permission-mode 同一判据
+      // (节点主人、网络 owner / admin、Hub 管理员;只给用户令牌)。客户端据此决定显示「权限」一行,不自己推导规则。
+      const netRoles = new Map<string, string | null>();
+      const canSetPermissionMode = (r: Record<string, any>): boolean => {
+        if (!restAuth || restAuth.networkId) return false;
+        if (isAdmin || (r.owner_user_id && r.owner_user_id === restAuth.userId)) return true;
+        if (!r.network_id) return false;
+        if (!netRoles.has(r.network_id)) netRoles.set(r.network_id, getUserNetworkRole(restAuth.userId, r.network_id));
+        const role = netRoles.get(r.network_id);
+        return role === "owner" || role === "admin";
+      };
       const rows = rawRows.map(r => {
         let role: string | null = null;
         const snap = r.config_snapshot;
@@ -4319,7 +4566,7 @@ return Bun.serve({
           try { role = (typeof snap === "string" ? JSON.parse(snap) : snap)?.role ?? null; }
           catch { /* malformed snapshot — leave role null */ }
         }
-        const { config_snapshot, ...rest } = r;
+        const { config_snapshot, owner_user_id, ...rest } = r;
         // `tags` is stored as JSON text; hand the dashboard a real array so
         // it can map() without a guard, and normalise legacy/absent values
         // to [] rather than null. attrs_revision is normalised to a number
@@ -4335,6 +4582,7 @@ return Bun.serve({
           role,
           lifecycle_controllable,
           lifecycle_daemon_node_id: controllable.get(r.node_id) ?? null,
+          viewer_can: { permission_mode: canSetPermissionMode(r) },
         };
       });
       return withCors(req, Response.json({ ok: true, nodes: rows, count: rows.length }));

package/src/task-access.ts

@@ -99,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; agent_owner_json?: 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; parent_id?: 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);
@@ -126,10 +126,33 @@ function headOf(userId: string, row: CardRow): boolean {
   return !!cards && isDepartmentCard(cards, row);
 }
 
-export type TaskCaller = { userId: string } | null;
+/**
+ * 调用者。userId = 按谁的任务权限判;node(RFC-041,#487)= 节点令牌按**主人**的权限判时带上节点:
+ *   only=false(正常模式、执行开关打开)—— 主人能改的能改,另外「派给这个节点的」在主人看得见时也能改;
+ *   only=true (受限模式)—— 只看、只改派给这个节点的卡(负责 Agent / 参与人 / 它建的,及这些卡的子任务)。
+ */
+export type TaskCaller = { userId: string; node?: { id: string; only: boolean } } | null;
+
+export const nodeRefPattern = (nodeId: string) => `%${likeEscape(`"kind":"node","id":"${nodeId}"`)}%`;
+const nodeRefIs = (json: string | null | undefined, nodeId: string) => !!json && json.includes(`"kind":"node","id":"${nodeId}"`);
+const directlyAssigned = (row: Pick<CardRow, "agent_owner_json" | "participants_json" | "created_by_json">, nodeId: string) =>
+  nodeRefIs(row.agent_owner_json, nodeId) || nodeRefIs(row.participants_json, nodeId) || nodeRefIs(row.created_by_json, nodeId);
+
+/** 这张卡派给了这个节点吗:负责 Agent / 参与人有它 / 它建的,或者父卡是。 */
+export function cardAssignedToNode(row: CardRow, nodeId: string): boolean {
+  if (directlyAssigned(row, nodeId)) return true;
+  if (!row.parent_id) return false;
+  const parent = db.get<{ agent_owner_json: string | null; participants_json: string | null; created_by_json: string | null }>(
+    "SELECT agent_owner_json, participants_json, created_by_json FROM requirements WHERE requirement_id = ?1", row.parent_id);
+  return !!parent && directlyAssigned(parent, nodeId);
+}
 
 /** 看得见这张卡吗。caller=null(节点令牌 / 管理员 / 旧的全局令牌)恒为 true。 */
 export function canSeeTask(caller: TaskCaller, row: CardRow): boolean {
+  if (caller?.node?.only && !cardAssignedToNode(row, caller.node.id)) return false;
+  return canSeeTaskAsUser(caller, row);
+}
+function canSeeTaskAsUser(caller: TaskCaller, row: CardRow): boolean {
   if (!caller) return true;
   const m = memberRow(caller.userId, row.network_id);
   if (!scopedRow(m)) return true;
@@ -141,6 +164,13 @@ export function canSeeTask(caller: TaskCaller, row: CardRow): boolean {
 
 /** 能改这张卡吗(PATCH / 勾子任务)。只对看得见的卡调用。 */
 export function canEditTask(caller: TaskCaller, row: CardRow): boolean {
+  if (caller?.node) {
+    const assigned = cardAssignedToNode(row, caller.node.id) && canSeeTaskAsUser(caller, row);
+    return caller.node.only ? assigned : assigned || canEditTaskAsUser(caller, row);
+  }
+  return canEditTaskAsUser(caller, row);
+}
+function canEditTaskAsUser(caller: TaskCaller, row: CardRow): boolean {
   if (!caller) return true;
   const m = memberRow(caller.userId, row.network_id);
   if (!scopedRow(m)) return true;
@@ -174,7 +204,7 @@ export const PARTICIPANT_EDIT_FIELDS: readonly string[] = ["column", "checklist"
 
 /** 这个调用者是不是「只能以参与人身份改」这张卡(canEditTask 为 false、但他是卡上的参与人)。viewer 不算。 */
 export function canParticipantEditTask(caller: TaskCaller, row: CardRow): boolean {
-  if (!caller) return false;
+  if (!caller || caller.node) return false; // 参与人身份是人的;节点按 canEditTask 判
   const m = memberRow(caller.userId, row.network_id);
   if (!scopedRow(m) || m?.member_role === "viewer") return false;
   return participates(row, caller.userId);
@@ -258,6 +288,14 @@ export function canUseProject(caller: TaskCaller, networkId: string, projectId:
  * 追加在已经按网络过滤过的 `FROM requirements WHERE …` 后面。
  */
 export function addTaskVisibilityScope(sql: string, params: unknown[], caller: TaskCaller): string {
+  const scoped = addTaskVisibilityScopeAsUser(sql, params, caller);
+  if (!caller?.node?.only) return scoped;
+  // 受限节点:再只留派给它的卡(及其子任务)。
+  const pat = params.push(nodeRefPattern(caller.node.id));
+  const mine = (t: string) => `${t}agent_owner_json LIKE ?${pat} ESCAPE '\\' OR ${t}participants_json LIKE ?${pat} ESCAPE '\\' OR ${t}created_by_json LIKE ?${pat} ESCAPE '\\'`;
+  return `${scoped} AND (${mine("")} OR parent_id IN (SELECT p.requirement_id FROM requirements p WHERE ${mine("p.")}))`;
+}
+function addTaskVisibilityScopeAsUser(sql: string, params: unknown[], caller: TaskCaller): string {
   if (!caller) return sql;
   const scoped = taskScopedNetworks(caller.userId);
   if (!scoped.length) return sql;