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

package/src/update-provider.test.ts

@@ -166,4 +166,69 @@ describe("update_provider — SQL invariants (RFC-028 P1.5)", () => {
     expect(row!.enabled).toBe(0);
     // dashboard renders different message for these two cases
   });
+
+  test("no-op same-value patch: NO audit_log row written (通信牛 nit)", () => {
+    // Regression for the post-merge fix: when patch fields all match the
+    // existing row (e.g. dashboard saves an unchanged form), the handler
+    // must early-return WITHOUT inserting an empty-diff audit row.
+    // Empty audit rows pollute the trail and make `forced_*` / sensitive
+    // actions harder to find.
+    seedProvider(PROV_A, NET_A, { name: "same-name", enabled: 1 });
+    const auditBefore = db.get<{n:number}>(
+      "SELECT COUNT(*) AS n FROM audit_log WHERE target_id = ?1 AND action = 'update_provider'",
+      PROV_A,
+    )!.n;
+
+    // Mirror the handler's diff-check logic on a same-value patch
+    const row = db.get<{name:string, enabled:number, base_url:string}>(
+      "SELECT name, enabled, base_url FROM providers WHERE provider_id = ?1", PROV_A,
+    )!;
+    const patch = { name: "same-name", enabled: true };
+    const sets: string[] = [];
+    if (patch.name !== undefined && patch.name !== row.name) sets.push("name");
+    if (patch.enabled !== undefined && (patch.enabled ? 1 : 0) !== row.enabled) sets.push("enabled");
+    const willReplaceModels = false;   // no patch.models
+
+    // sets MUST be empty for a same-value patch
+    expect(sets.length).toBe(0);
+    expect(willReplaceModels).toBe(false);
+
+    // Handler returns here WITHOUT writing audit_log → count unchanged
+    const auditAfter = db.get<{n:number}>(
+      "SELECT COUNT(*) AS n FROM audit_log WHERE target_id = ?1 AND action = 'update_provider'",
+      PROV_A,
+    )!.n;
+    expect(auditAfter).toBe(auditBefore);
+    expect(auditAfter).toBe(0);
+  });
+
+  test("real change DOES write audit_log row (positive guard for the early-return)", () => {
+    // Belt-and-suspenders: no-op early-return MUST NOT trigger when even
+    // one field actually changes. Otherwise we'd silently lose audit
+    // coverage for real updates.
+    seedProvider(PROV_A, NET_A, { name: "old-name", enabled: 1 });
+    const row = db.get<{name:string, enabled:number}>(
+      "SELECT name, enabled FROM providers WHERE provider_id = ?1", PROV_A,
+    )!;
+    const patch = { name: "new-name", enabled: true };
+    const sets: string[] = [];
+    if (patch.name !== undefined && patch.name !== row.name) sets.push("name");
+    if (patch.enabled !== undefined && (patch.enabled ? 1 : 0) !== row.enabled) sets.push("enabled");
+    expect(sets).toEqual(["name"]);
+
+    db.exec("BEGIN");
+    db.run("UPDATE providers SET name = ?1 WHERE provider_id = ?2", ["new-name", PROV_A]);
+    db.run(
+      `INSERT INTO audit_log (user_id, username, action, target_type, target_id, detail, network_id)
+       VALUES (?1, ?2, 'update_provider', 'provider', ?3, ?4, ?5)`,
+      ["u_test", "test", PROV_A, JSON.stringify({ diff: { name: { before: "old-name", after: "new-name" } }, fields_changed: ["name"] }), NET_A],
+    );
+    db.exec("COMMIT");
+
+    const audit = db.get<any>(
+      "SELECT detail FROM audit_log WHERE target_id = ?1 AND action = 'update_provider' ORDER BY id DESC LIMIT 1",
+      PROV_A,
+    )!;
+    expect(JSON.parse(audit.detail).fields_changed).toEqual(["name"]);
+  });
 });

package/src/upload-early-reject-guard.test.ts

@@ -0,0 +1,155 @@
+// #503 F3=A static guard: every 4xx return in the /api/upload handler
+// that fires BEFORE `req.formData()` drains the request body MUST be
+// wrapped in `earlyReject` (which sets `Connection: close`). Otherwise
+// the client's still-inbound body poisons the keepalive pool and the
+// next pooled request stalls.
+//
+// Why a STATIC guard (not a runtime one): mutation M9 in
+// docs/tests/p-503-file-network-scope/mutation-matrix.txt showed that
+// under Bun's fetch client in this test setup, removing
+// `Connection: close` does NOT turn any dynamic test red — the pool
+// poisoning is real HTTP-level behavior but the client under test does
+// not reliably reproduce it. Without a guard, deleting the helper or
+// forgetting to wrap a NEW 15th pre-drain return goes silent. This
+// test judges the SOURCE FILE, per lead 7a88ce29 and Constraint 3-1
+// pattern (source-based, not runner-output-based).
+//
+// PRIOR-ART GOTCHA (lead 7a88ce29 踩过): parse boundaries MUST exclude
+// comments. `req.formData()` appears in a doc comment near the top of
+// the handler too; if the boundary matches on that, the pre-drain
+// range collapses to empty and this guard silently becomes vacuously
+// true. Same trap family as "范围为空的全称断言恒真". So this test
+// has an explicit precondition: the parsed pre-drain return count must
+// be ≥ 10 (currently 14). If the count drops to 0, the boundary parser
+// broke, not the code.
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "fs";
+import { join } from "path";
+
+const SOURCE_PATH = join(import.meta.dirname, "server.ts");
+const RAW = readFileSync(SOURCE_PATH, "utf-8");
+const LINES = RAW.split("\n");
+
+// Strip line-comments so we don't match on comment-mentioned tokens
+// like the "req.formData()" doc references at the top of the handler.
+// (Block comments /* */ are rare inside this handler; if you add one
+// that mentions the boundary, extend this helper.)
+//
+// KNOWN LIMITATION (lead 50208c1b): this naive strip cuts on ANY `//`,
+// including one inside a string literal (e.g. `"https://…"`). If a
+// pre-drain line ever contains such a literal, the strip could snip
+// off the return statement after it and produce a false NEGATIVE (miss
+// a genuine unwrapped return). Currently no pre-drain line in the
+// /api/upload handler holds this shape; the precondition floor of 10
+// catches only "range collapsed to empty", not "silently minus one".
+// If someone adds a URL-string literal in this range in the future,
+// upgrade to a real tokenizer — not because block-comment mentions of
+// req.formData() need it, but because the string-literal-with-`//`
+// case is the actual gap.
+function stripLineComment(s: string): string {
+  const idx = s.indexOf("//");
+  return idx >= 0 ? s.slice(0, idx) : s;
+}
+const CODE = LINES.map(stripLineComment);
+
+// Find the /api/upload handler start (guard against a repo rename).
+const handlerStartIdx = CODE.findIndex((line) =>
+  line.includes('url.pathname === "/api/upload"') &&
+  line.includes('req.method === "POST"'),
+);
+
+// Find the true body-drain boundary: `await req.formData()` INSIDE the
+// handler. Search from handler start forward for the first NON-COMMENT
+// occurrence (stripLineComment above already ate any `// ... formData ...`
+// mention).
+let drainIdx = -1;
+if (handlerStartIdx >= 0) {
+  for (let i = handlerStartIdx + 1; i < CODE.length; i++) {
+    if (CODE[i].includes("req.formData()")) {
+      drainIdx = i;
+      break;
+    }
+  }
+}
+
+// Collect every `return` statement in the pre-drain range. Classify:
+//   earlyReject  — the correct wrapping (sets Connection: close)
+//   withCors     — bare wrapping without Connection: close (regression)
+//   other        — produces a Response some OTHER way (e.g.
+//                  `return Response.json(...)` / `return new Response(...)`);
+//                  this shape ALSO skips earlyReject and MUST fail the guard.
+//                  Detected via /Response\b/ so `return wrapped;` /
+//                  `return;` / `return blob;` (helper body, non-response
+//                  returns) are correctly skipped, but any new Response-
+//                  producing path (Response.json / new Response / etc.) is
+//                  caught. Lead 50208c1b: earlier version used implicit-skip
+//                  which made the third assertion恒真 — it counted only what
+//                  it recognised, so "unrecognised = 0" was vacuous.
+//                  Order matters: earlyReject → withCors → other. A line
+//                  like `return earlyReject(new Response(…))` contains
+//                  both `earlyReject` AND `Response`, and must classify as
+//                  earlyReject (already-wrapped), not as other.
+type ReturnHit = { lineNumber: number; text: string; kind: "earlyReject" | "withCors" | "other" };
+const preDrainReturns: ReturnHit[] = [];
+if (handlerStartIdx >= 0 && drainIdx > handlerStartIdx) {
+  for (let i = handlerStartIdx; i < drainIdx; i++) {
+    const code = CODE[i];
+    if (!/\breturn\b/.test(code)) continue;
+    if (/\breturn earlyReject\b/.test(code)) {
+      preDrainReturns.push({ lineNumber: i + 1, text: LINES[i].trim(), kind: "earlyReject" });
+    } else if (/\breturn withCors\b/.test(code)) {
+      preDrainReturns.push({ lineNumber: i + 1, text: LINES[i].trim(), kind: "withCors" });
+    } else if (/Response\b/.test(code)) {
+      // `return new Response(...)` / `return Response.json(...)` / etc.
+      // — produces a Response but skips the earlyReject wrapper.
+      preDrainReturns.push({ lineNumber: i + 1, text: LINES[i].trim(), kind: "other" });
+    }
+    // Bare `return wrapped;`, `return;`, `return blob;` are non-response
+    // returns and correctly skipped (no `Response` token).
+  }
+}
+
+describe("#503 F3=A static guard: /api/upload pre-body-drain returns use earlyReject", () => {
+  test("precondition: scanner located handler + drain boundary + non-trivial return count (defends against parse collapse)", () => {
+    expect(handlerStartIdx).toBeGreaterThanOrEqual(0);
+    expect(drainIdx).toBeGreaterThan(handlerStartIdx);
+    // If boundary parsing collapses (someone renames req.formData(),
+    // or a comment-strip bug lets a doc reference win), this range
+    // becomes 0 and the second test would vacuously pass. Anchor
+    // the range: at time of writing (85e5c140 + #503) the count is
+    // 14; lead 7a88ce29 confirmed 14/14. Floor at 10 to leave room
+    // for genuine deletions while still catching a full collapse.
+    expect(preDrainReturns.length).toBeGreaterThanOrEqual(10);
+  });
+
+  test("every pre-drain return is wrapped in earlyReject (not bare withCors)", () => {
+    const bareWithCors = preDrainReturns.filter((r) => r.kind === "withCors");
+    if (bareWithCors.length > 0) {
+      const detail = bareWithCors
+        .map((r) => `  L${r.lineNumber}: ${r.text}`)
+        .join("\n");
+      throw new Error(
+        `#503 F3=A regression: ${bareWithCors.length} pre-body-drain return(s) in ` +
+        `/api/upload use bare withCors() instead of earlyReject():\n${detail}\n\n` +
+        `Every early-reject in this range MUST set Connection: close. Otherwise ` +
+        `the client's in-flight request body poisons the keepalive pool and the ` +
+        `next pooled request stalls. Wrap with the earlyReject() helper defined ` +
+        `at the top of the upload handler.`,
+      );
+    }
+    expect(bareWithCors.length).toBe(0);
+  });
+
+  test("no pre-drain return produces a Response without going through earlyReject (catches new response shapes)", () => {
+    // Catches `return Response.json(...)` / `return new Response(...)` /
+    // any other pre-drain Response-producing path that skips the wrapper.
+    // Lead 50208c1b: previous version was 恒真 because unrecognised
+    // shapes were silently dropped from `preDrainReturns` — the filter
+    // then counted "recognised = recognised" and never failed. Now the
+    // collector classifies unrecognised Response-producers as "other";
+    // this assertion reports them by line, not just count.
+    const unknown = preDrainReturns.filter((r) => r.kind === "other");
+    expect(unknown.map((r) => `L${r.lineNumber}: ${r.text}`)).toEqual([]);
+  });
+});

package/src/uploads-http.test.ts

@@ -7,27 +7,32 @@
 // this file already exercises the same code path). The hub binds to
 // an ephemeral port so multiple test runs don't collide.
 import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import "./require-explicit-test-db.js";
 import { mkdtempSync, rmSync, existsSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
 import { register, login } from "./auth.js";
 
-const SERVER_DB = mkdtempSync(join(tmpdir(), "anet-upload-http-db-")) + "/commhub.db";
 const UPLOADS_DIR = mkdtempSync(join(tmpdir(), "anet-upload-http-fs-"));
-const PORT = 19000 + Math.floor(Math.random() * 1000);
-const BASE = `http://127.0.0.1:${PORT}`;
+// #438 corrective: private bootServer({ port: 0 }) instance — the OS
+// assigns the port and BASE is derived from the ACTUAL bound port, so
+// this suite is immune to both the parent-side random-port TOCTOU and
+// the aggregate module-cache no-op (import no longer boots anything).
+let BASE = "";
 
 let server: any;
 let userToken = "";
 let userNetworkId = "";
 
+// 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 () => {
   // Bootstrap a real admin + token on the temp DB so the server can
   // resolve it via requireAuth (we don't want to short-circuit auth —
   // we want to validate the production code path).
-  process.env.COMMHUB_DB = SERVER_DB;
   process.env.COMMHUB_UPLOADS_DIR = UPLOADS_DIR;
-  process.env.PORT = String(PORT);
   process.env.HOST = "127.0.0.1";
 
   // Use a unique username + strong password each run so we don't trip
@@ -50,31 +55,40 @@ beforeAll(async () => {
   }
   expect(userToken).toBeTruthy();
 
-  // Import the server module — its top-level `Bun.serve` call binds
-  // the port immediately. The import side effect IS the server start.
-  await import("./index.js");
+  // Importing is side-effect-free now; boot a private instance and
+  // read the real port back.
+  const { bootServer } = await import("./server.js");
+  server = bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${server.port}`;
   // Tiny settle so the listener is ready.
   await new Promise((r) => setTimeout(r, 100));
-});
+}, 30_000);
 
 afterAll(() => {
-  // Best-effort cleanup. The Bun.serve handle is created at import
-  // time so we can't easily stop it — process exit handles that.
+  try { server?.stop?.(true); } catch {}
   try { rmSync(UPLOADS_DIR, { recursive: true, force: true }); } catch {}
-  try { rmSync(SERVER_DB, { recursive: true, force: true }); } catch {}
 });
 
 function authHeaders(): Record<string, string> {
   return { "Authorization": `Bearer ${userToken}` };
 }
 
+// #503 — the bootstrap user is the first account in this suite's fresh
+// DB, so it is a system admin, and admins must name the target network
+// explicitly (attribution is never guessed). uploadNetworkId() keeps
+// that detail in one place.
+function uploadNetworkId(): string {
+  if (!userNetworkId) throw new Error("test bootstrap: userNetworkId missing");
+  return `?network_id=${encodeURIComponent(userNetworkId)}`;
+}
+
 async function uploadFile(content: Uint8Array, filename: string, mime: string, opts: { skipAuth?: boolean; overrideContentLength?: string | null } = {}): Promise<Response> {
   const form = new FormData();
   form.append("file", new Blob([content], { type: mime }), filename);
   const headers: Record<string, string> = opts.skipAuth ? {} : { ...authHeaders() };
   // Note: fetch sets Content-Length automatically; only override when
   // testing the missing-header path.
-  const res = await fetch(`${BASE}/api/upload`, { method: "POST", body: form, headers });
+  const res = await fetch(`${BASE}/api/upload${uploadNetworkId()}`, { method: "POST", body: form, headers });
   return res;
 }
 
@@ -134,7 +148,7 @@ describe("POST /api/upload — 6-item security checklist (HTTP integration)", ()
         controller.close();
       },
     });
-    const res = await fetch(`${BASE}/api/upload`, {
+    const res = await fetch(`${BASE}/api/upload${uploadNetworkId()}`, {
       method: "POST",
       body: stream,
       headers: { ...authHeaders(), "Content-Type": "multipart/form-data; boundary=xxx", "Transfer-Encoding": "chunked" },
@@ -150,7 +164,7 @@ describe("POST /api/upload — 6-item security checklist (HTTP integration)", ()
     // this body" which is the security property we care about; the
     // exact code depends on whether Bun's multipart parser bails before
     // or after our Content-Type pre-check.
-    const res = await fetch(`${BASE}/api/upload`, {
+    const res = await fetch(`${BASE}/api/upload${uploadNetworkId()}`, {
       method: "POST",
       body: JSON.stringify({ nope: 1 }),
       headers: { ...authHeaders(), "Content-Type": "application/json" },
@@ -161,12 +175,18 @@ describe("POST /api/upload — 6-item security checklist (HTTP integration)", ()
 
 describe("GET /api/files/:file_id — download safety", () => {
   let fileId = "";
+  let rangeFileId = "";
+  const rangeContent = Uint8Array.from({ length: 64 }, (_, i) => i);
 
   beforeAll(async () => {
     const content = new TextEncoder().encode("hello-world-from-#221-integration-test");
     const res = await uploadFile(content, "greeting.txt", "text/plain");
     const body = await res.json() as any;
     fileId = body.file_id;
+
+    const rangeRes = await uploadFile(rangeContent, "range.bin", "application/octet-stream");
+    const rangeBody = await rangeRes.json() as any;
+    rangeFileId = rangeBody.file_id;
   });
 
   test("(item 3) download returns the blob with Content-Disposition: attachment + X-Content-Type-Options: nosniff", async () => {
@@ -175,10 +195,72 @@ describe("GET /api/files/:file_id — download safety", () => {
     expect(res.headers.get("Content-Disposition") ?? "").toMatch(/^attachment(;|$)/i);
     expect(res.headers.get("X-Content-Type-Options")).toBe("nosniff");
     expect(res.headers.get("Content-Type")).toBe("application/octet-stream");
+    expect(res.headers.get("Accept-Ranges")).toBe("bytes");
     const text = await res.text();
     expect(text).toBe("hello-world-from-#221-integration-test");
   });
 
+  test("#514 Range bytes=a-b returns exact 206 partial content, not a tolerant 200/full body", async () => {
+    const res = await fetch(`${BASE}/api/files/${rangeFileId}`, {
+      headers: { ...authHeaders(), Range: "bytes=3-8" },
+    });
+    expect(res.status).toBe(206);
+    expect(res.headers.get("Content-Range")).toBe("bytes 3-8/64");
+    expect(res.headers.get("Content-Length")).toBe("6");
+    expect(res.headers.get("Accept-Ranges")).toBe("bytes");
+    const body = new Uint8Array(await res.arrayBuffer());
+    expect(body.length).toBe(6);
+    expect([...body]).toEqual([...rangeContent.slice(3, 9)]);
+  });
+
+  test("#514 Range bytes=N- returns the exact open-ended tail", async () => {
+    const res = await fetch(`${BASE}/api/files/${rangeFileId}`, {
+      headers: { ...authHeaders(), Range: "bytes=60-" },
+    });
+    expect(res.status).toBe(206);
+    expect(res.headers.get("Content-Range")).toBe("bytes 60-63/64");
+    expect(res.headers.get("Content-Length")).toBe("4");
+    const body = new Uint8Array(await res.arrayBuffer());
+    expect(body.length).toBe(4);
+    expect([...body]).toEqual([...rangeContent.slice(60)]);
+  });
+
+  test("#514 Range bytes=-N returns the exact suffix", async () => {
+    const res = await fetch(`${BASE}/api/files/${rangeFileId}`, {
+      headers: { ...authHeaders(), Range: "bytes=-7" },
+    });
+    expect(res.status).toBe(206);
+    expect(res.headers.get("Content-Range")).toBe("bytes 57-63/64");
+    expect(res.headers.get("Content-Length")).toBe("7");
+    const body = new Uint8Array(await res.arrayBuffer());
+    expect(body.length).toBe(7);
+    expect([...body]).toEqual([...rangeContent.slice(57)]);
+  });
+
+  test("#514 unsatisfiable Range returns 416 with concrete Content-Range size", async () => {
+    const res = await fetch(`${BASE}/api/files/${rangeFileId}`, {
+      headers: { ...authHeaders(), Range: "bytes=64-70" },
+    });
+    expect(res.status).toBe(416);
+    expect(res.headers.get("Content-Range")).toBe("bytes */64");
+    expect(res.headers.get("Content-Length")).toBe("0");
+    const body = new Uint8Array(await res.arrayBuffer());
+    expect(body.length).toBe(0);
+  });
+
+  test("#514 HEAD Range mirrors GET status and range headers without a body", async () => {
+    const res = await fetch(`${BASE}/api/files/${rangeFileId}`, {
+      method: "HEAD",
+      headers: { ...authHeaders(), Range: "bytes=3-8" },
+    });
+    expect(res.status).toBe(206);
+    expect(res.headers.get("Content-Range")).toBe("bytes 3-8/64");
+    expect(res.headers.get("Content-Length")).toBe("6");
+    expect(res.headers.get("Accept-Ranges")).toBe("bytes");
+    const body = new Uint8Array(await res.arrayBuffer());
+    expect(body.length).toBe(0);
+  });
+
   test("anonymous download is 401", async () => {
     const res = await fetch(`${BASE}/api/files/${fileId}`);
     expect(res.status).toBe(401);

package/src/uploads.test.ts

@@ -312,3 +312,69 @@ describe("indexEntryPath", () => {
     expect(p).toBe(`/srv/up/.index/${id}.json`);
   });
 });
+
+import { stripHostLocalPathsForCrossHostSafe } from "./uploads";
+
+describe("stripHostLocalPathsForCrossHostSafe (#222 cross-host attachment safety)", () => {
+  test("strips path when file_id is present (cross-host safe — agent will fetch via /api/files/<id>)", () => {
+    const meta = {
+      attachments: [
+        { type: "file", file_id: "abc12345", path: "/home/hub/uploads/abc12345.png", mime: "image/png" },
+      ],
+      otherKey: "preserved",
+    };
+    const out = stripHostLocalPathsForCrossHostSafe(meta);
+    expect(out.attachments[0]).toEqual({ type: "file", file_id: "abc12345", mime: "image/png" });
+    expect(out.attachments[0].path).toBeUndefined();
+    expect(out.otherKey).toBe("preserved");
+  });
+
+  test("PRESERVES path when file_id is absent (feishu single-host fallback)", () => {
+    // 🔴 通信龙 PR #222 pre-review nit — feishu-bridge ships path-only
+    // attachments (writes /work/feishu-attachments/...). If we strip
+    // unconditionally those break too. Lock the conditional contract.
+    const meta = {
+      attachments: [
+        { type: "file", path: "/work/feishu-attachments/feishu-local/oc_xxx/img.jpg", mime: "image/jpeg" },
+      ],
+    };
+    const out = stripHostLocalPathsForCrossHostSafe(meta);
+    expect(out.attachments[0].path).toBe("/work/feishu-attachments/feishu-local/oc_xxx/img.jpg");
+    expect(out.attachments[0].file_id).toBeUndefined();
+  });
+
+  test("mixed array: strips path on entries with file_id, preserves on path-only entries", () => {
+    const meta = {
+      attachments: [
+        { type: "file", file_id: "id1xxxxx", path: "/hub/local/id1.png", mime: "image/png" },
+        { type: "file", path: "/work/feishu-attachments/x.jpg", mime: "image/jpeg" },
+        { type: "file", file_id: "id2yyyyy", mime: "image/gif" },                            // already path-free
+      ],
+    };
+    const out = stripHostLocalPathsForCrossHostSafe(meta);
+    expect(out.attachments[0]).toEqual({ type: "file", file_id: "id1xxxxx", mime: "image/png" });
+    expect(out.attachments[1]).toEqual({ type: "file", path: "/work/feishu-attachments/x.jpg", mime: "image/jpeg" });
+    expect(out.attachments[2]).toEqual({ type: "file", file_id: "id2yyyyy", mime: "image/gif" });
+  });
+
+  test("no-op when meta has no attachments array", () => {
+    const meta = { something: "else" };
+    expect(stripHostLocalPathsForCrossHostSafe(meta)).toBe(meta);
+  });
+
+  test("no-op when nothing to strip (returns SAME object reference, not a copy)", () => {
+    const meta = { attachments: [{ type: "file", file_id: "x12345xx", mime: "image/png" }] };
+    expect(stripHostLocalPathsForCrossHostSafe(meta)).toBe(meta);
+  });
+
+  test("handles null / non-object meta gracefully", () => {
+    expect(stripHostLocalPathsForCrossHostSafe(null)).toBe(null);
+    expect(stripHostLocalPathsForCrossHostSafe(undefined as any)).toBe(undefined);
+    expect(stripHostLocalPathsForCrossHostSafe("string" as any)).toBe("string");
+  });
+
+  test("handles non-array attachments field gracefully", () => {
+    const meta = { attachments: "not-an-array" };
+    expect(stripHostLocalPathsForCrossHostSafe(meta)).toBe(meta);
+  });
+});