@sleep2agi/commhub-server 0.9.0-preview.13 → 0.9.0-preview.130

package/src/user-inbox-by-agent-http.test.ts

@@ -0,0 +1,161 @@
+// #1828 —— /api/messages?scope=user 按 agent 分的未读 + 用户 ack 覆盖 inbox 里的回复行。
+//
+// 生产 hub 24h:admin 收到的 70 条 agent 回复全在 `inbox`(session_name='admin', type='reply',
+// acked 永远 0),`user_inbox` 只有 2 行;角标链只读 user_inbox,所以回复从不进未读(app#260)。
+// 这里让 scope=user 同时给 `unread_by_agent`(两表合并)与 `unread_total`,`unread`/`pending_count`
+// 口径不动(qa-hub-14 钉着);POST /api/messages/ack 也能 ack inbox 里发给调用者用户名的回复行。
+//
+// 承重的是两条边界:
+//   ① 只算/只 ack **调用者自己用户名** 的 inbox 行 —— B 拿 A 的 id 来 ack 匹配不到;
+//   ② 用户名与某节点 alias 撞名时,inbox 那半边整体跳过(那是节点的待办,不是用户的)。
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-user-inbox-by-agent-"));
+process.env.COMMHUB_DB ||= join(PRIVATE_DB_DIR, "hub.db");
+
+let server: ReturnType<typeof Bun.serve>;
+let base = "";
+let aToken = "", bToken = "", cToken = "";
+let aUserId = "", bUserId = "", cUserId = "", aNet = "", cNet = "";
+let aName = "", bName = "", cName = "";
+
+const get = async (path: string, token: string) => {
+  const r = await fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${token}` } });
+  return { status: r.status, body: await r.json() as any };
+};
+const post = async (path: string, token: string, body: unknown) => {
+  const r = await fetch(`${base}${path}`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return { status: r.status, body: await r.json() as any };
+};
+
+function seedUserInbox(mid: string, userId: string, netId: string, from: string) {
+  const { db } = require("./db.js");
+  db.run(
+    `INSERT INTO user_inbox (message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json, acked)
+     VALUES (?1, ?2, ?3, ?4, 'agent_message', NULL, 'dm', 'info', NULL, 0)`,
+    [mid, netId, userId, from],
+  );
+}
+function seedInbox(id: string, sessionName: string, netId: string, from: string, type = "reply", acked = 0) {
+  const { db } = require("./db.js");
+  db.run(
+    `INSERT INTO inbox (id, session_name, type, priority, content, from_session, acked, network_id, created_at)
+     VALUES (?1, ?2, ?3, 'normal', 'reply body', ?4, ?5, ?6, datetime('now'))`,
+    [id, sessionName, type, from, acked, netId],
+  );
+}
+
+beforeAll(async () => {
+  process.env.COMMHUB_AUTH_TOKEN ||= "legacy-master-token-for-test";
+  const { db } = await import("./db.js");
+  const { register, addNetworkMember } = await import("./auth.js");
+  const stamp = Date.now();
+
+  // 首个注册用户 = 全局 admin;探针 A/B/C 都不是 admin(admin 走不过滤分支,隔离断言会白过)。
+  const admin = register(`uba_admin_${stamp}`, "UbaAdmin-Strong-1!");
+  expect(admin.ok).toBe(true);
+  aName = `uba_a_${stamp}`; bName = `uba_b_${stamp}`; cName = `uba_c_${stamp}`;
+  const a = register(aName, "UbaA-Strong-1!");
+  const b = register(bName, "UbaB-Strong-1!");
+  const c = register(cName, "UbaC-Strong-1!");
+  expect(a.ok && b.ok && c.ok).toBe(true);
+  aToken = a.token!; bToken = b.token!; cToken = c.token!;
+  aNet = a.network_id!; cNet = c.network_id!;
+  const uid = (name: string) => db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", name)!.user_id;
+  aUserId = uid(aName); bUserId = uid(bName); cUserId = uid(cName);
+  for (const id of [aUserId, bUserId, cUserId]) {
+    expect(db.get<{ role: string }>("SELECT role FROM users WHERE user_id = ?1", id)?.role).toBe("user");
+  }
+  // B 与 A 同网:user_id / session_name 过滤是唯一的隔离手段。
+  expect(addNetworkMember(aNet, bUserId, "member").ok).toBe(true);
+
+  // A:user_inbox 两条(node-x),inbox 回复两条(peer-1)+ 一条已 ack + 一条 status 类(不算)。
+  seedUserInbox("dm_a1", aUserId, aNet, "node-x");
+  seedUserInbox("dm_a2", aUserId, aNet, "node-x");
+  seedInbox("ib_a1", aName, aNet, "peer-1");
+  seedInbox("ib_a2", aName, aNet, "peer-1");
+  seedInbox("ib_a_acked", aName, aNet, "peer-1", "reply", 1);
+  seedInbox("ib_a_status", aName, aNet, "peer-1", "status");
+  // B 同网:自己的一条回复;不该出现在 A 的数里。
+  seedInbox("ib_b1", bName, aNet, "peer-2");
+  // C:用户名撞节点 alias —— inbox 里那行是节点的待办。
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at)
+     VALUES (?1, ?2, ?3, ?4, datetime('now'), datetime('now'))`,
+    [`node_${stamp}`, cName, cName, cNet],
+  );
+  seedInbox("ib_c_node_task", cName, cNet, "leader", "task");
+  seedUserInbox("dm_c1", cUserId, cNet, "node-y");
+
+  const mod = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+});
+
+afterAll(() => {
+  try { server?.stop(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("#1828 GET /api/messages?scope=user unread_by_agent", () => {
+  test("A:user_inbox + inbox 回复按 agent 合并;unread/pending_count 口径不变", async () => {
+    const { status, body } = await get("/api/messages?scope=user", aToken);
+    expect(status).toBe(200);
+    expect(body.unread).toBe(2);                 // 只算 user_inbox(qa-hub-14 钉着)
+    expect(body.pending_count).toBe(2);
+    expect(body.unread_by_agent).toEqual({ "node-x": 2, "peer-1": 2 }); // 已 ack 与 status 类不算
+    expect(body.unread_total).toBe(4);
+  });
+
+  test("B(同网):只看到自己的回复,看不到 A 的", async () => {
+    const { body } = await get("/api/messages?scope=user", bToken);
+    expect(body.unread_by_agent).toEqual({ "peer-2": 1 });
+    expect(body.unread_total).toBe(1);
+  });
+
+  test("🔴 C 的用户名撞节点 alias:inbox 半边整体跳过,只剩 user_inbox", async () => {
+    const { body } = await get("/api/messages?scope=user", cToken);
+    expect(body.unread_by_agent).toEqual({ "node-y": 1 });
+    expect(body.unread_total).toBe(1);
+  });
+});
+
+describe("#1828 POST /api/messages/ack covers inbox reply rows", () => {
+  test("🔴 B 拿 A 的 inbox id 来 ack:匹配不到,A 的数不动", async () => {
+    const { body } = await post("/api/messages/ack", bToken, { message_ids: ["ib_a1"] });
+    expect(body).toMatchObject({ ok: true, acked: 0, acked_inbox: 0 });
+    const a = await get("/api/messages?scope=user", aToken);
+    expect(a.body.unread_by_agent["peer-1"]).toBe(2);
+  });
+
+  test("A ack 一条 inbox 回复 + 一条 user_inbox:两边各减一,响应分开计数", async () => {
+    const { body } = await post("/api/messages/ack", aToken, { message_ids: ["ib_a1", "dm_a1"] });
+    expect(body).toMatchObject({ ok: true, acked: 2, acked_user_inbox: 1, acked_inbox: 1 });
+    const a = await get("/api/messages?scope=user", aToken);
+    expect(a.body.unread).toBe(1);
+    expect(a.body.unread_by_agent).toEqual({ "node-x": 1, "peer-1": 1 });
+    expect(a.body.unread_total).toBe(2);
+    // 再 ack 同一条:幂等,0 行。
+    const again = await post("/api/messages/ack", aToken, { message_ids: ["ib_a1"] });
+    expect(again.body.acked).toBe(0);
+  });
+
+  test("status 类 inbox 行不会被用户 ack 掉(不是发给用户的消息)", async () => {
+    const { body } = await post("/api/messages/ack", aToken, { message_ids: ["ib_a_status"] });
+    expect(body.acked_inbox).toBe(0);
+  });
+
+  test("🔴 C 撞名:节点的待办不能被用户 ack 走", async () => {
+    const { body } = await post("/api/messages/ack", cToken, { message_ids: ["ib_c_node_task"] });
+    expect(body.acked_inbox).toBe(0);
+    const { db } = require("./db.js");
+    expect(db.get<{ acked: number }>("SELECT acked FROM inbox WHERE id = 'ib_c_node_task'")?.acked).toBe(0);
+  });
+});

package/src/user-inbox-netid-notnull.test.ts

@@ -0,0 +1,122 @@
+// #1493 — user_inbox.network_id 升 schema 级 NOT NULL(belt-and-suspenders)。
+//
+// 「不产生 NULL 孤儿」原是代码级三闸(#1492 证不可达)。schema 级 NOT NULL 让**任何**
+// 未来绕过那三闸写 NULL 的回归在 INSERT 处被 DB 直接拒,而不是产出 scoped-unreadable
+// 的静默孤儿。生产 hub 已在 preview.41、user_inbox 有真实行 → 迁移必须:① 新库直接
+// NOT NULL;② 存量库无损重建(建新表→copy→drop→rename);③ 迁移前若发现 NULL 行(理应
+// 为 0)fail-closed 停下,不静默丢。
+//
+// 后两条要预置「旧 schema(nullable)」的库 → 用 bun:sqlite 手造库 + 子进程 import db.js
+// 触发迁移(与 boot-side-effect.test.ts 同款子进程范式)。
+
+import { describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { db } from "./db.js";
+
+const OLD_SCHEMA = `CREATE TABLE user_inbox (
+  message_id TEXT PRIMARY KEY, network_id TEXT, user_id TEXT NOT NULL, from_session TEXT,
+  kind TEXT NOT NULL DEFAULT 'info', title TEXT, content TEXT NOT NULL,
+  severity TEXT NOT NULL DEFAULT 'info', meta_json TEXT, acked INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')), acked_at TEXT)`;
+
+/** 预置一个「旧 schema(network_id 可空)」的库文件,可选带若干行。返回文件路径。 */
+function seedOldDb(rows: Array<{ mid: string; net: string | null; user: string }>): string {
+  const file = join(mkdtempSync(join(tmpdir(), "anet-1493-")), "hub.db");
+  const raw = new Database(file);
+  raw.exec(OLD_SCHEMA);
+  for (const r of rows) {
+    raw.run("INSERT INTO user_inbox (message_id, network_id, user_id, content) VALUES (?1, ?2, ?3, 'body')",
+      [r.mid, r.net, r.user]);
+  }
+  raw.close();
+  return file;
+}
+
+/** 子进程里 import db.js(触发迁移),回读一段结果。返回 {exitCode, stdout, stderr}。 */
+function bootWithDb(file: string, probe: string) {
+  const script = `
+    process.env.COMMHUB_DB = ${JSON.stringify(file)};
+    const { db } = await import("./src/db.js");
+    ${probe}
+    process.exit(0);
+  `;
+  const child = Bun.spawnSync({
+    cmd: ["bun", "-e", script],
+    cwd: `${import.meta.dir}/..`,
+    env: { ...process.env, COMMHUB_DB: file },
+    timeout: 20_000,
+  });
+  return {
+    exitCode: child.exitCode,
+    stdout: new TextDecoder().decode(child.stdout),
+    stderr: new TextDecoder().decode(child.stderr),
+  };
+}
+
+describe("#1493 user_inbox.network_id NOT NULL (belt-and-suspenders)", () => {
+  test("new DB: network_id is NOT NULL and rejects a NULL insert", () => {
+    const col = db.all<{ name: string; notnull: number }>("PRAGMA table_info(user_inbox)").find(c => c.name === "network_id");
+    expect(col?.notnull).toBe(1);
+    // 绕过代码闸直接写 NULL → DB 拒(这正是 belt-and-suspenders 的价值)
+    expect(() => db.run(
+      "INSERT INTO user_inbox (message_id, user_id, content) VALUES (?1, ?2, ?3)",
+      [`dm_nn_${Date.now()}`, "u_nn", "hi"],
+    )).toThrow(/NOT NULL/i);
+  });
+
+  test("migration: old nullable table with valid rows → rebuilt NOT NULL, rows preserved, index recreated", () => {
+    const file = seedOldDb([
+      { mid: "dm_1", net: "net_a", user: "u_1" },
+      { mid: "dm_2", net: "net_b", user: "u_2" },
+    ]);
+    const r = bootWithDb(file, `
+      const col = db.all("PRAGMA table_info(user_inbox)").find(c => c.name === "network_id");
+      const rows = db.get("SELECT COUNT(*) AS n FROM user_inbox").n;
+      const idx = db.get("SELECT COUNT(*) AS n FROM sqlite_master WHERE type='index' AND name='idx_user_inbox_user_acked'").n;
+      let nullRejected = false;
+      try { db.run("INSERT INTO user_inbox (message_id, user_id, content) VALUES ('dm_z','u_z','x')"); }
+      catch { nullRejected = true; }
+      console.log("RESULT:" + JSON.stringify({ notnull: col.notnull, rows, idx, nullRejected }));
+    `);
+    expect(r.exitCode).toBe(0);
+    const m = r.stdout.match(/RESULT:(\{.*\})/);
+    expect(m).not.toBeNull();
+    const out = JSON.parse(m![1]);
+    expect(out.notnull).toBe(1);      // 迁移后 NOT NULL
+    expect(out.rows).toBe(2);          // 两行无损保留
+    expect(out.idx).toBe(1);           // 索引重建
+    expect(out.nullRejected).toBe(true);
+  });
+
+  test("migration guard: old table with a network_id IS NULL row → fail-safe (warn + skip, hub boots, data intact)", () => {
+    const file = seedOldDb([
+      { mid: "dm_ok", net: "net_a", user: "u_1" },
+      { mid: "dm_orphan", net: null, user: "u_2" },   // 理应不可达;若真出现 → warn+跳过,不停机
+    ]);
+    const r = bootWithDb(file, `
+      const col = db.all("PRAGMA table_info(user_inbox)").find(c => c.name === "network_id");
+      const rows = db.get("SELECT COUNT(*) AS n FROM user_inbox").n;
+      console.log("RESULT:" + JSON.stringify({ notnull: col.notnull, rows }));
+    `);
+    expect(r.exitCode).toBe(0);                          // hub 照常启动(fail-safe,不停机)
+    expect(r.stderr).toMatch(/migrate #1493/);            // 大声 warn(明确运维信号)
+    expect(r.stderr).toMatch(/network_id IS NULL/);
+    const m = r.stdout.match(/RESULT:(\{.*\})/);
+    expect(m).not.toBeNull();
+    const out = JSON.parse(m![1]);
+    expect(out.notnull).toBe(0);                          // 迁移被跳过 → 列暂保持可空
+    expect(out.rows).toBe(2);                             // 数据没丢(没盲目清空)
+  });
+
+  test("idempotent: booting an already-migrated (NOT NULL) DB twice is a no-op", () => {
+    const file = seedOldDb([{ mid: "dm_a", net: "net_a", user: "u_1" }]);
+    const r1 = bootWithDb(file, `console.log("RESULT:" + db.all("PRAGMA table_info(user_inbox)").find(c=>c.name==="network_id").notnull);`);
+    expect(r1.exitCode).toBe(0);
+    const r2 = bootWithDb(file, `console.log("RESULT:" + db.all("PRAGMA table_info(user_inbox)").find(c=>c.name==="network_id").notnull);`);
+    expect(r2.exitCode).toBe(0);
+    expect(r2.stdout).toContain("RESULT:1");              // 第二次仍 NOT NULL、不炸
+  });
+});

package/src/user-inbox-read-http.test.ts

@@ -0,0 +1,223 @@
+// #1459 ① P3 —— per-user 收件回读 + ack + 未读数 + redact-at-read。
+//
+// 承重的是**隔离**：A 只能读到 A 的。所以下面每条隔离断言都额外钉住探针身份 ——
+// 首个注册用户会自动成为全局 admin，而 admin 在别处走的是不过滤的分支；
+// 若探针恰好是 admin，隔离断言会"通过但什么都没证明"（#500/#506 同款）。
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-user-inbox-read-"));
+process.env.COMMHUB_DB ||= join(PRIVATE_DB_DIR, "hub.db");
+
+let server: ReturnType<typeof Bun.serve>;
+let base = "";
+let adminToken = "", aToken = "", bToken = "";
+const MASTER_TOKEN = "legacy-master-token-for-test";
+let aUserId = "", bUserId = "", aNet = "", bNet = "";
+let adminUserId = "", adminNet = "";
+
+const get = async (path: string, token: string) => {
+  const r = await fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${token}` } });
+  return { status: r.status, body: await r.json() as any };
+};
+const post = async (path: string, token: string, body: unknown) => {
+  const r = await fetch(`${base}${path}`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return { status: r.status, body: await r.json() as any };
+};
+
+function seedMessage(mid: string, userId: string, netId: string, content: string, meta?: string, acked = 0) {
+  const { db } = require("./db.js");
+  db.run(
+    `INSERT INTO user_inbox (message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json, acked, acked_at)
+     VALUES (?1, ?2, ?3, 'node-x', 'agent_message', NULL, ?4, 'info', ?5, ?6, ?7)`,
+    [mid, netId, userId, content, meta ?? null, acked, acked ? "2026-01-01 00:00:00" : null],
+  );
+}
+
+beforeAll(async () => {
+  // 传统全局 master token：requireAuth 对 GET /api/* 放行，但 resolveRequestAuth
+  // 返回 null（没有 user）。这条路径是分支内 `if (!callerUserId)` 唯一能被触发的
+  // 场景 —— 必须在 import server.js 之前设，AUTH_TOKEN 是模块加载期读的常量。
+  process.env.COMMHUB_AUTH_TOKEN ||= MASTER_TOKEN;
+
+  const { db } = await import("./db.js");
+  const { register, addNetworkMember } = await import("./auth.js");
+  const stamp = Date.now();
+
+  // 首个注册用户 = 全局 admin。**故意先注册一个用不到的 admin**，这样下面
+  // 两个探针 A/B 都不是 admin —— 隔离断言才有分辨力。
+  const admin = register(`ui_admin_${stamp}`, "UiAdmin-Strong-1!");
+  expect(admin.ok).toBe(true);
+  adminToken = admin.token!;
+  adminUserId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", `ui_admin_${stamp}`)!.user_id;
+  adminNet = admin.network_id!;
+
+  const a = register(`ui_a_${stamp}`, "UiA-Strong-1!");
+  const b = register(`ui_b_${stamp}`, "UiB-Strong-1!");
+  expect(a.ok && b.ok).toBe(true);
+  aToken = a.token!; bToken = b.token!;
+  aNet = a.network_id!; bNet = b.network_id!;
+  aUserId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", `ui_a_${stamp}`)!.user_id;
+  bUserId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", `ui_b_${stamp}`)!.user_id;
+
+  // 前提断言：探针不是 admin。靠"注册顺序"是隐式前提，会随夹具变化悄悄失效，
+  // 所以显式断言。
+  // 承重的是 role ≠ "admin"；这里钉死具体值（auth.ts:88 非首用户写 "user"），
+  // 因为 `not.toBe("admin")` 在 role 为 undefined（查不到行）时也会通过 —— 松判据
+  // 会朝"没问题"那边失败。
+  for (const [name, id] of [["A", aUserId], ["B", bUserId]] as const) {
+    const role = db.get<{ role: string }>("SELECT role FROM users WHERE user_id = ?1", id)?.role;
+    expect([name, role]).toEqual([name, "user"]);
+  }
+
+  // 🔴 B 必须在**同一个 network** 里也有一条私信。
+  //    第一版夹具让 A/B 各处一网，于是 addNetworkScope 顺手挡住了 B 的行 ——
+  //    变异掉 `WHERE user_id = ?1` 后隔离断言照样通过（M1/M2/M4 全部存活）。
+  //    同网同事之间，user_id 过滤是**唯一**的隔离手段，夹具必须落在那一格。
+  expect(addNetworkMember(aNet, bUserId, "member").ok).toBe(true);
+
+  seedMessage("dm_a1", aUserId, aNet, "A 的第一条");
+  seedMessage("dm_a2", aUserId, aNet, "A 的第二条");
+  seedMessage("dm_b_same_net", bUserId, aNet, "B 在 A 同网里的私信");
+  seedMessage("dm_b1", bUserId, bNet, "B 的私信");
+  // A 自己的、但落在 A 不是成员的 network 上的行（例如 A 被移出该网后的遗留）。
+  // 它是 addNetworkScope 这次调用的唯一 witnessed-red 对象：user_id 过滤对它无效。
+  seedMessage("dm_a_foreign_net", aUserId, bNet, "A 在外网的遗留私信");
+  // #1493 —— network_id 升到 schema 级 NOT NULL 后,「network_id 为 NULL 的行」已
+  // **schema 级不可能**(写路径原本三闸挡、现在 DB 直接拒)。原先手播的 dm_a_nonet /
+  // dm_admin_nonet 两条 NULL 夹具随之删除:
+  //   · dm_a_nonet(证"受网络限制成员读不到 NULL 行")—— 网络 scope 隔离已由下面
+  //     dm_a_foreign_net(A 自己的行、落在 A 非成员的网)覆盖,不丢覆盖。
+  //   · dm_admin_nonet 重锚到 admin **自己网络**的非 NULL 行 dm_admin_own,保住
+  //     "admin(scope 助手 no-op)仍只读自己的、不绕过 user_id 过滤"这条覆盖。
+  seedMessage("dm_admin_own", adminUserId, adminNet, "admin 自己网络里的私信");
+  // #1493 SDK马 建议:用**非 NULL** 行补回"admin(scope 助手 no-op)能读到别网的自己的行"
+  // 这维覆盖(原先靠 NULL 行,现 NULL 不可能)。对照 dm_a_foreign_net(受限成员读不到),
+  // 两边都不依赖 NULL。
+  seedMessage("dm_admin_foreign_net", adminUserId, bNet, "admin 在别网的自己的私信");
+  seedMessage("dm_a_read", aUserId, aNet, "A 已读的一条", undefined, 1);
+  seedMessage("dm_a_secret", aUserId, aNet,
+    "凭据在正文里 ntok_abcdef123456", JSON.stringify({ k: "ghp_" + "A".repeat(24) }));
+
+  const mod = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+});
+
+afterAll(() => {
+  try { server?.stop(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("#1459 ① P3 GET /api/messages?scope=user", () => {
+  test("🔴 只返回调用者自己的消息 —— A 读不到 B 的", async () => {
+    const { status, body } = await get("/api/messages?scope=user", aToken);
+    expect(status).toBe(200);
+    expect(body.ok).toBe(true);
+    const ids = body.messages.map((m: any) => m.message_id);
+    expect(ids).toContain("dm_a1");
+    expect(ids).toContain("dm_a_read");          // 不加 unacked 时已读也要回来
+    expect(ids).not.toContain("dm_b_same_net");  // 承重：同网，只有 user_id 过滤挡得住
+    expect(ids).not.toContain("dm_b1");          // 跨网，scope 助手挡
+    expect(ids).not.toContain("dm_a_foreign_net"); // 承重：A 自己的行，只有 scope 助手挡得住
+    expect(body.messages.every((m: any) => m.user_id === aUserId)).toBe(true);
+  });
+
+  test("🔴 收件人取自 auth ctx —— query 里指定别人的 user_id 无效", async () => {
+    const { body } = await get(`/api/messages?scope=user&user_id=${bUserId}`, aToken);
+    const ids = body.messages.map((m: any) => m.message_id);
+    expect(ids).not.toContain("dm_b_same_net");
+    expect(ids).not.toContain("dm_b1");
+    expect(body.messages.every((m: any) => m.user_id === aUserId)).toBe(true);
+  });
+
+  test("🔴 redact-at-read：正文与 meta 里的凭据形状被遮住", async () => {
+    const { body } = await get("/api/messages?scope=user", aToken);
+    const row = body.messages.find((m: any) => m.message_id === "dm_a_secret");
+    expect(row).toBeTruthy();
+    expect(row.content).toContain("ntok_***redacted***");
+    expect(row.content).not.toContain("ntok_abcdef123456");
+    expect(row.meta_json).toContain("ghp_***redacted***");
+  });
+
+  // #1493 后 NULL 网络行不可能,原"受网络限制成员读不到 NULL 行"一测删除——
+  // 网络 scope 隔离已由上面 dm_a_foreign_net(承重断言,test 112 line 121)覆盖。
+  // admin 一测重锚到非 NULL:验 admin(scope 助手 no-op)**仍只读自己的、不绕过 user_id 过滤**。
+  test("admin(scope 助手 no-op)仍受 user_id 限制：只读自己的、不读别人的", async () => {
+    const { body } = await get("/api/messages?scope=user", adminToken);
+    const ids = body.messages.map((m: any) => m.message_id);
+    expect(ids).toContain("dm_admin_own");            // 读得到自己的
+    expect(ids).toContain("dm_admin_foreign_net");     // scope 助手 no-op → 跨网也读得到自己的
+    expect(ids).not.toContain("dm_a1");                // 承重:admin 不绕过 user_id 过滤读别人的
+    expect(body.messages.every((m: any) => m.user_id === adminUserId)).toBe(true);
+  });
+
+  test("unread 是未读数而非总数（A：4 条里 3 条未读）", async () => {
+    const { body } = await get("/api/messages?scope=user", aToken);
+    expect(body.messages.length).toBe(4);
+    expect(body.unread).toBe(3);
+    expect(body.pending_count).toBe(body.unread);
+  });
+
+  test("unacked=1 排掉已读那条", async () => {
+    const { body } = await get("/api/messages?scope=user&unacked=1", aToken);
+    const ids = body.messages.map((m: any) => m.message_id);
+    expect(ids).not.toContain("dm_a_read");      // 承重：集合里确实有已读行才有分辨力
+    expect(ids.sort()).toEqual(["dm_a1", "dm_a2", "dm_a_secret"]);
+  });
+
+  test("未鉴权 ⇒ 401（/api 全局闸）", async () => {
+    const r = await fetch(`${base}/api/messages?scope=user`);
+    expect(r.status).toBe(401);
+  });
+
+  test("🔴 legacy master token 过得了全局闸但没有 user ⇒ 401，不能回一个空列表", async () => {
+    // 这条才是分支内 `if (!callerUserId)` 的 witnessed-red：把它换成
+    // `?? ""` 后本条从 401 变成 200 + 空列表 —— "看起来正常"的错误答案。
+    const { status, body } = await get("/api/messages?scope=user", MASTER_TOKEN);
+    expect([status, body.error]).toEqual([401, "auth_required"]);
+  });
+
+  test("alias 分支未受影响（dashboard 依赖它）", async () => {
+    const { status, body } = await get("/api/messages", adminToken);
+    expect(status).toBe(200);
+    expect(body.ok).toBe(true);
+    expect(Array.isArray(body.messages)).toBe(true);
+    expect(body.unread).toBeUndefined();          // 老分支不该多出新字段
+  });
+});
+
+describe("#1459 ① P3 POST /api/messages/ack", () => {
+  test("ack 自己的消息 ⇒ acked 置位、未读数下降", async () => {
+    const before = (await get("/api/messages?scope=user", aToken)).body.unread;
+    const { status, body } = await post("/api/messages/ack", aToken, { message_id: "dm_a1" });
+    expect(status).toBe(200);
+    expect(body.acked).toBe(1);
+    const after = (await get("/api/messages?scope=user", aToken)).body.unread;
+    expect(after).toBe(before - 1);
+  });
+
+  test("🔴 ack 不了同网同事的消息 —— 改动行数为 0，且对方仍是未读", async () => {
+    const { body } = await post("/api/messages/ack", aToken, { message_id: "dm_b_same_net" });
+    expect(body.acked).toBe(0);
+    const bView = (await get("/api/messages?scope=user", bToken)).body;
+    expect(bView.messages.find((m: any) => m.message_id === "dm_b_same_net").acked).toBe(0);
+  });
+
+  test("ack 跨网的消息同样为 0", async () => {
+    const { body } = await post("/api/messages/ack", aToken, { message_id: "dm_b1" });
+    expect(body.acked).toBe(0);
+  });
+
+  test("缺参 ⇒ 400；未鉴权 ⇒ 401", async () => {
+    expect((await post("/api/messages/ack", aToken, {})).status).toBe(400);
+    const r = await fetch(`${base}/api/messages/ack`, { method: "POST", body: "{}" });
+    expect(r.status).toBe(401);
+  });
+});

package/src/user-inbox-schema.test.ts

@@ -0,0 +1,54 @@
+// #1459 ① — user_inbox 建表 + 幂等打底(P1)。零行为变化,只落 schema。
+//
+// 承重属性(SDK马 review 要点):message_id 即主键 → send_desktop_message 因 HTTP
+// 响应丢失被重试时,同一 dm_<uuid> 用 INSERT OR IGNORE 不会插出重复行(前端免去重)。
+
+import { describe, expect, test } from "bun:test";
+import { db } from "./db.js";
+
+describe("#1459 user_inbox schema (P1)", () => {
+  test("table exists with the expected columns", () => {
+    const cols = db.all<{ name: string }>("PRAGMA table_info(user_inbox)").map(c => c.name);
+    for (const c of ["message_id", "network_id", "user_id", "from_session", "kind", "title", "content", "severity", "meta_json", "acked", "created_at", "acked_at"]) {
+      expect(cols).toContain(c);
+    }
+  });
+
+  // 注:这条钉的是「主键在我们以为的那一列」(SQLite 行为),**不是**「写入路径幂等」——
+  // 后者要 P2 驱动真实 send_desktop_message 两次来证(SDK马 review)。这里只保证主键选对。
+  test("message_id is PRIMARY KEY → INSERT OR IGNORE dedups on the same id", () => {
+    const mid = `dm_test_${Date.now()}`;
+    try {
+      const ins = () => db.run(
+        `INSERT OR IGNORE INTO user_inbox (message_id, network_id, user_id, from_session, content)
+         VALUES (?1, ?2, ?3, ?4, ?5)`,
+        [mid, "net_test_1459", "u_test_1459", "sender-a", "hello"],
+      );
+      ins();
+      ins();   // 同 message_id 第二次插入应被 IGNORE
+      const n = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM user_inbox WHERE message_id = ?1", mid)?.n ?? 0;
+      expect(n).toBe(1);
+    } finally {
+      db.run("DELETE FROM user_inbox WHERE message_id = ?1", mid);
+    }
+  });
+
+  test("defaults: acked=0, kind/severity='info'", () => {
+    const mid = `dm_def_${Date.now()}`;
+    try {
+      db.run(
+        // #1493 后 network_id 是 NOT NULL,补上(本测试只验其它列的默认值)
+        `INSERT INTO user_inbox (message_id, network_id, user_id, content) VALUES (?1, ?2, ?3, ?4)`,
+        [mid, "net_def_1459", "u_def_1459", "body"],
+      );
+      const row = db.get<{ acked: number; kind: string; severity: string }>(
+        "SELECT acked, kind, severity FROM user_inbox WHERE message_id = ?1", mid,
+      );
+      expect(row?.acked).toBe(0);
+      expect(row?.kind).toBe("info");
+      expect(row?.severity).toBe("info");
+    } finally {
+      db.run("DELETE FROM user_inbox WHERE message_id = ?1", mid);
+    }
+  });
+});