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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.8.5",
+  "version": "0.8.6-preview.0",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -7,6 +7,22 @@ import { createSSEStream, pushEvent, getSSEStats } from "./push.js";
 import { register, login, resolveToken, getUserNetworks, getUserAllNetworks, createNetwork, deleteNetwork, renameNetwork, changePassword, issueUserToken, listTokens, createToken, revokeToken, getNetworkMembers, getUserNetworkRole, addNetworkMember, updateMemberRole, removeNetworkMember, createInvite, joinByInvite, createNetworkTokenForNode, type AuthUser } from "./auth.js";
 import { abortRename, cleanupCommittedRenameSessions, commitRename, prepareRename, resolveCanonicalAlias } from "./rename.js";
 import { sharedSendDedup, buildDuplicateSendPayload } from "./send_dedup.js";
+import {
+  FILE_ID_REGEX,
+  MAX_REQUEST_CONTENT_LENGTH,
+  MAX_UPLOAD_BYTES,
+  buildStoragePath,
+  generateFileId,
+  getUploadsRoot,
+  indexEntryPath,
+  isPathInsideUploadsRoot,
+  sanitizeExt,
+  sharedUploadRateLimiter,
+  validateAttachments,
+  validateIndexEntry,
+} from "./uploads.js";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync } from "fs";
+import { dirname as pathDirname } from "path";
 
 const PORT = Number(process.env.PORT) || 9200;
 const HOST = process.env.HOST || "127.0.0.1";
@@ -380,6 +396,10 @@ const TaskSchema = z.object({
   network_id: z.string().max(200).optional(),
   parent_task_id: z.string().max(200).optional(),
   ttl_seconds: z.number().min(1).max(86400).optional(),
+  // #221 — top-level attachments mirror the MCP send_task tool. They are
+  // merged into `meta.attachments` for persistence so the on-disk shape
+  // stays unified regardless of transport (REST or MCP).
+  attachments: z.any().optional(),
   meta: z.any().optional(),
 });
 
@@ -443,6 +463,13 @@ Bun.serve({
   port: PORT,
   hostname: HOST,
   idleTimeout: 255, // max value: keep SSE connections alive (seconds)
+  // #221 — defense-in-depth cap on the raw request body. The /api/upload
+  // handler also pre-checks Content-Length and post-checks parsed size
+  // against the documented 12 MiB cap (MAX_UPLOAD_BYTES); this knob
+  // simply guarantees Bun's own buffer won't grow past 13 MiB on any
+  // route. Default Bun ceiling is 128 MiB which is too permissive for
+  // a hub now exposed to the public internet.
+  maxRequestBodySize: MAX_REQUEST_CONTENT_LENGTH,
 
   async fetch(req, server) {
     const url = new URL(req.url, `http://localhost:${PORT}`);
@@ -1197,6 +1224,222 @@ Bun.serve({
       }));
     }
 
+    // ── REST: file upload (#221) ──
+    // POST multipart/form-data with a single `file` field. Bearer auth.
+    // 12 MiB cap (two-stage: Content-Length pre-check + post-parse size
+    // verify). Returns { ok, file_id, path, url, size, mime }. The
+    // file_id is server-generated (crypto.randomUUID with hyphens
+    // stripped) so a client-supplied filename never enters the storage
+    // path. The download URL `/api/files/<file_id>` requires the same
+    // Bearer auth and forces Content-Disposition: attachment +
+    // X-Content-Type-Options: nosniff so uploaded files can never be
+    // executed or served as HTML.
+    if (url.pathname === "/api/upload" && req.method === "POST") {
+      const authErr = requireAuth(req);
+      if (authErr) return withCors(req, authErr);
+
+      // Rate-limit key prefers the token id (so 60/h is per-token, not
+      // per-IP); falls back to IP for legacy or anonymous-but-dev-open.
+      const authCtx = resolveRequestAuth(req);
+      const rateKey = authCtx?.tokenId ?? `ip:${getClientIP(req, server)}`;
+      const rate = sharedUploadRateLimiter.check(rateKey);
+      if (!rate.allowed) {
+        const headers: Record<string, string> = {
+          "X-RateLimit-Limit": String(60),
+          "X-RateLimit-Remaining": "0",
+          "X-RateLimit-Reset": String(Math.floor(rate.resetAt / 1000)),
+        };
+        if (rate.retryAfterMs) headers["Retry-After"] = String(Math.ceil(rate.retryAfterMs / 1000));
+        return withCors(req, new Response(
+          JSON.stringify({ ok: false, error: "rate_limited", message: "Upload rate limit exceeded (60/hour). Try again later.", retry_after_ms: rate.retryAfterMs }),
+          { status: 429, headers: { ...headers, "Content-Type": "application/json" } },
+        ));
+      }
+
+      // Two-stage size cap per 通信龙 dispatch c38de7a9:
+      //   stage 1 — reject before reading body when Content-Length
+      //             exceeds the cap (saves bandwidth, fails fast)
+      //   stage 2 — re-verify the parsed File.size after Bun has parsed
+      //             the multipart envelope (defends against a missing
+      //             or lied Content-Length header)
+      const contentLength = req.headers.get("Content-Length");
+      if (!contentLength) {
+        return withCors(req, Response.json(
+          { ok: false, error: "length_required", message: "Content-Length header is required for /api/upload" },
+          { status: 411 },
+        ));
+      }
+      const declaredBytes = Number(contentLength);
+      if (!Number.isFinite(declaredBytes) || declaredBytes < 0) {
+        return withCors(req, Response.json({ ok: false, error: "bad_content_length" }, { status: 400 }));
+      }
+      if (declaredBytes > MAX_REQUEST_CONTENT_LENGTH) {
+        return withCors(req, Response.json(
+          { ok: false, error: "payload_too_large", message: `Upload exceeds the ${MAX_UPLOAD_BYTES} byte limit`, limit_bytes: MAX_UPLOAD_BYTES },
+          { status: 413 },
+        ));
+      }
+
+      const contentType = req.headers.get("Content-Type") ?? "";
+      if (!/^multipart\/form-data/i.test(contentType)) {
+        return withCors(req, Response.json(
+          { ok: false, error: "unsupported_media_type", message: "Use multipart/form-data with a 'file' field" },
+          { status: 415 },
+        ));
+      }
+
+      let form: FormData;
+      try {
+        form = await req.formData();
+      } catch (e: any) {
+        return withCors(req, Response.json(
+          { ok: false, error: "multipart_parse_failed", message: e?.message?.slice(0, 200) ?? "multipart parse failed" },
+          { status: 400 },
+        ));
+      }
+      const file = form.get("file");
+      if (!file || typeof file === "string") {
+        return withCors(req, Response.json(
+          { ok: false, error: "missing_file", message: "Expected a 'file' field with binary content" },
+          { status: 400 },
+        ));
+      }
+
+      // Stage 2 — re-verify parsed size against the documented cap.
+      if (file.size > MAX_UPLOAD_BYTES) {
+        return withCors(req, Response.json(
+          { ok: false, error: "payload_too_large", message: `Upload exceeds the ${MAX_UPLOAD_BYTES} byte limit`, limit_bytes: MAX_UPLOAD_BYTES, observed_bytes: file.size },
+          { status: 413 },
+        ));
+      }
+
+      const fileId = generateFileId();
+      const ext = sanitizeExt(file.name);
+      let storage;
+      try {
+        storage = buildStoragePath(fileId, ext);
+      } catch (e: any) {
+        // Should be unreachable — we generated the id ourselves — but
+        // surface as 500 if our own primitives reject our own input.
+        console.error("[/api/upload] buildStoragePath rejected:", e?.message);
+        return withCors(req, Response.json({ ok: false, error: "internal_path_error" }, { status: 500 }));
+      }
+
+      try {
+        mkdirSync(pathDirname(storage.absolutePath), { recursive: true });
+        const buf = Buffer.from(await file.arrayBuffer());
+        writeFileSync(storage.absolutePath, buf);
+        // Defense-in-depth: after writing, confirm the path still sits
+        // inside the uploads root (catches a symlink swap or root env
+        // poisoning across processes).
+        if (!isPathInsideUploadsRoot(storage.absolutePath)) {
+          // Refuse to acknowledge a write that landed outside the root.
+          // Don't try to clean up — better to keep evidence on disk than
+          // chase a symlink for cleanup.
+          console.error("[/api/upload] write escaped uploads root:", storage.absolutePath);
+          return withCors(req, Response.json({ ok: false, error: "internal_path_escape" }, { status: 500 }));
+        }
+
+        // Persist the index entry so /api/files/<file_id> can do an
+        // O(1) lookup without scanning every date bucket.
+        const idxPath = indexEntryPath(fileId);
+        if (idxPath) {
+          mkdirSync(pathDirname(idxPath), { recursive: true });
+          writeFileSync(idxPath, JSON.stringify({
+            file_id: fileId,
+            date_bucket: storage.dateBucket,
+            ext: storage.ext,
+            name: typeof file.name === "string" ? file.name.slice(0, 255) : "",
+            mime: typeof file.type === "string" ? file.type.slice(0, 100) : "application/octet-stream",
+            size: file.size,
+            owner: authCtx?.username ?? null,
+            owner_id: authCtx?.userId ?? null,
+            uploaded_at: new Date().toISOString(),
+          }, null, 2));
+        }
+      } catch (e: any) {
+        console.error("[/api/upload] write failed:", e?.message);
+        return withCors(req, Response.json({ ok: false, error: "write_failed", message: e?.message?.slice(0, 200) ?? "write failed" }, { status: 500 }));
+      }
+
+      return withCors(req, Response.json({
+        ok: true,
+        file_id: fileId,
+        path: storage.absolutePath,
+        url: `/api/files/${fileId}`,
+        size: file.size,
+        mime: typeof file.type === "string" ? file.type : "application/octet-stream",
+      }));
+    }
+
+    // ── REST: file download (#221) ──
+    // GET /api/files/:file_id with Bearer auth. Always forces
+    // Content-Disposition: attachment + X-Content-Type-Options: nosniff
+    // so the served file can never be executed or rendered as HTML.
+    // The file_id is validated against the same strict regex used at
+    // generation time before any filesystem access.
+    const fileMatch = url.pathname.match(/^\/api\/files\/(.+)$/);
+    if (fileMatch && req.method === "GET") {
+      const authErr = requireAuth(req);
+      if (authErr) return withCors(req, authErr);
+
+      const fileId = decodeURIComponent(fileMatch[1]);
+      if (!FILE_ID_REGEX.test(fileId)) {
+        return withCors(req, Response.json({ ok: false, error: "bad_file_id" }, { status: 400 }));
+      }
+
+      const idxPath = indexEntryPath(fileId);
+      if (!idxPath || !existsSync(idxPath)) {
+        return withCors(req, Response.json({ ok: false, error: "not_found" }, { status: 404 }));
+      }
+
+      let entry: any;
+      try { entry = JSON.parse(readFileSync(idxPath, "utf-8")); } catch {
+        return withCors(req, Response.json({ ok: false, error: "index_corrupt" }, { status: 500 }));
+      }
+      if (!validateIndexEntry(entry)) {
+        return withCors(req, Response.json({ ok: false, error: "index_invalid" }, { status: 500 }));
+      }
+
+      let storage;
+      try {
+        storage = buildStoragePath(entry.file_id, entry.ext);
+      } catch {
+        return withCors(req, Response.json({ ok: false, error: "index_invalid" }, { status: 500 }));
+      }
+      if (!isPathInsideUploadsRoot(storage.absolutePath)) {
+        // Defence: should be unreachable since buildStoragePath rejected
+        // malformed inputs, but a poisoned index could try to fool us.
+        return withCors(req, Response.json({ ok: false, error: "path_escape" }, { status: 500 }));
+      }
+      if (!existsSync(storage.absolutePath)) {
+        return withCors(req, Response.json({ ok: false, error: "blob_missing" }, { status: 404 }));
+      }
+
+      // Defence: verify the on-disk size matches what the index claims
+      // before serving — a tampered index could otherwise mislead the
+      // caller about file integrity.
+      const st = statSync(storage.absolutePath);
+      if (st.size !== entry.size) {
+        console.error("[/api/files] size mismatch:", { fileId, indexed: entry.size, onDisk: st.size });
+        return withCors(req, Response.json({ ok: false, error: "size_mismatch" }, { status: 500 }));
+      }
+
+      const safeFilename = (entry.name && /^[\x20-\x7e]+$/.test(entry.name))
+        ? entry.name
+        : `${fileId}${entry.ext}`;
+      const blob = Bun.file(storage.absolutePath);
+      const responseHeaders: Record<string, string> = {
+        ...corsHeaders(req),
+        "Content-Type": "application/octet-stream", // always opaque; nosniff prevents the client from re-deciding
+        "Content-Length": String(entry.size),
+        "Content-Disposition": `attachment; filename="${safeFilename.replace(/"/g, "")}"`,
+        "X-Content-Type-Options": "nosniff",
+        "Cache-Control": "private, no-store",
+      };
+      return new Response(blob, { status: 200, headers: responseHeaders });
+    }
+
     // ── REST: send task ──
     if (url.pathname === "/api/task" && req.method === "POST") {
       let raw: unknown;
@@ -1243,7 +1486,20 @@ Bun.serve({
       const id = crypto.randomUUID();
       const fromSession = body.from || "api";
       const ttlSeconds = (body as any).ttl_seconds || 3600;
-      const metaJson = normalizeMetaJson((body as any).meta);
+      // #221 — fold top-level `attachments` into `meta.attachments` so
+      // the REST and MCP send_task transports produce identical
+      // tasks.meta_json shape downstream. Top-level wins over any
+      // duplicate `meta.attachments` the client supplied. Validation
+      // matches the MCP-side schema (max 20 entries, file_id regex,
+      // size cap, etc.).
+      const attachmentsResult = validateAttachments((body as any).attachments ?? (body as any).meta?.attachments);
+      if (!attachmentsResult.ok) {
+        return withCors(req, Response.json({ ok: false, error: "bad_attachments", message: attachmentsResult.error }, { status: 400 }));
+      }
+      const mergedMeta = attachmentsResult.attachments.length
+        ? { ...((body as any).meta && typeof (body as any).meta === "object" ? (body as any).meta : {}), attachments: attachmentsResult.attachments }
+        : (body as any).meta;
+      const metaJson = normalizeMetaJson(mergedMeta);
 
       // #212 dedup guardrail. Mirrors the MCP `send_task` tool: same
       // (from_session, target_alias, task) within COMMHUB_SEND_DEDUP_WINDOW_MS

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.

package/src/uploads.test.ts

@@ -0,0 +1,294 @@
+// #221 — unit tests for the upload primitives. The HTTP wire-up + Bun
+// multipart parsing lives in server/src/index.ts; this file pins the
+// path / regex / rate-limit / attachment-schema invariants that the
+// 6-item security checklist depends on.
+//
+// Coverage matrix:
+//   1. file_id regex accepts server-generated ids + rejects traversal attempts
+//   2. sanitizeExt strips client-side filename paths, lowercases ext
+//   3. buildStoragePath rejects malformed id / ext, places file under date bucket
+//   4. isPathInsideUploadsRoot defends against symlink / traversal escape
+//   5. UploadRateLimiter — first call allowed, exhausting bucket blocks, window expiry resets
+//   6. validateAttachments accepts MCP-compatible shape, rejects too-many / bad type / bad file_id
+//   7. validateIndexEntry refuses tampered shapes
+//   8. indexEntryPath rejects malformed file_id
+import { describe, expect, test } from "bun:test";
+import {
+  FILE_ID_REGEX,
+  MAX_UPLOAD_BYTES,
+  UploadRateLimiter,
+  UPLOAD_RATE_MAX_PER_WINDOW,
+  UPLOAD_RATE_WINDOW_MS,
+  buildStoragePath,
+  generateFileId,
+  getDateBucket,
+  indexEntryPath,
+  isPathInsideUploadsRoot,
+  sanitizeExt,
+  validateAttachments,
+  validateIndexEntry,
+} from "./uploads";
+
+describe("FILE_ID_REGEX", () => {
+  test("accepts the server-generated uuidv4-without-hyphens shape (32 hex chars)", () => {
+    for (let i = 0; i < 20; i++) {
+      const id = generateFileId();
+      expect(FILE_ID_REGEX.test(id)).toBe(true);
+      expect(id.length).toBe(32);
+    }
+  });
+
+  test("rejects every directory-traversal attempt a client might try", () => {
+    const traversals = [
+      "../foo",
+      "..%2Ffoo",
+      "foo/bar",
+      "foo\\bar",
+      "foo.bar",
+      ".bashrc",
+      "/etc/passwd",
+      "foo bar",
+      "",
+      "abc", // too short
+      "x".repeat(65), // too long
+    ];
+    for (const t of traversals) {
+      expect(FILE_ID_REGEX.test(t)).toBe(false);
+    }
+  });
+});
+
+describe("sanitizeExt", () => {
+  test("returns a leading-dot lowercase extension for a normal filename", () => {
+    expect(sanitizeExt("photo.PNG")).toBe(".png");
+    expect(sanitizeExt("report.pdf")).toBe(".pdf");
+    expect(sanitizeExt("archive.tar.gz")).toBe(".gz");
+  });
+
+  test("strips any client-supplied directory prefix before reading the ext", () => {
+    // The handler must NEVER use the client filename for storage paths,
+    // but the ext is allowed through for nicer URLs. We still strip any
+    // path separator the client tries to sneak in.
+    expect(sanitizeExt("../../etc/passwd.jpg")).toBe(".jpg");
+    expect(sanitizeExt("..\\..\\windows\\boot.ini")).toBe(".ini");
+    expect(sanitizeExt("foo/bar/baz.html")).toBe(".html");
+  });
+
+  test("returns empty string for missing / weird inputs", () => {
+    expect(sanitizeExt(undefined)).toBe("");
+    expect(sanitizeExt(null)).toBe("");
+    expect(sanitizeExt("")).toBe("");
+    expect(sanitizeExt("noext")).toBe("");
+    // ".bashrc" → ".bashrc" is acceptable: storage uses the server-generated
+    // file_id, so the file lands as "<file_id>.bashrc". The download handler
+    // forces Content-Disposition: attachment + X-Content-Type-Options: nosniff,
+    // so the ext can't be leveraged to execute / mis-render the file.
+    expect(sanitizeExt(".bashrc")).toBe(".bashrc");
+    // ext > 16 chars is rejected; "extensiontoolong1" is 17 chars.
+    expect(sanitizeExt("foo.extensiontoolong1")).toBe("");
+  });
+
+  test("rejects exts with non-alphanumeric characters", () => {
+    expect(sanitizeExt("payload.exe;.png")).toBe(".png");
+    expect(sanitizeExt("foo.<script>")).toBe("");
+  });
+});
+
+describe("buildStoragePath", () => {
+  test("places the file under a YYYY-MM-DD bucket with file_id+ext as the name", () => {
+    const now = new Date("2026-06-11T03:00:00Z");
+    const r = buildStoragePath("abcdef1234567890abcdef1234567890", ".png", {
+      uploadsRoot: "/srv/uploads",
+      now,
+    });
+    expect(r.dateBucket).toBe("2026-06-11");
+    expect(r.relativePath).toBe("2026-06-11/abcdef1234567890abcdef1234567890.png");
+    expect(r.absolutePath).toBe("/srv/uploads/2026-06-11/abcdef1234567890abcdef1234567890.png");
+  });
+
+  test("rejects malformed file_id", () => {
+    expect(() => buildStoragePath("../etc/passwd", ".png", { uploadsRoot: "/srv" })).toThrow(/invalid/);
+    expect(() => buildStoragePath("ok", ".png", { uploadsRoot: "/srv" })).toThrow(/invalid/);
+  });
+
+  test("rejects malformed ext", () => {
+    expect(() => buildStoragePath(generateFileId(), "../passwd", { uploadsRoot: "/srv" })).toThrow(/invalid/);
+    expect(() => buildStoragePath(generateFileId(), ".x".repeat(40), { uploadsRoot: "/srv" })).toThrow(/invalid/);
+  });
+
+  test("allows empty ext", () => {
+    const r = buildStoragePath(generateFileId(), "", { uploadsRoot: "/srv" });
+    expect(r.relativePath.endsWith("/")).toBe(false);
+    expect(r.relativePath.includes(".")).toBe(false);
+  });
+});
+
+describe("getDateBucket", () => {
+  test("uses UTC so the bucket is consistent across hub timezones", () => {
+    expect(getDateBucket(new Date("2026-06-11T23:59:59Z"))).toBe("2026-06-11");
+    expect(getDateBucket(new Date("2026-06-12T00:00:01Z"))).toBe("2026-06-12");
+  });
+});
+
+describe("isPathInsideUploadsRoot", () => {
+  test("true for a normal nested path", () => {
+    expect(isPathInsideUploadsRoot("/srv/uploads/2026-06-11/abc.png", "/srv/uploads")).toBe(true);
+  });
+
+  test("false for an upward traversal that lands outside the root", () => {
+    expect(isPathInsideUploadsRoot("/srv/uploads/../etc/passwd", "/srv/uploads")).toBe(false);
+    expect(isPathInsideUploadsRoot("/etc/passwd", "/srv/uploads")).toBe(false);
+  });
+
+  test("false for the root itself (must be a file underneath, not the root dir)", () => {
+    expect(isPathInsideUploadsRoot("/srv/uploads", "/srv/uploads")).toBe(false);
+  });
+});
+
+describe("UploadRateLimiter", () => {
+  test("first N calls within window are allowed; the (N+1)th is blocked", () => {
+    const lim = new UploadRateLimiter(60_000, 3); // 3 per minute
+    const t0 = 1_700_000_000_000;
+    const a1 = lim.check("token-x", t0);
+    const a2 = lim.check("token-x", t0 + 100);
+    const a3 = lim.check("token-x", t0 + 200);
+    const a4 = lim.check("token-x", t0 + 300);
+    expect(a1.allowed).toBe(true);
+    expect(a2.allowed).toBe(true);
+    expect(a3.allowed).toBe(true);
+    expect(a4.allowed).toBe(false);
+    if (!a4.allowed) {
+      expect(a4.retryAfterMs).toBeGreaterThan(0);
+      expect(a4.retryAfterMs).toBeLessThanOrEqual(60_000);
+    }
+  });
+
+  test("different keys are isolated", () => {
+    const lim = new UploadRateLimiter(60_000, 1);
+    expect(lim.check("alice", 1).allowed).toBe(true);
+    expect(lim.check("alice", 2).allowed).toBe(false);
+    expect(lim.check("bob", 3).allowed).toBe(true);
+  });
+
+  test("window expiry resets the bucket", () => {
+    const lim = new UploadRateLimiter(60_000, 1);
+    const t0 = 1_700_000_000_000;
+    expect(lim.check("token-x", t0).allowed).toBe(true);
+    expect(lim.check("token-x", t0 + 30_000).allowed).toBe(false);
+    expect(lim.check("token-x", t0 + 60_001).allowed).toBe(true);
+  });
+
+  test("default constructor matches documented public defaults", () => {
+    const lim = new UploadRateLimiter();
+    expect(UPLOAD_RATE_WINDOW_MS).toBe(60 * 60 * 1000);
+    expect(UPLOAD_RATE_MAX_PER_WINDOW).toBe(60);
+    for (let i = 0; i < UPLOAD_RATE_MAX_PER_WINDOW; i++) {
+      expect(lim.check("token-y", 1 + i).allowed).toBe(true);
+    }
+    expect(lim.check("token-y", 1000).allowed).toBe(false);
+  });
+});
+
+describe("validateAttachments", () => {
+  test("undefined / null input → empty array", () => {
+    const a = validateAttachments(undefined);
+    expect(a.ok).toBe(true);
+    if (a.ok) expect(a.attachments).toEqual([]);
+    const b = validateAttachments(null);
+    expect(b.ok).toBe(true);
+    if (b.ok) expect(b.attachments).toEqual([]);
+  });
+
+  test("rejects non-array input", () => {
+    expect(validateAttachments("nope").ok).toBe(false);
+    expect(validateAttachments({}).ok).toBe(false);
+  });
+
+  test("accepts a well-formed attachment matching MCP send_task shape", () => {
+    const fileId = generateFileId();
+    const res = validateAttachments([
+      { type: "file", file_id: fileId, name: "photo.png", mime: "image/png", size: 12345 },
+    ]);
+    expect(res.ok).toBe(true);
+    if (res.ok) {
+      expect(res.attachments[0].file_id).toBe(fileId);
+      expect(res.attachments[0].mime).toBe("image/png");
+    }
+  });
+
+  test("rejects too many attachments (>20)", () => {
+    const fileId = generateFileId();
+    const many = Array.from({ length: 21 }, () => ({ type: "file" as const, file_id: fileId }));
+    const res = validateAttachments(many);
+    expect(res.ok).toBe(false);
+  });
+
+  test("rejects invalid file_id (path traversal)", () => {
+    const res = validateAttachments([{ type: "file", file_id: "../etc/passwd" }]);
+    expect(res.ok).toBe(false);
+  });
+
+  test("rejects size larger than MAX_UPLOAD_BYTES", () => {
+    const fileId = generateFileId();
+    const res = validateAttachments([{ type: "file", file_id: fileId, size: MAX_UPLOAD_BYTES + 1 }]);
+    expect(res.ok).toBe(false);
+  });
+
+  test("rejects unexpected type", () => {
+    const res = validateAttachments([{ type: "image", file_id: generateFileId() }]);
+    expect(res.ok).toBe(false);
+  });
+});
+
+describe("validateIndexEntry", () => {
+  test("accepts a well-formed entry", () => {
+    const id = generateFileId();
+    expect(
+      validateIndexEntry({
+        file_id: id,
+        date_bucket: "2026-06-11",
+        ext: ".png",
+        name: "anything",
+        mime: "image/png",
+        size: 12345,
+        uploaded_at: "2026-06-11T03:00:00Z",
+      }),
+    ).toBe(true);
+  });
+
+  test("rejects bad date_bucket (anti-tamper)", () => {
+    expect(
+      validateIndexEntry({ file_id: generateFileId(), date_bucket: "../etc", ext: ".png", size: 1 }),
+    ).toBe(false);
+  });
+
+  test("rejects bad ext", () => {
+    expect(
+      validateIndexEntry({ file_id: generateFileId(), date_bucket: "2026-06-11", ext: "/etc/passwd", size: 1 }),
+    ).toBe(false);
+  });
+
+  test("rejects size beyond MAX_UPLOAD_BYTES (anti-tamper)", () => {
+    expect(
+      validateIndexEntry({
+        file_id: generateFileId(),
+        date_bucket: "2026-06-11",
+        ext: "",
+        size: MAX_UPLOAD_BYTES + 1,
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("indexEntryPath", () => {
+  test("returns null on malformed file_id", () => {
+    expect(indexEntryPath("../etc/passwd", { uploadsRoot: "/srv" })).toBeNull();
+    expect(indexEntryPath("", { uploadsRoot: "/srv" })).toBeNull();
+  });
+
+  test("places the index file under <uploadsRoot>/.index/", () => {
+    const id = generateFileId();
+    const p = indexEntryPath(id, { uploadsRoot: "/srv/up" });
+    expect(p).toBe(`/srv/up/.index/${id}.json`);
+  });
+});

package/src/uploads.ts

@@ -0,0 +1,240 @@
+// #221 — commhub-server file upload primitives.
+//
+// Hub upload surface for the mobile APP (#220). The hub started reverse-
+// proxying over HTTPS to the public internet last night, so the upload
+// endpoint is a brand-new public attack surface. The six security items
+// in the issue are HARD verification items, encoded here:
+//
+//   1. file_id is server-generated (uuidv4, alphanumeric only), client-
+//      supplied filenames never enter the storage path.
+//   2. Storage root sits in $HOME/.anet/server/uploads (outside any
+//      web-served directory); downloads go through an explicit handler.
+//   3. Download handler forces Content-Disposition: attachment +
+//      X-Content-Type-Options: nosniff — uploaded files are never
+//      executed or served as HTML.
+//   4. 12 MB cap enforced two-stage per 通信龙: Content-Length header
+//      pre-check (reject before reading body) + post-parse size verify.
+//   5. Auth is the existing requireAuth — anonymous + bad tokens 401.
+//   6. Naive per-token rate limit: 60 uploads/hour per token (or IP for
+//      legacy/dev mode).
+//
+// This module stays pure-ish: file I/O lives in the HTTP handlers, the
+// path / id / rate-limit primitives are unit-testable.
+
+import { homedir } from "os";
+import { join, relative, isAbsolute } from "path";
+
+export const MAX_UPLOAD_BYTES = 12 * 1024 * 1024;
+
+// Allow ~1 MiB of multipart envelope overhead on top of the 12 MiB
+// payload limit when checking Content-Length. The post-parse check is
+// still done against MAX_UPLOAD_BYTES so the actual binary payload
+// never exceeds the documented cap.
+export const MAX_REQUEST_CONTENT_LENGTH = MAX_UPLOAD_BYTES + 1024 * 1024;
+
+// Per-token rate-limit constants. 60 uploads/hour matches the issue
+// "如 60 req/h" suggestion and is enforced in-memory (one process holds
+// the source of truth; resets on restart).
+export const UPLOAD_RATE_WINDOW_MS = 60 * 60 * 1000;
+export const UPLOAD_RATE_MAX_PER_WINDOW = 60;
+
+// Strict file_id regex. Generated server-side via crypto.randomUUID()
+// with hyphens stripped, so the natural output is 32 hex chars. The
+// regex is intentionally permissive on the upper bound (64 chars) to
+// allow future scheme changes (e.g. prefix), but it rejects ANY of `.`
+// `/` `\` `..` so the same regex used for path generation can also be
+// used to validate a /api/files/:file_id lookup against directory
+// traversal.
+export const FILE_ID_REGEX = /^[A-Za-z0-9_-]{8,64}$/;
+
+export type GeneratedFile = {
+  fileId: string;
+  ext: string;
+  dateBucket: string;
+  relativePath: string;
+  absolutePath: string;
+};
+
+export function getUploadsRoot(env: NodeJS.ProcessEnv = process.env): string {
+  return env.COMMHUB_UPLOADS_DIR || join(homedir(), ".anet/server/uploads");
+}
+
+export function getDateBucket(now: Date = new Date()): string {
+  // YYYY-MM-DD partitioning per issue spec — keeps a single directory
+  // from accumulating millions of entries while leaving the lookup
+  // path predictable from the disk index (file_id → date bucket).
+  return now.toISOString().slice(0, 10);
+}
+
+export function generateFileId(): string {
+  return crypto.randomUUID().replace(/-/g, "");
+}
+
+/**
+ * Extract a safe file extension from a client-supplied filename.
+ * Server NEVER uses the rest of the filename. Returns "" if no
+ * acceptable extension is present.
+ *
+ * Accepts: alphanumeric extensions of 1–16 chars (`.png`, `.tar`,
+ * `.docx`, `.tar.gz` returns only `.gz`). Rejects: anything containing
+ * path separators, dots in unusual positions, or non-ASCII characters.
+ */
+export function sanitizeExt(filename: string | undefined | null): string {
+  if (!filename || typeof filename !== "string") return "";
+  // Defense: strip any leading directory the client might have shoved
+  // into "name", then take only the last extension.
+  const base = filename.split(/[\\/]/).pop() ?? "";
+  const match = base.match(/\.([A-Za-z0-9]{1,16})$/);
+  return match ? "." + match[1].toLowerCase() : "";
+}
+
+/**
+ * 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.
+ */
+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`);
+  const dateBucket = getDateBucket(opts.now);
+  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
+  ext: string;         // ".png" / ".pdf" / etc., including the leading dot, lowercase
+  name: string;        // original filename — stored as metadata only, NEVER used in paths
+  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
+  uploaded_at: string; // ISO 8601
+};
+
+/** 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. */
+export function indexEntryPath(fileId: string, opts: { uploadsRoot?: string } = {}): string | null {
+  if (!FILE_ID_REGEX.test(fileId)) return null;
+  const root = opts.uploadsRoot ?? getUploadsRoot();
+  return join(root, ".index", fileId + ".json");
+}
+
+/** Validate an index entry shape before serving a download. Defends
+ * against a malformed/tampered .index file by re-checking the same
+ * invariants the upload handler enforces. */
+export function validateIndexEntry(entry: unknown): entry is UploadIndexEntry {
+  if (!entry || typeof entry !== "object") return false;
+  const e: any = entry;
+  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)) &&
+    typeof e.size === "number" && e.size >= 0 && e.size <= MAX_UPLOAD_BYTES
+  );
+}
+
+/**
+ * Defence-in-depth: confirm a resolved absolute path falls within
+ * the uploads root. The HTTP handler calls this after constructing
+ * the download path; if it ever reports `false` we hard-fail the
+ * request rather than serve whatever the resolved path points at.
+ */
+export function isPathInsideUploadsRoot(absPath: string, uploadsRoot?: string): boolean {
+  const root = uploadsRoot ?? getUploadsRoot();
+  const rel = relative(root, absPath);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+// ── Rate limit (in-memory, per token/IP) ────────────────────────────
+
+type UploadRateState = { count: number; resetAt: number };
+
+export class UploadRateLimiter {
+  private state = new Map<string, UploadRateState>();
+
+  constructor(
+    private readonly windowMs: number = UPLOAD_RATE_WINDOW_MS,
+    private readonly maxPerWindow: number = UPLOAD_RATE_MAX_PER_WINDOW,
+  ) {}
+
+  /**
+   * Attempt to consume one upload quota slot for `key` (typically the
+   * caller's token id, falling back to IP for legacy auth). Returns
+   * `{ allowed: true }` when the upload may proceed and
+   * `{ allowed: false, retryAfterMs }` when the caller is rate-limited.
+   * Window is rolling on first touch (not aligned to wall-clock hours).
+   */
+  check(key: string, nowMs: number = Date.now()): { allowed: boolean; remaining: number; resetAt: number; retryAfterMs?: number } {
+    const entry = this.state.get(key);
+    if (!entry || nowMs >= entry.resetAt) {
+      const resetAt = nowMs + this.windowMs;
+      this.state.set(key, { count: 1, resetAt });
+      return { allowed: true, remaining: this.maxPerWindow - 1, resetAt };
+    }
+    if (entry.count >= this.maxPerWindow) {
+      return { allowed: false, remaining: 0, resetAt: entry.resetAt, retryAfterMs: entry.resetAt - nowMs };
+    }
+    entry.count++;
+    return { allowed: true, remaining: this.maxPerWindow - entry.count, resetAt: entry.resetAt };
+  }
+
+  /** Visible for tests — clear all rate-limit state. */
+  reset(): void {
+    this.state.clear();
+  }
+
+  /** Visible for tests — current bucket count. */
+  size(): number {
+    return this.state.size;
+  }
+}
+
+/** Module-level singleton shared by the HTTP /api/upload handler. */
+export const sharedUploadRateLimiter = new UploadRateLimiter();
+
+// ── Attachment schema (shared between REST /api/task and MCP send_task) ───
+
+/**
+ * Canonical shape for the `attachments` field on tasks. Both the REST
+ * /api/task body and the MCP send_task tool accept this same array;
+ * server persistence routes through `tasks.meta_json` so the storage
+ * layout is identical regardless of transport.
+ */
+export type TaskAttachment = {
+  type: "file";
+  file_id: string;
+  name?: string;
+  mime?: string;
+  size?: number;
+};
+
+/** Light validator usable from the REST handler. Returns null on success or an error message string. */
+export function validateAttachments(input: unknown): { ok: true; attachments: TaskAttachment[] } | { ok: false; error: string } {
+  if (input === undefined || input === null) return { ok: true, attachments: [] };
+  if (!Array.isArray(input)) return { ok: false, error: "attachments must be an array" };
+  if (input.length > 20) return { ok: false, error: "too many attachments (max 20)" };
+  const out: TaskAttachment[] = [];
+  for (let i = 0; i < input.length; i++) {
+    const a: any = input[i];
+    if (!a || typeof a !== "object") return { ok: false, error: `attachments[${i}] is not an object` };
+    if (a.type !== "file") return { ok: false, error: `attachments[${i}].type must be "file"` };
+    if (typeof a.file_id !== "string" || !FILE_ID_REGEX.test(a.file_id)) {
+      return { ok: false, error: `attachments[${i}].file_id is invalid` };
+    }
+    if (a.name !== undefined && (typeof a.name !== "string" || a.name.length > 255)) {
+      return { ok: false, error: `attachments[${i}].name must be a string ≤ 255 chars` };
+    }
+    if (a.mime !== undefined && (typeof a.mime !== "string" || a.mime.length > 100)) {
+      return { ok: false, error: `attachments[${i}].mime must be a string ≤ 100 chars` };
+    }
+    if (a.size !== undefined && (typeof a.size !== "number" || a.size < 0 || a.size > MAX_UPLOAD_BYTES)) {
+      return { ok: false, error: `attachments[${i}].size must be a non-negative number ≤ ${MAX_UPLOAD_BYTES}` };
+    }
+    out.push({ type: "file", file_id: a.file_id, name: a.name, mime: a.mime, size: a.size });
+  }
+  return { ok: true, attachments: out };
+}