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

package/src/agent-access.ts

@@ -88,25 +88,45 @@ export function listAgentGrants(networkId: string, userId: string): AgentGrant[]
  * node_id 授权同时带出:nodes 表里这个节点的 alias、sessions 表里同 node_id 的会话 alias
  * (改名后 sessions 先于 nodes 更新的窗口里两者可能不同,两个都算)。都限定在同一网络。
  */
+/** visibleAgents 一次查询里最多放多少个节点 id(绑定参数上限;1000 个授权节点 = 2 次查询)。 */
+export const VISIBLE_AGENTS_CHUNK = 500;
+
 export function visibleAgents(userId: string, networkId: string): VisibleAgents {
   const aliases = new Set<string>();
   const nodeIds = new Set<string>();
   const messageAliases = new Set<string>();
   const messageNodeIds = new Set<string>();
-  for (const grant of listAgentGrants(networkId, userId)) {
-    const grantAliases: string[] = [];
+  // RFC-038 §8:组授权展开成「该组此刻的成员节点」—— 每次现算,组里新加的节点下一次请求就可见。
+  // 只并同网络、且 nodes 表里还在的节点;可对话取并集(直接授权或任一组给了就算)。
+  const grants: AgentGrant[] = [...listAgentGrants(networkId, userId), ...groupGrantNodes(networkId, userId)];
+  // #2133:所有授权节点的 alias 一次查完(原来每个节点单独查一次 nodes ∪ sessions:300 条授权 ≈ 300 次查询,
+  // 而受限成员的每次 /api/status 轮询都走这里)。结果与原实现逐字一致:授权按上面数组的顺序,
+  // 同一节点内的 alias 按 UNION 的去重升序 —— agent-access-batch.test.ts 在随机夹具上逐字比对。
+  // 分块只为绑定参数个数的上限;同一节点的所有 alias 必在同一块里,顺序不受分块影响。
+  const grantedNodeIds = [...new Set(grants.map((grant) => grant.node_id).filter((id): id is string => !!id))];
+  const aliasesByNode = new Map<string, string[]>();
+  for (let start = 0; start < grantedNodeIds.length; start += VISIBLE_AGENTS_CHUNK) {
+    const chunk = grantedNodeIds.slice(start, start + VISIBLE_AGENTS_CHUNK);
+    const inList = chunk.map((_, i) => `?${i + 2}`).join(", ");
+    for (const row of db.all<{ node_id: string; alias: string | null }>(
+      `SELECT node_id, alias FROM nodes WHERE network_id = ?1 AND node_id IN (${inList})
+       UNION SELECT node_id, alias FROM sessions WHERE network_id = ?1 AND node_id IN (${inList})
+       ORDER BY node_id, alias`,
+      networkId, ...chunk,
+    )) {
+      if (!row.alias) continue;
+      const list = aliasesByNode.get(row.node_id);
+      if (list) list.push(row.alias); else aliasesByNode.set(row.node_id, [row.alias]);
+    }
+  }
+  for (const grant of grants) {
+    let grantAliases: readonly string[] = [];
     if (grant.node_id) {
       nodeIds.add(grant.node_id);
       if (grant.can_message) messageNodeIds.add(grant.node_id);
-      for (const row of db.all<{ alias: string | null }>(
-        `SELECT alias FROM nodes WHERE node_id = ?1 AND network_id = ?2
-         UNION SELECT alias FROM sessions WHERE node_id = ?1 AND network_id = ?2`,
-        grant.node_id, networkId,
-      )) {
-        if (row.alias) grantAliases.push(row.alias);
-      }
+      grantAliases = aliasesByNode.get(grant.node_id) ?? [];
     } else if (grant.alias) {
-      grantAliases.push(grant.alias);
+      grantAliases = [grant.alias];
     }
     for (const alias of grantAliases) {
       aliases.add(alias);
@@ -121,6 +141,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 +331,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 +345,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 +393,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 +444,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 工具。每一个都逐条审过:

package/src/agent-acl-groups-http.test.ts

@@ -0,0 +1,247 @@
+// Agent 分组(RFC-038 §8)—— HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。
+//
+// 场景:Hub 管理员 admin 的网络 NET 里有 3 个 Agent(X、Y、Z);受限成员 alice 没有任何直接授权。
+// 正向:组授权 ⇒ 看得见、能派活;往组里加节点 ⇒ 下一次请求就可见(动态);直接授权与组授权取并集。
+// 反向:移出组 ⇒ 403 且与不存在的 alias 逐字节相同;删组 ⇒ 访问消失;跨网络 id ⇒ 400;
+//       节点令牌 / 受限成员碰组接口 ⇒ 403。
+// 兼容:旧 app 形状的 PUT(只带 grants)不动组授权;agent_access='all' 的成员不看组。
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-agent-groups-"));
+let BASE = "";
+let hub: any = null;
+
+const PW = "GroupTestPassw0rd!x";
+let adminToken = "";
+let adminId = "";
+let NET = "";
+let OTHER_NET = "";
+let aliceToken = "";
+let aliceId = "";
+let carolToken = "";
+let carolId = "";
+let nodeToken = "";
+
+const X = { alias: "grp-agent-x", node: "node_grp_x" };
+const Y = { alias: "grp-agent-y", node: "node_grp_y" };
+const Z = { alias: "grp-agent-z", node: "node_grp_z" };
+const FOREIGN = { alias: "grp-agent-foreign", node: "node_grp_foreign" };
+
+const auth = (token: string) => ({ Authorization: `Bearer ${token}` });
+const json = (token: string) => ({ ...auth(token), "Content-Type": "application/json" });
+
+function seedAgent(a: { alias: string; node: string }, net: string) {
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id, updated_at) VALUES (?1, ?2, ?2, ?3, ?4, datetime('now'))`,
+    [a.node, a.alias, net, adminId],
+  );
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, node_id, status, network_id, updated_at, last_seen_at)
+     VALUES (?1, ?2, ?3, 'idle', ?4, datetime('now'), datetime('now'))`,
+    [`resume_${a.node}`, a.alias, a.node, net],
+  );
+}
+
+async function send(token: string, method: string, path: string, payload?: unknown): Promise<{ status: number; body: any; text: string }> {
+  const res = await fetch(`${BASE}${path}`, { method, headers: json(token), body: payload === undefined ? undefined : JSON.stringify(payload) });
+  const text = await res.text();
+  let body: any = null;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body, text };
+}
+const get = (token: string, path: string) => send(token, "GET", path);
+const seen = async (token: string) => {
+  const r = await get(token, `/api/status?network_id=${NET}`);
+  expect(r.status).toBe(200);
+  return (r.body.sessions ?? []).map((s: any) => s.alias).filter((a: string) => a.startsWith("grp-agent-")).sort();
+};
+// 每次内容不同:hub 按内容哈希 5 分钟去重(send_dedup),同样的探针第二次会 429。
+let probeSeq = 0;
+const task = (token: string, alias: string) => send(token, "POST", "/api/task", { alias, task: `probe ${alias} #${++probeSeq}`, network_id: NET });
+const grantsPath = (uid: string) => `/api/networks/${NET}/members/${uid}/agent-grants`;
+const groupsPath = `/api/networks/${"__NET__"}/agent-groups`;
+const gp = (suffix = "") => groupsPath.replace("__NET__", NET) + suffix;
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+
+  const admin = register(`grp_admin_${Date.now()}`, PW, undefined, "Admin");
+  expect(admin.ok).toBe(true);
+  adminToken = admin.token!;
+  adminId = admin.user!.user_id;
+  NET = admin.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [adminId]);
+  for (const a of [X, Y, Z]) seedAgent(a, NET);
+
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+
+  // 另一个网络(admin 也是 owner),放一个外网节点,用来测跨网络 id。
+  const other = await send(adminToken, "POST", "/api/networks", { name: `grp-other-${Date.now()}` });
+  expect(other.status).toBe(200);
+  OTHER_NET = other.body.network_id ?? other.body.network?.network_id;
+  expect(typeof OTHER_NET).toBe("string");
+  seedAgent(FOREIGN, OTHER_NET);
+
+  const mk = async (username: string, agentAccess?: "all") => {
+    const r = await send(adminToken, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" });
+    expect(r.status).toBe(200);
+    const login = await send("", "POST", "/api/auth/login", { username, password: PW });
+    expect(login.status).toBe(200);
+    if (agentAccess) db.run("UPDATE network_members SET agent_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, login.body.user.user_id]);
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  const alice = await mk(`grp_alice_${Date.now()}`);
+  aliceToken = alice.token; aliceId = alice.id;
+  const carol = await mk(`grp_carol_${Date.now()}`, "all");
+  carolToken = carol.token; carolId = carol.id;
+
+  const nt = await send(adminToken, "POST", "/api/auth/node-token", { network_id: NET, node_name: X.alias, node_id: X.node });
+  expect(nt.status).toBe(200);
+  nodeToken = nt.body.token;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+let groupId = "";
+
+describe("Agent 分组:CRUD 与权限", () => {
+  test("owner 建组(带成员);重名 409;外网节点 400 且整批不写", async () => {
+    const r = await send(adminToken, "POST", gp(), { name: "前端组", node_ids: [X.node] });
+    expect(r.status).toBe(200);
+    groupId = r.body.group.group_id;
+    expect(r.body.group.node_ids).toEqual([X.node]);
+    expect((await send(adminToken, "POST", gp(), { name: "前端组" })).status).toBe(409);
+    const bad = await send(adminToken, "POST", gp(), { name: "坏组", node_ids: [Y.node, FOREIGN.node] });
+    expect(bad.status).toBe(400);
+    expect(bad.body.error).toBe("agent_not_in_network");
+    const list = await get(adminToken, gp());
+    expect(list.body.groups.map((g: any) => g.name)).toEqual(["前端组"]);
+  });
+
+  test("受限成员、节点令牌碰组接口 ⇒ 403", async () => {
+    expect((await get(aliceToken, gp())).status).toBe(403);
+    expect((await send(aliceToken, "POST", gp(), { name: "偷偷建" })).status).toBe(403);
+    expect((await get(nodeToken, gp())).status).toBe(403);
+  });
+
+  test("审计:建组写 agent_group_created(带 network_id)", () => {
+    const row = db.get<{ network_id: string; detail: string }>("SELECT network_id, detail FROM audit_log WHERE action = 'agent_group_created' AND target_id = ?1", groupId);
+    expect(row?.network_id).toBe(NET);
+    expect(row?.detail).toContain("前端组");
+  });
+});
+
+describe("组授权:动态生效", () => {
+  test("基线:alice 没有任何授权 ⇒ 看不到、发不了", async () => {
+    expect(await seen(aliceToken)).toEqual([]);
+    expect((await task(aliceToken, X.alias)).status).toBe(403);
+  });
+
+  test("授权给组 ⇒ 看到组里的 X、能派活;GET 回 group_grants", async () => {
+    const put = await send(adminToken, "PUT", grantsPath(aliceId), { group_grants: [{ group_id: groupId, can_message: true }] });
+    expect(put.status).toBe(200);
+    expect(put.body.group_grants).toEqual([{ group_id: groupId, name: "前端组", can_message: true }]);
+    expect(put.body.restricted).toBe(true);
+    expect(await seen(aliceToken)).toEqual([X.alias]);
+    expect((await task(aliceToken, X.alias)).status).toBe(200);
+    expect((await task(aliceToken, Y.alias)).status).toBe(403);
+    const g = await get(adminToken, grantsPath(aliceId));
+    expect(g.body.grants).toEqual([]);
+    expect(g.body.group_grants.length).toBe(1);
+  });
+
+  test("往组里加 Y ⇒ alice 下一次请求就看得见 Y(不用改她的授权)", async () => {
+    const r = await send(adminToken, "PUT", gp(`/${groupId}/members`), { node_ids: [X.node, Y.node] });
+    expect(r.status).toBe(200);
+    expect(r.body.added).toEqual([Y.node]);
+    expect(await seen(aliceToken)).toEqual([X.alias, Y.alias]);
+    expect((await task(aliceToken, Y.alias)).status).toBe(200);
+    const audit = db.get<{ detail: string }>("SELECT detail FROM audit_log WHERE action = 'agent_group_members_changed' AND target_id = ?1 ORDER BY id DESC LIMIT 1", groupId);
+    expect(JSON.parse(audit!.detail)).toEqual({ added: [Y.node], removed: [] });
+  });
+
+  test("从组里移出 Y ⇒ 看不见,派活 403 且与不存在的 alias 逐字节相同", async () => {
+    await send(adminToken, "PUT", gp(`/${groupId}/members`), { node_ids: [X.node] });
+    expect(await seen(aliceToken)).toEqual([X.alias]);
+    const y = await task(aliceToken, Y.alias);
+    const ghost = await task(aliceToken, "grp-agent-does-not-exist");
+    expect(y.status).toBe(403);
+    expect(y.text).toBe(ghost.text);
+  });
+
+  test("直接授权与组授权取并集;可对话任一来源给了就算", async () => {
+    // 组授权只读,Z 直接授权可对话
+    const put = await send(adminToken, "PUT", grantsPath(aliceId), {
+      grants: [{ node_id: Z.node, can_message: true }],
+      group_grants: [{ group_id: groupId, can_message: false }],
+    });
+    expect(put.status).toBe(200);
+    expect(await seen(aliceToken)).toEqual([X.alias, Z.alias]);
+    expect((await task(aliceToken, X.alias)).status).toBe(403);   // 组只读
+    expect((await task(aliceToken, Z.alias)).status).toBe(200);   // 直接可对话
+    // X 再给一条直接可对话授权 ⇒ 并集 ⇒ 可以发
+    await send(adminToken, "PUT", grantsPath(aliceId), { grants: [{ node_id: Z.node, can_message: true }, { node_id: X.node, can_message: true }] });
+    expect((await task(aliceToken, X.alias)).status).toBe(200);
+  });
+
+  test("兼容:旧 app 形状的 PUT(只带 grants,不带 group_grants)不动组授权", async () => {
+    const before = await get(adminToken, grantsPath(aliceId));
+    expect(before.body.group_grants.length).toBe(1);
+    const old = await send(adminToken, "PUT", grantsPath(aliceId), { grants: [{ node_id: Z.node, can_message: true }] });
+    expect(old.status).toBe(200);
+    expect(old.body.group_grants.length).toBe(1);
+    expect(await seen(aliceToken)).toEqual([X.alias, Z.alias]);
+  });
+
+  test("组授权:外网 / 不存在的 group_id ⇒ 400,整批不写", async () => {
+    const other = await send(adminToken, "POST", `/api/networks/${OTHER_NET}/agent-groups`, { name: "外网组" });
+    expect(other.status).toBe(200);
+    const bad = await send(adminToken, "PUT", grantsPath(aliceId), { group_grants: [{ group_id: other.body.group.group_id }] });
+    expect(bad.status).toBe(400);
+    expect(bad.body.error).toBe("group_not_in_network");
+    expect((await get(adminToken, grantsPath(aliceId))).body.group_grants.map((g: any) => g.group_id)).toEqual([groupId]);
+  });
+
+  test("agent_access='all' 的成员不看组:照旧全部可见", async () => {
+    expect(await seen(carolToken)).toEqual([X.alias, Y.alias, Z.alias]);
+  });
+
+  test("成员列表带 agent_group_count", async () => {
+    const r = await get(adminToken, `/api/networks/${NET}/members`);
+    const alice = r.body.members.find((m: any) => m.user_id === aliceId);
+    expect(alice.agent_group_count).toBe(1);
+  });
+
+  test("删组 ⇒ 组授权随之消失,只剩直接授权;响应带受影响成员;审计", async () => {
+    const del = await send(adminToken, "DELETE", gp(`/${groupId}`));
+    expect(del.status).toBe(200);
+    expect(del.body.affected_user_ids).toEqual([aliceId]);
+    expect(await seen(aliceToken)).toEqual([Z.alias]);
+    expect((await task(aliceToken, X.alias)).status).toBe(403);
+    expect((await get(adminToken, grantsPath(aliceId))).body.group_grants).toEqual([]);
+    expect(db.get("SELECT 1 FROM audit_log WHERE action = 'agent_group_deleted' AND target_id = ?1", groupId)).toBeTruthy();
+    expect((await send(adminToken, "DELETE", gp(`/${groupId}`))).status).toBe(404);
+  });
+
+  test("移出网络 ⇒ 组授权一并清掉", async () => {
+    const g2 = await send(adminToken, "POST", gp(), { name: "第二组", node_ids: [Y.node] });
+    await send(adminToken, "PUT", grantsPath(aliceId), { group_grants: [g2.body.group.group_id] });
+    expect(db.get("SELECT 1 FROM network_member_group_grants WHERE user_id = ?1", aliceId)).toBeTruthy();
+    const rm = await send(adminToken, "DELETE", `/api/networks/${NET}/members/${aliceId}`);
+    expect(rm.status).toBe(200);
+    expect(db.get("SELECT 1 FROM network_member_group_grants WHERE user_id = ?1", aliceId)).toBeFalsy();
+  });
+});

package/src/agent-acl-http.test.ts

@@ -368,6 +368,14 @@ describe("requirements: agent references alice cannot see are hidden and protect
     const r = await get(aliceToken, `/api/requirements?network_id=${NET}&agent_owner=node:${Z.node}`);
     expect(r.body.requirements).toEqual([]);
   });
+  test("q= does not match on a hidden agent's name (no 'who owns this card' probe); admin's q= does", async () => {
+    const zName = db.get<{ name: string }>("SELECT COALESCE(NULLIF(display_name,''), NULLIF(alias,''), node_name) AS name FROM nodes WHERE node_id = ?1", Z.node)!.name;
+    const ids = async (token: string, q: string) => (await get(token, `/api/requirements?network_id=${NET}&q=${encodeURIComponent(q)}`)).body.requirements.map((r: any) => r.id);
+    expect(await ids(aliceToken, zName)).not.toContain(reqId);
+    expect(await ids(adminToken, zName)).toContain(reqId);
+    // 看得见的字段照样能搜到(标题)
+    expect(await ids(aliceToken, "card")).toContain(reqId);
+  });
 });
 
 describe("cannot be abused", () => {