@sleep2agi/commhub-server 0.9.0-preview.22 → 0.9.0-preview.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.22",
+  "version": "0.9.0-preview.23",
   "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/api-nodes-shape.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 import { db } from "./db.js";
+import { parseStoredTags } from "./node-attrs-validate.js";
 
 // Regression test for SELECT * fragility on GET /api/nodes.
 //
@@ -41,7 +42,12 @@ function mapRow(r: Record<string, unknown>): Record<string, unknown> {
     catch { /* malformed */ }
   }
   const { config_snapshot, ...rest } = r;
-  return { ...rest, role };
+  return {
+    ...rest,
+    tags: parseStoredTags(r.tags),
+    attrs_revision: Number(r.attrs_revision ?? 0),
+    role,
+  };
 }
 
 describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", () => {
@@ -66,7 +72,7 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
       `SELECT node_id, node_name, alias, runtime, model,
               config_path, channels, server, hostname,
               network_id, created_at, updated_at,
-              config_snapshot
+              config_snapshot, display_name, team, tags, attrs_revision
        FROM nodes WHERE node_id = ?1`,
       TEST_NODE,
     );
@@ -85,11 +91,17 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     expect(row).not.toHaveProperty("config_snapshot");
     // role is EXTRACTED from config_snapshot JSON, not the raw blob
     expect(row.role).toBe("host_supervisor");
-    // Belt: full key set is exactly the 13 contract fields
+    // Belt: the key set is exactly the dashboard-facing contract.
+    // NOTE: this file MIRRORS the handler's SQL rather than calling it, so
+    // it can drift — it already lagged behind `lifecycle_state` /
+    // `avatar_url`, which the handler selects but this mirror does not.
+    // Treat a diff here as "re-read the handler", not as proof of the wire
+    // shape; node-attrs.test.ts asserts the real HTTP response.
     expect(Object.keys(row).sort()).toEqual([
-      "alias", "channels", "config_path", "created_at", "hostname",
-      "model", "network_id", "node_id", "node_name", "role", "runtime",
-      "server", "updated_at",
+      "alias", "attrs_revision", "channels", "config_path", "created_at",
+      "display_name", "hostname", "model", "network_id", "node_id",
+      "node_name", "role", "runtime", "server", "tags", "team",
+      "updated_at",
     ]);
   });
 
@@ -102,7 +114,8 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     );
     let row = mapRow(db.get<Record<string, unknown>>(
       `SELECT node_id, node_name, alias, runtime, model, config_path, channels,
-              server, hostname, network_id, created_at, updated_at, config_snapshot
+              server, hostname, network_id, created_at, updated_at, config_snapshot,
+              display_name, team, tags, attrs_revision
        FROM nodes WHERE node_id = ?1`,
       TEST_NODE,
     )!);
@@ -113,7 +126,8 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     db.run(`UPDATE nodes SET config_snapshot = ?1 WHERE node_id = ?2`, ["not-json{", TEST_NODE]);
     row = mapRow(db.get<Record<string, unknown>>(
       `SELECT node_id, node_name, alias, runtime, model, config_path, channels,
-              server, hostname, network_id, created_at, updated_at, config_snapshot
+              server, hostname, network_id, created_at, updated_at, config_snapshot,
+              display_name, team, tags, attrs_revision
        FROM nodes WHERE node_id = ?1`,
       TEST_NODE,
     )!);
@@ -124,7 +138,8 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
            [JSON.stringify({ model: "x", flags: {} }), TEST_NODE]);
     row = mapRow(db.get<Record<string, unknown>>(
       `SELECT node_id, node_name, alias, runtime, model, config_path, channels,
-              server, hostname, network_id, created_at, updated_at, config_snapshot
+              server, hostname, network_id, created_at, updated_at, config_snapshot,
+              display_name, team, tags, attrs_revision
        FROM nodes WHERE node_id = ?1`,
       TEST_NODE,
     )!);
@@ -141,7 +156,8 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     );
     const rows = db.all<Record<string, unknown>>(
       `SELECT node_id, node_name, alias, runtime, model, config_path, channels,
-              server, hostname, network_id, created_at, updated_at, config_snapshot
+              server, hostname, network_id, created_at, updated_at, config_snapshot,
+              display_name, team, tags, attrs_revision
        FROM nodes WHERE network_id = ?1`,
       TEST_NETWORK,
     ).map(mapRow);

package/src/db.ts

@@ -348,6 +348,38 @@ try {
   if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
 }
 
+// Node DISPLAY attributes (Vincent 目标第 3 条 — dashboard/app 多维度编辑).
+// Same posture as avatar_url above: hub-side presentation only, NOT part of
+// the RFC-024 config-apply pipeline (agent-node consumes none of them, so a
+// doorbell/ack round-trip would be meaningless and could wedge the config
+// revision). Written only via PUT /api/nodes/:ref/attrs.
+//
+//   display_name   — human label shown in the UI. Distinct from `alias`,
+//                    which is the ROUTING key (messages address the alias)
+//                    and from `node_name`, which is an addressing key
+//                    (`WHERE node_id OR node_name OR alias`). Renaming
+//                    either of those must go through the rename 2PC
+//                    (/api/node-rename/*), never through an attrs write.
+//   team, tags     — organisation metadata; tags stored as JSON array text.
+//   attrs_revision — optimistic-lock counter for these display fields ONLY.
+//                    Deliberately separate from config_revision so that
+//                    editing a tag never bumps the node's *config* revision
+//                    (which would perturb the config ack protocol).
+//
+// All nullable / defaulted so the ~100 rows already in flight keep reading.
+for (const ddl of [
+  `ALTER TABLE nodes ADD COLUMN display_name TEXT`,
+  `ALTER TABLE nodes ADD COLUMN team TEXT`,
+  `ALTER TABLE nodes ADD COLUMN tags TEXT`,
+  `ALTER TABLE nodes ADD COLUMN attrs_revision INTEGER NOT NULL DEFAULT 0`,
+]) {
+  try {
+    db.exec(ddl);
+  } catch (e: any) {
+    if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+  }
+}
+
 // RFC-027 §2 — stop/delete request envelope. Mirrors
 // node_create_requests structure so the daemon-side pull/ack pattern
 // is symmetric with create_node. action='stop'|'delete' picks which

package/src/file-download-authz-dev-open.test.ts

@@ -0,0 +1,135 @@
+// #495 — DEV_OPEN mode null-owner allowance (Test B from PR #500 CR
+// checklist). Sibling to file-download-authz.test.ts.
+//
+// Why a separate file: DEV_OPEN is captured at server.ts module-load
+// time (`const DEV_OPEN = process.argv.includes("--dev-open") ||
+// process.env.COMMHUB_DEV_OPEN === "1"`). Once the singleton is
+// loaded with DEV_OPEN=false, no `process.env` change can flip it
+// back inside the same Bun process. So the DEV_OPEN test lives in
+// its own file that sets `COMMHUB_DEV_OPEN=1` BEFORE importing.
+//
+// Skip discipline: if this file runs in aggregate `bun test src/`
+// AFTER file-download-authz.test.ts has already loaded server.ts
+// with DEV_OPEN=false, our env change is ignored. We detect that at
+// module load via a boot probe and `test.skipIf` the whole file so
+// the runner reports "skipped" (NOT "passed"). Standalone run
+// (`bun test src/file-download-authz-dev-open.test.ts`) always
+// works — CI must include a standalone target for this file to
+// guarantee it actually executes.
+
+import { describe, expect, test, afterAll } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+const SERVER_DB = mkdtempSync(join(tmpdir(), "anet-495-devopen-db-")) + "/commhub.db";
+const UPLOADS_DIR = mkdtempSync(join(tmpdir(), "anet-495-devopen-fs-"));
+
+// Set env BEFORE importing anything that touches db-adapter.ts or
+// server.ts (both capture env at module load).
+process.env.COMMHUB_DB = SERVER_DB;
+process.env.COMMHUB_UPLOADS_DIR = UPLOADS_DIR;
+process.env.HOST = "127.0.0.1";
+process.env.COMMHUB_DEV_OPEN = "1";
+delete process.env.COMMHUB_AUTH_TOKEN;
+
+const { register } = await import("./auth.js");
+const { db } = await import("./db.js");
+
+// #500 CR2 DEV_OPEN 假门 fix — register a FIRST user (userA) so any
+// "first-user-auto-admin" logic falls on userA. Then register userB
+// as the non-admin download-attempt actor. Without this two-user
+// split, the download test would short-circuit through the admin
+// allow-list branch instead of exercising the DEV_OPEN branch — the
+// mutation test (remove DEV_OPEN branch → expect RED) would silently
+// still pass.
+const nameA = `useraaa_devopen_${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+const rA = register(nameA, "BootstrapPw123Aa!", undefined, "userA");
+if (!rA.ok) throw new Error(`userA register failed: ${rA.error}`);
+
+const nameB = `userbbb_devopen_${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+const rB = register(nameB, "BootstrapPw123Aa!", undefined, "userB");
+if (!rB.ok) throw new Error(`userB register failed: ${rB.error}`);
+const userBToken = rB.token!;
+const userBUserId = rB.user!.user_id;
+
+// Fixture-drift guard: userB must NOT be admin. If a future auth.ts
+// change grants admin to more than the first user (or the DB seeder
+// promotes both), the DEV_OPEN test would silently short-circuit
+// through the admin branch of authorizeFileDownload. Fail loudly.
+{
+  const roleRow = db.get<{ role: string }>(
+    "SELECT role FROM users WHERE user_id = ?1",
+    userBUserId,
+  );
+  if (!roleRow) throw new Error("userB not found in users table after register");
+  if (roleRow.role === "admin") {
+    throw new Error(
+      `[#500 CR2 fixture-drift guard] userB was auto-promoted to admin ` +
+      `(role=${roleRow.role}) in DEV_OPEN sibling test. Refusing to run: ` +
+      `the DEV_OPEN branch would not actually be exercised — the download ` +
+      `would short-circuit through the admin allow-list and validate nothing.`,
+    );
+  }
+}
+
+const { bootServer } = await import("./server.js");
+const server = bootServer({ port: 0, hostname: "127.0.0.1" });
+const BASE = `http://127.0.0.1:${server.port}`;
+await new Promise((r) => setTimeout(r, 100));
+
+// Probe: is DEV_OPEN active in the loaded server module? Upload a file
+// with no auth — DEV_OPEN allows anon; production would 401.
+async function probeDevOpen(): Promise<boolean> {
+  const form = new FormData();
+  form.append("file", new Blob([new TextEncoder().encode("probe")], { type: "application/octet-stream" }), "probe.bin");
+  const res = await fetch(`${BASE}/api/upload`, { method: "POST", body: form });
+  return res.status === 200;
+}
+const devOpenActive = await probeDevOpen();
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(UPLOADS_DIR, { recursive: true, force: true }); } catch {}
+  try { rmSync(SERVER_DB, { recursive: true, force: true }); } catch {}
+  delete process.env.COMMHUB_DEV_OPEN;
+});
+
+async function uploadAnon(content: Uint8Array, filename: string): Promise<string> {
+  const form = new FormData();
+  form.append("file", new Blob([content], { type: "application/octet-stream" }), filename);
+  const res = await fetch(`${BASE}/api/upload`, { method: "POST", body: form });
+  expect(res.status).toBe(200);
+  const body: any = await res.json();
+  expect(typeof body.file_id).toBe("string");
+  return body.file_id;
+}
+
+async function downloadAs(token: string | null, fileId: string): Promise<Response> {
+  const headers: Record<string, string> = {};
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return fetch(`${BASE}/api/files/${fileId}`, { headers });
+}
+
+describe.skipIf(!devOpenActive)("#495 — DEV_OPEN null-owner allowance (Test B)", () => {
+  test("null-owner uploaded via anonymous DEV_OPEN request → non-admin userB can download (200) via DEV_OPEN branch", async () => {
+    const devOpenFileId = await uploadAnon(new TextEncoder().encode("dev-open-blob"), "dev.bin");
+
+    // Verify the upload really produced null-owner (matches the shape
+    // production callers might see if DEV_OPEN were misconfigured).
+    const { readFileSync } = await import("fs");
+    const entryPath = join(UPLOADS_DIR, ".index", `${devOpenFileId}.json`);
+    if (existsSync(entryPath)) {
+      const entry = JSON.parse(readFileSync(entryPath, "utf-8"));
+      expect(entry.owner_id).toBeNull();
+    }
+
+    // userB is non-admin (guarded at module load). If DEV_OPEN branch
+    // is removed from authorizeFileDownload, this returns 404 instead
+    // of 200 — the assertion below turns red, catching the regression
+    // structurally rather than via admin-branch short-circuit.
+    const res = await downloadAs(userBToken, devOpenFileId);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("dev-open-blob");
+  });
+});

package/src/file-download-authz.test.ts

@@ -0,0 +1,349 @@
+// #495 — file download authorization (P0 staged hotfix, PR #500).
+//
+// Before this fix, /api/files/:file_id only checked authentication.
+// Any authenticated principal could download any file cross-network by
+// guessing / obtaining a file_id.
+//
+// This suite spawns a real Bun.serve hub in-process and validates the
+// allow-list (owner + admin + legacy-master + null-owner-DEV_OPEN).
+// Same-network non-owner is EXPLICITLY out of scope in this stage —
+// see PR body access matrix + follow-up #503. That "same-network peer
+// returns 404" is an intentional carve-out here, not a bug.
+//
+// The DEV_OPEN branch is verified in a sibling test file
+// (file-download-authz-dev-open.test.ts) because DEV_OPEN is captured
+// at server.ts module-load time and can't be flipped mid-suite.
+//
+// Skip discipline: master-token tests use `test.skipIf(!masterTokenActive)`
+// so aggregate `bun test src/` reports "skipped" (not "passed") when
+// the loaded server module's frozen AUTH_TOKEN binding predates our
+// env setup. `if (!x) return` was previously used and Bun records
+// that as PASS — which is exactly the "skip-as-pass" trap that let
+// an earlier round claim coverage it never had. (See project memory
+// `feedback_skip_via_early_return_shows_as_pass`.)
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+const SERVER_DB = mkdtempSync(join(tmpdir(), "anet-495-db-")) + "/commhub.db";
+const UPLOADS_DIR = mkdtempSync(join(tmpdir(), "anet-495-fs-"));
+const MASTER_TOKEN = process.env.COMMHUB_AUTH_TOKEN ?? `master-495-${Date.now()}-${Math.floor(Math.random() * 100000)}`;
+
+// Set env BEFORE importing anything that pulls in db-adapter.ts (which
+// refuses to open a default DB under NODE_ENV=test) or server.ts (which
+// captures DEV_OPEN + AUTH_TOKEN at module load).
+process.env.COMMHUB_DB = SERVER_DB;
+process.env.COMMHUB_UPLOADS_DIR = UPLOADS_DIR;
+process.env.HOST = "127.0.0.1";
+process.env.COMMHUB_AUTH_TOKEN = MASTER_TOKEN;
+delete process.env.COMMHUB_DEV_OPEN;
+
+const { register, addNetworkMember, getUserAllNetworks } = await import("./auth.js");
+const { db } = await import("./db.js");
+
+// Seed accounts. register()'s "first-user-is-admin" is not reliable in
+// aggregate (earlier test files may seed users), so we promote via SQL.
+const adminName = `admin_495_${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+const rAdmin = register(adminName, "BootstrapPw123Aa!", undefined, "seed");
+if (!rAdmin.ok) throw new Error(`admin register failed: ${rAdmin.error}`);
+const adminToken = rAdmin.token!;
+db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [rAdmin.user!.user_id]);
+
+const nameA = `useraaa_495_${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+const rA = register(nameA, "BootstrapPw123Aa!", undefined, "userA");
+if (!rA.ok) throw new Error(`userA register failed: ${rA.error}`);
+const userAToken = rA.token!;
+const userAUserId = rA.user!.user_id;
+
+const nameB = `userbbb_495_${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+const rB = register(nameB, "BootstrapPw123Aa!", undefined, "userB");
+if (!rB.ok) throw new Error(`userB register failed: ${rB.error}`);
+const userBToken = rB.token!;
+const userBUserId = rB.user!.user_id;
+const userBNetworkToken = rB.network_token!;
+const userBNetworkId = getUserAllNetworks(userBUserId)[0]?.network_id!;
+if (!userBNetworkId) throw new Error("userB default network not found");
+
+// #500 CR2 DEV_OPEN 假门 fix — assert userB is NOT admin at fixture
+// setup time. If fixture ordering ever changes (e.g. auth.ts flips
+// "first user auto-admin" logic, or an earlier test file promotes
+// userB), the assertion catches it before Test A/B can silently
+// short-circuit through the admin branch of authorizeFileDownload
+// and hide a broken DEV_OPEN gate. Independent审员 caught this
+// class of假门 in the prior CR round — the assertion writes the
+// "userB is non-admin" invariant into the test itself so a future
+// fixture drift cannot re-open the hole.
+{
+  const userBRoleRow = db.get<{ role: string }>(
+    "SELECT role FROM users WHERE user_id = ?1",
+    userBUserId,
+  );
+  if (!userBRoleRow) throw new Error("userB not found in users table after register");
+  if (userBRoleRow.role === "admin") {
+    throw new Error(
+      `[#500 CR2 fixture-drift guard] userB was auto-promoted to admin ` +
+      `(role=${userBRoleRow.role}). Refusing to run: the DEV_OPEN and ` +
+      `cross-owner tests would short-circuit through the admin allow-list ` +
+      `branch and validate nothing.`,
+    );
+  }
+}
+
+// Add userA as a member of userB's default network. This is what makes
+// the "same-network non-owner" test cell meaningful — without it, that
+// test would only prove cross-network denial, which is a weaker claim.
+const addMember = addNetworkMember(userBNetworkId, userAUserId, "member", userBUserId);
+if (!addMember.ok) throw new Error(`add userA to userB network failed: ${addMember.error}`);
+
+const { bootServer } = await import("./server.js");
+const server = bootServer({ port: 0, hostname: "127.0.0.1" });
+const BASE = `http://127.0.0.1:${server.port}`;
+await new Promise((r) => setTimeout(r, 100));
+
+// Probe the loaded server's frozen AUTH_TOKEN binding. If master token
+// works we can exercise the legacy branch; if not (aggregate load-order
+// effect), `test.skipIf` reports "skipped" (NOT "passed").
+const _probeMaster = await fetch(`${BASE}/api/files/00000000000000000000000000000000`, {
+  headers: { Authorization: `Bearer ${MASTER_TOKEN}` },
+});
+const masterTokenActive = _probeMaster.status === 404;
+
+// Probe the loaded server's frozen DEV_OPEN binding. This file is
+// meant to run against a DEV_OPEN=false server. In aggregate mode,
+// if file-download-authz-dev-open.test.ts loaded server.ts first
+// with DEV_OPEN=true, the singleton wins — we can't flip it. Skip
+// the whole production-mode suite via `describe.skipIf` (NOT
+// early-return in each test body) so the runner reports "skipped".
+async function _uploadProbe(): Promise<number> {
+  const form = new FormData();
+  form.append("file", new Blob([new TextEncoder().encode("p")], { type: "application/octet-stream" }), "p");
+  const r = await fetch(`${BASE}/api/upload`, { method: "POST", body: form });
+  return r.status;
+}
+const devOpenSuspected = (await _uploadProbe()) === 200;
+const isProdMode = !devOpenSuspected;
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(UPLOADS_DIR, { recursive: true, force: true }); } catch {}
+  try { rmSync(SERVER_DB, { recursive: true, force: true }); } catch {}
+  delete process.env.COMMHUB_AUTH_TOKEN;
+});
+
+async function uploadAs(token: string, content: Uint8Array, filename: string): Promise<string> {
+  const form = new FormData();
+  form.append("file", new Blob([content], { type: "application/octet-stream" }), filename);
+  const res = await fetch(`${BASE}/api/upload`, {
+    method: "POST",
+    body: form,
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  expect(res.status).toBe(200);
+  const body: any = await res.json();
+  expect(typeof body.file_id).toBe("string");
+  return body.file_id;
+}
+
+async function downloadAs(token: string | null, fileId: string): Promise<Response> {
+  const headers: Record<string, string> = {};
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return fetch(`${BASE}/api/files/${fileId}`, { headers });
+}
+
+describe.skipIf(!isProdMode)("#495 — GET /api/files/:file_id authorization (owner-only staged)", () => {
+  let userBFileId = "";
+
+  beforeAll(async () => {
+    userBFileId = await uploadAs(userBToken, new TextEncoder().encode("secret-from-B"), "b-secret.txt");
+    expect(userBFileId.length).toBe(32);
+  });
+
+  test("owner (userB) via utok_ downloads own file → 200 (normal path)", async () => {
+    const res = await downloadAs(userBToken, userBFileId);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("secret-from-B");
+  });
+
+  test("owner (userB) via ntok_ downloads own file → 200 (agent self-upload+self-download)", async () => {
+    const agentFileId = await uploadAs(userBNetworkToken, new TextEncoder().encode("agent-blob"), "agent.bin");
+    const res = await downloadAs(userBNetworkToken, agentFileId);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("agent-blob");
+  });
+
+  test("🔴 non-owner (userA) downloads userB's file → 404 (was 200 pre-#495)", async () => {
+    const res = await downloadAs(userAToken, userBFileId);
+    expect(res.status).toBe(404);
+    const body: any = await res.json();
+    expect(body.error).toBe("not_found");
+  });
+
+  test("🔴 same-network non-owner (userA is a member of userB's network) → 404 (STAGED carve-out; follow-up #503)", async () => {
+    // Precondition — userA really is a member of userB's default
+    // network (added in module setup). Guard the invariant so the
+    // 404 result actually represents "same-network peer denied",
+    // not "cross-network denied".
+    const rows = db.all<{ network_id: string }>(
+      "SELECT network_id FROM network_members WHERE user_id = ?1 AND network_id = ?2",
+      userAUserId, userBNetworkId,
+    );
+    expect(rows.length).toBe(1);
+    const res = await downloadAs(userAToken, userBFileId);
+    expect(res.status).toBe(404);
+    const body: any = await res.json();
+    expect(body.error).toBe("not_found");
+  });
+
+  test("admin caller downloads any file → 200 (operational access preserved)", async () => {
+    const res = await downloadAs(adminToken, userBFileId);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("secret-from-B");
+  });
+
+  test.skipIf(!masterTokenActive)("legacy master AUTH_TOKEN downloads any file → 200 (single-tenant deployments)", async () => {
+    const res = await downloadAs(MASTER_TOKEN, userBFileId);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("secret-from-B");
+  });
+
+  test("anonymous request → 401 (auth still required)", async () => {
+    const res = await downloadAs(null, userBFileId);
+    expect(res.status).toBe(401);
+  });
+
+  test("non-owner request for an UNKNOWN file_id → 404 with same shape as owner-denied (no enumeration signal)", async () => {
+    const res = await downloadAs(userAToken, "0123456789abcdef0123456789abcdef");
+    expect(res.status).toBe(404);
+    const body: any = await res.json();
+    expect(body.error).toBe("not_found");
+  });
+});
+
+// #500 CR2 ① — HEAD verb explicit authz coverage. Pre-CR2, HEAD fell
+// through to a fallback 200 page; body was byte-identical to unknown
+// file_id so no oracle formed by accident, but it was coincidence, not
+// a gate. This suite asserts HEAD routes through authorizeFileDownload
+// per RFC 9110 §9.3.2: same status/headers as GET, body omitted.
+async function headAs(token: string | null, fileId: string): Promise<Response> {
+  const headers: Record<string, string> = {};
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return fetch(`${BASE}/api/files/${fileId}`, { method: "HEAD", headers });
+}
+
+describe.skipIf(!isProdMode)("#500 CR2 — HEAD /api/files/:file_id authorization (parity with GET)", () => {
+  let userBFileId = "";
+
+  beforeAll(async () => {
+    userBFileId = await uploadAs(userBToken, new TextEncoder().encode("head-scenario-payload"), "b-head.txt");
+  });
+
+  test("owner (userB) HEAD own file → 200 + content-length header (body omitted per HEAD)", async () => {
+    const res = await headAs(userBToken, userBFileId);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-length")).toBe(String("head-scenario-payload".length));
+    expect(res.headers.get("content-disposition")).toContain("attachment");
+    expect(res.headers.get("x-content-type-options")).toBe("nosniff");
+  });
+
+  test("🔴 cross-owner HEAD (userA HEAD userB's file) → 404 via helper (was fallback 200 pre-CR2)", async () => {
+    const res = await headAs(userAToken, userBFileId);
+    expect(res.status).toBe(404);
+    // 404 must originate from authorizeFileDownload, not the fallback
+    // page. Body is application/json ({"ok":false,"error":"not_found"})
+    // — check Content-Type so a future fallback rewrite (e.g. adding
+    // "requested resource type: X") does not silently form an oracle
+    // while HEAD still returns 200 from that page.
+    expect(res.headers.get("content-type")?.toLowerCase()).toContain("application/json");
+  });
+
+  test("HEAD unknown file_id → 404 with same shape as cross-owner (no enumeration signal)", async () => {
+    const res = await headAs(userAToken, "0123456789abcdef0123456789abcdef");
+    expect(res.status).toBe(404);
+    expect(res.headers.get("content-type")?.toLowerCase()).toContain("application/json");
+  });
+
+  test("HEAD anonymous → 401 (auth still required, symmetric with GET)", async () => {
+    const res = await headAs(null, userBFileId);
+    expect(res.status).toBe(401);
+  });
+
+  test("admin HEAD any file → 200 (operational access preserved on HEAD)", async () => {
+    const res = await headAs(adminToken, userBFileId);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-length")).toBe(String("head-scenario-payload".length));
+  });
+});
+
+// #500 CR2 ④ — Upload owner persistence. Prove that new authenticated
+// uploads always write a truthy owner_id to the on-disk index entry.
+// If the upload handler ever regresses to writing owner_id=null in
+// requireAuth-guarded paths, D1 turns red — the invariant that
+// "production uploads never produce null-owner blobs" is documented
+// in the authorizeFileDownload comment and this test enforces it.
+describe.skipIf(!isProdMode)("#500 CR2 — upload persists truthy owner_id (D1)", () => {
+  test("D1: userA authenticated upload → index entry owner_id === userA.userId (never null)", async () => {
+    const fileId = await uploadAs(userAToken, new TextEncoder().encode("owner-persistence-check"), "d1.bin");
+    const { readFileSync } = await import("fs");
+    const entryPath = join(UPLOADS_DIR, ".index", `${fileId}.json`);
+    expect(existsSync(entryPath)).toBe(true);
+    const entry = JSON.parse(readFileSync(entryPath, "utf-8"));
+    expect(entry.owner_id).not.toBeNull();
+    expect(entry.owner_id).toBe(userAUserId);
+    expect(entry.owner).toBe(nameA); // owner username stays consistent with the token that uploaded
+  });
+
+  test("D1b: userB authenticated upload via utok_ → owner_id === userB.userId", async () => {
+    const fileId = await uploadAs(userBToken, new TextEncoder().encode("owner-persistence-check-b"), "d1b.bin");
+    const { readFileSync } = await import("fs");
+    const entryPath = join(UPLOADS_DIR, ".index", `${fileId}.json`);
+    expect(existsSync(entryPath)).toBe(true);
+    const entry = JSON.parse(readFileSync(entryPath, "utf-8"));
+    expect(entry.owner_id).not.toBeNull();
+    expect(entry.owner_id).toBe(userBUserId);
+  });
+});
+
+describe.skipIf(!isProdMode)("#495 — null-owner policy in production (DEV_OPEN=off, non-admin/non-legacy)", () => {
+  let nullOwnerFileId = "";
+
+  beforeAll(async () => {
+    // Simulate a legacy null-owner index entry by uploading normally
+    // then rewriting the on-disk index to owner_id=null. This precisely
+    // reproduces the shape a DEV_OPEN or legacy master upload would
+    // create, without needing to spin up a second server in a
+    // different mode.
+    nullOwnerFileId = await uploadAs(userAToken, new TextEncoder().encode("legacy-blob"), "legacy.txt");
+    const { readFileSync: rfs, writeFileSync: wfs } = await import("fs");
+    const entryFile = join(UPLOADS_DIR, ".index", `${nullOwnerFileId}.json`);
+    if (!existsSync(entryFile)) throw new Error(`index entry not found: ${entryFile}`);
+    const entry = JSON.parse(rfs(entryFile, "utf-8"));
+    entry.owner = null;
+    entry.owner_id = null;
+    wfs(entryFile, JSON.stringify(entry, null, 2));
+  });
+
+  test.skipIf(!masterTokenActive)("null-owner + legacy master → 200 (RFC-001 read-only backward-compat)", async () => {
+    const res = await downloadAs(MASTER_TOKEN, nullOwnerFileId);
+    expect(res.status).toBe(200);
+  });
+
+  test("null-owner + admin utok_ → 200 (operational access preserved)", async () => {
+    const res = await downloadAs(adminToken, nullOwnerFileId);
+    expect(res.status).toBe(200);
+  });
+
+  test("🔴 Test A (production default) — null-owner + normal user + DEV_OPEN off → 404 fail-closed", async () => {
+    // Runtime invariant: this test file explicitly deletes COMMHUB_DEV_OPEN
+    // at module setup, so the DEV_OPEN branch in authorizeFileDownload
+    // MUST NOT execute here. If someone weakens the guard so that
+    // null-owner is granted even without DEV_OPEN, this assertion turns
+    // red. That IS the mutation self-check for the production carve-out.
+    expect(process.env.COMMHUB_DEV_OPEN).toBeUndefined();
+    const res = await downloadAs(userAToken, nullOwnerFileId);
+    expect(res.status).toBe(404);
+    const body: any = await res.json();
+    expect(body.error).toBe("not_found");
+  });
+});