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

package/src/auth.ts

@@ -3,6 +3,8 @@
  */
 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
@@ -41,6 +43,7 @@ export interface AuthResult {
   error?: string;
   user?: AuthUser;
   token?: string;           // user token (utok_)
+  token_id?: string;        // api_tokens.token_id of `token` — lets a client tell which row in GET /api/auth/sessions is itself
   network_token?: string;   // network token (ntok_) for default network
   network_id?: string;
   // #261 P0-2 (2026-06-28): true when the logged-in user still has the
@@ -59,7 +62,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; client?: SessionClientInfo } = {}): 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" };
@@ -87,23 +90,54 @@ export function register(username: string, password: string, email?: string, dis
     [userId, username, pwHash, email || null, displayName || username, isFirstUser ? "admin" : "user"]
   );
 
-  // Auto-create default network + add as owner member
+  // Auto-create the user's own network + add as owner member.
+  //
+  // Name it after the user rather than the literal "default". Every
+  // registration used to mint a network called "default", so a hub with N
+  // users showed N identical "default" rows in the Dashboard sidebar with
+  // no way to tell them apart (23 of them on the live hub, 22 empty).
+  // Three CLI call sites (bin/cli.ts debate / demo-social / pr-review) resolve
+  // a network as:
+  //     me.user.default_network_id
+  //       || networks.find(n => n.network_name === "default")
+  //       || networks[0]
+  // Checked against the live hub: GET /api/auth/me returns
+  // {user_id, username, display_name, email, role} — there is no
+  // default_network_id field, and nothing in server/ ever writes one. So the
+  // first term is always undefined and the name lookup is the operative path,
+  // not a fallback.
+  //
+  // After this change that lookup misses for new users and they land on
+  // networks[0]. That still resolves to this network because listNetworks()
+  // is `ORDER BY created_at` ascending (auth.ts:296) and this row is the
+  // user's oldest. Reordering that query would silently point those three
+  // commands at the wrong network.
   const networkId = generateId("net");
   db.run(
     "INSERT INTO networks (network_id, network_name, owner_id, description) VALUES (?1, ?2, ?3, ?4)",
-    [networkId, "default", userId, "Auto-created default network"]
+    [networkId, username, userId, `Auto-created network for ${username}`]
   );
   db.run(
     "INSERT INTO network_members (network_id, user_id, role) VALUES (?1, ?2, 'owner')",
     [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");
   db.run(
-    "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope) VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
-    [userTokenId, hashToken(userToken), userId, null, "user-login", "user"]
+    "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope, client_label, user_agent) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
+    [userTokenId, hashToken(userToken), userId, null, "user-login", "user", cleanClientField(opts.client?.label, 64), cleanClientField(opts.client?.userAgent, 256)]
   );
 
   // Network token (ntok_) — bound to default network, for agent-node
@@ -118,12 +152,13 @@ export function register(username: string, password: string, email?: string, dis
     ok: true,
     user: { user_id: userId, username, display_name: displayName || username, email: email || null, role: isFirstUser ? "admin" : "user" },
     token: userToken,
+    token_id: userTokenId,
     network_token: networkToken,
     network_id: networkId,
   };
 }
 
-export function login(username: string, password: string): AuthResult {
+export function login(username: string, password: string, client: SessionClientInfo = {}): AuthResult {
   const user = db.get<any>(
     "SELECT user_id, username, password_hash, display_name, email, role, must_change_password FROM users WHERE username = ?1",
     username);
@@ -167,8 +202,8 @@ export function login(username: string, password: string): AuthResult {
   const userToken = generateUserToken();
   const tokenId = generateId("tok");
   db.run(
-    "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope) VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
-    [tokenId, hashToken(userToken), user.user_id, null, "user-login", "user"]
+    "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope, client_label, user_agent) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
+    [tokenId, hashToken(userToken), user.user_id, null, "user-login", "user", cleanClientField(client.label, 64), cleanClientField(client.userAgent, 256)]
   );
 
   // Find default network
@@ -184,6 +219,7 @@ export function login(username: string, password: string): AuthResult {
     ok: true,
     user: { user_id: user.user_id, username: user.username, display_name: user.display_name, email: user.email, role: user.role },
     token,
+    token_id: tokenId,
     network_id: networkId,
     // #261 P0-2 — only include field when truthy (back-compat; old clients
     // don't see this field at all unless their account is flagged).
@@ -191,35 +227,141 @@ export function login(username: string, password: string): AuthResult {
   };
 }
 
-/** Create a network-scoped token (ntok_) for a specific node */
-export function createNetworkTokenForNode(userId: string, networkId: string, nodeName: string): { ok: boolean; token?: string; error?: string } {
+/**
+ * Create a network-scoped token (ntok_) for a specific node.
+ *
+ * RFC-036: callers that provide nodeId atomically establish the immutable
+ * node-owner binding before the plaintext token is returned. The 3-argument
+ * legacy form remains available for old clients, but its token has no bound
+ * node id and therefore cannot consume external-schedule edit intents.
+ */
+export function createNetworkTokenForNode(userId: string, networkId: string, nodeName: string, nodeId?: string): { ok: boolean; token?: string; token_id?: string; node_id?: string; error?: string } {
   // 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" };
+  }
   const token = generateNetworkToken();
   const tokenId = generateId("tok");
-  db.run(
-    "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope) VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
-    [tokenId, hashToken(token), userId, networkId, `node:${nodeName}`, "network"]
-  );
-  return { ok: true, token };
+  try {
+    db.transaction(() => {
+      if (nodeId) {
+        const existing = db.get<{ network_id: string | null; owner_user_id: string | null }>(
+          "SELECT network_id, owner_user_id FROM nodes WHERE node_id = ?1",
+          nodeId,
+        );
+        if (existing?.network_id && existing.network_id !== networkId) throw new Error("cross_network_node");
+        // Existing pre-RFC-036 rows have no trustworthy owner anchor. A token
+        // refresh must not turn knowledge of a legacy node_id into ownership.
+        // They remain read-only until a separately authorized migration.
+        if (existing && !existing.owner_user_id) throw new Error("node_owner_unclaimed");
+        if (existing?.owner_user_id && existing.owner_user_id !== userId) throw new Error("node_owner_mismatch");
+        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'))
+           ON CONFLICT(node_id) DO UPDATE SET
+             node_name = COALESCE(nodes.node_name, ?2),
+             alias = COALESCE(nodes.alias, ?2),
+             network_id = COALESCE(nodes.network_id, ?3),
+             owner_user_id = COALESCE(nodes.owner_user_id, ?4),
+             updated_at = datetime('now')`,
+          [nodeId, nodeName, networkId, userId],
+        );
+        if (!existing) {
+          db.run(
+            `INSERT INTO audit_log (user_id, action, target_type, target_id, detail, network_id)
+             VALUES (?1, 'external_schedule.owner_claimed', 'node', ?2, ?3, ?4)`,
+            [userId, nodeId, JSON.stringify({ node_id: nodeId, network_id: networkId }), networkId],
+          );
+        }
+      }
+      db.run(
+        "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope, bound_node_id) VALUES (?1, ?2, ?3, ?4, ?5, 'network', ?6)",
+        [tokenId, hashToken(token), userId, networkId, `node:${nodeName}`, nodeId ?? null],
+      );
+    });
+  } catch (error: any) {
+    const code = String(error?.message || "node_token_create_failed");
+    if (code === "cross_network_node" || code === "node_owner_unclaimed" || code === "node_owner_mismatch") return { ok: false, error: code };
+    throw error;
+  }
+  return { ok: true, token, token_id: tokenId, ...(nodeId ? { node_id: nodeId } : {}) };
+}
+
+// ── 登录会话(login session)令牌 ──
+// 「会话令牌」= scope='user' 且不绑网络的 utok_:登录 / 注册签发的 user-login、改密码后换发的
+// password-change、管理员重置签发的 admin-reset。它们代表「某台设备上的一次登录」,
+// 由 GET /api/auth/sessions 列出、可被「退出其他设备」撤销,并且**闲置 N 天自动过期**(滑动窗口,
+// 以 last_used_at 计,从没用过的以 created_at 计)。
+// 不受影响:POST /api/auth/tokens 显式创建的 API 令牌(scope='full')、节点 / 网络令牌(network_id 非空)。
+// 它们是给脚本和节点长期用的凭据,由各自的管理入口撤销,不该因为一段时间没被用就失效。
+const SESSION_TOKEN_SQL = "scope = 'user' AND network_id IS NULL";
+// last_used_at 最多每小时写一次:每个请求都会解析令牌,原来每次都 UPDATE。
+// 以小时为粒度对一个以天计的闲置窗口没有影响。
+const LAST_USED_WRITE_INTERVAL_SECONDS = 3600;
+
+export type SessionClientInfo = { label?: unknown; userAgent?: unknown };
+
+function cleanClientField(value: unknown, max: number): string | null {
+  if (typeof value !== "string") return null;
+  const cleaned = value.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, max);
+  return cleaned || null;
+}
+
+/** 会话令牌闲置多少天后过期;COMMHUB_SESSION_IDLE_DAYS,默认 30,0 = 关闭闲置过期。每次读,测试可以改。 */
+export function sessionIdleDays(): number {
+  const raw = process.env.COMMHUB_SESSION_IDLE_DAYS;
+  if (raw === undefined || raw.trim() === "") return 30;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : 30;
+}
+
+// datetime('now', ?N) 的偏移参数;PgAdapter 把它译成 NOW() + $N::INTERVAL。
+function idleCutoffOffset(): string | null {
+  const days = sessionIdleDays();
+  return days > 0 ? `-${Math.round(days * 86400)} seconds` : null;
+}
+
+// 已按闲置过期的会话令牌:只有 resolveToken 拒绝之后才查,用来把 401 说清楚是「过期」而不是「无效」。
+export function isExpiredSessionToken(token: string): boolean {
+  const cutoff = idleCutoffOffset();
+  if (!token || !cutoff) return false;
+  const row = db.get<any>(
+    `SELECT token_id FROM api_tokens
+     WHERE token_hash = ?1 AND ${SESSION_TOKEN_SQL} AND revoked_at IS NULL
+       AND COALESCE(last_used_at, created_at) < datetime('now', ?2)`,
+    hashToken(token), cutoff);
+  return !!row;
 }
 
 export function resolveToken(token: string): { user: AuthUser; networkId: string | null; tokenName: string | null; tokenId: string | null } | null {
   const tHash = hashToken(token);
+  const cutoff = idleCutoffOffset();
   const row = db.get<any>(
     `SELECT t.token_id, t.user_id, t.network_id, t.scope, t.name AS token_name,
             u.username, u.display_name, u.email, u.role
      FROM api_tokens t JOIN users u ON t.user_id = u.user_id
      WHERE t.token_hash = ?1
        AND (t.expires_at IS NULL OR t.expires_at > datetime('now'))
-       AND t.revoked_at IS NULL`,
-    tHash);
+       AND t.revoked_at IS NULL${cutoff ? `
+       AND NOT (t.scope = 'user' AND t.network_id IS NULL AND COALESCE(t.last_used_at, t.created_at) < datetime('now', ?2))` : ""}`,
+    ...(cutoff ? [tHash, cutoff] : [tHash]));
 
   if (!row) return null;
 
-  // Update last_used
-  db.run("UPDATE api_tokens SET last_used_at = datetime('now') WHERE token_hash = ?1", [tHash]);
+  // 多用户 Agent 权限:网络令牌(ntok_ / 邀请码令牌)的权限是「这个网络里的一切」,
+  // 受限成员在受限网络里不能持有它 —— 否则拿它就绕过了授权过滤。这里是唯一的解析入口,
+  // 在这里拒绝,所有 REST / MCP / SSE 路径一起生效(含升级前就签发、后来才被设为受限的令牌)。
+  if (row.network_id && isAgentRestricted(row.user_id, row.network_id)) return null;
+
+  // Update last_used(节流:见 LAST_USED_WRITE_INTERVAL_SECONDS)
+  db.run(
+    "UPDATE api_tokens SET last_used_at = datetime('now') WHERE token_id = ?1 AND (last_used_at IS NULL OR last_used_at < datetime('now', ?2))",
+    [row.token_id, `-${LAST_USED_WRITE_INTERVAL_SECONDS} seconds`]
+  );
 
   return {
     user: { user_id: row.user_id, username: row.username, display_name: row.display_name, email: row.email, role: row.role },
@@ -235,7 +377,7 @@ export function resolveToken(token: string): { user: AuthUser; networkId: string
 
 export function getUserNetworks(userId: string) {
   return db.all<any>(
-    "SELECT * FROM networks WHERE owner_id = ?1 ORDER BY created_at",
+    `SELECT ${NETWORK_REST_SELECT} FROM networks WHERE owner_id = ?1 ORDER BY created_at`,
     userId);
 }
 
@@ -280,7 +422,7 @@ export function listTokens(userId: string) {
 }
 
 export function renameNetwork(userId: string, networkId: string, newName: string): { ok: boolean; error?: string } {
-  const net = db.get<any>("SELECT * FROM networks WHERE network_id = ?1", networkId);
+  const net = db.get<any>("SELECT owner_id FROM networks WHERE network_id = ?1", networkId);
   if (!net) return { ok: false, error: "network not found" };
   if (net.owner_id !== userId) return { ok: false, error: "not your network" };
   const dup = db.get<any>("SELECT network_id FROM networks WHERE owner_id = ?1 AND network_name = ?2", userId, newName);
@@ -290,13 +432,18 @@ export function renameNetwork(userId: string, networkId: string, newName: string
 }
 
 export function deleteNetwork(userId: string, networkId: string): { ok: boolean; error?: string } {
-  const net = db.get<any>("SELECT * FROM networks WHERE network_id = ?1", networkId);
+  const net = db.get<any>("SELECT owner_id FROM networks WHERE network_id = ?1", networkId);
   if (!net) return { ok: false, error: "network not found" };
   if (net.owner_id !== userId) return { ok: false, error: "not your network" };
   // Check if any sessions/tasks still reference this network
   const sessions = db.get<{ cnt: number }>("SELECT COUNT(*) as cnt FROM sessions WHERE network_id = ?1", networkId);
   if (sessions && sessions.cnt > 0) return { ok: false, error: `network has ${sessions.cnt} active session(s) — stop them first` };
   db.run("DELETE FROM networks WHERE network_id = ?1 AND owner_id = ?2", [networkId, userId]);
+  // PR #519 codex catch: leaving membership rows behind made deleted
+  // networks count toward getUserNetworkIds — a stale row could flip a
+  // single-network user to "ambiguous" or auto-resolve writes INTO the
+  // deleted network. Remove memberships with the network.
+  db.run("DELETE FROM network_members WHERE network_id = ?1", [networkId]);
   return { ok: true };
 }
 
@@ -306,6 +453,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");
@@ -338,6 +486,47 @@ export function revokeOtherUserTokens(userId: string, exceptTokenId?: string | n
   return result.changes;
 }
 
+export type LoginSession = {
+  token_id: string;
+  name: string;
+  created_at: string;
+  last_used_at: string | null;
+  client_label: string | null;
+  user_agent: string | null;
+  is_current: boolean;
+};
+
+/** 我的登录会话(未过期、未撤销),最近使用的在前。 */
+export function listSessions(userId: string, currentTokenId: string | null): LoginSession[] {
+  const cutoff = idleCutoffOffset();
+  const rows = db.all<any>(
+    `SELECT token_id, name, created_at, last_used_at, client_label, user_agent FROM api_tokens
+     WHERE user_id = ?1 AND ${SESSION_TOKEN_SQL} AND revoked_at IS NULL${cutoff ? `
+       AND COALESCE(last_used_at, created_at) >= datetime('now', ?2)` : ""}
+     ORDER BY COALESCE(last_used_at, created_at) DESC, created_at DESC`,
+    ...(cutoff ? [userId, cutoff] : [userId]));
+  return rows.map((r) => ({
+    token_id: r.token_id,
+    name: r.name,
+    created_at: r.created_at,
+    last_used_at: r.last_used_at ?? null,
+    client_label: r.client_label ?? null,
+    user_agent: r.user_agent ?? null,
+    is_current: !!currentTokenId && r.token_id === currentTokenId,
+  }));
+}
+
+/** 撤销我的一个登录会话;可以是当前这个(= 退出登录)。不是会话令牌(API 令牌 / 节点令牌)时当作不存在。 */
+export function revokeSession(userId: string, tokenId: string): { ok: boolean; error?: string } {
+  const result = db.run(`DELETE FROM api_tokens WHERE token_id = ?1 AND user_id = ?2 AND ${SESSION_TOKEN_SQL}`, [tokenId, userId]);
+  return result.changes > 0 ? { ok: true } : { ok: false, error: "session_not_found" };
+}
+
+/** 退出其他所有设备:撤销我除当前之外的全部登录会话(含已闲置过期的)。API 令牌、节点令牌不动。 */
+export function revokeOtherSessions(userId: string, currentTokenId: string): number {
+  return db.run(`DELETE FROM api_tokens WHERE user_id = ?1 AND ${SESSION_TOKEN_SQL} AND token_id != ?2`, [userId, currentTokenId]).changes;
+}
+
 export function changePassword(userId: string, oldPassword: string, newPassword: string, currentTokenId?: string | null): { ok: boolean; error?: string; revoked?: number } {
   const passwordError = validatePasswordStrength(newPassword, "new password");
   if (passwordError) return { ok: false, error: passwordError };
@@ -391,22 +580,56 @@ 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,
+            (SELECT COUNT(*) FROM network_member_group_grants gg WHERE gg.network_id = nm.network_id AND gg.user_id = nm.user_id) AS agent_group_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 };
 }
 
@@ -422,6 +645,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 };
 }
 
@@ -444,7 +668,10 @@ export function createInvite(networkId: string, createdBy: string, role: string
 }
 
 export function joinByInvite(inviteCode: string, userId: string): { ok: boolean; network_id?: string; role?: string; error?: string } {
-  const invite = db.get<any>("SELECT * FROM network_invites WHERE invite_code = ?1", inviteCode);
+  const invite = db.get<any>(
+    "SELECT invite_code, network_id, role, created_by, max_uses, used_count, expires_at, created_at FROM network_invites WHERE invite_code = ?1",
+    inviteCode,
+  );
   if (!invite) return { ok: false, error: "invalid invite code" };
   if (invite.max_uses > 0 && invite.used_count >= invite.max_uses) return { ok: false, error: "invite code fully used" };
   if (invite.expires_at) {
@@ -454,10 +681,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");
@@ -469,8 +699,172 @@ 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 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) ?? [] }));
+}
+
+// Hub 管理员删**别人的**网络(清理旧测试账号留下的个人网络)。只删空网络:
+// 下面每张表里有一行就拒(409),并把计数原样回给调用方。表是按 schema 里所有带
+// network_id 的表逐个分类的,不是凭记忆 —— 新加一张带 network_id 的表要在这里归一类。
+//   阻断:真实内容,或会在删后重新长出节点的在途请求。
+//   清理:只描述「这个网络」本身的元数据/历史,网络没了它们就悬空。
+//   保留:audit_log(删除记录本身要留下)。
+const NETWORK_CONTENT_CHECKS: Array<[label: string, sql: string]> = [
+  ["nodes", "SELECT COUNT(*) AS cnt FROM nodes WHERE network_id = ?1"],
+  ["sessions", "SELECT COUNT(*) AS cnt FROM sessions WHERE network_id = ?1"],
+  ["tasks", "SELECT COUNT(*) AS cnt FROM tasks WHERE network_id = ?1"],
+  ["inbox", "SELECT COUNT(*) AS cnt FROM inbox WHERE network_id = ?1"],
+  ["user_inbox", "SELECT COUNT(*) AS cnt FROM user_inbox WHERE network_id = ?1"],
+  ["requirements", "SELECT COUNT(*) AS cnt FROM requirements WHERE network_id = ?1"],
+  ["requirement_projects", "SELECT COUNT(*) AS cnt FROM requirement_projects WHERE network_id = ?1"],
+  ["scheduled_tasks", "SELECT COUNT(*) AS cnt FROM scheduled_tasks WHERE network_id = ?1"],
+  ["providers", "SELECT COUNT(*) AS cnt FROM providers WHERE network_id = ?1"],
+  ["network_secrets", "SELECT COUNT(*) AS cnt FROM network_secrets WHERE network_id = ?1"],
+  ["skillhub_skills", "SELECT COUNT(*) AS cnt FROM skillhub_skills WHERE network_id = ?1"],
+  ["side_chats", "SELECT COUNT(*) AS cnt FROM side_chats WHERE network_id = ?1"],
+  ["pending_node_create_requests", "SELECT COUNT(*) AS cnt FROM node_create_requests WHERE network_id = ?1 AND status IN ('pending', 'delivered')"],
+  ["pending_node_start_requests", "SELECT COUNT(*) AS cnt FROM node_start_requests WHERE network_id = ?1 AND status IN ('pending', 'delivered')"],
+];
+const NETWORK_CLEANUP_TABLES = [
+  "network_members", "network_member_agent_grants", "network_invites", "api_tokens",
+  "node_create_requests", "node_start_requests", "node_stop_requests", "node_rules_requests",
+  "node_config_updates", "rename_txn", "probe_results", "agent_telemetry", "completions",
+  "task_events", "task_terminal_events", "scheduled_task_runs", "external_schedule_edits",
+];
+
+function tableExists(name: string): boolean {
+  return db.dialect === "postgres"
+    ? !!db.get("SELECT 1 AS x FROM information_schema.tables WHERE table_name = ?1", name)
+    : !!db.get("SELECT 1 AS x FROM sqlite_master WHERE type = 'table' AND name = ?1", name);
+}
+
+export function countNetworkContents(networkId: string): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const [label, sql] of NETWORK_CONTENT_CHECKS) {
+    const table = sql.match(/FROM (\w+)/)![1];
+    // 按需建表的模块(requirements / side-thread)在没用过的库上可能还没有这张表 —— 那就是 0 行。
+    if (!tableExists(table)) continue;
+    const cnt = db.get<{ cnt: number }>(sql, networkId)?.cnt ?? 0;
+    if (cnt > 0) counts[label] = cnt;
+  }
+  return counts;
+}
+
+export type AdminDeleteNetworkResult =
+  | { ok: true; owner_id: string; network_name: string; cleaned: Record<string, number> }
+  | { ok: false; status: number; error: string; counts?: Record<string, number> };
+
+// extraCounts:库外的内容(上传文件的索引在磁盘上),由调用方数好传进来,和库内计数一起判。
+export function adminDeleteEmptyNetwork(networkId: string, extraCounts: Record<string, number> = {}): AdminDeleteNetworkResult {
+  if (networkId === "default") return { ok: false, status: 409, error: "the default network cannot be deleted" };
+  return db.transaction((): AdminDeleteNetworkResult => {
+    const net = db.get<{ owner_id: string; network_name: string }>("SELECT owner_id, network_name FROM networks WHERE network_id = ?1", networkId);
+    if (!net) return { ok: false, status: 404, error: "network not found" };
+    const counts = { ...countNetworkContents(networkId) };
+    for (const [k, v] of Object.entries(extraCounts)) if (v > 0) counts[k] = v;
+    if (Object.keys(counts).length > 0) {
+      const summary = Object.entries(counts).map(([k, v]) => `${k}=${v}`).join(", ");
+      return { ok: false, status: 409, error: `network is not empty (${summary}); only empty networks can be deleted by a hub admin`, counts };
+    }
+    const cleaned: Record<string, number> = {};
+    for (const table of NETWORK_CLEANUP_TABLES) {
+      if (!tableExists(table)) continue;
+      const changes = db.run(`DELETE FROM ${table} WHERE network_id = ?1`, [networkId]).changes;
+      if (changes > 0) cleaned[table] = changes;
+    }
+    db.run("DELETE FROM networks WHERE network_id = ?1", [networkId]);
+    return { ok: true, owner_id: net.owner_id, network_name: net.network_name, cleaned };
+  });
+}