@sleep2agi/commhub-server 0.9.0-preview.24 → 0.9.0-preview.26

package/src/tools.ts

@@ -4,6 +4,7 @@ import { db, uuidv4, logTaskEvent, chainReplyToParent, hashToken, generateId, ge
 import { pushEvent, pushNetworkObserverEvent } from "./push.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
 import { getUserNetworkRole, createNetworkTokenForNode } from "./auth.js";
+import { canRestWriteNetwork, getUserNetworkIds, singleNetworkId } from "./network-scope.js";
 import {
   buildAnetArgs as _unused_buildAnetArgs,           // ensure module is loaded
   validateName as validateChildName,
@@ -30,7 +31,7 @@ import {
   vaultUpsert, vaultGet, vaultListKeys, vaultDelete,
   VaultError,
 } from "./vault.js";
-import { stripHostLocalPathsForCrossHostSafe } from "./uploads.js";
+import { stripHostLocalPathsForCrossHostSafe, validateAttachments } from "./uploads.js";
 import {
   validateBaseUrl as _validateBaseUrl,
   SUPPORTED_VENDORS,
@@ -97,28 +98,54 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       }],
     };
   };
-  // If enforceNetworkId is set, override any client-supplied network_id
-  const getNetworkId = (clientNetId?: string | null) => enforceNetworkId ?? clientNetId ?? null;
+  // MCP-side auth context in the shape network-scope.ts helpers take.
+  // null = legacy global-token / open-dev mode (unscoped, allow-all).
+  const mcpAuthCtx = enforceUserId ? { userId: enforceUserId, networkId: enforceNetworkId ?? null } : null;
+
+  // If enforceNetworkId is set (ntok_), override any client-supplied
+  // network_id. #517: for utok_ with no explicit network_id, fall back to
+  // the user's single membership via the SAME singleNetworkId used by REST
+  // POST /api/task (network-scope.ts) — utok_ rows carry network_id=null by
+  // design, so without this fallback single-network nodes could read
+  // everything but write nothing. Multi-network stays null (ambiguous) and
+  // canWrite rejects with network_id_required.
+  const getNetworkId = (clientNetId?: string | null) => {
+    const explicit = enforceNetworkId ?? clientNetId ?? null;
+    if (explicit !== null || !enforceUserId) return explicit;
+    return singleNetworkId({ networkId: null, networkIds: getUserNetworkIds(enforceUserId) });
+  };
 
-  // Check write access. For ntok_ the network is enforced by the token.
-  // For utok_ (no enforced network) we accept the network_id supplied in the
-  // request and verify the user has a write role on it.
+  // Check write access — delegates to the shared canRestWriteNetwork so MCP
+  // and REST cannot drift again (#517). isAdmin=false: MCP has no admin
+  // bypass today; keep behavior identical to before the extraction.
   const canWrite = (effectiveNetworkId?: string | null): boolean => {
-    if (!enforceUserId) return true; // legacy global token mode, allow
     const netId = enforceNetworkId ?? effectiveNetworkId ?? null;
-    if (!netId) return false; // no network resolvable
-    const role = getUserNetworkRole(enforceUserId, netId);
-    return !!role && role !== "viewer"; // owner/admin/member can write
+    return canRestWriteNetwork(mcpAuthCtx, netId, false);
   };
 
+  // #517: name the REAL cause. The old catch-all blamed permissions for
+  // what was actually an unresolvable network, sending operators down the
+  // wrong debugging path (roles/membership) for hours.
   const writeDeniedReply = (effectiveNetworkId?: string | null, action = "write") => {
     const netId = enforceNetworkId ?? effectiveNetworkId ?? null;
-    const message = !netId
-      ? "network_id required (utok current_network is null; pass explicit network_id from /api/auth/me networks[0].network_id)"
-      : action === "send_task"
+    let error: string;
+    let message: string;
+    if (!netId) {
+      const memberships = enforceUserId ? getUserNetworkIds(enforceUserId) : [];
+      error = "network_id_required";
+      message = memberships.length === 0
+        ? "user token has no network memberships; join or create a network first"
+        : `user token spans ${memberships.length} networks; pass network_id explicitly (see /api/auth/me networks[].network_id)`;
+    } else if (enforceUserId && !getUserNetworkRole(enforceUserId, netId)) {
+      error = "access_denied";
+      message = "access denied to requested network (not a member)";
+    } else {
+      error = "permission_denied";
+      message = action === "send_task"
         ? "Viewer role cannot send tasks"
         : "Viewer role cannot write to this network";
-    return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "permission_denied", message }) }] };
+    }
+    return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error, message }) }] };
   };
 
   const addScope = (sql: string, params: any[], networkId?: string | null, column = "network_id"): string => {
@@ -130,13 +157,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   type ReadScope = { networkId?: string | null; networkIds?: string[] | null; denied?: string };
 
-  const getReadableNetworkIds = (): string[] => {
-    if (!enforceUserId) return [];
-    return db.all<{ network_id: string }>(
-      "SELECT network_id FROM network_members WHERE user_id = ?1",
-      enforceUserId
-    ).map((row) => row.network_id);
-  };
+  // Delegates to the shared membership query (network-scope.ts) — was a
+  // byte-for-byte duplicate of getUserNetworkIds before #517.
+  const getReadableNetworkIds = (): string[] =>
+    enforceUserId ? getUserNetworkIds(enforceUserId) : [];
 
   const resolveReadScope = (clientNetId?: string | null): ReadScope => {
     if (!enforceUserId) return { networkId: clientNetId ?? null, networkIds: null };
@@ -690,9 +714,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       alias: z.string().min(1).max(200).describe("Session alias"),
       message_id: z.string().min(1).max(200),
       response: z.string().max(10000).optional(),
+      network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
     },
-    async ({ alias, message_id, response }) => {
-      const effectiveNetId = getNetworkId(null);
+    async ({ alias, message_id, response, network_id: netId }) => {
+      const effectiveNetId = getNetworkId(netId);
       if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId);
       console.log(`[${ts()}] ${alias} → ack_inbox: ${message_id.slice(0, 8)}`);
       const ackParams: any[] = [message_id, alias];
@@ -1004,9 +1029,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       alias: z.string().min(1).max(200).describe("Target session alias"),
       message: z.string().min(1).max(10000).describe("Message content"),
       from_session: z.string().max(200).optional(),
+      network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
     },
-    async ({ alias, message, from_session: _fromIn }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
-      const effectiveNetId = getNetworkId(null);
+    async ({ alias, message, from_session: _fromIn, network_id: netId }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
+      const effectiveNetId = getNetworkId(netId);
       if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId);
       const canonical = resolveCanonicalAlias(effectiveNetId, alias);
       const targetAlias = canonical.alias;
@@ -1065,11 +1091,48 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       in_reply_to: z.string().max(200).optional().describe("Original task/message ID"),
       status: z.enum(["replied", "failed", "cancelled"]).optional().default("replied").describe("Task outcome"),
       from_session: z.string().max(200).optional(),
+      network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
+      // #507 — top-level attachments (parity with REST /api/task L506). MCP Zod
+      // otherwise silently strips unknown fields, so a caller passing
+      // `attachments` before this schema entry existed would see `ok:true`
+      // and never learn the attachments were dropped. Validated by
+      // validateAttachments (uploads.ts) — the same helper the REST path uses.
+      attachments: z.any().optional().describe("Optional attachment array; parity with send_task's meta.attachments. Each item: {type:'file', file_id, name?, mime?, size?}. Persisted into tasks.meta_json + inbox.meta_json."),
+      // #507 — optional structured metadata (parity with send_task L837). If
+      // both `attachments` (top-level) and `meta.attachments` are supplied,
+      // top-level wins (same rule as REST /api/task L2101).
+      meta: z.any().optional().describe("Optional structured reply metadata, e.g. { attachments: [...] }."),
     },
-    async ({ alias, text, in_reply_to, status: replyStatus, from_session: _fromIn }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
-      const effectiveNetId = getNetworkId(null);
+    async ({ alias, text, in_reply_to, status: replyStatus, from_session: _fromIn, network_id: netId, attachments, meta }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
+      const effectiveNetId = getNetworkId(netId);
       if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId);
-      console.log(`[${ts()}] ${from_session} → send_reply (${replyStatus}) → ${alias}: ${text.slice(0, 60)}`);
+
+      // #507 — validate attachments BEFORE any DB write. Rejects malformed
+      // input (bad file_id, >20 items, size > cap, non-object item, wrong
+      // type field) with an explicit error the caller can act on. Empty /
+      // absent attachments return { ok: true, attachments: [] } — the
+      // reverse-(e) invariant (no attachments → behavior unchanged) is
+      // pinned by tests that assert byte-identical response shape
+      // before/after this validation runs.
+      const attachmentsResult = validateAttachments(attachments ?? (meta && typeof meta === "object" ? (meta as any).attachments : undefined));
+      if (!attachmentsResult.ok) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              ok: false,
+              error: "bad_attachments",
+              message: attachmentsResult.error,
+            }),
+          }],
+        };
+      }
+      const mergedMeta = attachmentsResult.attachments.length
+        ? { ...(meta && typeof meta === "object" ? meta : {}), attachments: attachmentsResult.attachments }
+        : meta;
+      const metaJson = normalizeMetaJson(mergedMeta);
+
+      console.log(`[${ts()}] ${from_session} → send_reply (${replyStatus}) → ${alias}: ${text.slice(0, 60)}${attachmentsResult.attachments.length ? ` [+${attachmentsResult.attachments.length} attachments]` : ""}`);
       const id = uuidv4();
       let taskBefore: { status: string } | null = null;
       if (in_reply_to) {
@@ -1114,17 +1177,32 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         if (!lc.ok) return { content: [{ type: "text" as const, text: JSON.stringify(lc) }] };
       }
       const replyLogged = db.transaction(() => {
+        // #507 — write meta_json on inbox insert (parity with send_task L952).
+        // Prior to this the attachments field on a send_reply call was
+        // silently stripped by MCP Zod, leaving `ok:true` with no persisted
+        // meta.
         db.run(
-          `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, in_reply_to, requires_response, network_id)
-           VALUES (?1, ?2, ?3, 'reply', 'normal', ?4, ?5, ?6, 'none', ?7)`,
-          [id, alias, replyTargetNodeId, text, from_session, in_reply_to ?? null, effectiveNetId ?? null]
+          `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, in_reply_to, requires_response, network_id, meta_json)
+           VALUES (?1, ?2, ?3, 'reply', 'normal', ?4, ?5, ?6, 'none', ?7, ?8)`,
+          [id, alias, replyTargetNodeId, text, from_session, in_reply_to ?? null, effectiveNetId ?? null, metaJson]
         );
 
         // 更新 tasks 表
         if (in_reply_to) {
-          const updateParams: any[] = [replyStatus, text, in_reply_to];
-          let updateSql = `UPDATE tasks SET status = ?1, result = ?2, completed_at = datetime('now')
-             WHERE task_id = ?3 AND status IN ('created', 'delivered', 'acked', 'running')`;
+          // #507 — persist meta_json onto the tasks row too, so
+          // dashboard's task view sees the reply's attachments alongside
+          // the reply text (parity with send_task L957/959 which writes
+          // meta_json into both inbox and tasks). The COALESCE guards
+          // against clobbering pre-existing meta_json when this reply
+          // brings no attachments (metaJson === null → keep the existing
+          // task meta_json unchanged). Reverse-(e) invariant.
+          const updateParams: any[] = [replyStatus, text, metaJson, in_reply_to];
+          let updateSql = `UPDATE tasks
+             SET status = ?1,
+                 result = ?2,
+                 completed_at = datetime('now'),
+                 meta_json = COALESCE(?3, meta_json)
+             WHERE task_id = ?4 AND status IN ('created', 'delivered', 'acked', 'running')`;
           updateSql = addScope(updateSql, updateParams, effectiveNetId);
           const result = db.run(updateSql, updateParams);
           if (result.changes === 0) {
@@ -1202,6 +1280,29 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         ? `Target "${alias}" is an agent node. commhub_reply/send_reply does NOT wake agent peers (they only log new_reply, they do not processInbox on it) — the peer will not see this reply in real time. For agent-to-agent replies, use commhub_send_task(alias="${alias}", task="<your reply>") so the peer wakes via new_task SSE and processes it. (RFC-030, Vincent 2026-07-28 全网规则.)`
         : undefined;
 
+      // #507 — echo attachments READ BACK FROM DB (lead 2b5f6634): the point
+      // of the echo is to prove attachments actually landed in storage, not
+      // to reflect the in-memory variable we tried to write. Reading
+      // `attachmentsResult.attachments` here would still show `ok:true` +
+      // full echo if the UPDATE failed with `changes=0` (e.g. task moved to
+      // terminal between the pre-check and the transaction). SELECT from
+      // inbox.meta_json (always written, uses the id we just generated) so
+      // the echo means "these attachments are on disk now". Absent field
+      // when the caller sent no attachments — reverse-(e) invariant: a
+      // no-attachment call returns the exact same response shape as before
+      // this PR. Persisted-attachments field is only added when the caller
+      // actually asked for attachments.
+      let attachmentsSaved: unknown[] | null = null;
+      if (attachmentsResult.attachments.length > 0) {
+        const persistedRow = db.get<{ meta_json: string | null }>(
+          "SELECT meta_json FROM inbox WHERE id = ?1", [id]
+        );
+        const persistedMeta = parseMetaJson(persistedRow?.meta_json ?? null);
+        attachmentsSaved = persistedMeta && typeof persistedMeta === "object" && Array.isArray((persistedMeta as any).attachments)
+          ? (persistedMeta as any).attachments
+          : [];
+      }
+
       return {
         content: [{
           type: "text" as const,
@@ -1210,6 +1311,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
             message_id: id,
             session_status: session?.status ?? "unknown",
             ...(warning ? { warning } : {}),
+            ...(attachmentsSaved !== null ? { attachments_saved: attachmentsSaved } : {}),
           }),
         }],
       };
@@ -1223,9 +1325,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     {
       task_id: z.string().min(1).max(200).describe("Task ID to acknowledge"),
       from_session: z.string().max(200).optional(),
+      network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
     },
-    async ({ task_id, from_session: _fromIn }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
-      const effectiveNetId = getNetworkId(null);
+    async ({ task_id, from_session: _fromIn, network_id: netId }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
+      const effectiveNetId = getNetworkId(netId);
       if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId);
       console.log(`[${ts()}] ${from_session} → send_ack → task ${task_id.slice(0, 8)}`);
       const updateParams: any[] = [task_id];
@@ -1249,9 +1352,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     {
       task_id: z.string().min(1).max(200).describe("Task ID to retry"),
       from_session: z.string().max(200).optional(),
+      network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
     },
-    async ({ task_id, from_session: _fromIn }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
-      const effectiveNetId = getNetworkId(null);
+    async ({ task_id, from_session: _fromIn, network_id: netId }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
+      const effectiveNetId = getNetworkId(netId);
       if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId);
       console.log(`[${ts()}] ${from_session} → retry_task → ${task_id.slice(0, 8)}`);
       // Find the original task
@@ -1368,9 +1472,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       task_id: z.string().min(1).max(200).describe("Task ID to cancel"),
       reason: z.string().max(1000).optional().describe("Cancellation reason"),
       from_session: z.string().max(200).optional(),
+      network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
     },
-    async ({ task_id, reason, from_session: _fromIn }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
-      const effectiveNetId = getNetworkId(null);
+    async ({ task_id, reason, from_session: _fromIn, network_id: netId }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
+      const effectiveNetId = getNetworkId(netId);
       if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId);
       console.log(`[${ts()}] ${from_session} → cancel_task → ${task_id.slice(0, 8)}`);
       const updateParams: any[] = [reason || "cancelled by " + from_session, task_id];
@@ -1400,9 +1505,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       task_id: z.string().min(1).max(200).describe("Task ID to reassign"),
       new_alias: z.string().min(1).max(200).describe("Target agent alias"),
       from_session: z.string().max(200).optional(),
+      network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
     },
-    async ({ task_id, new_alias, from_session: _fromIn }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
-      const effectiveNetId = getNetworkId(null);
+    async ({ task_id, new_alias, from_session: _fromIn, network_id: netId }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
+      const effectiveNetId = getNetworkId(netId);
       if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId);
       console.log(`[${ts()}] ${from_session} → reassign_task → ${task_id.slice(0, 8)} → ${new_alias}`);
       const taskParams: any[] = [task_id];

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

@@ -71,13 +71,22 @@ 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;
 }
 
@@ -137,7 +146,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" },
@@ -153,7 +162,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" },
@@ -164,12 +173,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 () => {
@@ -178,10 +193,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);