@sleep2agi/commhub-server 0.9.0-preview.8 → 0.9.0-preview.80

package/src/migrate-sqlite-to-pg.ts

@@ -0,0 +1,263 @@
+/**
+ * RFC-039 S5 — offline copy of a Hub's SQLite database into an EMPTY
+ * PostgreSQL database.
+ *
+ *   commhub-server migrate-to-pg --from <sqlite file> --to <postgres url>
+ *                                [--dry-run] [--i-know-this-is-a-copy]
+ *
+ * Contract:
+ *   - offline: no running process may have the source (or its -wal/-shm)
+ *     open (checked through /proc on Linux). A stopped Hub normally leaves a
+ *     -wal behind — that is expected, and its contents are included: the
+ *     source is opened read-only and read through a `VACUUM INTO` snapshot in
+ *     a private temp dir.
+ *   - never the live Hub's database: a source whose real path is under
+ *     ~/.commhub is refused unless --i-know-this-is-a-copy is given.
+ *   - empty target only: the target's `public` schema must hold no tables,
+ *     views, sequences or functions. The schema is then built by the Hub's
+ *     own module graph (no second copy of the DDL).
+ *   - one transaction: every table is copied and verified — row counts plus
+ *     a SHA-256 over canonicalised rows — before COMMIT; any mismatch or
+ *     error rolls everything back.
+ *   - --dry-run does all of the above, rolls back, and drops what it created,
+ *     leaving the target as it found it.
+ *   - the target URL is printed with credentials removed.
+ */
+import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { PgAdapter, redactPgUrl, type DbAdapter } from "./db-adapter.js";
+
+export type MigrateOptions = {
+  from: string;
+  to: string;
+  dryRun?: boolean;
+  allowCommhubCopy?: boolean;
+  home?: string;
+  log?: (line: string) => void;
+};
+
+export type TableReport = { table: string; rows: number; sha256: string };
+export type MigrateReport = { ok: true; dryRun: boolean; tables: TableReport[] };
+
+class DryRunRollback extends Error {}
+
+/** Refusals are thrown as MigrateRefused so the CLI can print them without a stack. */
+export class MigrateRefused extends Error {}
+
+function refuse(message: string): never {
+  throw new MigrateRefused(`[migrate-to-pg] REFUSING: ${message}`);
+}
+
+const quoteIdent = (name: string) => `"${name.replace(/"/g, '""')}"`;
+
+/** One canonical text per value, identical for bun:sqlite and PgAdapter output. */
+function canonical(value: unknown): unknown {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "bigint") return `i:${value.toString()}`;
+  if (typeof value === "number") return Number.isInteger(value) ? `i:${value}` : `f:${value}`;
+  if (value instanceof Uint8Array) return `b:${Buffer.from(value).toString("hex")}`;
+  if (typeof value === "string" && /^-?\d+$/.test(value) && value.length > 15) return `i:${value}`; // unsafe int8 comes back as text
+  return `s:${String(value)}`;
+}
+
+/** Order-independent digest: hash each row, sort the row hashes, hash the list. */
+function tableDigest(rows: Iterable<Record<string, unknown>>, cols: string[]): { rows: number; sha256: string } {
+  const rowHashes: string[] = [];
+  for (const row of rows) {
+    rowHashes.push(createHash("sha256").update(JSON.stringify(cols.map((c) => canonical(row[c])))).digest("hex"));
+  }
+  rowHashes.sort();
+  return { rows: rowHashes.length, sha256: createHash("sha256").update(rowHashes.join("\n")).digest("hex") };
+}
+
+function bindValue(value: unknown): unknown {
+  if (typeof value === "bigint") {
+    const n = Number(value);
+    return Number.isSafeInteger(n) ? n : value.toString();
+  }
+  return value;
+}
+
+function checkSource(from: string, home: string, allowCommhubCopy: boolean): string {
+  const abs = resolve(from);
+  if (!existsSync(abs)) refuse(`source ${abs} does not exist`);
+  const real = realpathSync(abs);
+  if (!statSync(real).isFile()) refuse(`source ${real} is not a file`);
+  const commhubDir = join(home, ".commhub");
+  const guarded = existsSync(commhubDir) ? realpathSync(commhubDir) : resolve(commhubDir);
+  if ((real === guarded || real.startsWith(guarded + sep)) && !allowCommhubCopy) {
+    refuse(`source ${real} is under ${guarded}, the live Hub's directory. Stop the Hub, copy the database elsewhere, ` +
+      "and migrate the copy — or pass --i-know-this-is-a-copy if this file already is one");
+  }
+  const holders = processesHolding([real, `${real}-wal`, `${real}-shm`]);
+  if (holders === null) {
+    console.warn("[migrate-to-pg] cannot inspect open files on this platform — make sure the Hub using this database is stopped");
+  } else if (holders.length) {
+    refuse(`${real} is open in running process(es) ${holders.join(", ")} — stop the Hub first`);
+  }
+  return real;
+}
+
+/** PIDs (other than ours) with any of `paths` open; null where /proc is unavailable. */
+function processesHolding(paths: string[]): number[] | null {
+  if (!existsSync("/proc/self/fd")) return null;
+  const wanted = new Set(paths);
+  const holders: number[] = [];
+  for (const entry of readdirSync("/proc")) {
+    const pid = Number(entry);
+    if (!Number.isInteger(pid) || pid === process.pid) continue;
+    let fds: string[];
+    try { fds = readdirSync(`/proc/${pid}/fd`); } catch { continue; } // gone, or another user's
+    for (const fd of fds) {
+      let target = "";
+      try { target = readlinkSync(`/proc/${pid}/fd/${fd}`); } catch { continue; }
+      if (wanted.has(target.replace(/ \(deleted\)$/, ""))) { holders.push(pid); break; }
+    }
+  }
+  return holders;
+}
+
+function publicObjectCount(pg: PgAdapter): number {
+  const row = pg.get<{ n: number }>(
+    `SELECT (SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public')
+          + (SELECT COUNT(*) FROM information_schema.sequences WHERE sequence_schema = 'public')
+          + (SELECT COUNT(*) FROM information_schema.routines WHERE routine_schema = 'public') AS n`,
+  );
+  return Number(row?.n ?? 0);
+}
+
+function dropEverythingInPublic(pg: DbAdapter) {
+  // Only ever called on a target that was verified empty before we started,
+  // so everything here was created by this run.
+  pg.exec(`DO $$ DECLARE r record; BEGIN
+    FOR r IN SELECT tablename FROM pg_tables WHERE schemaname = 'public' LOOP
+      EXECUTE 'DROP TABLE IF EXISTS public.' || quote_ident(r.tablename) || ' CASCADE';
+    END LOOP;
+    FOR r IN SELECT p.oid::regprocedure AS sig FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace WHERE n.nspname = 'public' LOOP
+      EXECUTE 'DROP FUNCTION IF EXISTS ' || r.sig || ' CASCADE';
+    END LOOP;
+    FOR r IN SELECT sequencename FROM pg_sequences WHERE schemaname = 'public' LOOP
+      EXECUTE 'DROP SEQUENCE IF EXISTS public.' || quote_ident(r.sequencename) || ' CASCADE';
+    END LOOP;
+  END $$`);
+}
+
+export async function migrateSqliteToPg(opts: MigrateOptions): Promise<MigrateReport> {
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const home = opts.home ?? process.env.HOME ?? "";
+  if (!/^postgres(ql)?:\/\//.test(opts.to)) refuse("--to must be a postgres:// or postgresql:// URL");
+  const source = checkSource(opts.from, home, !!opts.allowCommhubCopy);
+  log(`[migrate-to-pg] source ${source}`);
+  log(`[migrate-to-pg] target ${redactPgUrl(opts.to)}${opts.dryRun ? " (dry run)" : ""}`);
+
+  // Empty-target check on a connection of our own, before the schema exists.
+  const probe = new PgAdapter(opts.to);
+  const existing = publicObjectCount(probe);
+  probe.close();
+  if (existing > 0) refuse(`target schema "public" is not empty (${existing} tables/sequences/functions). Migrate only into a new, empty database`);
+
+  // Snapshot the source: a consistent read that cannot touch the original.
+  const snapDir = mkdtempSync(join(tmpdir(), "anet-migrate-"));
+  const snapshot = join(snapDir, "snapshot.db");
+  try {
+    const original = new Database(source, { readonly: true });
+    original.exec(`VACUUM INTO '${snapshot.replace(/'/g, "''")}'`);
+    original.close();
+    const src = new Database(snapshot, { readonly: true, safeIntegers: true });
+
+    // Build the target schema exactly as the Hub does: import its module graph
+    // with DATABASE_URL pointing at the target.
+    delete process.env.COMMHUB_DB;
+    process.env.DATABASE_URL = opts.to;
+    await import("./server.js");
+    const { db } = await import("./db.js");
+    if (db.dialect !== "postgres") throw new Error("schema build did not select PostgreSQL");
+
+    const tables = (src.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all() as { name: string }[])
+      .map((r) => r.name);
+    const report: TableReport[] = [];
+
+    try {
+      db.transaction(() => {
+        for (const table of tables) {
+          const srcCols = (src.query(`PRAGMA table_info(${quoteIdent(table)})`).all() as { name: string }[]).map((c) => c.name);
+          const tgtCols = new Set(db.all<{ column_name: string }>(
+            "SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = ?1", table,
+          ).map((c) => c.column_name));
+          const srcCount = Number((src.query(`SELECT COUNT(*) AS n FROM ${quoteIdent(table)}`).get() as { n: bigint | number }).n);
+          if (tgtCols.size === 0) {
+            if (srcCount > 0) throw new Error(`table ${table} (${srcCount} rows) does not exist in the Hub's PostgreSQL schema`);
+            log(`[migrate-to-pg] skip ${table}: not in the PostgreSQL schema, and empty in the source`);
+            continue;
+          }
+          const missing = srcCols.filter((c) => !tgtCols.has(c));
+          if (missing.length && srcCount > 0) throw new Error(`table ${table}: column(s) ${missing.join(", ")} do not exist in PostgreSQL`);
+          const cols = srcCols.filter((c) => tgtCols.has(c));
+          // SQLite's implicit rowid carries insertion order; PostgreSQL keeps it
+          // in a real `rowid` column on the tables that sort by it (RFC-039 F3).
+          const copyRowid = tgtCols.has("rowid") && !srcCols.includes("rowid");
+          const selectCols = [...(copyRowid ? ["rowid AS rowid"] : []), ...cols.map(quoteIdent)].join(", ");
+          const insertCols = [...(copyRowid ? ["rowid"] : []), ...cols];
+
+          // Triggers are off only while this table is being filled. Re-enabled
+          // in `finally` so no path — including a failed batch — leaves them
+          // off; a rollback also restores them (DDL is transactional in PG).
+          db.exec(`ALTER TABLE ${quoteIdent(table)} DISABLE TRIGGER USER`);
+          try {
+            db.run(`DELETE FROM ${quoteIdent(table)}`); // rows the schema bootstrap seeded; the source is authoritative
+            const perBatch = Math.max(1, Math.floor(30000 / insertCols.length));
+            const stmt = src.query(`SELECT ${selectCols} FROM ${quoteIdent(table)} ORDER BY rowid LIMIT ?1 OFFSET ?2`);
+            for (let offset = 0; offset < srcCount; offset += perBatch) {
+              const rows = stmt.all(perBatch, offset) as Record<string, unknown>[];
+              if (!rows.length) break;
+              const params: unknown[] = [];
+              const tuples = rows.map((row) => `(${insertCols.map((c) => { params.push(bindValue(row[c])); return `?${params.length}`; }).join(", ")})`);
+              db.run(`INSERT INTO ${quoteIdent(table)} (${insertCols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")}`, params);
+            }
+          } finally {
+            db.exec(`ALTER TABLE ${quoteIdent(table)} ENABLE TRIGGER USER`);
+          }
+
+          // Sequences behind BIGSERIAL columns continue after the copied ids.
+          for (const seq of db.all<{ column_name: string }>(
+            "SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = ?1 AND column_default LIKE 'nextval(%'", table,
+          )) {
+            db.get(`SELECT setval(pg_get_serial_sequence(?1, ?2), COALESCE((SELECT MAX(${quoteIdent(seq.column_name)}) FROM ${quoteIdent(table)}), 0) + 1, false)`,
+              table, seq.column_name);
+          }
+
+          // Verify before COMMIT.
+          const hashCols = copyRowid ? ["rowid", ...cols] : cols;
+          const srcDigest = tableDigest(src.query(`SELECT ${selectCols} FROM ${quoteIdent(table)}`).all() as Record<string, unknown>[], hashCols);
+          const tgtDigest = tableDigest(db.all(`SELECT ${hashCols.map(quoteIdent).join(", ")} FROM ${quoteIdent(table)}`), hashCols);
+          if (srcDigest.rows !== tgtDigest.rows || srcDigest.sha256 !== tgtDigest.sha256) {
+            throw new Error(`verification failed for ${table}: source ${srcDigest.rows} rows ${srcDigest.sha256.slice(0, 12)}, ` +
+              `target ${tgtDigest.rows} rows ${tgtDigest.sha256.slice(0, 12)}`);
+          }
+          report.push({ table, rows: srcDigest.rows, sha256: srcDigest.sha256 });
+          log(`[migrate-to-pg] ${table}: ${srcDigest.rows} rows, sha256 ${srcDigest.sha256.slice(0, 16)} ✓`);
+        }
+        if (opts.dryRun) throw new DryRunRollback("dry run");
+      });
+    } catch (e) {
+      const rows = report.reduce((n, t) => n + t.rows, 0);
+      dropEverythingInPublic(db);
+      src.close();
+      if (!(e instanceof DryRunRollback)) {
+        const verify = e instanceof Error && e.message.startsWith("verification failed") ? "MISMATCH" : "NOT-REACHED";
+        log(`[migrate-to-pg] SUMMARY result=FAILED tables_verified=${report.length}/${tables.length} rows=${rows} verify=${verify} — rolled back, target left empty`);
+        throw e;
+      }
+      log(`[migrate-to-pg] SUMMARY result=DRY-RUN tables=${report.length} rows=${rows} verify=OK — rolled back, target left empty`);
+      return { ok: true, dryRun: true, tables: report };
+    }
+    src.close();
+    log(`[migrate-to-pg] SUMMARY result=COMMITTED tables=${report.length} rows=${report.reduce((n, t) => n + t.rows, 0)} verify=OK`);
+    return { ok: true, dryRun: false, tables: report };
+  } finally {
+    rmSync(snapDir, { recursive: true, force: true });
+  }
+}

package/src/network-name-http.test.ts

@@ -0,0 +1,75 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-network-name-http-"));
+let server: any;
+let base = "";
+let userToken = "";
+let nodeToken = "";
+let networkId = "";
+let username = "";
+
+// 30s 而不是 bun 默认的 5s:这个 hook 跑 register()(KDF)+bootServer(),
+// 本机空载基线 ~620ms,而 2026-08-17 与 2026-08-31 两次 CI 上它被 5s 上限打死
+// (0 pass / 1 fail / Ran 1 test —— 见 #928、#1627)。5247ms 是**被截断的下界**,
+// 不是测量值,所以余量按基线的 ~48x 取,而不是按那个数取。
+beforeAll(async () => {
+  process.env.COMMHUB_DB = process.env.COMMHUB_DB || join(PRIVATE_DB_DIR, "hub.db");
+  username = `network_name_${Date.now()}_${process.pid}`;
+  const registered = register(username, "NetworkName123!", undefined, "seed");
+  expect(registered.ok).toBe(true);
+  userToken = registered.token!;
+  networkId = registered.network_id!;
+  const userId = db.get<{ user_id: string }>(
+    "SELECT user_id FROM users WHERE username = ?1",
+    [username],
+  )!.user_id;
+  const minted = createNetworkTokenForNode(userId, networkId, "network-name-node");
+  expect(minted.ok).toBe(true);
+  nodeToken = minted.token!;
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+async function networks(token: string): Promise<any[]> {
+  const response = await fetch(`${base}/api/networks`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  expect(response.status).toBe(200);
+  const body = await response.json() as any;
+  expect(body.ok).toBe(true);
+  return body.networks;
+}
+
+describe("GET /api/networks name compatibility (#449)", () => {
+  test("utok rows expose equal non-null name and network_name", async () => {
+    const rows = await networks(userToken);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].network_id).toBe(networkId);
+    // #449 is about `name` and `network_name` agreeing and being non-null.
+    // Pin them to the registered username rather than the literal "default":
+    // the auto-created network is named after its owner, so hardcoding the
+    // old literal would test the naming scheme instead of the compat shim.
+    expect(rows[0].network_name).toBe(username);
+    expect(rows[0].name).toBe(username);
+  });
+
+  test("network-bound ntok rows expose the same alias", async () => {
+    const rows = await networks(nodeToken);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].network_id).toBe(networkId);
+    expect(rows[0].network_name).toBe(username);
+    expect(rows[0].name).toBe(rows[0].network_name);
+    expect(rows[0].name).not.toBeNull();
+  });
+});

package/src/network-scope.ts

@@ -0,0 +1,224 @@
+// Network-scope resolution shared by BOTH transports.
+//
+// #517: REST (server.ts) and MCP (tools.ts) each carried their own copy of
+// the "which network does this caller write to" rule. REST grew a
+// single-network fallback (POST /api/task); MCP never did — so a utok_
+// caller could read everything but write nothing, with a misleading
+// permission_denied. Extracted here (same pattern as lifecycle-guard.ts)
+// so the rule has exactly ONE implementation. If you change write-scope
+// semantics, this module is the only place — do NOT re-inline a copy in
+// server.ts or tools.ts.
+
+import { db } from "./db.js";
+import { getUserNetworkRole } from "./auth.js";
+import { isAgentRestricted, restrictedNetworkIds, usernameIsAgentAlias, visibleAgents } from "./agent-access.js";
+
+export type RestNetworkScope = {
+  networkId: string | null;
+  networkIds: string[] | null;
+  denied?: string;
+  // 多用户 Agent 权限:scope 里哪些网络对这个调用者是「只看授权 Agent」的。
+  // addNetworkScope 对这些网络 fail-closed(整网不返回);要按授权放行的路径
+  // 显式改用 addAgentNetworkScope / addOwnTrafficScope,人类数据用 addHumanNetworkScope。
+  agentRestriction?: { userId: string; username: string; networkIds: string[] };
+};
+
+type ScopeAuthCtx = { userId: string; networkId: string | null; username?: string | null };
+
+function usernameOf(userId: string, known?: string | null): string {
+  if (known) return known;
+  return db.get<{ username: string }>("SELECT username FROM users WHERE user_id = ?1", userId)?.username ?? "";
+}
+
+function withAgentRestriction(scope: RestNetworkScope, authCtx: ScopeAuthCtx): RestNetworkScope {
+  const inScope = scope.networkId ? [scope.networkId] : (scope.networkIds ?? []);
+  if (inScope.length === 0) return scope;
+  const restricted = restrictedNetworkIds(authCtx.userId).filter((id) => inScope.includes(id));
+  if (restricted.length === 0) return scope;
+  return { ...scope, agentRestriction: { userId: authCtx.userId, username: usernameOf(authCtx.userId, authCtx.username), networkIds: restricted } };
+}
+
+export function getUserNetworkIds(userId: string): string[] {
+  // JOIN networks: deleteNetwork historically left network_members rows
+  // behind (fixed alongside PR #519, but legacy DBs still carry strays).
+  // A ghost membership must neither make a single-network user look
+  // ambiguous nor let the write fallback resolve INTO a deleted network.
+  return db.all<{ network_id: string }>(
+    `SELECT m.network_id FROM network_members m
+     JOIN networks n ON n.network_id = m.network_id
+     WHERE m.user_id = ?1`,
+    userId
+  ).map((row) => row.network_id);
+}
+
+export function resolveRestNetworkScope(requested: string | null, authCtx: ScopeAuthCtx | null, isAdmin: boolean): RestNetworkScope {
+  // Legacy global token or open dev mode keeps the old global behavior.
+  if (!authCtx) return { networkId: requested || null, networkIds: null };
+
+  // Network tokens are forcibly scoped to their bound network.
+  if (authCtx.networkId) return { networkId: authCtx.networkId, networkIds: null };
+
+  // System admins may intentionally inspect all networks.
+  if (isAdmin) return { networkId: requested || null, networkIds: null };
+
+  if (requested) {
+    const role = getUserNetworkRole(authCtx.userId, requested);
+    if (!role) return { networkId: null, networkIds: [], denied: "access denied to requested network" };
+    return withAgentRestriction({ networkId: requested, networkIds: null }, authCtx);
+  }
+
+  return withAgentRestriction({ networkId: null, networkIds: getUserNetworkIds(authCtx.userId) }, authCtx);
+}
+
+function unrestrictedNetworks(scope: RestNetworkScope): string[] | null {
+  const excluded = scope.agentRestriction?.networkIds ?? [];
+  if (scope.networkId) return excluded.includes(scope.networkId) ? [] : [scope.networkId];
+  if (scope.networkIds) return scope.networkIds.filter((id) => !excluded.includes(id));
+  return null;
+}
+
+function placeholders(params: any[], values: string[]): string {
+  const start = params.length;
+  params.push(...values);
+  return values.map((_, i) => `?${start + i + 1}`).join(", ");
+}
+
+/**
+ * 默认的网络作用域 —— 对受限成员的受限网络 **fail-closed**:整网不返回。
+ * 没被逐条审过、不知道按授权怎么放行的查询,默认走这里,受限成员什么都看不到。
+ */
+export function addNetworkScope(sql: string, params: any[], scope: RestNetworkScope, column = "network_id"): string {
+  if (!scope.agentRestriction) return addHumanNetworkScope(sql, params, scope, column);
+  const allowed = unrestrictedNetworks(scope) ?? [];
+  if (allowed.length === 0) return `${sql} AND 1=0`;
+  return `${sql} AND ${column} IN (${placeholders(params, allowed)})`;
+}
+
+/**
+ * 人类数据(自己的私信收件箱、需求看板、项目、网络成员)的作用域:受限成员照常看得到
+ * 自己所在网络。只给已确认不含 Agent 内容的查询用。
+ */
+export function addHumanNetworkScope(sql: string, params: any[], scope: RestNetworkScope, column = "network_id"): string {
+  if (scope.networkId) {
+    sql += ` AND ${column} = ?${params.length + 1}`;
+    params.push(scope.networkId);
+  } else if (scope.networkIds) {
+    if (scope.networkIds.length === 0) {
+      sql += " AND 1=0";
+    } else {
+      const placeholders = scope.networkIds.map((_, i) => `?${params.length + i + 1}`).join(", ");
+      sql += ` AND ${column} IN (${placeholders})`;
+      params.push(...scope.networkIds);
+    }
+  }
+  return sql;
+}
+
+type AgentColumns = { network?: string; alias: string; nodeId?: string };
+
+/**
+ * Agent 行(sessions / nodes)的作用域:不受限的网络整网放行;受限网络只放行授权的 Agent。
+ * mode="message" 时只放行 can_message 的授权。
+ */
+export function addAgentNetworkScope(sql: string, params: any[], scope: RestNetworkScope, cols: AgentColumns, mode: "see" | "message" = "see"): string {
+  const restriction = scope.agentRestriction;
+  if (!restriction) return addHumanNetworkScope(sql, params, scope, cols.network ?? "network_id");
+  const net = cols.network ?? "network_id";
+  const parts: string[] = [];
+  const allowed = unrestrictedNetworks(scope) ?? [];
+  if (allowed.length) parts.push(`${net} IN (${placeholders(params, allowed)})`);
+  for (const networkId of restriction.networkIds) {
+    const visible = visibleAgents(restriction.userId, networkId);
+    const aliases = mode === "message" ? visible.messageAliases : visible.aliases;
+    const nodeIds = mode === "message" ? visible.messageNodeIds : visible.nodeIds;
+    const conds: string[] = [];
+    if (aliases.length) conds.push(`${cols.alias} IN (${placeholders(params, aliases)})`);
+    if (cols.nodeId && nodeIds.length) conds.push(`${cols.nodeId} IN (${placeholders(params, nodeIds)})`);
+    if (conds.length === 0) continue;
+    parts.push(`(${net} = ${placeholders(params, [networkId])} AND (${conds.join(" OR ")}))`);
+  }
+  return parts.length ? `${sql} AND (${parts.join(" OR ")})` : `${sql} AND 1=0`;
+}
+
+type TrafficColumns = { network?: string; from: string; to: string; fromNodeId?: string; toNodeId?: string };
+
+/**
+ * 任务 / inbox 这类「谁发给谁」的行:受限网络里只放行**自己**与**授权 Agent**之间的往来
+ * (from=自己 且 to=授权 Agent,或反过来)。别人(包括 owner)和同一个 Agent 的对话看不到。
+ */
+export function addOwnTrafficScope(sql: string, params: any[], scope: RestNetworkScope, cols: TrafficColumns): string {
+  const restriction = scope.agentRestriction;
+  if (!restriction) return addHumanNetworkScope(sql, params, scope, cols.network ?? "network_id");
+  const net = cols.network ?? "network_id";
+  const parts: string[] = [];
+  const allowed = unrestrictedNetworks(scope) ?? [];
+  if (allowed.length) parts.push(`${net} IN (${placeholders(params, allowed)})`);
+  if (restriction.username) {
+    for (const networkId of restriction.networkIds) {
+      // 用户名与本网络某个 Agent 的 alias 撞名时(入网时拦过,但 Agent 之后注册的 alias 拦不住),
+      // 「发给我的」无法和「发给那个 Agent 的」区分开 —— 这个网络的往来一律不放行。
+      if (usernameIsAgentAlias(networkId, restriction.username)) continue;
+      const visible = visibleAgents(restriction.userId, networkId);
+      // 先判空再生成占位符:side() 会往 params 里推值,推了又丢弃会让参数个数对不上。
+      const useNodeIds = !!(cols.fromNodeId && cols.toNodeId) && visible.nodeIds.length > 0;
+      if (visible.aliases.length === 0 && !useNodeIds) continue;
+      const side = (aliasCol: string, nodeCol?: string): string | null => {
+        const conds: string[] = [];
+        if (visible.aliases.length) conds.push(`${aliasCol} IN (${placeholders(params, visible.aliases)})`);
+        if (nodeCol && useNodeIds) conds.push(`${nodeCol} IN (${placeholders(params, visible.nodeIds)})`);
+        return conds.length ? `(${conds.join(" OR ")})` : null;
+      };
+      const toAgent = side(cols.to, cols.toNodeId)!;
+      const fromAgent = side(cols.from, cols.fromNodeId)!;
+      const me = placeholders(params, [restriction.username]);
+      parts.push(`(${net} = ${placeholders(params, [networkId])} AND ((${cols.from} = ${me} AND ${toAgent}) OR (${cols.to} = ${me} AND ${fromAgent})))`);
+    }
+  }
+  return parts.length ? `${sql} AND (${parts.join(" OR ")})` : `${sql} AND 1=0`;
+}
+
+export function singleNetworkId(scope: RestNetworkScope): string | null {
+  if (scope.networkId) return scope.networkId;
+  if (scope.networkIds?.length === 1) return scope.networkIds[0];
+  return null;
+}
+
+/**
+ * Resolve one unambiguous network for a REST write.
+ *
+ * Admin read scope is intentionally global (`networkIds=null`), so it cannot
+ * by itself express that an admin happens to have exactly one membership.
+ * Writes must not inherit that ambiguity: use the sole real membership when
+ * one exists, and keep requiring an explicit network for zero or 2+.
+ */
+export function resolveRestWriteNetworkId(
+  scope: RestNetworkScope,
+  authCtx: { userId: string; networkId: string | null } | null,
+  isAdmin: boolean,
+): string | null {
+  const scoped = singleNetworkId(scope);
+  if (scoped) return scoped;
+  if (!authCtx || !isAdmin) return null;
+  const memberships = getUserNetworkIds(authCtx.userId);
+  return memberships.length === 1 ? memberships[0] : null;
+}
+
+/**
+ * 能不能往这个网络写**面向 Agent 的东西**(派任务、改节点、排程……)。
+ * 受限成员在受限网络里恒为 false(fail-closed);给授权 Agent 发任务的路径另用
+ * canMessageAgent 单独放行,人类侧的写入(私信、需求、上传)用 canRestWriteNetworkAsHuman。
+ */
+export function canRestWriteNetwork(authCtx: { userId: string; networkId: string | null } | null, networkId: string | null, isAdmin: boolean): boolean {
+  if (!canRestWriteNetworkAsHuman(authCtx, networkId, isAdmin)) return false;
+  if (!authCtx || isAdmin || !networkId) return true;
+  return !isAgentRestricted(authCtx.userId, networkId);
+}
+
+/** 旧的「成员且不是 viewer」判据,不看 Agent 授权。只给人类侧写入用。 */
+export function canRestWriteNetworkAsHuman(authCtx: { userId: string; networkId: string | null } | null, networkId: string | null, isAdmin: boolean): boolean {
+  if (!authCtx) return true; // legacy global token or open dev mode
+  if (isAdmin) return true;
+  if (!networkId) return false;
+  const role = getUserNetworkRole(authCtx.userId, networkId);
+  return !!role && role !== "viewer";
+}

package/src/node-attrs-validate.ts

@@ -0,0 +1,88 @@
+// Boundary validation for node DISPLAY attributes (display_name / team /
+// tags). Mirrors `avatar-validate.ts` in spirit: this is the only place
+// that decides what a client is allowed to store, and it trusts nothing.
+//
+// Two different postures on purpose:
+//
+//   display_name / team — SCALAR fields the user typed. A wrong TYPE here
+//     is a client bug, so it is REJECTED (400) rather than coerced: silently
+//     turning `{}` into "[object Object]" would persist garbage the user
+//     never typed and can't explain.
+//
+//   tags — a LIST. Same reasoning as the `channels` patch in tools.ts: the
+//     wire contract wants junk dropped instead of failing the whole request,
+//     so one fat-fingered entry from a dashboard doesn't 400 the save. Each
+//     element is narrowed independently (typeof → trim → length cap →
+//     dedup), so nothing non-string can reach the database.
+
+/** Max stored length of display_name / team. */
+export const MAX_ATTR_LEN = 120;
+/** Max stored length of a single tag. */
+export const MAX_TAG_LEN = 64;
+/** Max number of tags kept per node. */
+export const MAX_TAGS = 16;
+
+export type ScalarAttrResult =
+  | { ok: true; value: string | null }
+  | { ok: false; reason: string };
+
+/**
+ * Narrow an optional scalar display attribute.
+ *   undefined      → not part of this patch (caller leaves the column alone)
+ *   null / ""      → explicit clear
+ *   non-string     → rejected (never coerced)
+ *   over-long      → rejected (the user should see it, not silently lose text)
+ */
+export function validateScalarAttr(raw: unknown, field: string): ScalarAttrResult {
+  if (raw === undefined) return { ok: true, value: null };
+  if (raw === null) return { ok: true, value: null };
+  if (typeof raw !== "string") {
+    return { ok: false, reason: `${field} must be a string or null` };
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return { ok: true, value: null };
+  if (trimmed.length > MAX_ATTR_LEN) {
+    return { ok: false, reason: `${field} exceeds ${MAX_ATTR_LEN} characters` };
+  }
+  // Control characters would corrupt any log line / table cell that renders
+  // the value; strip rather than reject (they are almost always a paste
+  // artefact, not user intent).
+  // eslint-disable-next-line no-control-regex
+  const clean = trimmed.replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
+  return { ok: true, value: clean.length > 0 ? clean : null };
+}
+
+/**
+ * Narrow an untrusted tags array. NEVER throws, never rejects the request:
+ * unusable entries are dropped. Returns the canonical list to store.
+ */
+export function narrowTags(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const item of raw) {
+    if (typeof item !== "string") continue; // numbers/objects/arrays/null
+    // eslint-disable-next-line no-control-regex
+    const t = item.replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
+    if (t.length === 0) continue;
+    if (t.length > MAX_TAG_LEN) continue; // absurd entry — drop, don't truncate
+    const key = t.toLowerCase(); // case-fold for dedup, keep first spelling
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(t);
+    if (out.length >= MAX_TAGS) break;
+  }
+  return out;
+}
+
+/** Parse the stored tags column back into an array. Storage is JSON text;
+ *  anything unparseable (hand-edited DB, older format) reads as empty so a
+ *  dashboard can always `.map()` without a guard. */
+export function parseStoredTags(stored: unknown): string[] {
+  if (typeof stored !== "string" || stored.length === 0) return [];
+  try {
+    return narrowTags(JSON.parse(stored));
+  } catch {
+    return [];
+  }
+}