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

package/bin/commhub.ts

@@ -12,19 +12,56 @@
 
 const args = process.argv.slice(2);
 
-for (let i = 0; i < args.length; i++) {
-  if (args[i] === "--port" || args[i] === "-p") process.env.PORT = args[++i];
-  if (args[i] === "--host") process.env.HOST = args[++i];
-  if (args[i] === "--token" || args[i] === "-t") process.env.COMMHUB_AUTH_TOKEN = args[++i];
-  if (args[i] === "--db") process.env.COMMHUB_DB = args[++i];
-  if (args[i] === "--cors") process.env.COMMHUB_CORS_ORIGINS = args[++i];
-  if (args[i] === "--dev-open") process.env.COMMHUB_DEV_OPEN = "1";
-  if (args[i] === "--help" || args[i] === "-h") {
+// RFC-039 S5 — offline SQLite → PostgreSQL copy. Handled before any server
+// option parsing: it never starts a Hub and never opens the default database.
+if (args[0] === "migrate-to-pg") {
+  const flag = (name: string) => args.includes(name);
+  const value = (name: string) => { const i = args.indexOf(name); return i > 0 ? args[i + 1] : undefined; };
+  const MIGRATE_VALUE_FLAGS = new Set(["--from", "--to"]);
+  const MIGRATE_FLAGS = new Set(["--dry-run", "--i-know-this-is-a-copy", "--help", "-h"]);
+  for (let i = 1; i < args.length; i++) {
+    if (MIGRATE_VALUE_FLAGS.has(args[i])) { i++; continue; }
+    if (!MIGRATE_FLAGS.has(args[i])) {
+      console.error(`commhub-server migrate-to-pg: unknown argument ${args[i]}\nRun "commhub-server migrate-to-pg --help" for usage.`);
+      process.exit(2);
+    }
+  }
+  if (flag("--help") || flag("-h") || !value("--from") || !value("--to")) {
     console.log(`
+Usage:
+  commhub-server migrate-to-pg --from <sqlite file> --to <postgres url> [--dry-run] [--i-know-this-is-a-copy]
+
+Copies a stopped Hub's SQLite database into an EMPTY PostgreSQL database, in one
+transaction, verifying per-table row counts and content hashes before COMMIT.
+Experimental (RFC-039); available from commhub-server 0.9.0-preview.73.
+Files under the uploads directory are not copied.
+
+  --dry-run                 do everything, then roll back and leave the target empty
+  --i-know-this-is-a-copy   allow a source under ~/.commhub (refused by default)
+`);
+    process.exit(flag("--help") || flag("-h") ? 0 : 2);
+  }
+  const { migrateSqliteToPg, MigrateRefused } = await import("../src/migrate-sqlite-to-pg.ts");
+  try {
+    await migrateSqliteToPg({
+      from: value("--from")!,
+      to: value("--to")!,
+      dryRun: flag("--dry-run"),
+      allowCommhubCopy: flag("--i-know-this-is-a-copy"),
+    });
+    process.exit(0);
+  } catch (error) {
+    console.error(error instanceof MigrateRefused ? error.message : `[migrate-to-pg] FAILED, rolled back: ${(error as Error)?.message ?? error}`);
+    process.exit(error instanceof MigrateRefused ? 2 : 1);
+  }
+}
+
+const HELP = `
 CommHub MCP Server — AI Agent 通信中枢
 
 Usage:
   commhub-server [options]
+  commhub-server migrate-to-pg --help    Copy a stopped Hub's SQLite database into PostgreSQL (experimental)
 
 Options:
   --port, -p <port>       Port to listen on (default: 9200, env: PORT)
@@ -34,6 +71,7 @@ Options:
   --cors <origins>        CORS origins, comma-separated (env: COMMHUB_CORS_ORIGINS)
   --dev-open              Explicit unauthenticated local development mode
   --help, -h              Show this help
+  --version, -v           Print the version and exit
 
 Environment Variables:
   PORT                    Server port (default: 9200)
@@ -49,8 +87,43 @@ Examples:
   commhub-server --port 9200 --token my-secret-token
   commhub-server --port 9200 --dev-open
   PORT=9200 COMMHUB_AUTH_TOKEN=secret commhub-server
-`);
+`;
+
+// Anything this bin does not recognise is a usage error: exit 2 and never
+// start a Hub. Before this, unknown words and flags were ignored and a Hub
+// started on the defaults — `commhub-server <some-subcommand>` on a version
+// without that subcommand opened ~/.commhub/commhub.db on :9200.
+function usageError(message: string): never {
+  console.error(`commhub-server: ${message}\nRun "commhub-server --help" for usage.`);
+  process.exit(2);
+}
+
+const VALUE_FLAGS: Record<string, string> = {
+  "--port": "PORT", "-p": "PORT",
+  "--host": "HOST",
+  "--token": "COMMHUB_AUTH_TOKEN", "-t": "COMMHUB_AUTH_TOKEN",
+  "--db": "COMMHUB_DB",
+  "--cors": "COMMHUB_CORS_ORIGINS",
+};
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (Object.hasOwn(VALUE_FLAGS, arg)) {
+    const value = args[i + 1];
+    if (value === undefined || value.startsWith("--")) usageError(`${arg} needs a value`);
+    process.env[VALUE_FLAGS[arg]] = value;
+    i++;
+  } else if (arg === "--dev-open") {
+    process.env.COMMHUB_DEV_OPEN = "1";
+  } else if (arg === "--help" || arg === "-h") {
+    console.log(HELP);
+    process.exit(0);
+  } else if (arg === "--version" || arg === "-v") {
+    const pkg = (await import("../package.json", { with: { type: "json" } })).default as { version: string };
+    console.log(pkg.version);
     process.exit(0);
+  } else {
+    usageError(arg.startsWith("-") ? `unknown option ${arg}` : `unknown command ${arg}`);
   }
 }
 

package/package.json

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

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

@@ -255,7 +255,7 @@ describe("humans: restricted members can still see and DM other humans", () => {
     const r = await get(aliceToken, `/api/networks/${NET}/humans`);
     expect(r.status).toBe(200);
     expect(r.body.humans.map((h: any) => h.user_id).sort()).toEqual([adminId, aliceId, bobId].sort());
-    expect(Object.keys(r.body.humans[0]).sort()).toEqual(["display_name", "user_id", "username"]);
+    expect(Object.keys(r.body.humans[0]).sort()).toEqual(["display_name", "last_seen_at", "online", "user_id", "username"]);
     // 非成员拿不到。
     const outsider = register(`acl_out_${Date.now()}`, PW);
     expect((await get(outsider.token!, `/api/networks/${NET}/humans`)).status).toBe(403);
@@ -344,6 +344,8 @@ describe("granted member sees and messages ONLY what was granted", () => {
 describe("requirements: agent references alice cannot see are hidden and protected", () => {
   let reqId = "";
   test("a card owned by Z shows agent_owner=null to alice, Z to admin", async () => {
+    // 这一组测的是「看不见的 Agent 引用被隐去、不能被改」,不是任务范围:alice 按 RFC-038 §9 之前的语义能改全网的卡。
+    db.run("UPDATE network_members SET task_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, aliceId]);
     const c = await send(adminToken, "POST", "/api/requirements", { name: "card", network_id: NET, agent_owner: { kind: "node", id: Z.node }, participants: [{ kind: "node", id: Z.node }, { kind: "user", id: aliceId }] });
     expect(c.status).toBe(201);
     reqId = c.body.requirement.id;

package/src/auth.ts

@@ -4,7 +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";
+import { deleteAgentGrants, isAgentRestricted } from "./agent-access.js"; import { deleteTaskGrantsForMember, NEW_MEMBER_TASK_ACCESS, type TaskAccessMode } from "./task-access.js"; // 一行两个 import:文档钉着 auth.ts 的行号
 
 // Round-6 A1 hardening — dummy hash for username-enumeration timing
 // close. We compute ONE scrypt hash of a throwaway password and reuse
@@ -586,6 +586,8 @@ export function getNetworkMembers(networkId: string) {
     `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,
+            CASE WHEN u.role = 'admin' OR nm.role IN ('owner', 'admin') OR nm.task_access = 'all' THEN 'all' ELSE 'scoped' END AS task_access,
+            (SELECT COUNT(*) FROM network_member_project_grants pg WHERE pg.network_id = nm.network_id AND pg.user_id = nm.user_id) AS task_project_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`,
@@ -624,15 +626,17 @@ export function usernameCollidesWithAgent(networkId: string, userId: string): bo
 }
 
 // 新成员默认 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 } {
+export function addNetworkMember(networkId: string, userId: string, role: string, invitedBy?: string, opts: { agentAccess?: "all" | "granted"; taskAccess?: TaskAccessMode } = {}): { ok: boolean; error?: string } {
   if (!MEMBER_ROLES.has(role)) return { ok: false, error: "invalid role" };
   const agentAccess = opts.agentAccess === "all" ? "all" : "granted";
+  // 任务范围:新成员默认 NEW_MEMBER_TASK_ACCESS(task-access.ts 一处定义)。
+  const taskAccess: TaskAccessMode = opts.taskAccess === "all" || opts.taskAccess === "scoped" ? opts.taskAccess : NEW_MEMBER_TASK_ACCESS;
   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" };
   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]);
+  db.run("INSERT INTO network_members (network_id, user_id, role, invited_by, agent_access, task_access) VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
+    [networkId, userId, role, invitedBy || null, agentAccess, taskAccess]);
   return { ok: true };
 }
 
@@ -649,6 +653,7 @@ export function removeNetworkMember(networkId: string, userId: string): { ok: bo
   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);
+  deleteTaskGrantsForMember(networkId, userId);
   return { ok: true };
 }
 
@@ -686,8 +691,8 @@ export function joinByInvite(inviteCode: string, userId: string): { ok: boolean;
   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, agent_access) VALUES (?1, ?2, ?3, ?4, 'granted')",
-    [invite.network_id, userId, invite.role, invite.created_by]);
+  db.run("INSERT INTO network_members (network_id, user_id, role, invited_by, agent_access, task_access) VALUES (?1, ?2, ?3, ?4, 'granted', ?5)",
+    [invite.network_id, userId, invite.role, invite.created_by, NEW_MEMBER_TASK_ACCESS]);
   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 };
@@ -704,7 +709,9 @@ export function getUserAllNetworks(userId: string) {
   return db.all<any>(
     `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
+            CASE WHEN u.role = 'admin' OR nm.role IN ('owner', 'admin') OR nm.agent_access = 'all' THEN 'all' ELSE 'granted' END AS agent_access,
+            -- 任务权限(RFC-038 §9):客户端据此显示只读提示与「还没有与你相关的任务」。
+            CASE WHEN u.role = 'admin' OR nm.role IN ('owner', 'admin') OR nm.task_access = 'all' THEN 'all' ELSE 'scoped' END AS task_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`,
@@ -827,6 +834,8 @@ const NETWORK_CLEANUP_TABLES = [
   "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",
+  // 标签颜色:网络本身的元数据(标签本体在 requirements 行里,那张表是阻断项)。
+  "network_tags",
 ];
 
 function tableExists(name: string): boolean {

package/src/commhub-bin-args.test.ts

@@ -0,0 +1,85 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// commhub-server must refuse what it does not understand instead of starting a
+// Hub on the defaults (the live ~/.commhub/commhub.db). Every child gets a
+// throwaway HOME and a throwaway PORT, so even a regression binds nothing real.
+const BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "commhub.ts");
+const PKG_VERSION = JSON.parse(readFileSync(join(dirname(BIN), "..", "package.json"), "utf8")).version as string;
+const home = mkdtempSync(join(tmpdir(), "anet-bin-args-"));
+const PORT = String(26000 + Math.floor(Math.random() * 3000));
+
+afterAll(() => rmSync(home, { recursive: true, force: true }));
+
+function run(args: string[], extraEnv: Record<string, string> = {}, timeoutMs = 15_000) {
+  const proc = Bun.spawnSync(["bun", BIN, ...args], {
+    env: { PATH: process.env.PATH ?? "", HOME: home, PORT, HOST: "127.0.0.1", ...extraEnv },
+    stdout: "pipe", stderr: "pipe", timeout: timeoutMs,
+  });
+  return { code: proc.exitCode, stdout: proc.stdout.toString(), stderr: proc.stderr.toString() };
+}
+
+async function listening(port: string): Promise<boolean> {
+  try { await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(500) }); return true; } catch { return false; }
+}
+
+describe("commhub-server argument handling", () => {
+  for (const [args, message] of [
+    [["bogus"], "unknown command bogus"],
+    [["--port=29999"], "unknown option --port=29999"],
+    [["--bogus-flag"], "unknown option --bogus-flag"],
+    [["--port"], "--port needs a value"],
+    [["--db", "--dev-open"], "--db needs a value"],
+  ] as const) {
+    test(`${args.join(" ")} → exit 2, no database, nothing listening`, async () => {
+      const r = run([...args]);
+      expect(r.code).toBe(2);
+      expect(r.stderr).toContain(message);
+      expect(r.stderr).toContain("commhub-server --help");
+      expect(existsSync(join(home, ".commhub"))).toBe(false);
+      expect(await listening(PORT)).toBe(false);
+    });
+  }
+
+  test("migrate-to-pg with missing or unknown arguments exits 2 and starts nothing", async () => {
+    const missing = run(["migrate-to-pg", "--from", "/x.db"]);
+    expect(missing.code).toBe(2);
+    expect(missing.stdout).toContain("commhub-server migrate-to-pg --from <sqlite file> --to <postgres url>");
+    const unknown = run(["migrate-to-pg", "--from", "/x.db", "--to", "postgres://u@127.0.0.1/anet_x_test", "--bogus"]);
+    expect(unknown.code).toBe(2);
+    expect(unknown.stderr).toContain("unknown argument --bogus");
+    expect(existsSync(join(home, ".commhub"))).toBe(false);
+    expect(await listening(PORT)).toBe(false);
+  });
+
+  test("--help and --version exit 0 without starting", async () => {
+    const help = run(["--help"]);
+    expect(help.code).toBe(0);
+    expect(help.stdout).toContain("--port, -p <port>");
+    const version = run(["--version"]);
+    expect(version.code).toBe(0);
+    expect(version.stdout.trim()).toBe(PKG_VERSION);
+    expect(existsSync(join(home, ".commhub"))).toBe(false);
+  });
+
+  test("the known forms still start a Hub", async () => {
+    const db = join(home, "known.db");
+    const port = String(Number(PORT) + 1);
+    const child = Bun.spawn(["bun", BIN, "--port", port, "--host", "127.0.0.1", "--db", db, "--dev-open"], {
+      env: { PATH: process.env.PATH ?? "", HOME: home }, stdout: "pipe", stderr: "pipe",
+    });
+    try {
+      let up = false;
+      for (let i = 0; i < 100 && !up; i++) { up = await listening(port); if (!up) await Bun.sleep(100); }
+      expect(up).toBe(true);
+      expect(existsSync(db)).toBe(true);
+      expect(existsSync(join(home, ".commhub", "commhub.db"))).toBe(false);
+    } finally {
+      child.kill();
+      await child.exited;
+    }
+  }, 30_000);
+});

package/src/db-adapter-translate.test.ts

@@ -38,6 +38,11 @@ describe("RFC-039 S2a sqliteToPostgres", () => {
     expect(sqliteToPostgres("CAST(x AS INTEGER)")).toBe("CAST(x AS BIGINT)");
   });
 
+  test("REAL → DOUBLE PRECISION (SQLite REAL is 8-byte), identifiers containing real untouched", () => {
+    expect(sqliteToPostgres("mem_used_gb REAL, realm TEXT")).toBe("mem_used_gb DOUBLE PRECISION, realm TEXT");
+    expect(sqliteToPostgres("CAST(x AS REAL)")).toBe("CAST(x AS DOUBLE PRECISION)");
+  });
+
   test("BLOB → BYTEA, identifiers containing blob untouched", () => {
     expect(sqliteToPostgres("iv BLOB NOT NULL, blob_ref TEXT")).toBe("iv BYTEA NOT NULL, blob_ref TEXT");
   });

package/src/db-adapter.ts

@@ -90,6 +90,17 @@ export class SQLiteAdapter implements DbAdapter {
   }
 
   close(): void {
+    // #2151: once more than 20 distinct SQL strings have gone through query(),
+    // bun:sqlite's close() can no longer really close the connection (measured:
+    // close(true) reports "database is locked"), so SQLite never checkpoints and
+    // a cleanly stopped Hub left its latest writes in -wal. Checkpoint first,
+    // so the .db file alone is complete after a clean stop.
+    try {
+      const r = this.rawDb.query<{ busy: number; log: number; checkpointed: number }, []>("PRAGMA wal_checkpoint(TRUNCATE)").get();
+      if (r && r.busy !== 0) console.warn(`[commhub] WAL checkpoint on close was busy: ${JSON.stringify(r)}`);
+    } catch (e) {
+      console.warn(`[commhub] WAL checkpoint on close failed: ${(e as Error)?.message ?? e}`);
+    }
     this.rawDb.close();
   }
 }
@@ -140,6 +151,9 @@ export function sqliteToPostgres(sql: string): string {
   // INTEGER → BIGINT: SQLite integers are 64-bit, and the Hub stores epoch
   // milliseconds in INTEGER columns (a 32-bit PG integer overflows).
   s = s.replace(/\bINTEGER\b/gi, "BIGINT");
+  // REAL → DOUBLE PRECISION: SQLite REAL is 8-byte; PostgreSQL REAL is 4-byte
+  // and would silently round telemetry and scores.
+  s = s.replace(/\bREAL\b/gi, "DOUBLE PRECISION");
   // BLOB → BYTEA
   s = s.replace(/\bBLOB\b/gi, "BYTEA");
   return s;

package/src/dm-file-scope-http.test.ts

@@ -0,0 +1,178 @@
+// 人与人私信的文件只给私信里的人看(owner 2026-09-30「给人好像发不了图片」的后续)。
+//
+// 规则:文件上传时带 `?purpose=dm`(App 私信输入框这么传)= 它第一次用途就是私信 → 私信文件(index scope=dm)。
+// 私信文件只有上传者、带着它的私信的收发双方、管理员能下载;同网络的其他成员和节点令牌(Agent)都 404
+// (与其它拒绝同一个形状,不泄露文件存在)。不带 purpose 上传的文件 —— 例如先在 agent 会话里发过 —— 永远不会
+// 变成私信文件,之后转进私信也照旧全网成员可见。私信文件只能由看得见它的人再转发。
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, addNetworkMember } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-dm-file-scope-"));
+const PW = "DmFileScopePassw0rd!";
+let BASE = "";
+let hub: any = null;
+let NET = "";
+type U = { token: string; id: string };
+let admin: U, alice: U, bob: U, carol: U, dave: U;
+let adminNtok = "";
+
+const auth = (t: string) => ({ Authorization: `Bearer ${t}` });
+async function upload(token: string, body: string, query: string) {
+  const form = new FormData();
+  form.append("file", new Blob([new TextEncoder().encode(body)], { type: "image/png" }), "shot.png");
+  const res = await fetch(`${BASE}/api/upload?network_id=${NET}${query}`, { method: "POST", body: form, headers: auth(token) });
+  return { status: res.status, body: await res.json().catch(() => null) as any };
+}
+async function uploadId(token: string, body: string, query = "") {
+  const r = await upload(token, body, query);
+  expect(r.status).toBe(200);
+  return r.body.file_id as string;
+}
+async function dm(from: U, to: U, fileId: string, message = "") {
+  const res = await fetch(`${BASE}/api/dm`, {
+    method: "POST",
+    headers: { ...auth(from.token), "Content-Type": "application/json" },
+    body: JSON.stringify({ network_id: NET, to_user_id: to.id, message, attachments: [{ type: "file", file_id: fileId, name: "shot.png", mime: "image/png" }] }),
+  });
+  return { status: res.status, body: await res.json().catch(() => null) as any };
+}
+const fileStatus = async (token: string, fileId: string, method = "GET") =>
+  (await fetch(`${BASE}/api/files/${fileId}`, { method, headers: auth(token) })).status;
+const entry = (fileId: string) => JSON.parse(readFileSync(join(DIR, "uploads", ".index", `${fileId}.json`), "utf8"));
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const stamp = Date.now();
+  const a = register(`dmfs_admin_${stamp}`, PW);
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [a.user!.user_id]);
+  admin = { token: a.token!, id: a.user!.user_id };
+  adminNtok = a.network_token!;
+  NET = a.network_id!;
+  // alice / bob / carol see every agent (agent_access=all) — the members for whom a network-scoped file was readable
+  // before, i.e. where the gap was. dave is a restricted member (only granted agents).
+  const mk = (name: string, agentAccess: "all" | "granted"): U => {
+    const r = register(`${name}_${stamp}`, PW);
+    expect(addNetworkMember(NET, r.user!.user_id, "member", admin.id, { agentAccess }).ok).toBe(true);
+    return { token: r.token!, id: r.user!.user_id };
+  };
+  alice = mk("dmfs_alice", "all"); bob = mk("dmfs_bob", "all"); carol = mk("dmfs_carol", "all"); dave = mk("dmfs_dave", "granted");
+  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("upload ?purpose=dm", () => {
+  test("marks the index entry; absent purpose writes no scope key (old shape)", async () => {
+    expect(entry(await uploadId(alice.token, "p1", "&purpose=dm")).scope).toBe("dm");
+    expect("scope" in entry(await uploadId(alice.token, "p2"))).toBe(false);
+  });
+  test("an unknown purpose is refused, not silently treated as network scope", async () => {
+    const r = await upload(alice.token, "p3", "&purpose=DM");
+    expect(r.status).toBe(400);
+    expect(r.body.error).toBe("bad_purpose");
+  });
+});
+
+describe("a DM file is readable only by the people in the DM", () => {
+  test("alice → bob: alice and bob read it; carol (same network, not in the DM) and agents get 404; admin reads", async () => {
+    const fid = await uploadId(alice.token, "alice-to-bob", "&purpose=dm");
+    expect((await dm(alice, bob, fid)).status).toBe(200);
+    expect(await fileStatus(alice.token, fid)).toBe(200);
+    expect(await fileStatus(bob.token, fid)).toBe(200);
+    expect(await fileStatus(carol.token, fid)).toBe(404);
+    expect(await fileStatus(carol.token, fid, "HEAD")).toBe(404);
+    expect(await fileStatus(adminNtok, fid)).toBe(404);
+    expect(await fileStatus(admin.token, fid)).toBe(200);
+  });
+  test("bob → alice (other direction): same rule", async () => {
+    const fid = await uploadId(bob.token, "bob-to-alice", "&purpose=dm");
+    expect((await dm(bob, alice, fid)).status).toBe(200);
+    expect(await fileStatus(bob.token, fid)).toBe(200);
+    expect(await fileStatus(alice.token, fid)).toBe(200);
+    expect(await fileStatus(carol.token, fid)).toBe(404);
+  });
+  test("a restricted member in the DM reads it both ways; out of it, not", async () => {
+    const toDave = await uploadId(alice.token, "alice-to-dave", "&purpose=dm");
+    expect((await dm(alice, dave, toDave)).status).toBe(200);
+    expect(await fileStatus(dave.token, toDave)).toBe(200);
+    const fromDave = await uploadId(dave.token, "dave-to-alice", "&purpose=dm");
+    expect((await dm(dave, alice, fromDave)).status).toBe(200);
+    expect(await fileStatus(alice.token, fromDave)).toBe(200);
+    expect(await fileStatus(bob.token, fromDave)).toBe(404);
+    const other = await uploadId(alice.token, "alice-to-bob-2", "&purpose=dm");
+    await dm(alice, bob, other);
+    expect(await fileStatus(dave.token, other)).toBe(404);
+  });
+  test("before it is sent, only the uploader reads it", async () => {
+    const fid = await uploadId(alice.token, "draft", "&purpose=dm");
+    expect(await fileStatus(alice.token, fid)).toBe(200);
+    expect(await fileStatus(bob.token, fid)).toBe(404);
+  });
+  test("the DM thread still returns the attachment to both sides", async () => {
+    const fid = await uploadId(alice.token, "thread", "&purpose=dm");
+    await dm(alice, bob, fid, "看图");
+    const t = await (await fetch(`${BASE}/api/dm?network_id=${NET}&with=${alice.id}`, { headers: auth(bob.token) })).json() as any;
+    expect(JSON.parse(t.messages[0].meta_json).attachments[0].file_id).toBe(fid);
+  });
+});
+
+describe("nobody unlocks a DM file by putting its id into their own DM", () => {
+  test("carol DMs alice's DM file to bob → 403, and she still can't read it", async () => {
+    const fid = await uploadId(alice.token, "secret", "&purpose=dm");
+    expect((await dm(alice, bob, fid)).status).toBe(200);
+    const r = await dm(carol, bob, fid);
+    expect(r.status).toBe(403);
+    expect(r.body.error).toBe("attachment_not_accessible");
+    expect(await fileStatus(carol.token, fid)).toBe(404);
+  });
+  test("bob (who received it) may forward it to carol, and then carol reads it", async () => {
+    const fid = await uploadId(alice.token, "forwardable", "&purpose=dm");
+    expect((await dm(alice, bob, fid)).status).toBe(200);
+    expect((await dm(bob, carol, fid)).status).toBe(200);
+    expect(await fileStatus(carol.token, fid)).toBe(200);
+  });
+});
+
+describe("files whose first use was not a DM keep their scope", () => {
+  test("uploaded in an agent chat, then forwarded into a DM → still readable by every member", async () => {
+    const fid = await uploadId(alice.token, "agent-chat-first");
+    // first use: an agent task (what ChatScreen does: upload without purpose, send_task with the file id)
+    db.run(
+      `INSERT INTO tasks (task_id, from_name, to_name, status, content, network_id, meta_json) VALUES (?1, ?2, 'dmfs-agent', 'delivered', 'see image', ?3, ?4)`,
+      [`t_dmfs_${Date.now()}`, "dmfs_alice", NET, JSON.stringify({ attachments: [{ type: "file", file_id: fid }] })],
+    );
+    expect(await fileStatus(carol.token, fid)).toBe(200);
+    expect((await dm(alice, bob, fid)).status).toBe(200);
+    expect("scope" in entry(fid)).toBe(false);
+    expect(await fileStatus(carol.token, fid)).toBe(200);
+    expect(await fileStatus(bob.token, fid)).toBe(200);
+    expect(await fileStatus(adminNtok, fid)).toBe(200);
+  });
+  test("an old app's DM upload (no purpose) behaves exactly as before", async () => {
+    const fid = await uploadId(alice.token, "old-app");
+    expect((await dm(alice, bob, fid)).status).toBe(200);
+    expect(await fileStatus(carol.token, fid)).toBe(200);
+  });
+});
+
+describe("index entry integrity", () => {
+  test("a hand-edited unknown scope makes the entry invalid (404), never network-wide", async () => {
+    const fid = await uploadId(alice.token, "tamper", "&purpose=dm");
+    const path = join(DIR, "uploads", ".index", `${fid}.json`);
+    writeFileSync(path, JSON.stringify({ ...entry(fid), scope: "public" }));
+    expect(await fileStatus(alice.token, fid)).toBe(404);
+    expect(await fileStatus(carol.token, fid)).toBe(404);
+  });
+});

package/src/human-dm.ts

@@ -11,7 +11,7 @@ import { getUserNetworkRole } from "./auth.js";
 import { isAgentRestricted } from "./agent-access.js";
 import { pushUserEvent, hasUserSubscribers } from "./push.js";
 import { existsSync, readFileSync } from "fs";
-import { FILE_ID_REGEX, indexEntryPath, validateAttachments, validateIndexEntry } from "./uploads.js";
+import { DM_FILE_SCOPE, FILE_ID_REGEX, indexEntryPath, validateAttachments, validateIndexEntry, type UploadIndexEntry } from "./uploads.js";
 import { restrictedMemberCanUseFile } from "./restricted-files.js";
 import { redactMessageRow } from "./redact-tokens.js";
 
@@ -57,10 +57,16 @@ export function sendHumanDm(input: HumanDmSendInput): HumanDmSendResult {
   for (const a of attachments.attachments) {
     const fileId = (a as { file_id?: string }).file_id;
     if (!fileId) continue;
+    const entry = networkFileEntry(networkId, fileId);
     const usable = restricted
       ? restrictedMemberCanUseFile(sender.userId, sender.username, networkId, fileId)
-      : fileInNetwork(networkId, fileId);
+      : !!entry;
     if (!usable) return { ok: false, error: "attachment_not_accessible", status: 403 };
+    // 私信文件只能由看得见它的人转发:否则任何成员把别人私信里的 file_id 塞进一条自己发出的私信,
+    // 就成了「私信参与者」而解锁它。上传者本人、以及已经在某段私信里收到/发出过它的人可以转。
+    if (entry?.scope === DM_FILE_SCOPE && entry.owner_id !== sender.userId && !dmParticipantSeesFile(sender.userId, networkId, fileId)) {
+      return { ok: false, error: "attachment_not_accessible", status: 403 };
+    }
   }
 
   const clientRequestId = typeof input.clientRequestId === "string" && /^[A-Za-z0-9._-]{1,80}$/.test(input.clientRequestId)
@@ -107,15 +113,36 @@ export function sendHumanDm(input: HumanDmSendInput): HumanDmSendResult {
   return { ok: true, message: redactMessageRow(row), delivered };
 }
 
-/** 不受限的成员带附件:文件必须属于这个网络(防把别的网络的 file_id 塞进来)。 */
-function fileInNetwork(networkId: string, fileId: string): boolean {
-  if (!FILE_ID_REGEX.test(fileId)) return false;
+/** 带附件:文件必须属于这个网络(防把别的网络的 file_id 塞进来)。返回它的索引条目,不属于 → null。 */
+function networkFileEntry(networkId: string, fileId: string): UploadIndexEntry | null {
+  if (!FILE_ID_REGEX.test(fileId)) return null;
   const path = indexEntryPath(fileId);
-  if (!path || !existsSync(path)) return false;
+  if (!path || !existsSync(path)) return null;
   try {
     const entry = JSON.parse(readFileSync(path, "utf8"));
-    return validateIndexEntry(entry) && entry.file_id === fileId && entry.network_id === networkId;
-  } catch { return false; }
+    return validateIndexEntry(entry) && entry.file_id === fileId && entry.network_id === networkId ? entry : null;
+  } catch { return null; }
+}
+
+/**
+ * 这个用户是不是某段带着这个文件的私信里的一方(收到的或发出的)。私信文件(scope=dm)的下载只认它
+ * 和上传者本人(server.ts authorizeFileDownload)。LIKE 只做预筛,真正的判定按 attachments 键解析。
+ */
+export function dmParticipantSeesFile(userId: string, networkId: string, fileId: string): boolean {
+  if (!FILE_ID_REGEX.test(fileId)) return false;
+  const needle = `%"${fileId.replace(/_/g, "\\_")}"%`;
+  const rows = db.all<{ meta_json: string | null }>(
+    `SELECT meta_json FROM user_inbox
+      WHERE network_id = ?1 AND kind = '${HUMAN_DM_KIND}' AND (user_id = ?2 OR sender_user_id = ?2)
+        AND meta_json LIKE ?3 ESCAPE '\\' LIMIT 50`,
+    networkId, userId, needle,
+  );
+  return rows.some((row) => {
+    try {
+      const list = JSON.parse(row.meta_json ?? "null")?.attachments;
+      return Array.isArray(list) && list.some((a: any) => a && typeof a === "object" && a.file_id === fileId);
+    } catch { return false; }
+  });
 }
 
 /** 我和某人的私信记录(双向),新的在前。before = 上一页最后一条的 created_at。 */