@sleep2agi/commhub-server 0.9.0-preview.67 → 0.9.0-preview.68

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

@@ -0,0 +1,267 @@
+// 多用户账号与 Agent 权限 —— slice 3:剩下的面向 Agent 的路径。
+//
+// slice 1(agent-acl-http.test.ts)把默认作用域做成 fail-closed,并对核心路径逐条放行。
+// 这里补:授权后 task_events / messages 的「只看自己往来」、改名广播不外泄 alias、
+// 排程在建的人被收权后不再代派、用户名与后注册的 Agent alias 撞名、以及
+// rules / skills / files / logs 对受限成员(即使授权了)仍然拒绝 —— 这是一个明确的产品决定:
+// 授权 = 能看见、能对话;不等于能管理这个 Agent。
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, addNetworkMember } from "./auth.js";
+import { db } from "./db.js";
+import { replaceAgentGrants } from "./agent-access.js";
+import { dispatchScheduledOccurrence } from "./scheduled-tasks.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-agent-acl3-"));
+let BASE = "";
+let hub: any = null;
+const PW = "AclSlice3Passw0rd!";
+let adminToken = "", adminId = "", adminName = "", NET = "";
+let carolToken = "", carolId = "";
+
+const X = { alias: "acl3-agent-x", node: "node_acl3_x" };
+const Z = { alias: "acl3-agent-z", node: "node_acl3_z" };
+const auth = (t: string) => ({ Authorization: `Bearer ${t}` });
+
+async function get(token: string, path: string) {
+  const res = await fetch(`${BASE}${path}`, { headers: auth(token) });
+  return { status: res.status, body: await res.json().catch(() => null) as any };
+}
+async function send(token: string, method: string, path: string, payload?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: { ...auth(token), "Content-Type": "application/json" }, body: payload === undefined ? undefined : JSON.stringify(payload) });
+  return { status: res.status, body: await res.json().catch(() => null) as any };
+}
+async function tool(token: string, name: string, args: Record<string, unknown>) {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { ...auth(token), "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const data = raw.split("\n").filter(x => x.startsWith("data:"));
+  const payload = data.length ? JSON.parse(data.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  const text = payload.result.content[0].text;
+  // 参数没过 zod 的调用根本没进到处理函数(也就没进到权限判定),当成测试写错了而不是「被拒」。
+  if (!text.startsWith("{")) throw new Error(`${name}: ${text}`);
+  return JSON.parse(text);
+}
+function seedAgent(a: { alias: string; node: string }) {
+  db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id) VALUES (?1, ?2, ?2, ?3, ?4)`, [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'))`, [`r_${a.node}`, a.alias, a.node, NET]);
+}
+function seedTask(id: string, from: string, to: string, content: string) {
+  db.run(`INSERT INTO tasks (task_id, from_name, to_name, status, content, network_id) VALUES (?1, ?2, ?3, 'replied', ?4, ?5)`, [id, from, to, content, NET]);
+  db.run(`INSERT INTO inbox (id, task_id, session_name, type, priority, content, from_session, network_id) VALUES (?1, ?2, ?3, 'task', 'normal', ?4, ?5, ?6)`, [`ib_${id}`, id, to, content, from, NET]);
+  db.run(`INSERT INTO task_events (task_id, to_status, actor, network_id) VALUES (?1, 'replied', 'test', ?2)`, [id, NET]);
+}
+async function openStream(path: string, token: string) {
+  const ctrl = new AbortController();
+  const res = await fetch(`${BASE}${path}`, { headers: auth(token), signal: ctrl.signal });
+  const reader = res.body!.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  let pending: ReturnType<typeof reader.read> | null = null;
+  const readFor = async (ms: number) => {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+      pending ??= reader.read();
+      const chunk = await Promise.race([pending, new Promise<null>(r => setTimeout(() => r(null), until - Date.now()))]);
+      if (!chunk) break;
+      pending = null;
+      if (chunk.done) break;
+      buf += decoder.decode(chunk.value);
+    }
+  };
+  return { status: res.status, readFor, events: () => buf.split("\n").filter(l => l.startsWith("data:")).map(l => JSON.parse(l.slice(5))), close: () => ctrl.abort() };
+}
+
+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";
+  adminName = `acl3_admin_${Date.now()}`;
+  const admin = register(adminName, PW);
+  adminToken = admin.token!; adminId = admin.user!.user_id; NET = admin.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [adminId]);
+  seedAgent(X); seedAgent(Z);
+  const carol = register("acl3_carol", PW);
+  carolToken = carol.token!; carolId = carol.user!.user_id;
+  expect(addNetworkMember(NET, carolId, "member", adminId).ok).toBe(true);
+  expect(replaceAgentGrants({ networkId: NET, userId: carolId, grants: [{ node_id: X.node }], actorUserId: adminId }).ok).toBe(true);
+  seedTask("t3_admin_x", adminName, X.alias, "admin to X");
+  seedTask("t3_carol_x", "acl3_carol", X.alias, "carol to X");
+  seedTask("t3_x_carol", X.alias, "acl3_carol", "X to carol");
+  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}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("granted member: task_events and messages are limited to own traffic", () => {
+  test("task_events: own exchange with X visible, admin's task to X not", async () => {
+    const mine = await get(carolToken, `/api/task_events?task_id=t3_carol_x`);
+    expect(mine.body.events.length).toBe(1);
+    expect((await get(carolToken, `/api/task_events?task_id=t3_x_carol`)).body.events.length).toBe(1);
+    expect((await get(carolToken, `/api/task_events?task_id=t3_admin_x`)).body.events).toEqual([]);
+    const all = await get(carolToken, `/api/task_events?network_id=${NET}`);
+    expect(all.body.events.map((e: any) => e.task_id).sort()).toEqual(["t3_carol_x", "t3_x_carol"]);
+  });
+  test("messages (alias branch): own inbox rows with X only; admin's never", async () => {
+    const r = await get(carolToken, `/api/messages?network_id=${NET}&since=2000-01-01`);
+    expect(r.body.messages.map((m: any) => m.content).sort()).toEqual(["X to carol", "carol to X"].sort());
+    const x = await get(carolToken, `/api/messages?alias=${X.alias}&since=2000-01-01`);
+    expect(x.body.messages.map((m: any) => m.content)).toEqual(["carol to X"]);
+    expect(x.body.pending_count).toBe(1);
+  });
+});
+
+describe("decision: granted ≠ administer — rules / skills / files / logs / config stay refused", () => {
+  test("every read and write admin op on the GRANTED agent is refused", async () => {
+    for (const [name, args] of [
+      ["read_node_rules_file", { alias: X.alias, network_id: NET }],
+      ["write_node_rules_file", { alias: X.alias, content: "x", network_id: NET }],
+      ["list_node_skills", { alias: X.alias, network_id: NET }],
+      ["list_node_files", { alias: X.alias, network_id: NET }],
+      ["tail_node_logs", { alias: X.alias, network_id: NET }],
+      ["update_node_config", { node_id: X.node, base_revision: 0, patch: { model: "m" }, network_id: NET }],
+      ["restart_node", { node_id: X.node, network_id: NET }],
+    ] as const) {
+      expect((await tool(carolToken, name, args as any)).error).toBe("agent_access_restricted");
+    }
+    expect((await send(carolToken, "PUT", `/api/nodes/${X.node}/attrs?network_id=${NET}`, { display_name: "pwned" })).status).toBeGreaterThanOrEqual(403);
+    expect(db.get<{ display_name: string | null }>("SELECT display_name FROM nodes WHERE node_id = ?1", X.node)?.display_name ?? null).toBeNull();
+  });
+});
+
+describe("rename broadcast does not leak aliases to restricted members", () => {
+  test("renaming Z (not granted) sends nothing to carol; renaming X (granted) does", async () => {
+    const s = await openStream(`/events/acl3_carol?network_id=${NET}`, carolToken);
+    expect(s.status).toBe(200);
+    await s.readFor(100);
+    const renameTo = async (oldAlias: string, newAlias: string) => {
+      const p = await send(adminToken, "POST", "/api/node-rename/prepare", { network_id: NET, old_alias: oldAlias, new_alias: newAlias });
+      expect(p.body.ok).toBe(true);
+      expect((await send(adminToken, "POST", "/api/node-rename/commit", { txn_id: p.body.txn_id })).body.ok).toBe(true);
+    };
+    await renameTo(Z.alias, "acl3-agent-z2");
+    await renameTo(X.alias, "acl3-agent-x2");
+    await s.readFor(400);
+    s.close();
+    const renamed = s.events().filter(e => e.type === "node.renamed").map(e => e.data.new_alias);
+    expect(renamed).toEqual(["acl3-agent-x2"]);
+    // 改名后授权(按 node_id)仍然有效。
+    expect((await get(carolToken, `/api/status?network_id=${NET}`)).body.sessions.map((r: any) => r.alias)).toEqual(["acl3-agent-x2"]);
+    await renameTo("acl3-agent-z2", Z.alias);
+    await renameTo("acl3-agent-x2", X.alias);
+  });
+});
+
+describe("schedules created before a restriction stop dispatching", () => {
+  function schedule(createdBy: string, target: { alias: string; node: string }) {
+    const id = `sched_acl3_${createdBy}_${target.node}`;
+    db.run(
+      `INSERT INTO scheduled_tasks (schedule_id, network_id, created_by, name, target_node_id, target_alias, task_content, schedule_type, schedule_json, next_run_at)
+       VALUES (?1, ?2, ?3, 'n', ?4, ?5, 'scheduled work', 'interval', '{"type":"interval","minutes":60}', datetime('now'))`,
+      [id, NET, createdBy, target.node, target.alias],
+    );
+    return db.get<any>("SELECT * FROM scheduled_tasks WHERE schedule_id = ?1", id);
+  }
+  test("carol (restricted) → Z (not granted): run fails creator_access_revoked, no task created", () => {
+    const row = schedule(carolId, Z);
+    const r = dispatchScheduledOccurrence(row, new Date().toISOString(), false);
+    expect(r.status).toBe("failed");
+    expect(r.taskId).toBeUndefined();
+    expect(db.get<{ error_code: string }>("SELECT error_code FROM scheduled_task_runs WHERE run_id = ?1", r.runId)?.error_code).toBe("creator_access_revoked");
+  });
+  test("carol → X (granted, can_message): dispatches", () => {
+    const r = dispatchScheduledOccurrence(schedule(carolId, X), new Date(Date.now() + 1000).toISOString(), false);
+    expect(r.taskId).toBeTruthy();
+  });
+  test("owner-created schedules are unaffected", () => {
+    const r = dispatchScheduledOccurrence(schedule(adminId, Z), new Date(Date.now() + 2000).toISOString(), false);
+    expect(r.taskId).toBeTruthy();
+  });
+});
+
+describe("username collides with an agent alias registered later", () => {
+  test("carol's own channel and own traffic close for that network", async () => {
+    expect((await get(carolToken, `/api/tasks?network_id=${NET}`)).body.tasks.length).toBeGreaterThan(0);
+    db.run(`INSERT INTO sessions (resume_id, alias, status, network_id, updated_at, last_seen_at) VALUES ('r_collide', 'acl3_carol', 'idle', ?1, datetime('now'), datetime('now'))`, [NET]);
+    const s = await fetch(`${BASE}/events/acl3_carol?network_id=${NET}`, { headers: auth(carolToken) });
+    expect(s.status).toBe(403);
+    await s.body?.cancel();
+    expect((await get(carolToken, `/api/tasks?network_id=${NET}`)).body.tasks).toEqual([]);
+    expect((await get(carolToken, `/api/messages?network_id=${NET}&since=2000-01-01`)).body.messages).toEqual([]);
+    db.run("DELETE FROM sessions WHERE resume_id = 'r_collide'");
+    expect((await get(carolToken, `/api/tasks?network_id=${NET}`)).body.tasks.length).toBeGreaterThan(0);
+  });
+});
+
+describe("human ↔ human DM (/api/dm): restricted members can talk to people", () => {
+  let daveToken = "", daveId = "";
+  test("carol (restricted) DMs dave; dave sees it in thread + threads + user inbox and replies", async () => {
+    const dave = register("acl3_dave", PW);
+    daveToken = dave.token!; daveId = dave.user!.user_id;
+    expect(addNetworkMember(NET, daveId, "member", adminId).ok).toBe(true);
+    const sent = await send(carolToken, "POST", "/api/dm", { network_id: NET, to_user_id: daveId, message: "hi dave", client_request_id: "c1" });
+    expect(sent.status).toBe(200);
+    expect(sent.body.message.sender_user_id).toBe(carolId);
+    // 重试同一个气泡不产生第二条。
+    expect((await send(carolToken, "POST", "/api/dm", { network_id: NET, to_user_id: daveId, message: "hi dave", client_request_id: "c1" })).body.message.message_id).toBe(sent.body.message.message_id);
+    const threads = await get(daveToken, `/api/dm/threads?network_id=${NET}`);
+    expect(threads.body.threads).toEqual([expect.objectContaining({ other_user_id: carolId, unread: 1 })]);
+    expect((await get(daveToken, `/api/messages?scope=user&network_id=${NET}`)).body.messages.map((m: any) => m.content)).toContain("hi dave");
+    expect((await send(daveToken, "POST", "/api/dm", { network_id: NET, to_username: "acl3_carol", message: "hi carol" })).status).toBe(200);
+    const thread = await get(carolToken, `/api/dm?network_id=${NET}&with=${daveId}`);
+    expect(thread.body.messages.map((m: any) => [m.direction, m.content])).toEqual([["in", "hi carol"], ["out", "hi dave"]]);
+    // 私信不进按 Agent 的未读(发信人不是 Agent)。
+    const inbox = await get(daveToken, `/api/messages?scope=user&network_id=${NET}`);
+    expect(inbox.body.unread_by_agent["acl3_carol"]).toBeUndefined();
+    const daveThread = await get(daveToken, `/api/dm?network_id=${NET}&with=${carolId}`);
+    expect(daveThread.body.messages.map((m: any) => m.direction)).toEqual(["out", "in"]);
+  });
+  test("sender identity comes from the token, not from the body", async () => {
+    await send(carolToken, "POST", "/api/dm", { network_id: NET, to_user_id: daveId, message: "who am i", from: adminName, sender_user_id: adminId });
+    const row = db.get<{ sender_user_id: string; from_session: string }>("SELECT sender_user_id, from_session FROM user_inbox WHERE content = 'who am i'");
+    expect(row).toEqual({ sender_user_id: carolId, from_session: "acl3_carol" });
+  });
+  test("a third party cannot read someone else's thread", async () => {
+    const eve = register("acl3_eve", PW);
+    expect(addNetworkMember(NET, eve.user!.user_id, "member", adminId).ok).toBe(true);
+    // eve 查「她和 dave」的会话:空(carol↔dave 的不会出现)。
+    expect((await get(eve.token!, `/api/dm?network_id=${NET}&with=${daveId}`)).body.messages).toEqual([]);
+    expect((await get(eve.token!, `/api/dm/threads?network_id=${NET}`)).body.threads).toEqual([]);
+  });
+  test("non-members and outsiders are refused; unknown and outside users look the same", async () => {
+    const out = register("acl3_out", PW);
+    expect((await send(out.token!, "POST", "/api/dm", { network_id: NET, to_user_id: daveId, message: "x" })).status).toBe(403);
+    expect((await get(out.token!, `/api/dm/threads?network_id=${NET}`)).status).toBe(403);
+    const a = await send(carolToken, "POST", "/api/dm", { network_id: NET, to_user_id: out.user!.user_id, message: "x" });
+    const b = await send(carolToken, "POST", "/api/dm", { network_id: NET, to_user_id: "u_nobody", message: "x" });
+    expect(a).toEqual(b);
+    expect(a.status).toBe(404);
+  });
+  test("a restricted member cannot smuggle a file they cannot see into a DM", async () => {
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array([1, 2, 3])]), "a.bin");
+    const up = await fetch(`${BASE}/api/upload?network_id=${NET}`, { method: "POST", body: form, headers: auth(adminToken) });
+    const fid = (await up.json()).file_id;
+    const r = await send(carolToken, "POST", "/api/dm", { network_id: NET, to_user_id: daveId, message: "f", attachments: [{ type: "file", file_id: fid }] });
+    expect(r.status).toBe(403);
+    expect(r.body.error).toBe("attachment_not_accessible");
+    // 管理员(不受限)可以附带本网络文件发给 carol;carol 因此能下载它。
+    expect((await send(adminToken, "POST", "/api/dm", { network_id: NET, to_user_id: carolId, message: "file for you", attachments: [{ type: "file", file_id: fid }] })).status).toBe(200);
+    expect((await fetch(`${BASE}/api/files/${fid}`, { headers: auth(carolToken) })).status).toBe(200);
+  });
+  test("node tokens cannot use the DM API", async () => {
+    const r = await fetch(`${BASE}/api/dm/threads?network_id=${NET}`, { headers: { Authorization: "Bearer ntok_x" } });
+    expect(r.status).toBeGreaterThanOrEqual(401);
+  });
+});

package/src/auth.ts

@@ -4,6 +4,7 @@
 import { db, generateId, hashPassword, verifyPassword, hashToken, generateToken, generateUserToken, generateNetworkToken, uuidv4 } from "./db.js";
 import { WEAK_PASSWORDS } from "./password-dict.js";
 import { NETWORK_REST_COLUMNS, NETWORK_REST_SELECT, sqlColumns } from "./rest-projections.js";
+import { deleteAgentGrants, isAgentRestricted } from "./agent-access.js";
 
 // Round-6 A1 hardening — dummy hash for username-enumeration timing
 // close. We compute ONE scrypt hash of a throwaway password and reuse
@@ -60,7 +61,7 @@ function validatePasswordStrength(password: string, label = "password"): string
   return null;
 }
 
-export function register(username: string, password: string, email?: string, displayName?: string): AuthResult {
+export function register(username: string, password: string, email?: string, displayName?: string, opts: { issueTokens?: boolean } = {}): AuthResult {
   if (!username || username.length < 2) return { ok: false, error: "username must be at least 2 characters" };
   if (username.length > 50) return { ok: false, error: "username too long (max 50)" };
   if (!/^[a-zA-Z0-9_\-\u4e00-\u9fff]+$/.test(username)) return { ok: false, error: "username contains invalid characters" };
@@ -120,6 +121,16 @@ export function register(username: string, password: string, email?: string, dis
     [networkId, userId]
   );
 
+  // 管理员代建账号(POST /api/admin/users)时不给管理员发这个用户的令牌:
+  // 令牌只该由用户本人登录时拿到。
+  if (opts.issueTokens === false) {
+    return {
+      ok: true,
+      user: { user_id: userId, username, display_name: displayName || username, email: email || null, role: isFirstUser ? "admin" : "user" },
+      network_id: networkId,
+    };
+  }
+
   // User token (utok_) — not bound to network, for CLI/Dashboard login
   const userToken = generateUserToken();
   const userTokenId = generateId("tok");
@@ -225,6 +236,7 @@ export function createNetworkTokenForNode(userId: string, networkId: string, nod
   // Verify user is a member of this network with write access
   const role = getUserNetworkRole(userId, networkId);
   if (!role || role === "viewer") return { ok: false, error: "no write access to this network" };
+  if (isAgentRestricted(userId, networkId)) return { ok: false, error: "restricted members cannot create network tokens" };
   if (!nodeName || nodeName.length > 200) return { ok: false, error: "invalid_node_name" };
   if (nodeId !== undefined && (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(nodeId))) {
     return { ok: false, error: "invalid_node_id" };
@@ -289,6 +301,11 @@ export function resolveToken(token: string): { user: AuthUser; networkId: string
 
   if (!row) return null;
 
+  // 多用户 Agent 权限:网络令牌(ntok_ / 邀请码令牌)的权限是「这个网络里的一切」,
+  // 受限成员在受限网络里不能持有它 —— 否则拿它就绕过了授权过滤。这里是唯一的解析入口,
+  // 在这里拒绝,所有 REST / MCP / SSE 路径一起生效(含升级前就签发、后来才被设为受限的令牌)。
+  if (row.network_id && isAgentRestricted(row.user_id, row.network_id)) return null;
+
   // Update last_used
   db.run("UPDATE api_tokens SET last_used_at = datetime('now') WHERE token_hash = ?1", [tHash]);
 
@@ -382,6 +399,7 @@ export function createToken(userId: string, name: string, networkId?: string): {
     const role = getUserNetworkRole(userId, networkId);
     if (!role) return { ok: false, error: "not a member of this network" };
     if (role === "viewer") return { ok: false, error: "viewer cannot create full-access network tokens" };
+    if (isAgentRestricted(userId, networkId)) return { ok: false, error: "restricted members cannot create network tokens" };
   }
   const token = generateToken();
   const tokenId = generateId("tok");
@@ -467,22 +485,55 @@ export function resetUserPassword(targetUsername: string, callerIsHubAdmin: bool
 
 export function getNetworkMembers(networkId: string) {
   return db.all<any>(
-    `SELECT nm.user_id, nm.role, nm.joined_at, nm.invited_by, u.username, u.display_name
+    `SELECT nm.user_id, nm.role, nm.joined_at, nm.invited_by, u.username, u.display_name,
+            CASE WHEN u.role = 'admin' OR nm.role IN ('owner', 'admin') OR nm.agent_access = 'all' THEN 'all' ELSE 'granted' END AS agent_access,
+            (SELECT COUNT(*) FROM network_member_agent_grants g WHERE g.network_id = nm.network_id AND g.user_id = nm.user_id) AS agent_grant_count
      FROM network_members nm JOIN users u ON nm.user_id = u.user_id
      WHERE nm.network_id = ?1 ORDER BY nm.joined_at`,
     networkId);
 }
 
+/** 网络里的人类成员(给受限成员也能看的通讯录):只有身份字段,不含角色与授权。 */
+export function getNetworkHumans(networkId: string) {
+  return db.all<{ user_id: string; username: string; display_name: string | null }>(
+    `SELECT u.user_id, u.username, u.display_name
+       FROM network_members nm JOIN users u ON nm.user_id = u.user_id
+      WHERE nm.network_id = ?1 ORDER BY COALESCE(NULLIF(u.display_name, ''), u.username), u.user_id`,
+    networkId);
+}
+
 export function getUserNetworkRole(userId: string, networkId: string): string | null {
   const row = db.get<any>("SELECT role FROM network_members WHERE network_id = ?1 AND user_id = ?2", networkId, userId);
   return row?.role || null;
 }
 
-export function addNetworkMember(networkId: string, userId: string, role: string, invitedBy?: string): { ok: boolean; error?: string } {
+const MEMBER_ROLES = new Set(["admin", "member", "viewer"]);
+
+/**
+ * 用户名与本网络某个 Agent 的 alias 相同时不能入网:用户的私人 SSE 频道、inbox、
+ * 任务往来都按「用户名」寻址,与 alias 撞名会让受限成员收到那个 Agent 的流量。
+ * 只在入网时查(管理员 / 邀请码持有者才触发),不放在公开的 /api/auth/register 上,
+ * 免得注册接口变成 alias 探测器。
+ */
+export function usernameCollidesWithAgent(networkId: string, userId: string): boolean {
+  return !!db.get(
+    `SELECT 1 FROM users u WHERE u.user_id = ?2 AND (
+       EXISTS (SELECT 1 FROM sessions s WHERE s.network_id = ?1 AND s.alias = u.username)
+       OR EXISTS (SELECT 1 FROM nodes n WHERE n.network_id = ?1 AND n.alias = u.username))`,
+    networkId, userId,
+  );
+}
+
+// 新成员默认 agent_access='granted'(零 Agent 权限),owner/admin 角色不看这一列。
+export function addNetworkMember(networkId: string, userId: string, role: string, invitedBy?: string, opts: { agentAccess?: "all" | "granted" } = {}): { ok: boolean; error?: string } {
+  if (!MEMBER_ROLES.has(role)) return { ok: false, error: "invalid role" };
+  const agentAccess = opts.agentAccess === "all" ? "all" : "granted";
+  if (!db.get("SELECT 1 FROM users WHERE user_id = ?1", userId)) return { ok: false, error: "user not found" };
   const existing = db.get<any>("SELECT 1 FROM network_members WHERE network_id = ?1 AND user_id = ?2", networkId, userId);
   if (existing) return { ok: false, error: "user already a member" };
-  db.run("INSERT INTO network_members (network_id, user_id, role, invited_by) VALUES (?1, ?2, ?3, ?4)",
-    [networkId, userId, role, invitedBy || null]);
+  if (usernameCollidesWithAgent(networkId, userId)) return { ok: false, error: "username_collides_with_agent_alias" };
+  db.run("INSERT INTO network_members (network_id, user_id, role, invited_by, agent_access) VALUES (?1, ?2, ?3, ?4, ?5)",
+    [networkId, userId, role, invitedBy || null, agentAccess]);
   return { ok: true };
 }
 
@@ -498,6 +549,7 @@ export function removeNetworkMember(networkId: string, userId: string): { ok: bo
   if (!member) return { ok: false, error: "not a member" };
   if (member.role === "owner") return { ok: false, error: "cannot remove owner" };
   db.run("DELETE FROM network_members WHERE network_id = ?1 AND user_id = ?2", [networkId, userId]);
+  deleteAgentGrants(networkId, userId);
   return { ok: true };
 }
 
@@ -533,10 +585,13 @@ export function joinByInvite(inviteCode: string, userId: string): { ok: boolean;
   // Check not already member
   const existing = db.get<any>("SELECT 1 FROM network_members WHERE network_id = ?1 AND user_id = ?2", invite.network_id, userId);
   if (existing) return { ok: false, error: "already a member of this network" };
+  if (usernameCollidesWithAgent(invite.network_id, userId)) return { ok: false, error: "username_collides_with_agent_alias" };
   // Add member + increment used count
-  db.run("INSERT INTO network_members (network_id, user_id, role, invited_by) VALUES (?1, ?2, ?3, ?4)",
+  db.run("INSERT INTO network_members (network_id, user_id, role, invited_by, agent_access) VALUES (?1, ?2, ?3, ?4, 'granted')",
     [invite.network_id, userId, invite.role, invite.created_by]);
   db.run("UPDATE network_invites SET used_count = used_count + 1 WHERE invite_code = ?1", [inviteCode]);
+  // 受限成员不能持有网络令牌(resolveToken 会拒),别签一个用不了的。
+  if (isAgentRestricted(userId, invite.network_id)) return { ok: true, network_id: invite.network_id, role: invite.role };
   // Auto-create a token for this network
   const token = generateToken();
   const tokenId = generateId("tok");
@@ -548,8 +603,98 @@ export function joinByInvite(inviteCode: string, userId: string): { ok: boolean;
 /** Get all networks a user is a member of (replaces owner-only query) */
 export function getUserAllNetworks(userId: string) {
   return db.all<any>(
-    `SELECT ${sqlColumns(NETWORK_REST_COLUMNS, "n")}, nm.role as member_role
+    `SELECT ${sqlColumns(NETWORK_REST_COLUMNS, "n")}, nm.role as member_role,
+            -- 多用户 Agent 权限:客户端据此显示「还没有被分配任何 Agent,请联系管理员」。
+            CASE WHEN u.role = 'admin' OR nm.role IN ('owner', 'admin') OR nm.agent_access = 'all' THEN 'all' ELSE 'granted' END AS agent_access
      FROM networks n JOIN network_members nm ON n.network_id = nm.network_id
+     JOIN users u ON u.user_id = nm.user_id
      WHERE nm.user_id = ?1 ORDER BY nm.role = 'owner' DESC, n.created_at`,
     userId);
 }
+
+// ══════════════════════════════════════
+//  多用户账号:管理员建号
+// ══════════════════════════════════════
+
+export type AdminCreateUserInput = {
+  username?: unknown;
+  password?: unknown;
+  display_name?: unknown;
+  email?: unknown;
+  network_id?: unknown;
+  role?: unknown;
+};
+
+export type AdminCreateUserResult =
+  | { ok: true; user: AuthUser; network_id: string; membership: { network_id: string; role: string; agent_access: "granted" } | null }
+  | { ok: false; error: string; status: number };
+
+/**
+ * 管理员(或某网络的 owner/admin,限于把人建进自己管的网络)代建账号。
+ * 走 register() 的全部规则(用户名、密码 ≥ 8 且不是弱密码、自动建个人网络),
+ * 但不签发令牌 —— 用户自己登录才拿令牌。
+ * 可选一步把新用户加进 network_id,默认 role=member、agent_access='granted'(零 Agent 权限)。
+ * 建号与入网在同一事务里:入网失败(如用户名与 Agent alias 撞名)时账号也不落库。
+ */
+export function adminCreateUser(input: AdminCreateUserInput, actor: { userId: string; isHubAdmin: boolean }): AdminCreateUserResult {
+  const str = (v: unknown) => (typeof v === "string" ? v.trim() : "");
+  const username = str(input.username);
+  const password = typeof input.password === "string" ? input.password : "";
+  const displayName = str(input.display_name) || undefined;
+  const email = str(input.email) || undefined;
+  const networkId = str(input.network_id) || null;
+  const role = str(input.role) || "member";
+
+  if (networkId) {
+    if (!db.get("SELECT 1 FROM networks WHERE network_id = ?1", networkId)) return { ok: false, error: "network_not_found", status: 404 };
+    if (!MEMBER_ROLES.has(role)) return { ok: false, error: "invalid role", status: 400 };
+    const actorRole = getUserNetworkRole(actor.userId, networkId);
+    if (!actor.isHubAdmin && actorRole !== "owner" && actorRole !== "admin") return { ok: false, error: "owner/admin required", status: 403 };
+    // 网络 admin 不能建出和自己平级的 admin;只有 owner / Hub 管理员可以。
+    if (role === "admin" && !actor.isHubAdmin && actorRole !== "owner") return { ok: false, error: "owner required to add admins", status: 403 };
+  } else if (!actor.isHubAdmin) {
+    return { ok: false, error: "admin required", status: 403 };
+  }
+  // 首个用户会被 register() 自动设成 Hub 管理员;代建路径上永远不会是首个用户(调用者本身就是用户)。
+  // 但仍显式拒绝,防止空库 + 旧令牌之类的边角把代建变成「造管理员」。
+  const userCount = db.get<{ cnt: number }>("SELECT COUNT(*) as cnt FROM users");
+  if (!userCount || userCount.cnt === 0) return { ok: false, error: "bootstrap_via_register", status: 400 };
+
+  class Rollback extends Error { constructor(readonly result: AdminCreateUserResult) { super("rollback"); } }
+  try {
+    return db.transaction(() => {
+      const created = register(username, password, email, displayName, { issueTokens: false });
+      if (!created.ok || !created.user) throw new Rollback({ ok: false, error: created.error || "register_failed", status: 400 });
+      if (!networkId) return { ok: true as const, user: created.user, network_id: created.network_id!, membership: null };
+      const added = addNetworkMember(networkId, created.user.user_id, role, actor.userId);
+      if (!added.ok) throw new Rollback({ ok: false, error: added.error || "add_member_failed", status: added.error === "username_collides_with_agent_alias" ? 409 : 400 });
+      return {
+        ok: true as const,
+        user: created.user,
+        network_id: created.network_id!,
+        membership: { network_id: networkId, role, agent_access: "granted" as const },
+      };
+    });
+  } catch (error) {
+    if (error instanceof Rollback) return error.result;
+    throw error;
+  }
+}
+
+/** Hub 管理员的用户列表:每个用户带上他所在的网络与角色、agent_access。不含密码哈希。 */
+export function listUsersWithMemberships() {
+  const users = db.all<{ user_id: string; username: string; display_name: string | null; email: string | null; role: string; created_at: string }>(
+    "SELECT user_id, username, display_name, email, role, created_at FROM users ORDER BY created_at",
+  );
+  const memberships = db.all<{ user_id: string; network_id: string; network_name: string | null; role: string; agent_access: string | null }>(
+    `SELECT nm.user_id, nm.network_id, n.network_name, nm.role, nm.agent_access
+       FROM network_members nm JOIN networks n ON n.network_id = nm.network_id`,
+  );
+  const byUser = new Map<string, Array<{ network_id: string; network_name: string | null; role: string; agent_access: "all" | "granted" }>>();
+  for (const m of memberships) {
+    const list = byUser.get(m.user_id) ?? [];
+    list.push({ network_id: m.network_id, network_name: m.network_name, role: m.role, agent_access: m.agent_access === "all" ? "all" : "granted" });
+    byUser.set(m.user_id, list);
+  }
+  return users.map((u) => ({ ...u, networks: byUser.get(u.user_id) ?? [] }));
+}

package/src/create-node-workdir.test.ts

@@ -206,7 +206,8 @@ describe("/api/host-supervisors — default_workdir_root visibility", () => {
     if (!m.ok || !m.token) throw new Error("member register failed");
     memberTok = m.token;
     const memberId = login(`wd_member_${sfx}`, pw).user!.user_id;
-    const add = addNetworkMember(restNet, memberId, "member");
+    // 多用户 Agent 权限:新成员默认只看授权 Agent;本测试测的是「完全信任的成员」旧语义,显式 agent_access=all。
+    const add = addNetworkMember(restNet, memberId, "member", undefined, { agentAccess: "all" });
     if (!add.ok) throw new Error("add member failed: " + add.error);
     const { bootServer } = await import("./server.js");
     server = bootServer({ port: 0, hostname: "127.0.0.1" });

package/src/db.ts

@@ -818,6 +818,10 @@ function migrateUserInboxNetworkIdNotNull() {
 migrateUserInboxNetworkIdNotNull();
 // 迁移会 drop 掉旧表上的 idx_user_inbox_user_acked → 重建(IF NOT EXISTS;未迁移时 no-op)。
 db.exec(`CREATE INDEX IF NOT EXISTS idx_user_inbox_user_acked ON user_inbox(user_id, acked, created_at);`);
+// 多用户:人与人私信。sender_user_id 由 Hub 按发信人的**用户令牌**写入(不是客户端填的 from_session),
+// 会话记录按它双向取;Agent / 节点令牌发来的桌面消息这一列为 NULL。
+try { db.exec("ALTER TABLE user_inbox ADD COLUMN sender_user_id TEXT"); } catch {}
+db.exec(`CREATE INDEX IF NOT EXISTS idx_user_inbox_dm ON user_inbox(network_id, user_id, sender_user_id, created_at);`);
 
 db.exec(`
   CREATE INDEX IF NOT EXISTS idx_ncr_daemon_status ON node_create_requests(daemon_node_id, status);
@@ -974,6 +978,7 @@ db.exec(`
 `);
 try { db.exec("ALTER TABLE requirements ADD COLUMN client_id TEXT"); } catch {}
 try { db.exec("ALTER TABLE requirements ADD COLUMN issues_json TEXT"); } catch {}
+try { db.exec("ALTER TABLE requirements ADD COLUMN tags_json TEXT NOT NULL DEFAULT '[]'"); } catch (e: any) { if (!/duplicate column|already exists/i.test(e?.message || "")) throw e; }
 db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_requirements_client ON requirements(network_id, client_id) WHERE client_id IS NOT NULL AND client_id != ''");
 for (const column of ["owner_json TEXT", "participants_json TEXT NOT NULL DEFAULT '[]'", "agent_owner_json TEXT", "description TEXT", "checklist_json TEXT", "project_id TEXT", "external_ref TEXT", "external_url TEXT", "archived INTEGER NOT NULL DEFAULT 0", "created_by_json TEXT", "updated_by_json TEXT", "parent_id TEXT"]) {
   try { db.exec(`ALTER TABLE requirements ADD COLUMN ${column}`); } catch (e: any) { if (!/duplicate column|already exists/i.test(e?.message || "")) throw e; }
@@ -1035,6 +1040,31 @@ db.exec(`
   );
 `);
 
+// ── 多用户账号与 Agent 权限:成员可见哪些 Agent ──
+// network_members.agent_access:
+//   'all'     —— 旧语义:能看到并联系网络里所有 Agent。ALTER 的 DEFAULT 让**升级前已有的**成员行
+//                全部落在这里,生产上已有成员的可见范围不因升级而变。
+//   'granted' —— 只看到 network_member_agent_grants 里给了的 Agent。此后**新加入**的
+//                member/viewer(管理员建号、POST members、邀请码)都以它入库,即默认零权限。
+// owner/admin 角色与 Hub 管理员不看这一列(永远全部可见),判定集中在 agent-access.ts。
+try { db.exec("ALTER TABLE network_members ADD COLUMN agent_access TEXT NOT NULL DEFAULT 'all'"); } catch {}
+// node_id 优先(稳定);alias 只给没有 node_id 的旧会话用。两者恰有其一。
+db.exec(`
+  CREATE TABLE IF NOT EXISTS network_member_agent_grants (
+    network_id   TEXT NOT NULL,
+    user_id      TEXT NOT NULL,
+    node_id      TEXT,
+    alias        TEXT,
+    can_message  INTEGER NOT NULL DEFAULT 1,
+    created_by   TEXT,
+    created_at   TEXT NOT NULL DEFAULT (datetime('now')),
+    CHECK ((node_id IS NULL) <> (alias IS NULL))
+  );
+
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_grants_node ON network_member_agent_grants(network_id, user_id, node_id) WHERE node_id IS NOT NULL;
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_grants_alias ON network_member_agent_grants(network_id, user_id, alias) WHERE alias IS NOT NULL;
+`);
+
 // ── #84: node rename — rename_txn table (RFC-010 §4) ──
 // Single isolated table holding the rename 2PC transaction state. It doubles
 // as the alias_rename_log (RFC §4 risk #5): the audit log of completed renames

package/src/external-schedule-edits-http.test.ts

@@ -67,8 +67,9 @@ beforeAll(async () => {
   const adminId = admin.user!.user_id;
   ownerId = owner.user!.user_id;
   memberId = member.user!.user_id;
-  expect(addNetworkMember(networkId, ownerId, "member", adminId).ok).toBe(true);
-  expect(addNetworkMember(networkId, memberId, "member", adminId).ok).toBe(true);
+  // 多用户 Agent 权限:新成员默认只看授权 Agent;本测试测的是「完全信任的成员」旧语义,显式 agent_access=all。
+  expect(addNetworkMember(networkId, ownerId, "member", adminId, { agentAccess: "all" }).ok).toBe(true);
+  expect(addNetworkMember(networkId, memberId, "member", adminId, { agentAccess: "all" }).ok).toBe(true);
 
   const minted = createNetworkTokenForNode(ownerId, networkId, alias, nodeId);
   expect(minted.ok).toBe(true);

package/src/file-download-authz.test.ts

@@ -104,7 +104,8 @@ if (!userBNetworkId) throw new Error("userB default network not found");
 // Add userA as a member of userB's default network. This is what makes
 // the "same-network non-owner" test cell meaningful — without it, that
 // test would only prove cross-network denial, which is a weaker claim.
-const addMember = addNetworkMember(userBNetworkId, userAUserId, "member", userBUserId);
+// 多用户 Agent 权限:新成员默认只看授权 Agent;本测试测的是「完全信任的成员」旧语义,显式 agent_access=all。
+const addMember = addNetworkMember(userBNetworkId, userAUserId, "member", userBUserId, { agentAccess: "all" });
 if (!addMember.ok) throw new Error(`add userA to userB network failed: ${addMember.error}`);
 
 const { bootServer } = await import("./server.js");

package/src/file-network-scope.test.ts

@@ -108,13 +108,14 @@ const N2 = nonAdminUserB.networkId;
 const N3 = seedUser.networkId;
 const N_FAKE = `net_503fake${STAMP}`;
 
-if (!addNetworkMember(N1, nonAdminUserB.userId, "member", nonAdminUserA.userId).ok) {
+// 多用户 Agent 权限:新成员默认只看授权 Agent;本测试测的是「完全信任的成员」旧语义,显式 agent_access=all。
+if (!addNetworkMember(N1, nonAdminUserB.userId, "member", nonAdminUserA.userId, { agentAccess: "all" }).ok) {
   throw new Error("fixture: userB → N1 member failed");
 }
 // The admin needs write access to N1 to be issued a node ntok_ there
 // (createNetworkTokenForNode refuses non-members and viewers). That
 // token is the D15 probe: a ntok_ ISSUED BY an admin.
-if (!addNetworkMember(N1, adminUser.userId, "member", nonAdminUserA.userId).ok) {
+if (!addNetworkMember(N1, adminUser.userId, "member", nonAdminUserA.userId, { agentAccess: "all" }).ok) {
   throw new Error("fixture: admin → N1 member failed");
 }
 // viewerOnlyUser must hold exactly one network, with role viewer, so the
@@ -122,15 +123,15 @@ if (!addNetworkMember(N1, adminUser.userId, "member", nonAdminUserA.userId).ok)
 // reachable. register() makes everyone owner of a default network, so
 // that membership is dropped here.
 db.run("DELETE FROM network_members WHERE user_id = ?1", [viewerOnlyUser.userId]);
-if (!addNetworkMember(N1, viewerOnlyUser.userId, "viewer", nonAdminUserA.userId).ok) {
+if (!addNetworkMember(N1, viewerOnlyUser.userId, "viewer", nonAdminUserA.userId, { agentAccess: "all" }).ok) {
   throw new Error("fixture: viewerOnly → N1 viewer failed");
 }
 // mixedUser can write in N1 but only read in N2 — U14 asserts that an
 // explicit param pointing at the viewer network is refused.
-if (!addNetworkMember(N1, mixedUser.userId, "member", nonAdminUserA.userId).ok) {
+if (!addNetworkMember(N1, mixedUser.userId, "member", nonAdminUserA.userId, { agentAccess: "all" }).ok) {
   throw new Error("fixture: mixed → N1 member failed");
 }
-if (!addNetworkMember(N2, mixedUser.userId, "viewer", nonAdminUserB.userId).ok) {
+if (!addNetworkMember(N2, mixedUser.userId, "viewer", nonAdminUserB.userId, { agentAccess: "all" }).ok) {
   throw new Error("fixture: mixed → N2 viewer failed");
 }