@sleep2agi/commhub-server 0.8.5 → 0.8.6-preview.1

package/src/rename.ts

@@ -16,11 +16,14 @@ import { randomUUID } from "crypto";
 import { db } from "./db";
 import { getUserNetworkRole, getNetworkMembers } from "./auth";
 import { pushEvent } from "./push";
+import { eventBus } from "./event_bus";
 
 export interface RenameResult {
   ok: boolean;
   txn_id?: string;
   error?: string;
+  code?: string;
+  suggested?: string;
 }
 
 export interface CanonicalAlias {
@@ -111,7 +114,14 @@ export function prepareRename(
   // old-alias must exist as a session in this network
   const oldSession = db.get<any>(
     "SELECT 1 FROM sessions WHERE network_id = ?1 AND alias = ?2", networkId, oldAlias);
-  if (!oldSession) return { ok: false, error: `node "${oldAlias}" not found in this network` };
+  if (!oldSession) {
+    return {
+      ok: false,
+      code: "node_local_only",
+      error: `node "${oldAlias}" has no server session in this network`,
+      suggested: "rename locally",
+    };
+  }
 
   // new-alias must not be taken — in sessions OR reserved by another prepared txn
   const newInSessions = db.get<any>(
@@ -147,19 +157,32 @@ export function commitRename(userId: string, txnId: string): RenameResult {
     "SELECT 1 FROM sessions WHERE network_id = ?1 AND alias = ?2", txn.network_id, txn.new_alias);
   if (conflict) return { ok: false, error: `alias "${txn.new_alias}" was taken since prepare` };
 
-  db.run(
-    "UPDATE sessions SET alias = ?1, updated_at = datetime('now') WHERE network_id = ?2 AND alias = ?3",
-    [txn.new_alias, txn.network_id, txn.old_alias]);
-  cleanupRenamedAliasSession(txn.network_id, txn.old_alias, txn.new_alias);
-  db.run(
-    "UPDATE nodes SET alias = ?1, updated_at = datetime('now') WHERE network_id = ?2 AND alias = ?3",
-    [txn.new_alias, txn.network_id, txn.old_alias]);
-  db.run(
-    "UPDATE api_tokens SET name = ?1 WHERE network_id = ?2 AND name = ?3",
-    [`node:${txn.new_alias}`, txn.network_id, `node:${txn.old_alias}`]);
-  db.run(
-    "UPDATE rename_txn SET status = 'committed', committed_at = datetime('now') WHERE txn_id = ?1",
-    [txnId]);
+  const renamedNode = db.transaction(() => {
+    db.run(
+      "UPDATE sessions SET alias = ?1, updated_at = datetime('now') WHERE network_id = ?2 AND alias = ?3",
+      [txn.new_alias, txn.network_id, txn.old_alias]);
+    cleanupRenamedAliasSession(txn.network_id, txn.old_alias, txn.new_alias);
+    db.run(
+      "UPDATE nodes SET alias = ?1, updated_at = datetime('now') WHERE network_id = ?2 AND alias = ?3",
+      [txn.new_alias, txn.network_id, txn.old_alias]);
+    db.run(
+      "UPDATE api_tokens SET name = ?1 WHERE network_id = ?2 AND name = ?3",
+      [`node:${txn.new_alias}`, txn.network_id, `node:${txn.old_alias}`]);
+    db.run(
+      "UPDATE rename_txn SET status = 'committed', committed_at = datetime('now') WHERE txn_id = ?1",
+      [txnId]);
+    const node = db.get<{ node_id: string | null }>(
+      "SELECT node_id FROM sessions WHERE network_id = ?1 AND alias = ?2",
+      [txn.network_id, txn.new_alias]
+    );
+    eventBus.emit("rename-committed", {
+      networkId: txn.network_id,
+      old_alias: txn.old_alias,
+      new_alias: txn.new_alias,
+      node_id: node?.node_id ?? null,
+    });
+    return node;
+  });
 
   // RFC-010 §4.2.1 C4 — broadcast node.renamed SSE. (#84 实施补漏: the Server
   // surface originally missed C4; N站马's dashboard slice needs this event.)
@@ -174,9 +197,11 @@ export function commitRename(userId: string, txnId: string): RenameResult {
     txn_id: txnId,
     alias: txn.new_alias,
     network_id: txn.network_id,
+    node_id: renamedNode?.node_id ?? null,
     data: {
       old_alias: txn.old_alias,
       new_alias: txn.new_alias,
+      node_id: renamedNode?.node_id ?? null,
       surfaces_updated: ["config", "tmux", "commhub", "dashboard", "batch_prefix", "session_resume"],
       history_policy: "preserve",
     },

package/src/tools.ts

@@ -119,11 +119,18 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   const scopedSessionStatus = (alias: string, networkId?: string | null) => {
     const params: any[] = [alias];
-    let sql = "SELECT status, updated_at, last_seen_at FROM sessions WHERE alias = ?1";
+    let sql = "SELECT status, updated_at, last_seen_at, node_id FROM sessions WHERE alias = ?1";
     sql = addScope(sql, params, networkId);
     return db.get<any>(sql, ...params);
   };
 
+  const resolveNodeIdForAlias = (alias: string, networkId?: string | null): string | null => {
+    if (!alias || alias === "hub" || alias === "api") return null;
+    const canonical = resolveCanonicalAlias(networkId, alias);
+    const session = scopedSessionStatus(canonical.alias, networkId);
+    return session?.node_id ?? null;
+  };
+
   const resolveDeliveryTarget = (alias: string, networkId?: string | null): DeliveryTarget => {
     const session = scopedSessionStatus(alias, networkId);
     if (!session) {
@@ -746,20 +753,22 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
       console.log(`[${ts()}] ${from_session} → send_task → ${targetAlias}: ${task.slice(0, 60)}${priority === "high" ? " [HIGH]" : ""}${canonical.renamed ? ` [renamed from ${alias}]` : ""}`);
       const id = uuidv4();
+      const fromNodeId = resolveNodeIdForAlias(from_session, effectiveNetId);
+      const targetNodeId = target.session?.node_id ?? null;
       // 事务：inbox + tasks 双写 + 触碰目标 session 的 task/updated_at（让
       // dashboard 在派任务一刻就反映出"任务已下发"，不再等 agent 的
       // report_status 心跳；status 字段交给 agent，避免与 working/idle
       // 报告冲突）。
       db.transaction(() => {
         db.run(
-          `INSERT INTO inbox (id, session_name, type, priority, content, context, from_session, requires_response, network_id, meta_json)
-           VALUES (?1, ?2, 'task', ?3, ?4, ?5, ?6, 'reply', ?7, ?8)`,
-          [id, targetAlias, priority, task, context ?? null, from_session, effectiveNetId ?? null, metaJson]
+          `INSERT INTO inbox (id, session_name, node_id, type, priority, content, context, from_session, requires_response, network_id, meta_json)
+           VALUES (?1, ?2, ?3, 'task', ?4, ?5, ?6, ?7, 'reply', ?8, ?9)`,
+          [id, targetAlias, targetNodeId, priority, task, context ?? null, from_session, effectiveNetId ?? null, metaJson]
         );
         db.run(
-          `INSERT INTO tasks (task_id, from_name, to_name, priority, status, content, requires_response, created_at, delivered_at, expires_at, network_id, parent_task_id, meta_json)
-           VALUES (?1, ?2, ?3, ?4, 'delivered', ?5, 'reply', datetime('now'), datetime('now'), datetime('now', ?6), ?7, ?8, ?9)`,
-          [id, from_session, targetAlias, priority, task, `+${ttl_seconds || 3600} seconds`, effectiveNetId ?? null, parentTaskId, metaJson]
+          `INSERT INTO tasks (task_id, from_node_id, from_name, to_node_id, to_name, priority, status, content, requires_response, created_at, delivered_at, expires_at, network_id, parent_task_id, meta_json)
+           VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'delivered', ?7, 'reply', datetime('now'), datetime('now'), datetime('now', ?8), ?9, ?10, ?11)`,
+          [id, fromNodeId, from_session, targetNodeId, targetAlias, priority, task, `+${ttl_seconds || 3600} seconds`, effectiveNetId ?? null, parentTaskId, metaJson]
         );
         const touchParams: any[] = [task.slice(0, 200), targetAlias];
         let touchSql = "UPDATE sessions SET task = ?1, updated_at = datetime('now') WHERE alias = ?2";
@@ -833,22 +842,31 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     async ({ alias, message, from_session: _fromIn }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
       const effectiveNetId = getNetworkId(null);
       if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId);
-      const target = resolveDeliveryTarget(alias, effectiveNetId);
+      const canonical = resolveCanonicalAlias(effectiveNetId, alias);
+      const targetAlias = canonical.alias;
+      const target = resolveDeliveryTarget(targetAlias, effectiveNetId);
       if (target.state === "not_found") return deliveryTargetReply(target)!;
-      console.log(`[${ts()}] ${from_session} → send_message → ${alias}: ${message.slice(0, 60)}`);
+      console.log(`[${ts()}] ${from_session} → send_message → ${targetAlias}: ${message.slice(0, 60)}${canonical.renamed ? ` [renamed from ${alias}]` : ""}`);
       const id = uuidv4();
       db.run(
-        `INSERT INTO inbox (id, session_name, type, priority, content, from_session, network_id)
-         VALUES (?1, ?2, 'message', 'normal', ?3, ?4, ?5)`,
-        [id, alias, message, from_session, effectiveNetId ?? null]
+        `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, network_id)
+         VALUES (?1, ?2, ?3, 'message', 'normal', ?4, ?5, ?6)`,
+        [id, targetAlias, target.session?.node_id ?? null, message, from_session, effectiveNetId ?? null]
       );
 
       if (target.state === "online") {
-        pushEvent(alias, { type: "new_message", from: from_session, message_id: id }, effectiveNetId);
+        pushEvent(targetAlias, { type: "new_message", from: from_session, message_id: id, ...(canonical.renamed ? { renamed_from: alias } : {}) }, effectiveNetId);
       }
 
       const offlineReply = deliveryTargetReply(target, { message_id: id });
-      if (offlineReply) return offlineReply;
+      if (offlineReply) {
+        const payload = JSON.parse(offlineReply.content[0].text);
+        offlineReply.content[0].text = JSON.stringify({
+          ...payload,
+          ...(canonical.renamed ? { renamed_from: alias, renamed_to: targetAlias } : {}),
+        });
+        return offlineReply;
+      }
 
       return {
         content: [
@@ -857,6 +875,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
             text: JSON.stringify({
               ok: true,
               message_id: id,
+              ...(canonical.renamed ? { renamed_from: alias, renamed_to: targetAlias } : {}),
               session_status: target.session?.status ?? "unknown",
             }),
           },
@@ -917,11 +936,12 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           };
         }
       }
+      const replyTargetNodeId = resolveNodeIdForAlias(alias, effectiveNetId);
       const replyLogged = db.transaction(() => {
         db.run(
-          `INSERT INTO inbox (id, session_name, type, priority, content, from_session, in_reply_to, requires_response, network_id)
-           VALUES (?1, ?2, 'reply', 'normal', ?3, ?4, ?5, 'none', ?6)`,
-          [id, alias, 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)
+           VALUES (?1, ?2, ?3, 'reply', 'normal', ?4, ?5, ?6, 'none', ?7)`,
+          [id, alias, replyTargetNodeId, text, from_session, in_reply_to ?? null, effectiveNetId ?? null]
         );
 
         // 更新 tasks 表
@@ -1053,9 +1073,9 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         // Re-queue in inbox with new ID (original ID may already exist)
         const retryInboxId = uuidv4();
         db.run(
-          `INSERT INTO inbox (id, session_name, type, priority, content, from_session, requires_response, network_id)
-           VALUES (?1, ?2, 'task', ?3, ?4, ?5, 'reply', ?6)`,
-          [retryInboxId, task.to_name, task.priority, task.content, from_session, effectiveNetId ?? task.network_id ?? null]
+          `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, requires_response, network_id)
+           VALUES (?1, ?2, ?3, 'task', ?4, ?5, ?6, 'reply', ?7)`,
+          [retryInboxId, task.to_name, task.to_node_id ?? resolveNodeIdForAlias(task.to_name, effectiveNetId ?? task.network_id ?? null), task.priority, task.content, from_session, effectiveNetId ?? task.network_id ?? null]
         );
       });
       logTaskEvent(task_id, task.status, "delivered", from_session, "retry");
@@ -1098,18 +1118,20 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       alias: z.string().max(200).optional().describe("Filter by to_name (target agent)"),
       status: z.string().max(50).optional().describe("Filter by status"),
       from_name: z.string().max(200).optional().describe("Filter by sender"),
+      from_node_id: z.string().max(200).optional().describe("Filter by immutable sender node_id"),
       network_id: z.string().max(200).optional().describe("Filter by network"),
       limit: z.number().min(1).max(100).optional().default(20),
     },
-    async ({ alias, status, from_name, network_id: netId, limit }) => {
+    async ({ alias, status, from_name, from_node_id, network_id: netId, limit }) => {
       const readScope = resolveReadScope(netId);
       if (readScope.denied) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: readScope.denied }) }] };
-      let sql = "SELECT task_id, from_name, to_name, priority, status, content, result, created_at, completed_at FROM tasks WHERE 1=1";
+      let sql = "SELECT task_id, from_node_id, from_name, to_node_id, to_name, priority, status, content, result, created_at, completed_at FROM tasks WHERE 1=1";
       const params: any[] = [];
       sql = addReadScope(sql, params, readScope);
       if (alias) { sql += ` AND to_name = ?${params.length + 1}`; params.push(alias); }
       if (status) { sql += ` AND status = ?${params.length + 1}`; params.push(status); }
       if (from_name) { sql += ` AND from_name = ?${params.length + 1}`; params.push(from_name); }
+      if (from_node_id) { sql += ` AND from_node_id = ?${params.length + 1}`; params.push(from_node_id); }
       sql += ` ORDER BY created_at DESC LIMIT ?${params.length + 1}`;
       params.push(limit);
       const tasks = db.all(sql, ...params);
@@ -1184,6 +1206,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: `task is terminal (${task.status})` }) }] };
       }
       const oldAlias = task.to_name;
+      const canonical = resolveCanonicalAlias(effectiveNetId ?? task.network_id ?? null, new_alias);
+      const reassignedAlias = canonical.alias;
+      const target = resolveDeliveryTarget(reassignedAlias, effectiveNetId ?? task.network_id ?? null);
+      const newNodeId = target.state === "not_found" ? null : (target.session?.node_id ?? null);
       db.transaction(() => {
         // Ack old inbox to prevent original agent from picking it up
         const inboxParams: any[] = [task_id];
@@ -1191,18 +1217,18 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         inboxSql = addScope(inboxSql, inboxParams, effectiveNetId);
         db.run(inboxSql, inboxParams);
 
-        const updateParams: any[] = [new_alias, task_id];
-        let updateSql = "UPDATE tasks SET to_name = ?1, status = 'delivered', started_at = NULL, delivered_at = datetime('now') WHERE task_id = ?2";
+        const updateParams: any[] = [reassignedAlias, newNodeId, task_id];
+        let updateSql = "UPDATE tasks SET to_name = ?1, to_node_id = ?2, status = 'delivered', started_at = NULL, delivered_at = datetime('now') WHERE task_id = ?3";
         updateSql = addScope(updateSql, updateParams, effectiveNetId);
         db.run(updateSql, updateParams);
 
         const newInboxId = uuidv4();
-        db.run("INSERT INTO inbox (id, session_name, type, priority, content, from_session, requires_response, network_id) VALUES (?1, ?2, 'task', ?3, ?4, ?5, 'reply', ?6)",
-          [newInboxId, new_alias, task.priority, task.content, from_session, effectiveNetId ?? task.network_id ?? null]);
+        db.run("INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, requires_response, network_id) VALUES (?1, ?2, ?3, 'task', ?4, ?5, ?6, 'reply', ?7)",
+          [newInboxId, reassignedAlias, newNodeId, task.priority, task.content, from_session, effectiveNetId ?? task.network_id ?? null]);
       });
-      logTaskEvent(task_id, task.status, "delivered", from_session, `reassign: ${oldAlias} → ${new_alias}`);
-      pushEvent(new_alias, { type: "new_task", inbox_count: 1, priority: task.priority, from: from_session }, effectiveNetId ?? task.network_id ?? null);
-      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, task_id, reassigned_from: oldAlias, reassigned_to: new_alias }) }] };
+      logTaskEvent(task_id, task.status, "delivered", from_session, `reassign: ${oldAlias} → ${reassignedAlias}`);
+      pushEvent(reassignedAlias, { type: "new_task", inbox_count: 1, priority: task.priority, from: from_session, ...(canonical.renamed ? { renamed_from: new_alias } : {}) }, effectiveNetId ?? task.network_id ?? null);
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, task_id, reassigned_from: oldAlias, reassigned_to: reassignedAlias, ...(canonical.renamed ? { renamed_from: new_alias, renamed_to: reassignedAlias } : {}) }) }] };
     }
   );
 
@@ -1219,21 +1245,21 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       const effectiveNetId = getNetworkId(netId);
       if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId);
       console.log(`[${ts()}] hub → broadcast: ${message.slice(0, 60)}${effectiveNetId ? " [net=" + effectiveNetId.slice(0, 12) + "]" : ""}`);
-      let sql = "SELECT alias, network_id FROM sessions WHERE alias IS NOT NULL";
+      let sql = "SELECT alias, node_id, network_id FROM sessions WHERE alias IS NOT NULL";
       const params: any[] = [];
       sql = addScope(sql, params, effectiveNetId);
       if (filter_server) { sql += " AND server = ?"; params.push(filter_server); }
       if (filter_status) { sql += " AND status = ?"; params.push(filter_status); }
 
-      const targets = db.all<{ alias: string; network_id: string | null }>(sql, ...params);
+      const targets = db.all<{ alias: string; node_id: string | null; network_id: string | null }>(sql, ...params);
       const ids: string[] = [];
 
       for (const t of targets) {
         const id = uuidv4();
         db.run(
-          `INSERT INTO inbox (id, session_name, type, priority, content, from_session, network_id)
-           VALUES (?1, ?2, 'broadcast', 'normal', ?3, 'hub', ?4)`,
-          [id, t.alias, message, effectiveNetId ?? t.network_id ?? null]
+          `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, network_id)
+           VALUES (?1, ?2, ?3, 'broadcast', 'normal', ?4, 'hub', ?5)`,
+          [id, t.alias, t.node_id ?? null, message, effectiveNetId ?? t.network_id ?? null]
         );
         ids.push(id);
       }

package/src/uploads-http.test.ts

@@ -0,0 +1,208 @@
+// #221 — integration smoke for /api/upload + /api/files/:file_id + /api/task
+// attachments. Spawns the real Bun.serve hub in a child process, hits it
+// with real fetch() calls, asserts on the 6-item security checklist.
+//
+// Runs entirely under bun test — no Docker needed for the in-repo
+// signal (Docker harness is documented in #221 for 测试马's UAT, but
+// 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 { 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}`;
+
+let server: any;
+let userToken = "";
+let userNetworkId = "";
+
+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
+  // over "already taken" from a prior test in the same DB. Strong
+  // password keeps us past validatePasswordStrength even when we're
+  // not the first user in the DB.
+  const username = `upload_admin_${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+  const password = "BootstrapPw123Aa!";
+  let r = register(username, password, undefined, "seed");
+  if (!r.ok) {
+    console.error("[test bootstrap] register failed:", r.error);
+  }
+  if (r.token) {
+    userToken = r.token;
+    userNetworkId = r.network_id ?? "";
+  } else {
+    const lr = login(username, password);
+    if (lr.token) userToken = lr.token;
+    if (lr.network_id) userNetworkId = lr.network_id;
+  }
+  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");
+  // Tiny settle so the listener is ready.
+  await new Promise((r) => setTimeout(r, 100));
+});
+
+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 { 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}` };
+}
+
+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 });
+  return res;
+}
+
+describe("POST /api/upload — 6-item security checklist (HTTP integration)", () => {
+  test("(item 5) anonymous request → 401", async () => {
+    const res = await uploadFile(new Uint8Array([1, 2, 3]), "tiny.bin", "application/octet-stream", { skipAuth: true });
+    expect(res.status).toBe(401);
+  });
+
+  test("(item 5) bad bearer token → 401", async () => {
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array([1, 2, 3])]), "tiny.bin");
+    const res = await fetch(`${BASE}/api/upload`, {
+      method: "POST",
+      body: form,
+      headers: { "Authorization": "Bearer this-is-not-a-real-token" },
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("(items 1+2) successful upload returns server-generated file_id + url, blob lands inside uploads root", async () => {
+    const content = new Uint8Array(1024).fill(0xab);
+    const res = await uploadFile(content, "client-supplied-name.bin", "application/octet-stream");
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.ok).toBe(true);
+    expect(typeof body.file_id).toBe("string");
+    expect(body.file_id.length).toBe(32);
+    expect(body.url).toBe(`/api/files/${body.file_id}`);
+    expect(body.size).toBe(1024);
+    // The path MUST live inside the configured uploads root.
+    expect(String(body.path).startsWith(UPLOADS_DIR)).toBe(true);
+    // The path MUST NOT contain the client-supplied filename.
+    expect(String(body.path).includes("client-supplied-name")).toBe(false);
+    // Blob really exists on disk.
+    expect(existsSync(body.path)).toBe(true);
+  });
+
+  test("(item 4 stage-2) 12 MiB cap — slightly over the limit is rejected with 413", async () => {
+    const overLimit = new Uint8Array(12 * 1024 * 1024 + 16).fill(0xcd);
+    const res = await uploadFile(overLimit, "over.bin", "application/octet-stream");
+    expect(res.status).toBe(413);
+    const body = await res.json() as any;
+    expect(body.ok).toBe(false);
+    expect(body.error).toBe("payload_too_large");
+    expect(body.limit_bytes).toBe(12 * 1024 * 1024);
+  });
+
+  test("(item 4 stage-1) missing Content-Length → 411 Length Required", async () => {
+    // Forge a raw request with a body but no Content-Length. The
+    // simplest way to do this in Bun is to construct a Request with a
+    // streaming ReadableStream body — Bun then doesn't set
+    // Content-Length on outgoing fetch.
+    const stream = new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode("not actually multipart"));
+        controller.close();
+      },
+    });
+    const res = await fetch(`${BASE}/api/upload`, {
+      method: "POST",
+      body: stream,
+      headers: { ...authHeaders(), "Content-Type": "multipart/form-data; boundary=xxx", "Transfer-Encoding": "chunked" },
+      // @ts-expect-error — Bun-specific to force streaming upload
+      duplex: "half",
+    });
+    expect(res.status).toBe(411);
+  });
+
+  test("(extra defense) non-multipart body is rejected (415 or 400)", async () => {
+    // We accept either 415 (Content-Type !multipart) or 400 (body
+    // failed to parse as multipart). Both mean "we refused to accept
+    // 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`, {
+      method: "POST",
+      body: JSON.stringify({ nope: 1 }),
+      headers: { ...authHeaders(), "Content-Type": "application/json" },
+    });
+    expect([400, 415]).toContain(res.status);
+  });
+});
+
+describe("GET /api/files/:file_id — download safety", () => {
+  let fileId = "";
+
+  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;
+  });
+
+  test("(item 3) download returns the blob with Content-Disposition: attachment + X-Content-Type-Options: nosniff", async () => {
+    const res = await fetch(`${BASE}/api/files/${fileId}`, { headers: authHeaders() });
+    expect(res.status).toBe(200);
+    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");
+    const text = await res.text();
+    expect(text).toBe("hello-world-from-#221-integration-test");
+  });
+
+  test("anonymous download is 401", async () => {
+    const res = await fetch(`${BASE}/api/files/${fileId}`);
+    expect(res.status).toBe(401);
+  });
+
+  test("traversal attempt in path is rejected at the regex layer with 400", async () => {
+    const res = await fetch(`${BASE}/api/files/..%2Fetc%2Fpasswd`, { headers: authHeaders() });
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.error).toBe("bad_file_id");
+  });
+
+  test("unknown file_id is 404", async () => {
+    const res = await fetch(`${BASE}/api/files/0123456789abcdef0123456789abcdef`, { headers: authHeaders() });
+    expect(res.status).toBe(404);
+  });
+});
+
+// NOTE on /api/task attachments coverage: the validation logic
+// (validateAttachments) is exercised end-to-end in
+// uploads.test.ts with 6 cases covering happy path / too-many /
+// bad type / bad file_id / size cap / non-array. The HTTP wire-up
+// (server/src/index.ts inside the /api/task handler) is a one-line
+// merge that surfaces `validateAttachments`'s structured error as a
+// 400 `bad_attachments` to the caller — see the #221 contract in
+// the issue comment for the full request/response shape that N站马
+// APP will consume.