@sleep2agi/commhub-server 0.9.0-preview.4 → 0.9.0-preview.41

package/src/uploads.ts

@@ -53,6 +53,17 @@ export const UPLOAD_RATE_MAX_ENTRIES = 50_000;
 // traversal.
 export const FILE_ID_REGEX = /^[A-Za-z0-9_-]{8,64}$/;
 
+// Stored extension tokens have one invariant at every path boundary:
+// either no extension, or a leading dot followed by 1-16 ASCII
+// alphanumeric characters. Keep this separate from sanitizeExt(), which
+// parses a client filename and therefore deliberately has different
+// capture/anchoring semantics.
+const EXT_TOKEN_REGEX = /^\.[A-Za-z0-9]{1,16}$/;
+
+function isValidExtToken(ext: unknown): ext is string {
+  return typeof ext === "string" && (ext === "" || EXT_TOKEN_REGEX.test(ext));
+}
+
 export type GeneratedFile = {
   fileId: string;
   ext: string;
@@ -94,14 +105,51 @@ export function sanitizeExt(filename: string | undefined | null): string {
   return match ? "." + match[1].toLowerCase() : "";
 }
 
+// YYYY-MM-DD bucket string regex — matches what getDateBucket produces
+// and what an index entry's `date_bucket` field is validated against.
+const DATE_BUCKET_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+
 /**
- * Build the per-upload storage path. The file_id and ext are validated
- * against strict regexes; any path-separator or `..` segment from a
- * malicious client gets rejected at the regex layer before any I/O.
+ * Validate a date_bucket string against BOTH shape (YYYY-MM-DD regex)
+ * AND real-calendar semantics: rejects "2026-02-30", "2026-13-01",
+ * "2026-00-15", leap-day-on-non-leap-year, etc. Shape-only check is not
+ * enough because the regex accepts any digit combination in each
+ * position.
+ *
+ * Used as a pre-check by the download handler before it calls into
+ * pathForExistingBlob — a non-calendar bucket is a 404 (invalid input
+ * rejected at the boundary), NOT a 500 (uncaught throw from deep in
+ * the read path). Distinguishing these matters: 500 says "server
+ * failed"; 404 says "we know your request is bad, refused early".
+ */
+export function isValidCalendarBucket(bucket: unknown): bucket is string {
+  if (typeof bucket !== "string") return false;
+  if (!DATE_BUCKET_REGEX.test(bucket)) return false;
+  // Round-trip via Date to reject non-calendar shapes like "2026-02-30"
+  // or "2026-13-01". `Date.UTC` coerces overflow ("2026-02-30" becomes
+  // "2026-03-02") — if the ISO round-trip doesn't equal the input, the
+  // caller supplied a non-calendar bucket.
+  const [yStr, mStr, dStr] = bucket.split("-");
+  const y = Number(yStr), m = Number(mStr), d = Number(dStr);
+  if (m < 1 || m > 12) return false;
+  if (d < 1 || d > 31) return false;
+  const roundtrip = new Date(Date.UTC(y, m - 1, d)).toISOString().slice(0, 10);
+  return roundtrip === bucket;
+}
+
+/**
+ * Build the storage path for a NEW upload. Computes today's date bucket
+ * from the runtime clock (or `opts.now` for tests). Use ONLY for creating
+ * a fresh blob; for reading an existing blob whose bucket is already
+ * recorded in the index, use pathForExistingBlob() instead.
+ *
+ * The file_id and ext are validated against strict regexes; any
+ * path-separator or `..` segment from a malicious client gets rejected
+ * at the regex layer before any I/O.
  */
 export function buildStoragePath(fileId: string, ext: string, opts: { uploadsRoot?: string; now?: Date } = {}): GeneratedFile {
   if (!FILE_ID_REGEX.test(fileId)) throw new Error(`file_id "${fileId}" is invalid`);
-  if (ext && !/^\.[A-Za-z0-9]{1,16}$/.test(ext)) throw new Error(`ext "${ext}" is invalid`);
+  if (!isValidExtToken(ext)) throw new Error(`ext "${ext}" is invalid`);
   const dateBucket = getDateBucket(opts.now);
   const root = opts.uploadsRoot ?? getUploadsRoot();
   const relativePath = join(dateBucket, fileId + ext);
@@ -109,6 +157,32 @@ export function buildStoragePath(fileId: string, ext: string, opts: { uploadsRoo
   return { fileId, ext, dateBucket, relativePath, absolutePath };
 }
 
+/**
+ * Build the storage path for an EXISTING blob, using the caller-supplied
+ * `dateBucket` (typically read from the index entry). Does NOT compute
+ * a date from the runtime clock — that is the write-side concern.
+ *
+ * This split exists because sharing one date-computing function between
+ * write and read semantics caused #509: yesterday's file downloaded
+ * today would look under today's bucket → blob_missing → 404, even
+ * though the blob was still sitting in yesterday's directory.
+ *
+ * The file_id, ext and dateBucket are validated against strict regexes
+ * before any I/O; a poisoned index bucket (e.g. `../etc`) is rejected
+ * here just as file_id path-escape attempts are.
+ */
+export function pathForExistingBlob(dateBucket: string, fileId: string, ext: string, opts: { uploadsRoot?: string } = {}): GeneratedFile {
+  if (!FILE_ID_REGEX.test(fileId)) throw new Error(`file_id "${fileId}" is invalid`);
+  if (!isValidExtToken(ext)) throw new Error(`ext "${ext}" is invalid`);
+  if (typeof dateBucket !== "string" || !DATE_BUCKET_REGEX.test(dateBucket)) {
+    throw new Error(`date_bucket "${dateBucket}" is invalid`);
+  }
+  const root = opts.uploadsRoot ?? getUploadsRoot();
+  const relativePath = join(dateBucket, fileId + ext);
+  const absolutePath = join(root, relativePath);
+  return { fileId, ext, dateBucket, relativePath, absolutePath };
+}
+
 export type UploadIndexEntry = {
   file_id: string;
   date_bucket: string; // YYYY-MM-DD
@@ -117,6 +191,15 @@ export type UploadIndexEntry = {
   mime: string;        // best-effort mime from the multipart Content-Type
   size: number;        // byte length of the binary
   owner?: string;      // upload token id / username, for traceability
+  // Written by the upload handler as `authCtx?.userId ?? null`, so `null`
+  // is a real on-disk value — the type must say so rather than pretend
+  // the field is `string | undefined`.
+  owner_id?: string | null;
+  // #503 — network the upload is attributed to. The key is OMITTED (not
+  // written as null) when there is no attribution, so "absent" and
+  // "unattributed" are the same on-disk shape and legacy entries written
+  // before #503 are indistinguishable from new unattributed ones.
+  network_id?: string;
   uploaded_at: string; // ISO 8601
 };
 
@@ -135,10 +218,16 @@ export function indexEntryPath(fileId: string, opts: { uploadsRoot?: string } =
 export function validateIndexEntry(entry: unknown): entry is UploadIndexEntry {
   if (!entry || typeof entry !== "object") return false;
   const e: any = entry;
+  // #503 — if the network_id key is present it must be a non-empty string.
+  // An absent key is valid (legacy entries + unattributed uploads); that
+  // keeps this in sync with the writer, which omits the key entirely
+  // rather than writing null. owner_id is deliberately NOT constrained
+  // here — existing entries legitimately carry owner_id=null.
+  if ("network_id" in e && !(typeof e.network_id === "string" && e.network_id.length > 0)) return false;
   return (
     typeof e.file_id === "string" && FILE_ID_REGEX.test(e.file_id) &&
     typeof e.date_bucket === "string" && /^\d{4}-\d{2}-\d{2}$/.test(e.date_bucket) &&
-    typeof e.ext === "string" && (e.ext === "" || /^\.[A-Za-z0-9]{1,16}$/.test(e.ext)) &&
+    isValidExtToken(e.ext) &&
     typeof e.size === "number" && e.size >= 0 && e.size <= MAX_UPLOAD_BYTES
   );
 }
@@ -241,6 +330,42 @@ export type TaskAttachment = {
   size?: number;
 };
 
+/**
+ * #222 cross-host attachment safety — strip `path` from meta.attachments
+ * entries that ALSO carry a `file_id`. Reason: the hub's /api/upload
+ * returns `{file_id, path}` where `path` is a hub-machine-local
+ * absolute path. Senders sometimes echo `path` back into meta.attachments.
+ * When the receiving agent runs on a different host (Vincent 2026-06-30
+ * toodadev2 case), that path string is meaningless. agent-node's
+ * fetch-attachment.ts will fetch via `file_id` regardless, but leaving
+ * the stale `path` in the JSON misleads any tooling that reads it.
+ *
+ * CRITICAL — conditional, not unconditional (通信龙 PR #222 pre-review
+ * nit): feishu-bridge currently writes `/work/feishu-attachments/<conn>/
+ * <chat>/` directly and ships path-only attachments (NO file_id). If we
+ * strip path unconditionally those break too. Only strip when file_id
+ * is present (the "safe to drop" signal). Single-host feishu fallback
+ * preserved.
+ *
+ * Shared by tools.ts (MCP send_task) and index.ts (REST /api/task) so
+ * both transports apply the same sanitization to meta.
+ */
+export function stripHostLocalPathsForCrossHostSafe(meta: any): any {
+  if (!meta || typeof meta !== "object") return meta;
+  if (!Array.isArray((meta as any).attachments)) return meta;
+  let mutated = false;
+  const sanitized = (meta as any).attachments.map((a: any) => {
+    if (a && typeof a === "object" && typeof a.file_id === "string" && a.file_id && typeof a.path === "string") {
+      mutated = true;
+      const { path: _stripped, ...rest } = a;
+      return rest;
+    }
+    return a;
+  });
+  if (!mutated) return meta;
+  return { ...meta, attachments: sanitized };
+}
+
 /** Light validator usable from the REST handler. Returns null on success or an error message string. */
 export function validateAttachments(input: unknown): { ok: true; attachments: TaskAttachment[] } | { ok: false; error: string } {
   if (input === undefined || input === null) return { ok: true, attachments: [] };

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

@@ -0,0 +1,220 @@
+// #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 = "";
+
+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;
+
+  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 在外网的遗留私信");
+  // network_id 为 NULL 的行。**写路径产不出这种行** —— send_desktop_message 有
+  // 三道闸（canWrite / `if (!effectiveNetId)` / targetRole），拆掉任意一道都还有
+  // 别的挡着，见 desktop-message-seam.test.ts 的两条孤儿断言。这里是手写夹具，
+  // 用来钉「万一库里有这种行（历史数据、将来的第二个写入方），谁读得到」。
+  seedMessage("dm_a_nonet", aUserId, null as any, "A 的无网络私信");
+  seedMessage("dm_admin_nonet", adminUserId, null as any, "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***");
+  });
+
+  // NULL 网络行的可见性**取决于调用者的 scope，不取决于行本身**：
+  //   受网络限制的成员 → addNetworkScope 生成 `network_id IN (...)`，NULL 不匹配 ⇒ 读不到
+  //   admin（resolveRestNetworkScope 给 networkIds=null，助手是 no-op） ⇒ 读得到
+  // 两条一起才说明"NULL 读不到"是 scope 造成的，不是 user_id 过滤造成的。
+  test("NULL 网络行：受网络限制的成员读不到", async () => {
+    const { body } = await get("/api/messages?scope=user", aToken);
+    expect(body.messages.map((m: any) => m.message_id)).not.toContain("dm_a_nonet");
+  });
+
+  test("NULL 网络行：scope 为 no-op 的调用者（admin）读得到自己的那条", 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_nonet");
+    expect(ids).not.toContain("dm_a1");   // 仍然只读自己的：admin 不绕过 user_id 过滤
+  });
+
+  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,53 @@
+// #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(
+        `INSERT INTO user_inbox (message_id, user_id, content) VALUES (?1, ?2, ?3)`,
+        [mid, "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);
+    }
+  });
+});

package/src/vault.test.ts

@@ -0,0 +1,200 @@
+// RFC-028 P1 §4.1 vault layer tests. F2 lazy gate is the critical
+// invariant — existing prod hub升级 without ANET_HUB_SECRET_VAULT_KEY
+// must NOT boot-fail. Every test runs with deterministic key isolation.
+
+import { describe, expect, test, beforeEach, afterAll } from "bun:test";
+import {
+  encryptSecret, decryptSecret,
+  vaultUpsert, vaultGet, vaultListKeys, vaultDelete,
+  vaultStatusForBoot, vaultMasterKeyFingerprint,
+  _resetVaultKeyForTest, VaultError,
+} from "./vault.js";
+import { db } from "./db.js";
+
+const TEST_KEY_HEX = "0123456789abcdef".repeat(4);   // 32 bytes hex = 64 chars
+
+function setKey(hex: string | undefined): void {
+  if (hex === undefined) delete process.env.ANET_HUB_SECRET_VAULT_KEY;
+  else process.env.ANET_HUB_SECRET_VAULT_KEY = hex;
+  _resetVaultKeyForTest();
+}
+
+beforeEach(() => {
+  db.run("DELETE FROM network_secrets");
+  db.run("DELETE FROM provider_models");
+  db.run("DELETE FROM providers");
+});
+afterAll(() => { _resetVaultKeyForTest(); delete process.env.ANET_HUB_SECRET_VAULT_KEY; });
+
+describe("RFC-028 P1 §4.1 F2 — LAZY GATE (critical: don't brick prod hub)", () => {
+  test("hub boot WITHOUT env + WITHOUT vault data → vaultStatusForBoot says configured=false, needsKeyToOp=false (boots OK)", () => {
+    setKey(undefined);
+    const s = vaultStatusForBoot();
+    expect(s.configured).toBe(false);
+    expect(s.tablesHaveData).toBe(false);
+    expect(s.needsKeyToOp).toBe(false);
+    // Crucially: no throw, no crash, hub keeps running.
+  });
+
+  test("hub boot WITH env + WITHOUT vault data → configured=true, tablesEmpty (no fingerprint needed)", () => {
+    setKey(TEST_KEY_HEX);
+    const s = vaultStatusForBoot();
+    expect(s.configured).toBe(true);
+    expect(s.tablesHaveData).toBe(false);
+    expect(s.needsKeyToOp).toBe(false);
+  });
+
+  test("hub WITHOUT env + WITH vault data → needsKeyToOp=true (banner warning, NO throw)", () => {
+    setKey(TEST_KEY_HEX);
+    vaultUpsert("net_test", "TEST_KEY", "plaintext-value");
+    setKey(undefined);
+    const s = vaultStatusForBoot();
+    expect(s.configured).toBe(false);
+    expect(s.tablesHaveData).toBe(true);
+    expect(s.needsKeyToOp).toBe(true);
+    // Still no throw — banner is informational; throw only happens on
+    // actual vault op (test below).
+  });
+
+  test("vault op WITHOUT env throws vault_master_key_missing (lazy throw, not boot throw)", () => {
+    setKey(undefined);
+    expect(() => vaultUpsert("net_test", "K", "v")).toThrow(VaultError);
+    try { vaultUpsert("net_test", "K", "v"); }
+    catch (e: any) { expect(e.code).toBe("vault_master_key_missing"); }
+  });
+
+  test("vault op WITH invalid env (not 32 bytes hex) throws vault_master_key_invalid", () => {
+    setKey("not-hex");
+    expect(() => vaultUpsert("net_test", "K", "v")).toThrow(/vault_master_key_invalid/);
+    setKey("aabbcc");  // too short
+    expect(() => vaultUpsert("net_test", "K", "v")).toThrow(/vault_master_key_invalid/);
+  });
+});
+
+describe("RFC-028 P1 §4.1 — AES-GCM encrypt/decrypt round-trip", () => {
+  test("encrypt+decrypt roundtrip preserves plaintext", () => {
+    setKey(TEST_KEY_HEX);
+    const pt = "sk-ant-api03-abc123xyz";
+    const enc = encryptSecret(pt);
+    expect(enc.ciphertext.length).toBeGreaterThan(0);
+    expect(enc.iv.length).toBe(12);
+    expect(enc.tag.length).toBe(16);
+    expect(decryptSecret(enc)).toBe(pt);
+  });
+
+  test("ciphertext is unique per call (random IV)", () => {
+    setKey(TEST_KEY_HEX);
+    const a = encryptSecret("same-secret");
+    const b = encryptSecret("same-secret");
+    expect(a.iv.equals(b.iv)).toBe(false);
+    expect(a.ciphertext.equals(b.ciphertext)).toBe(false);
+    // Both decrypt back to same plaintext
+    expect(decryptSecret(a)).toBe("same-secret");
+    expect(decryptSecret(b)).toBe("same-secret");
+  });
+
+  test("tamper detection — flipping ciphertext bit throws vault_decrypt_failed", () => {
+    setKey(TEST_KEY_HEX);
+    const enc = encryptSecret("important");
+    enc.ciphertext[0] ^= 0x01;
+    expect(() => decryptSecret(enc)).toThrow(/vault_decrypt_failed/);
+  });
+
+  test("tamper detection — flipping tag bit throws vault_decrypt_failed", () => {
+    setKey(TEST_KEY_HEX);
+    const enc = encryptSecret("important");
+    enc.tag[0] ^= 0x01;
+    expect(() => decryptSecret(enc)).toThrow(/vault_decrypt_failed/);
+  });
+
+  test("wrong key cannot decrypt", () => {
+    setKey(TEST_KEY_HEX);
+    const enc = encryptSecret("important");
+    setKey("ff".repeat(32));  // different key
+    expect(() => decryptSecret(enc)).toThrow(/vault_decrypt_failed/);
+  });
+});
+
+describe("RFC-028 P1 §4.1 — DB ops + key listing (永不返 value)", () => {
+  test("vaultUpsert + vaultGet roundtrip via DB", () => {
+    setKey(TEST_KEY_HEX);
+    vaultUpsert("net_A", "ANTHROPIC_API_KEY", "sk-ant-prod-1");
+    expect(vaultGet("net_A", "ANTHROPIC_API_KEY")).toBe("sk-ant-prod-1");
+  });
+
+  test("vaultUpsert replaces existing key (same network_id + key)", () => {
+    setKey(TEST_KEY_HEX);
+    vaultUpsert("net_B", "K1", "v1");
+    vaultUpsert("net_B", "K1", "v2");
+    expect(vaultGet("net_B", "K1")).toBe("v2");
+  });
+
+  test("vaultGet returns null for missing key (does NOT throw)", () => {
+    setKey(TEST_KEY_HEX);
+    expect(vaultGet("net_X", "MISSING")).toBeNull();
+  });
+
+  test("vaultListKeys returns key NAMES only (no values, ever)", () => {
+    setKey(TEST_KEY_HEX);
+    vaultUpsert("net_L", "KEY_A", "value-a");
+    vaultUpsert("net_L", "KEY_B", "value-b");
+    const keys = vaultListKeys("net_L");
+    expect(keys).toEqual(["KEY_A", "KEY_B"]);  // sorted; no values
+    expect(JSON.stringify(keys)).not.toContain("value-a");
+    expect(JSON.stringify(keys)).not.toContain("value-b");
+  });
+
+  test("network isolation — netA's secret不 visible to netB", () => {
+    setKey(TEST_KEY_HEX);
+    vaultUpsert("net_A", "SHARED_NAME", "value-from-A");
+    vaultUpsert("net_B", "SHARED_NAME", "value-from-B");
+    expect(vaultGet("net_A", "SHARED_NAME")).toBe("value-from-A");
+    expect(vaultGet("net_B", "SHARED_NAME")).toBe("value-from-B");
+    expect(vaultListKeys("net_A")).toEqual(["SHARED_NAME"]);
+    expect(vaultListKeys("net_B")).toEqual(["SHARED_NAME"]);
+  });
+
+  test("vaultDelete removes key + returns true; second delete returns false", () => {
+    setKey(TEST_KEY_HEX);
+    vaultUpsert("net_D", "K", "v");
+    expect(vaultDelete("net_D", "K")).toBe(true);
+    expect(vaultGet("net_D", "K")).toBeNull();
+    expect(vaultDelete("net_D", "K")).toBe(false);  // no-op
+  });
+});
+
+describe("RFC-028 P1 §4.1 — master key fingerprint", () => {
+  test("fingerprint same for same key, different for different key", () => {
+    setKey(TEST_KEY_HEX);
+    const fp1 = vaultMasterKeyFingerprint();
+    expect(fp1.length).toBe(16);
+    setKey(TEST_KEY_HEX);  // re-set same key
+    expect(vaultMasterKeyFingerprint()).toBe(fp1);
+    setKey("ff".repeat(32));
+    expect(vaultMasterKeyFingerprint()).not.toBe(fp1);
+  });
+});
+
+describe("RFC-028 P1 §4.1 — DB ciphertext storage (PRAGMA-style: NO plaintext in DB)", () => {
+  test("BLOB stored is ciphertext, not plaintext (raw SELECT verifies)", () => {
+    setKey(TEST_KEY_HEX);
+    const plaintext = "sk-very-secret-key-do-not-leak";
+    vaultUpsert("net_P", "ANTHROPIC_API_KEY", plaintext);
+    const raw = db.get<{ ciphertext: Buffer | Uint8Array; iv: Buffer | Uint8Array; tag: Buffer | Uint8Array }>(
+      "SELECT ciphertext, iv, tag FROM network_secrets WHERE network_id = ?1 AND key = ?2",
+      "net_P", "ANTHROPIC_API_KEY",
+    );
+    expect(raw).not.toBeNull();
+    const ctBuf = Buffer.isBuffer(raw!.ciphertext) ? raw!.ciphertext : Buffer.from(raw!.ciphertext as any);
+    // Plaintext substring MUST NOT appear in ciphertext bytes
+    expect(ctBuf.toString("binary")).not.toContain(plaintext);
+    expect(ctBuf.toString("utf8")).not.toContain(plaintext);
+    // Even as hex / base64 / partial — bytes must not match plaintext bytes
+    const plainBytes = Buffer.from(plaintext, "utf8");
+    let found = false;
+    for (let i = 0; i <= ctBuf.length - plainBytes.length; i++) {
+      if (ctBuf.subarray(i, i + plainBytes.length).equals(plainBytes)) { found = true; break; }
+    }
+    expect(found).toBe(false);
+  });
+});