@sleep2agi/commhub-server 0.9.0-preview.70 → 0.9.0-preview.71

package/README.md

@@ -150,9 +150,11 @@ delivered/acked/running → reassign → delivered (new agent)
 
 ## PostgreSQL (community extension point — not on the maintained roadmap)
 
+> **PostgreSQL support is still in development and does not work yet** (PostgreSQL 支持尚在开发中，目前不可用). With `DATABASE_URL=postgres://…` the hub exits while creating its schema. Progress: [RFC-039](https://github.com/sleep2agi/agent-network/blob/main/docs/rfcs/RFC-039-hub-postgresql-backend.md).
+
 > v0.8+ product direction is **SQLite only** (see [docs/v3-postgresql-design.md banner](https://github.com/sleep2agi/agent-network/blob/main/docs/v3-postgresql-design.md)). The PostgreSQL adapter interface is preserved as a community extension point — no E2E coverage on the current stable line; **not recommended for mainline production**.
 
-Set `DATABASE_URL` to switch to PostgreSQL — the SQL layer auto-translates SQLite-isms (datetime, parameter placeholders) so application code is unchanged. Requires `bun add pg`.
+Design intent (not working today): setting `DATABASE_URL` switches to PostgreSQL, and the SQL layer translates SQLite-isms (datetime, parameter placeholders). Requires `bun add pg`.
 
 ```bash
 DATABASE_URL=postgres://user:pass@host:5432/commhub bunx @sleep2agi/commhub-server
@@ -166,7 +168,7 @@ DATABASE_URL=postgres://user:pass@host:5432/commhub bunx @sleep2agi/commhub-serv
 | `HOST` | `0.0.0.0` in the server package, `127.0.0.1` when launched by `anet hub start` | listen address |
 | `COMMHUB_AUTH_TOKEN` | (none) | Bearer token gate (legacy) |
 | `COMMHUB_DB` | `~/.commhub/commhub.db` | SQLite path |
-| `DATABASE_URL` | (none) | switches to PostgreSQL when set (unverified) |
+| `DATABASE_URL` | (none) | switches to PostgreSQL when set — **does not work yet**, see above |
 
 ## Running the unit tests
 
@@ -274,7 +276,7 @@ main 上 66 处写的是 `SOURCE_COMMIT`,另有若干写成 `TEST<编号>_SOURCE
 ## Not verified
 
 - `/api/license*` — experimental legacy trial/pro-license endpoints.
-- PostgreSQL backend — translation layer exists, no E2E run.
+- PostgreSQL backend — in development, does not work yet (hub exits while creating its schema; RFC-039).
 - Telegram / WeChat / Feishu channel endpoints — channel code exists, but only Telegram-oriented agent-node paths are actively exercised.
 
 ## License

package/package.json

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

package/src/admin-delete-network-http.test.ts

@@ -0,0 +1,177 @@
+// Hub 管理员删别人的**空**网络(清理旧测试账号留下的个人网络)。
+// 真 HTTP:走 DELETE /api/networks/:id,库和上传目录都是本文件私有的临时目录。
+//   bun test server/src/admin-delete-network-http.test.ts
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const PRIVATE_DIR = mkdtempSync(join(tmpdir(), "anet-admin-delete-network-"));
+process.env.COMMHUB_DB ||= join(PRIVATE_DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(PRIVATE_DIR, "uploads");
+
+let server: ReturnType<typeof Bun.serve>;
+let base = "";
+let db: typeof import("./db.js").db;
+let auth: typeof import("./auth.js");
+let adminToken = "";
+let adminUserId = "";
+let adminNetworkId = "";
+let memberToken = "";
+let memberUserId = "";
+let memberNodeToken = "";
+const stamp = Date.now();
+
+function del(networkId: string, token: string) {
+  return fetch(`${base}/api/networks/${networkId}`, { method: "DELETE", headers: { Authorization: `Bearer ${token}` } });
+}
+
+function memberNetwork(name: string): string {
+  const created = auth.createNetwork(memberUserId, `${name}-${stamp}`);
+  expect(created.ok).toBe(true);
+  return created.network_id!;
+}
+
+function rowCount(table: string, networkId: string): number {
+  return db.get<{ cnt: number }>(`SELECT COUNT(*) AS cnt FROM ${table} WHERE network_id = ?1`, networkId)!.cnt;
+}
+
+// 同 admin-networks-http.test.ts:register() 跑 KDF + bootServer,给 30s 而不是 bun 默认 5s。
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  auth = await import("./auth.js");
+
+  // 第一个注册的是 Hub 管理员;第二个是普通用户,不在管理员的网络里。
+  const admin = auth.register(`admin_delnet_${stamp}`, "AdminDelNet-Strong-1!", undefined, "admin");
+  expect(admin.ok).toBe(true);
+  adminToken = admin.token!;
+  adminNetworkId = admin.network_id!;
+  adminUserId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", `admin_delnet_${stamp}`)!.user_id;
+
+  const member = auth.register(`member_delnet_${stamp}`, "MemberDelNet-Strong-1!", undefined, "member");
+  expect(member.ok).toBe(true);
+  memberToken = member.token!;
+  memberUserId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", `member_delnet_${stamp}`)!.user_id;
+  expect(db.get<{ role: string }>("SELECT role FROM users WHERE user_id = ?1", adminUserId)!.role).toBe("admin");
+  expect(db.get<{ role: string }>("SELECT role FROM users WHERE user_id = ?1", memberUserId)!.role).not.toBe("admin");
+  // free 档只能拥有 2 个网络;本文件要给它建七八个。plan 只影响配额,不影响任何权限判定。
+  db.run("UPDATE users SET plan = 'pro' WHERE user_id = ?1", [memberUserId]);
+
+  const minted = auth.createNetworkTokenForNode(memberUserId, member.network_id!, "delnet-node");
+  expect(minted.ok).toBe(true);
+  memberNodeToken = minted.token!;
+
+  const mod = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop(true); } catch {}
+  try { rmSync(PRIVATE_DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("DELETE /api/networks/:id — hub admin override for empty foreign networks", () => {
+  test("admin deletes an empty foreign network: 200, network + members + scoped tokens gone, audit has admin_override", async () => {
+    const netId = memberNetwork("empty");
+    const minted = auth.createNetworkTokenForNode(memberUserId, netId, "leftover-node");
+    expect(minted.ok).toBe(true);
+    expect(rowCount("network_members", netId)).toBe(1);
+    expect(rowCount("api_tokens", netId)).toBe(1);
+
+    const res = await del(netId, adminToken);
+    const body = await res.json() as any;
+    expect(res.status).toBe(200);
+    expect(body.ok).toBe(true);
+    expect(body.admin_override).toBe(true);
+
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = ?1", netId)).toBeFalsy();
+    expect(rowCount("network_members", netId)).toBe(0);
+    expect(rowCount("api_tokens", netId)).toBe(0);
+    // 被删网络的节点令牌不再能解析。
+    expect(auth.resolveToken(minted.token!)).toBeFalsy();
+
+    const audit = db.get<{ user_id: string; detail: string; network_id: string }>(
+      "SELECT user_id, detail, network_id FROM audit_log WHERE action = 'network_deleted' AND target_id = ?1", netId);
+    expect(audit).toBeTruthy();
+    expect(audit!.user_id).toBe(adminUserId);
+    const detail = JSON.parse(audit!.detail);
+    expect(detail.admin_override).toBe(true);
+    expect(detail.owner_id).toBe(memberUserId);
+  });
+
+  test("admin is refused with 409 and counts when the network has a node and a session", async () => {
+    const netId = memberNetwork("busy");
+    db.run("INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at) VALUES (?1, ?2, ?2, ?3, datetime('now'), datetime('now'))",
+      [`node-${stamp}`, `busy-node-${stamp}`, netId]);
+    db.run("INSERT INTO sessions (resume_id, alias, network_id) VALUES (?1, ?2, ?3)", [`resume-${stamp}`, `busy-node-${stamp}`, netId]);
+
+    const res = await del(netId, adminToken);
+    const body = await res.json() as any;
+    expect(res.status).toBe(409);
+    expect(body.ok).toBe(false);
+    expect(body.counts).toEqual({ nodes: 1, sessions: 1 });
+    expect(body.error).toContain("nodes=1");
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = ?1", netId)).toBeTruthy();
+    expect(rowCount("network_members", netId)).toBe(1);
+  });
+
+  test("admin is refused when the only content left is an uploaded file (disk index, not the DB)", async () => {
+    const netId = memberNetwork("files");
+    const indexDir = join(process.env.COMMHUB_UPLOADS_DIR!, ".index");
+    mkdirSync(indexDir, { recursive: true });
+    writeFileSync(join(indexDir, `f${stamp}.json`), JSON.stringify({ file_id: `f${stamp}`, network_id: netId }));
+
+    const res = await del(netId, adminToken);
+    const body = await res.json() as any;
+    expect(res.status).toBe(409);
+    expect(body.counts).toEqual({ files: 1 });
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = ?1", netId)).toBeTruthy();
+  });
+
+  test("admin cannot delete the 'default' network even when it is empty", async () => {
+    db.run("INSERT INTO networks (network_id, network_name, owner_id) VALUES ('default', ?1, ?2)", [`legacy-default-${stamp}`, memberUserId]);
+    const res = await del("default", adminToken);
+    expect(res.status).toBe(409);
+    expect(((await res.json()) as any).error).toContain("default");
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = 'default'")).toBeTruthy();
+  });
+
+  test("a non-admin user cannot delete someone else's network", async () => {
+    const res = await del(adminNetworkId, memberToken);
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as any).error).toBe("not your network");
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = ?1", adminNetworkId)).toBeTruthy();
+  });
+
+  test("a node token is refused with user_token_required", async () => {
+    const netId = memberNetwork("ntok");
+    const res = await del(netId, memberNodeToken);
+    expect(res.status).toBe(403);
+    expect(((await res.json()) as any).error).toBe("user_token_required");
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = ?1", netId)).toBeTruthy();
+  });
+
+  test("owner path is unchanged: owner deletes own network (even with a node row), sessions still block it", async () => {
+    const withNode = memberNetwork("owner-node");
+    db.run("INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at) VALUES (?1, ?2, ?2, ?3, datetime('now'), datetime('now'))",
+      [`owner-node-${stamp}`, `owner-node-${stamp}`, withNode]);
+    const ok = await del(withNode, memberToken);
+    expect(ok.status).toBe(200);
+    expect(await ok.json()).toEqual({ ok: true });
+
+    const withSession = memberNetwork("owner-session");
+    db.run("INSERT INTO sessions (resume_id, alias, network_id) VALUES (?1, ?2, ?3)", [`owner-resume-${stamp}`, `owner-s-${stamp}`, withSession]);
+    const blocked = await del(withSession, memberToken);
+    expect(blocked.status).toBe(400);
+    expect(((await blocked.json()) as any).error).toContain("active session");
+  });
+
+  test("admin deleting its OWN network goes through the owner path (no admin_override)", async () => {
+    const created = auth.createNetwork(adminUserId, `admin-own-${stamp}`);
+    expect(created.ok).toBe(true);
+    const res = await del(created.network_id!, adminToken);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+  });
+});

package/src/agent-access.ts

@@ -93,7 +93,10 @@ export function visibleAgents(userId: string, networkId: string): VisibleAgents
   const nodeIds = new Set<string>();
   const messageAliases = new Set<string>();
   const messageNodeIds = new Set<string>();
-  for (const grant of listAgentGrants(networkId, userId)) {
+  // RFC-038 §8:组授权展开成「该组此刻的成员节点」—— 每次现算,组里新加的节点下一次请求就可见。
+  // 只并同网络、且 nodes 表里还在的节点;可对话取并集(直接授权或任一组给了就算)。
+  const grants: AgentGrant[] = [...listAgentGrants(networkId, userId), ...groupGrantNodes(networkId, userId)];
+  for (const grant of grants) {
     const grantAliases: string[] = [];
     if (grant.node_id) {
       nodeIds.add(grant.node_id);
@@ -121,6 +124,162 @@ export function visibleAgents(userId: string, networkId: string): VisibleAgents
   };
 }
 
+// ══════════════ Agent 分组(RFC-038 §8) ══════════════
+
+export type AgentGroupGrant = { group_id: string; name: string; can_message: boolean };
+export type AgentGroup = { group_id: string; network_id: string; name: string; description: string | null; node_ids: string[]; member_count: number; granted_user_count: number; created_at: string; updated_at: string | null };
+
+/** 该成员被授权的组,展开成节点级授权(只取同网络、仍存在的节点)。 */
+function groupGrantNodes(networkId: string, userId: string): AgentGrant[] {
+  return db.all<{ node_id: string; can_message: number }>(
+    `SELECT m.node_id, g.can_message
+       FROM network_member_group_grants g
+       JOIN agent_groups ag ON ag.group_id = g.group_id AND ag.network_id = g.network_id
+       JOIN agent_group_members m ON m.group_id = g.group_id
+       JOIN nodes n ON n.node_id = m.node_id AND n.network_id = g.network_id
+      WHERE g.network_id = ?1 AND g.user_id = ?2`,
+    networkId, userId,
+  ).map((row) => ({ node_id: row.node_id, alias: null, can_message: row.can_message === 1 }));
+}
+
+export function listGroupGrants(networkId: string, userId: string): AgentGroupGrant[] {
+  return db.all<{ group_id: string; name: string; can_message: number }>(
+    `SELECT g.group_id, ag.name, g.can_message
+       FROM network_member_group_grants g JOIN agent_groups ag ON ag.group_id = g.group_id
+      WHERE g.network_id = ?1 AND g.user_id = ?2 ORDER BY ag.name`,
+    networkId, userId,
+  ).map((row) => ({ group_id: row.group_id, name: row.name, can_message: row.can_message === 1 }));
+}
+
+export function listAgentGroups(networkId: string): AgentGroup[] {
+  const groups = db.all<{ group_id: string; network_id: string; name: string; description: string | null; created_at: string; updated_at: string | null }>(
+    "SELECT group_id, network_id, name, description, created_at, updated_at FROM agent_groups WHERE network_id = ?1 ORDER BY name",
+    networkId,
+  );
+  return groups.map((g) => {
+    const nodeIds = db.all<{ node_id: string }>(
+      `SELECT m.node_id FROM agent_group_members m JOIN nodes n ON n.node_id = m.node_id AND n.network_id = ?2
+        WHERE m.group_id = ?1 ORDER BY m.node_id`,
+      g.group_id, networkId,
+    ).map((row) => row.node_id);
+    const granted = db.get<{ c: number }>("SELECT COUNT(*) AS c FROM network_member_group_grants WHERE group_id = ?1", g.group_id)?.c ?? 0;
+    return { ...g, node_ids: nodeIds, member_count: nodeIds.length, granted_user_count: granted };
+  });
+}
+
+export function getAgentGroup(networkId: string, groupId: string): AgentGroup | null {
+  return listAgentGroups(networkId).find((g) => g.group_id === groupId) ?? null;
+}
+
+/** 这个组上有授权的成员(组变化时要断开他们的实时流,让其按新权限重连)。 */
+export function usersGrantedGroup(groupId: string): string[] {
+  return db.all<{ user_id: string }>("SELECT user_id FROM network_member_group_grants WHERE group_id = ?1", groupId).map((r) => r.user_id);
+}
+
+const MAX_GROUP_NAME = 64;
+const MAX_GROUP_MEMBERS = 1000;
+
+export type GroupResult = { ok: true; group: AgentGroup } | { ok: false; error: string; status: number; detail?: unknown };
+
+function normalizeName(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+  const name = raw.trim();
+  if (!name || name.length > MAX_GROUP_NAME) return null;
+  return name;
+}
+
+/** node_ids 必须都是本网络里存在的节点;任何一个不合格 ⇒ 整批拒绝。去重。 */
+function validateNodeIds(networkId: string, raw: unknown): { ok: true; ids: string[] } | { ok: false; error: string; status: number; detail?: unknown } {
+  if (!Array.isArray(raw)) return { ok: false, error: "node_ids_must_be_array", status: 400 };
+  if (raw.length > MAX_GROUP_MEMBERS) return { ok: false, error: "too_many_members", status: 400, detail: { limit: MAX_GROUP_MEMBERS } };
+  const ids: string[] = [];
+  const seen = new Set<string>();
+  for (const [index, item] of raw.entries()) {
+    const id = typeof item === "string" ? item.trim() : "";
+    if (!id) return { ok: false, error: "invalid_node_id", status: 400, detail: { index } };
+    if (!db.get("SELECT 1 FROM nodes WHERE node_id = ?1 AND network_id = ?2", id, networkId)) {
+      return { ok: false, error: "agent_not_in_network", status: 400, detail: { index, node_id: id } };
+    }
+    if (!seen.has(id)) { seen.add(id); ids.push(id); }
+  }
+  return { ok: true, ids };
+}
+
+export function createAgentGroup(input: { networkId: string; name: unknown; description?: unknown; nodeIds?: unknown; actorUserId: string }): GroupResult {
+  const name = normalizeName(input.name);
+  if (!name) return { ok: false, error: "invalid_group_name", status: 400, detail: { max_length: MAX_GROUP_NAME } };
+  if (db.get("SELECT 1 FROM agent_groups WHERE network_id = ?1 AND name = ?2", input.networkId, name)) {
+    return { ok: false, error: "group_name_taken", status: 409 };
+  }
+  let ids: string[] = [];
+  if (input.nodeIds !== undefined) {
+    const v = validateNodeIds(input.networkId, input.nodeIds);
+    if (!v.ok) return v;
+    ids = v.ids;
+  }
+  const description = typeof input.description === "string" ? input.description.trim().slice(0, 500) || null : null;
+  const groupId = `agrp_${crypto.randomUUID().replace(/-/g, "")}`;
+  db.transaction(() => {
+    db.run("INSERT INTO agent_groups (group_id, network_id, name, description, created_by) VALUES (?1, ?2, ?3, ?4, ?5)",
+      [groupId, input.networkId, name, description, input.actorUserId]);
+    for (const id of ids) db.run("INSERT INTO agent_group_members (group_id, node_id, added_by) VALUES (?1, ?2, ?3)", [groupId, id, input.actorUserId]);
+  });
+  return { ok: true, group: getAgentGroup(input.networkId, groupId)! };
+}
+
+export function updateAgentGroup(input: { networkId: string; groupId: string; name?: unknown; description?: unknown }): GroupResult {
+  if (!db.get("SELECT 1 FROM agent_groups WHERE group_id = ?1 AND network_id = ?2", input.groupId, input.networkId)) {
+    return { ok: false, error: "group_not_found", status: 404 };
+  }
+  if (input.name !== undefined) {
+    const name = normalizeName(input.name);
+    if (!name) return { ok: false, error: "invalid_group_name", status: 400, detail: { max_length: MAX_GROUP_NAME } };
+    if (db.get("SELECT 1 FROM agent_groups WHERE network_id = ?1 AND name = ?2 AND group_id != ?3", input.networkId, name, input.groupId)) {
+      return { ok: false, error: "group_name_taken", status: 409 };
+    }
+    db.run("UPDATE agent_groups SET name = ?1, updated_at = datetime('now') WHERE group_id = ?2", [name, input.groupId]);
+  }
+  if (input.description !== undefined) {
+    const description = typeof input.description === "string" ? input.description.trim().slice(0, 500) || null : null;
+    db.run("UPDATE agent_groups SET description = ?1, updated_at = datetime('now') WHERE group_id = ?2", [description, input.groupId]);
+  }
+  return { ok: true, group: getAgentGroup(input.networkId, input.groupId)! };
+}
+
+/** 整体替换组成员;返回增删 diff(审计只记 diff)。 */
+export function replaceAgentGroupMembers(input: { networkId: string; groupId: string; nodeIds: unknown; actorUserId: string }):
+  { ok: true; group: AgentGroup; added: string[]; removed: string[] } | { ok: false; error: string; status: number; detail?: unknown } {
+  if (!db.get("SELECT 1 FROM agent_groups WHERE group_id = ?1 AND network_id = ?2", input.groupId, input.networkId)) {
+    return { ok: false, error: "group_not_found", status: 404 };
+  }
+  const v = validateNodeIds(input.networkId, input.nodeIds);
+  if (!v.ok) return v;
+  const before = new Set(db.all<{ node_id: string }>("SELECT node_id FROM agent_group_members WHERE group_id = ?1", input.groupId).map((r) => r.node_id));
+  const after = new Set(v.ids);
+  const added = v.ids.filter((id) => !before.has(id));
+  const removed = [...before].filter((id) => !after.has(id));
+  db.transaction(() => {
+    for (const id of removed) db.run("DELETE FROM agent_group_members WHERE group_id = ?1 AND node_id = ?2", [input.groupId, id]);
+    for (const id of added) db.run("INSERT INTO agent_group_members (group_id, node_id, added_by) VALUES (?1, ?2, ?3)", [input.groupId, id, input.actorUserId]);
+    db.run("UPDATE agent_groups SET updated_at = datetime('now') WHERE group_id = ?1", [input.groupId]);
+  });
+  return { ok: true, group: getAgentGroup(input.networkId, input.groupId)!, added, removed };
+}
+
+/** 删组:连同组成员与组上的全部授权。返回受影响的成员(调用方断开其实时流、写审计)。 */
+export function deleteAgentGroup(networkId: string, groupId: string): { ok: true; affected_user_ids: string[] } | { ok: false; error: string; status: number } {
+  if (!db.get("SELECT 1 FROM agent_groups WHERE group_id = ?1 AND network_id = ?2", groupId, networkId)) {
+    return { ok: false, error: "group_not_found", status: 404 };
+  }
+  const affected = usersGrantedGroup(groupId);
+  db.transaction(() => {
+    db.run("DELETE FROM network_member_group_grants WHERE group_id = ?1", [groupId]);
+    db.run("DELETE FROM agent_group_members WHERE group_id = ?1", [groupId]);
+    db.run("DELETE FROM agent_groups WHERE group_id = ?1", [groupId]);
+  });
+  return { ok: true, affected_user_ids: affected };
+}
+
 /** 这个用户名在该网络里是否同时是某个 Agent 的 alias(sessions 或 nodes)。 */
 export function usernameIsAgentAlias(networkId: string, username: string): boolean {
   if (!username) return false;
@@ -155,7 +314,7 @@ export function canMessageAgent(userId: string, networkId: string | null | undef
 export type AgentGrantInput = { node_id?: unknown; alias?: unknown; can_message?: unknown };
 
 export type ReplaceGrantsResult =
-  | { ok: true; agent_access: AgentAccessMode; grants: AgentGrant[] }
+  | { ok: true; agent_access: AgentAccessMode; grants: AgentGrant[]; group_grants: AgentGroupGrant[] }
   | { ok: false; error: string; status: number; detail?: unknown };
 
 const MAX_GRANTS = 1000;
@@ -169,6 +328,8 @@ export function replaceAgentGrants(input: {
   userId: string;
   grants: unknown;
   agentAccess?: unknown;
+  /** RFC-038 §8:组授权。undefined = 保持原样(旧 app 的 PUT 不带它,不能把组授权清掉)。 */
+  groupGrants?: unknown;
   actorUserId: string;
 }): ReplaceGrantsResult {
   const member = db.get<{ role: string }>(
@@ -215,7 +376,38 @@ export function replaceAgentGrants(input: {
     }
   }
 
+  let groupRows: Array<{ group_id: string; can_message: number }> | undefined;
+  if (input.groupGrants !== undefined) {
+    if (!Array.isArray(input.groupGrants)) return { ok: false, error: "group_grants_must_be_array", status: 400 };
+    if (input.groupGrants.length > MAX_GRANTS) return { ok: false, error: "too_many_grants", status: 400, detail: { limit: MAX_GRANTS } };
+    const seenGroups = new Set<string>();
+    groupRows = [];
+    for (const [index, raw] of input.groupGrants.entries()) {
+      const item = typeof raw === "string" ? { group_id: raw } : (raw && typeof raw === "object" && !Array.isArray(raw) ? raw as { group_id?: unknown; can_message?: unknown } : {});
+      const groupId = typeof item.group_id === "string" ? item.group_id.trim() : "";
+      if (!groupId) return { ok: false, error: "group_grant_needs_group_id", status: 400, detail: { index } };
+      if (item.can_message !== undefined && typeof item.can_message !== "boolean") {
+        return { ok: false, error: "can_message_must_be_boolean", status: 400, detail: { index } };
+      }
+      if (!db.get("SELECT 1 FROM agent_groups WHERE group_id = ?1 AND network_id = ?2", groupId, input.networkId)) {
+        return { ok: false, error: "group_not_in_network", status: 400, detail: { index, group_id: groupId } };
+      }
+      if (seenGroups.has(groupId)) continue;
+      seenGroups.add(groupId);
+      groupRows.push({ group_id: groupId, can_message: item.can_message === false ? 0 : 1 });
+    }
+  }
+
   db.transaction(() => {
+    if (groupRows) {
+      db.run("DELETE FROM network_member_group_grants WHERE network_id = ?1 AND user_id = ?2", [input.networkId, input.userId]);
+      for (const row of groupRows) {
+        db.run(
+          `INSERT INTO network_member_group_grants (network_id, user_id, group_id, can_message, created_by) VALUES (?1, ?2, ?3, ?4, ?5)`,
+          [input.networkId, input.userId, row.group_id, row.can_message, input.actorUserId],
+        );
+      }
+    }
     if (mode) {
       db.run("UPDATE network_members SET agent_access = ?1 WHERE network_id = ?2 AND user_id = ?3", [mode, input.networkId, input.userId]);
     }
@@ -235,12 +427,14 @@ export function replaceAgentGrants(input: {
     ok: true,
     agent_access: getAgentAccessMode(input.networkId, input.userId) ?? "granted",
     grants: listAgentGrants(input.networkId, input.userId),
+    group_grants: listGroupGrants(input.networkId, input.userId),
   };
 }
 
 /** 成员被移出网络时一并清掉授权,重新加入时从零开始。 */
 export function deleteAgentGrants(networkId: string, userId: string): void {
   db.run("DELETE FROM network_member_agent_grants WHERE network_id = ?1 AND user_id = ?2", [networkId, userId]);
+  db.run("DELETE FROM network_member_group_grants WHERE network_id = ?1 AND user_id = ?2", [networkId, userId]);
 }
 
 // 多用户 Agent 权限 —— 受限成员(只看授权 Agent 的成员)能调的 MCP 工具。每一个都逐条审过: