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

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.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}$/;
+
+/**
+ * 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 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.
+ * 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,9 +191,24 @@ 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;
+  // 私信文件:上传时声明 `?purpose=dm`(App 的私信输入框这么传)。第一次用途就是私信 ——
+  // 只有上传者、收到/发出过带它的私信的人和管理员能下载(server.ts authorizeFileDownload)。
+  // 不是私信的文件不写这个键;以后被转进私信也不会补写,原来谁能看还是谁能看。
+  scope?: typeof DM_FILE_SCOPE;
   uploaded_at: string; // ISO 8601
 };
 
+export const DM_FILE_SCOPE = "dm";
+
 /** Path to the index entry file for a given file_id. Lives in
  * `<uploadsRoot>/.index/<file_id>.json` so /api/files/:file_id can do
  * an O(1) lookup without scanning every date bucket. */
@@ -135,10 +224,18 @@ 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;
+  // 未知的 scope 值不当成「没有 scope」放行(那等于把私信文件退回全网可见):整条判坏,下载 404。
+  if ("scope" in e && e.scope !== DM_FILE_SCOPE) 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
   );
 }
@@ -247,7 +344,7 @@ export type TaskAttachment = {
  * 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
+ * a partner-team host 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.
  *

package/src/user-avatar-http.test.ts

@@ -0,0 +1,74 @@
+import { expect, test } from "bun:test";
+import { register, login, createNetworkTokenForNode, addNetworkMember } from "./auth.js";
+import { db } from "./db.js";
+
+// One sequential HTTP scenario: fail a prerequisite before running the next layer.
+// Docker supplies an isolated DB; never import this against a production DB.
+test("human avatar: auth → save/read/login → member visibility → isolation/rejection → clear", async () => {
+  const a = register("avatar_alice", "AvatarPassw0rd!");
+  const b = register("avatar_bob", "AvatarPassw0rd!");
+  const stranger = register("avatar_stranger", "AvatarPassw0rd!");
+  expect(a.ok && b.ok && stranger.ok).toBe(true);
+  expect(addNetworkMember(a.network_id!, b.user!.user_id, "member").ok).toBe(true);
+  const node = createNetworkTokenForNode(a.user!.user_id, a.network_id!, "avatar_alice", "avatar_node");
+  expect(node.ok).toBe(true);
+  const { bootServer } = await import("./server.js");
+  const hub = bootServer({ port: 0, hostname: "127.0.0.1" });
+  const base = `http://127.0.0.1:${hub.port}`;
+  const call = async (token: string, method: string, path: string, body?: unknown) => {
+    const res = await fetch(base + path, { method,
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body) });
+    return { status: res.status, body: await res.json() as any };
+  };
+  const put = (token: string, body: unknown) => call(token, "PUT", "/api/auth/me/avatar", body);
+  const me = (token: string) => call(token, "GET", "/api/auth/me");
+  try {
+    expect((await me(a.token!)).status).toBe(200);
+    expect((await me(a.token!)).body.user.avatar_url).toBeNull();
+    expect((await put("invalid", { avatar_url: null })).status).toBe(401);
+    expect((await put(node.token!, { avatar_url: null })).status).toBe(403);
+
+    const avatar = "/avatars/avatar-03.webp";
+    const saved = await put(a.token!, { avatar_url: avatar });
+    expect(saved.status).toBe(200);
+    expect(saved.body).toEqual({ ok: true, user_id: a.user!.user_id, avatar_url: avatar });
+    expect((await me(a.token!)).body.user.avatar_url).toBe(avatar);
+    const secondDevice = login("avatar_alice", "AvatarPassw0rd!");
+    expect(secondDevice.ok).toBe(true);
+    expect(secondDevice.user!.avatar_url).toBe(avatar);
+    expect((await me(secondDevice.token!)).body.user.avatar_url).toBe(avatar);
+    // An ordinary profile edit must preserve and return the saved avatar.
+    const profile = await call(a.token!, "PUT", "/api/auth/me", { display_name: "Alice" });
+    expect(profile.status).toBe(200);
+    expect(profile.body.user.avatar_url).toBe(avatar);
+    const people = await call(b.token!, "GET", `/api/networks/${a.network_id}/humans`);
+    expect(people.status).toBe(200);
+    expect(people.body.humans.find((u: any) => u.user_id === a.user!.user_id).avatar_url).toBe(avatar);
+    expect((await call(stranger.token!, "GET", `/api/networks/${a.network_id}/humans`)).status).toBe(403);
+    expect((await me(b.token!)).body.user.avatar_url).toBeNull();
+
+    for (const body of [null, [], {}, { avatar_url: avatar, user_id: b.user!.user_id },
+      ...[123, {}, "javascript:alert(1)", "file:///tmp/photo.png", "data:image/png;base64,AAAA",
+        "//evil.example/a.png", "/avatars/../x.png", "https://user:secret@example.com/x.png", "x".repeat(3000)]
+        .map((avatar_url) => ({ avatar_url }))]) {
+      expect((await put(a.token!, body)).status).toBe(400);
+      expect((await me(a.token!)).body.user.avatar_url).toBe(avatar);
+    }
+    const malformed = await fetch(base + "/api/auth/me/avatar", { method: "PUT",
+      headers: { Authorization: `Bearer ${a.token}`, "Content-Type": "application/json" }, body: "{" });
+    expect(malformed.status).toBe(400);
+    expect((await put(node.token!, { avatar_url: "/avatars/avatar-09.webp" })).status).toBe(403);
+    expect((await me(a.token!)).body.user.avatar_url).toBe(avatar);
+    expect((await me(b.token!)).body.user.avatar_url).toBeNull();
+    expect(db.get<any>("SELECT avatar_url FROM nodes WHERE node_id = ?1", "avatar_node")?.avatar_url ?? null).toBeNull();
+
+    const remote = "https://example.invalid/photo.png";
+    expect((await put(a.token!, { avatar_url: remote })).status).toBe(200);
+    expect((await me(a.token!)).body.user.avatar_url).toBe(remote);
+    expect((await put(a.token!, { avatar_url: null })).status).toBe(200);
+    expect((await me(secondDevice.token!)).body.user.avatar_url).toBeNull();
+    expect((await put(a.token!, { avatar_url: avatar })).status).toBe(200);
+    expect((await put(a.token!, { avatar_url: "  " })).body.avatar_url).toBeNull();
+  } finally { hub.stop(true); }
+}, 30_000);

package/src/user-avatar-migration.test.ts

@@ -0,0 +1,25 @@
+import { expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+
+test("existing users survive additive avatar migration and next process preserves it", async () => {
+  const path = process.env.COMMHUB_DB!;
+  expect(typeof path).toBe("string");
+  const old = new Database(path);
+  old.exec(`CREATE TABLE users (
+    user_id TEXT PRIMARY KEY, username TEXT UNIQUE NOT NULL, password_hash TEXT NOT NULL,
+    email TEXT, display_name TEXT, role TEXT DEFAULT 'user',
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+  ); INSERT INTO users (user_id, username, password_hash) VALUES ('old_user', 'old_user', 'test-only-hash');`);
+  old.close();
+  const { db } = await import("./db.js");
+  expect(db.get<any>("SELECT avatar_url, password_hash FROM users WHERE user_id = ?1", "old_user"))
+    .toEqual({ avatar_url: null, password_hash: "test-only-hash" });
+  db.run("UPDATE users SET avatar_url = ?1 WHERE user_id = ?2", ["/avatars/avatar-03.webp", "old_user"]);
+  const child = Bun.spawn([process.execPath, "-e", `
+    const { db } = await import('./src/db.ts');
+    const row = db.get('SELECT avatar_url, password_hash FROM users WHERE user_id = ?1', 'old_user');
+    if (row.avatar_url !== '/avatars/avatar-03.webp' || row.password_hash !== 'test-only-hash') process.exit(1);
+  `], { cwd: new URL("..", import.meta.url).pathname, env: process.env, stdout: "pipe", stderr: "pipe" });
+  expect(await child.exited).toBe(0);
+});