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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.23",
+  "version": "0.9.0-preview.25",
   "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/file-download-date-bucket.test.ts

@@ -0,0 +1,454 @@
+// #509 — file download must use the date_bucket stored in the index
+// entry, NOT today's date computed from the runtime clock.
+//
+// Bug: server.ts:1793 called `buildStoragePath(entry.file_id, entry.ext)`
+// without passing a bucket. buildStoragePath internally calls
+// getDateBucket(opts.now) which defaults to `new Date()` → today. Any
+// file uploaded on a previous day would look under today's directory
+// and return 404 blob_missing, even though authorization passed and
+// the blob was still on disk in yesterday's directory.
+//
+// The 6 layers of pre-release verification (byte-for-byte review, two
+// independent audits, dev-confirm, two validator container matrices,
+// pre-release smoke) all uploaded + downloaded within the same UTC day,
+// so the paths coincidentally matched. See project memory
+// `feedback_time_based_storage_tests_must_inject_time`.
+//
+// This suite constructs fixture entries with hard-coded past date
+// buckets and matching on-disk blobs; the runtime clock is never
+// advanced. Mutation self-check: reverting the download path to use
+// buildStoragePath (which computes today) must turn Door 1 tests red.
+//
+// Cross-lane note: This is orthogonal to #495/#500/#505 (authz).
+// Reuses the utok_ + admin fixture pattern from file-download-authz
+// but constructs entries by writing the .index JSON + blob directly
+// so we can pin the date_bucket without waiting for real time.
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+const SERVER_DB = mkdtempSync(join(tmpdir(), "anet-509-db-")) + "/commhub.db";
+const UPLOADS_DIR = mkdtempSync(join(tmpdir(), "anet-509-fs-"));
+
+// Set env BEFORE importing anything that pulls in db-adapter.ts or
+// server.ts (which capture 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";
+delete process.env.COMMHUB_DEV_OPEN;
+
+const { register } = await import("./auth.js");
+const { db } = await import("./db.js");
+
+// Register an admin FIRST to consume the "first-user-auto-admin" slot,
+// then register userA as a regular user. Prior CR rounds landed the
+// fixture-drift guard as a canonical pattern (see project memory
+// `feedback_first_registered_user_is_admin_fake_green`).
+const seedName = `seed509_${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+const rSeed = register(seedName, "BootstrapPw123Aa!", undefined, "seed509");
+if (!rSeed.ok) throw new Error(`seed509 register failed: ${rSeed.error}`);
+// Also promote via SQL in case the auto-admin heuristic changes.
+db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [rSeed.user!.user_id]);
+
+const nameA = `user509a_${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+const rA = register(nameA, "BootstrapPw123Aa!", undefined, "user509A");
+if (!rA.ok) throw new Error(`user509A register failed: ${rA.error}`);
+const userAToken = rA.token!;
+const userAUserId = rA.user!.user_id;
+
+// #500 CR2 fixture-drift guard — assert userA is NOT admin so tests
+// exercise the regular utok_ path, not the admin bypass.
+{
+  const row = db.get<{ role: string }>("SELECT role FROM users WHERE user_id = ?1", userAUserId);
+  if (!row) throw new Error("userA missing after register");
+  if (row.role === "admin") {
+    throw new Error(
+      `[#509 fixture-drift guard] userA was auto-promoted to admin ` +
+      `(role=${row.role}). Refusing to run: download tests 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));
+
+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 isProdMode = (await _uploadProbe()) !== 200;
+
+/**
+ * 🔴 Precondition, deliberately OUTSIDE every skipIf.
+ *
+ * The whole #509 suite below hangs off `describe.skipIf(!isProdMode)`, and
+ * `isProdMode` is decided by a *live probe* rather than a constant. If the
+ * probe comes back 200 (DEV_OPEN active in this environment), every Door
+ * test silently disappears and the file still reports green — a validator
+ * running it in a differently-configured container would report PASS while
+ * having exercised none of the #509 read path.
+ *
+ * Unlike the master-token / dev-open conditionals elsewhere in this repo,
+ * #509 has no dev-open counterpart suite: skipping here means the coverage
+ * is simply absent, not relocated. So an unrunnable suite must fail loudly
+ * and say why, instead of vanishing quietly.
+ */
+test("precondition: #509 suite is actually runnable (not silently skipped)", () => {
+  expect(isProdMode).toBe(true);
+});
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(UPLOADS_DIR, { recursive: true, force: true }); } catch {}
+  try { rmSync(SERVER_DB, { recursive: true, force: true }); } catch {}
+});
+
+/**
+ * Manually construct an index entry + matching blob at a caller-chosen
+ * date bucket. This lets Door 1 tests pin "yesterday" without waiting
+ * for real time — the whole point of #509's fix is that read path must
+ * respect index-recorded bucket, so we test by placing a blob in a
+ * bucket that is NOT today.
+ */
+function plantFileAtBucket(opts: {
+  ownerToken: string;
+  ownerUserId: string;
+  dateBucket: string;         // "YYYY-MM-DD" — put blob HERE
+  content: Uint8Array;
+  ext?: string;               // default ".txt"
+  name?: string;              // metadata only
+}): string {
+  const ext = opts.ext ?? ".txt";
+  const fileId = require("crypto").randomUUID().replace(/-/g, "");
+  const bucketDir = join(UPLOADS_DIR, opts.dateBucket);
+  mkdirSync(bucketDir, { recursive: true });
+  writeFileSync(join(bucketDir, fileId + ext), opts.content);
+
+  const indexDir = join(UPLOADS_DIR, ".index");
+  mkdirSync(indexDir, { recursive: true });
+  const entry = {
+    file_id: fileId,
+    date_bucket: opts.dateBucket,
+    ext,
+    name: opts.name ?? "planted.txt",
+    mime: "application/octet-stream",
+    size: opts.content.length,
+    owner: opts.ownerUserId,
+    owner_id: opts.ownerUserId,
+    uploaded_at: new Date().toISOString(),
+  };
+  writeFileSync(join(indexDir, fileId + ".json"), JSON.stringify(entry, null, 2));
+  return fileId;
+}
+
+async function downloadAs(token: string, fileId: string, extraHeaders: Record<string, string> = {}): Promise<Response> {
+  return fetch(`${BASE}/api/files/${fileId}`, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${token}`, ...extraHeaders },
+  });
+}
+
+async function headAs(token: string, fileId: string, extraHeaders: Record<string, string> = {}): Promise<Response> {
+  return fetch(`${BASE}/api/files/${fileId}`, {
+    method: "HEAD",
+    headers: { Authorization: `Bearer ${token}`, ...extraHeaders },
+  });
+}
+
+// Yesterday, three-days-ago (relative to test-run time). Fully static
+// dates would rot; computing offsets keeps the test durable while
+// still isolating the "yesterday" case from today.
+const _pad = (n: number) => String(n).padStart(2, "0");
+function bucketNDaysAgo(n: number): string {
+  const d = new Date();
+  d.setUTCDate(d.getUTCDate() - n);
+  return `${d.getUTCFullYear()}-${_pad(d.getUTCMonth() + 1)}-${_pad(d.getUTCDate())}`;
+}
+const BUCKET_YESTERDAY = bucketNDaysAgo(1);
+const BUCKET_3_DAYS_AGO = bucketNDaysAgo(3);
+const BUCKET_TODAY = bucketNDaysAgo(0);
+
+describe.skipIf(!isProdMode)("#509 — download uses index date_bucket, not today's date", () => {
+  test("Door 1: yesterday's file downloads today → 200 (was 404 blob_missing pre-fix)", async () => {
+    const content = new TextEncoder().encode("blob-from-yesterday");
+    const fileId = plantFileAtBucket({
+      ownerToken: userAToken,
+      ownerUserId: userAUserId,
+      dateBucket: BUCKET_YESTERDAY,
+      content,
+    });
+
+    // Precondition: blob is REALLY in yesterday's bucket, not today's.
+    // If both existed the test would be indistinguishable from a
+    // buildStoragePath-uses-today bug regression.
+    expect(existsSync(join(UPLOADS_DIR, BUCKET_YESTERDAY, fileId + ".txt"))).toBe(true);
+    expect(existsSync(join(UPLOADS_DIR, BUCKET_TODAY, fileId + ".txt"))).toBe(false);
+
+    const res = await downloadAs(userAToken, fileId);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("blob-from-yesterday");
+  });
+
+  test("Door 1 (further past): 3-days-ago file downloads today → 200", async () => {
+    const content = new TextEncoder().encode("blob-from-3-days-ago");
+    const fileId = plantFileAtBucket({
+      ownerToken: userAToken,
+      ownerUserId: userAUserId,
+      dateBucket: BUCKET_3_DAYS_AGO,
+      content,
+    });
+
+    const res = await downloadAs(userAToken, fileId);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("blob-from-3-days-ago");
+  });
+
+  test("Door 2 regression: today's file downloads today → 200 (unchanged behavior)", async () => {
+    const content = new TextEncoder().encode("blob-from-today");
+    const fileId = plantFileAtBucket({
+      ownerToken: userAToken,
+      ownerUserId: userAUserId,
+      dateBucket: BUCKET_TODAY,
+      content,
+    });
+
+    const res = await downloadAs(userAToken, fileId);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("blob-from-today");
+  });
+
+  test("Door 3 GET: yesterday's file via GET → 200 with correct body", async () => {
+    const content = new TextEncoder().encode("GET-cross-day");
+    const fileId = plantFileAtBucket({
+      ownerToken: userAToken,
+      ownerUserId: userAUserId,
+      dateBucket: BUCKET_YESTERDAY,
+      content,
+    });
+    const res = await downloadAs(userAToken, fileId);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("GET-cross-day");
+  });
+
+  test("Door 3 HEAD: yesterday's file via HEAD → 200 with Content-Length, no body", async () => {
+    const content = new TextEncoder().encode("HEAD-cross-day-payload");
+    const fileId = plantFileAtBucket({
+      ownerToken: userAToken,
+      ownerUserId: userAUserId,
+      dateBucket: BUCKET_YESTERDAY,
+      content,
+    });
+    const res = await headAs(userAToken, fileId);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Length")).toBe(String(content.length));
+    // HEAD must not return a body — Bun exposes the stream but reads to
+    // 0 bytes. Some HTTP stacks return no ReadableStream at all; either
+    // is acceptable per RFC 9110 §9.3.2 — check size, not presence.
+    const buf = await res.arrayBuffer();
+    expect(buf.byteLength).toBe(0);
+  });
+
+  test("Door 3 Range: yesterday's file with Range header → data served from correct bucket", async () => {
+    const content = new TextEncoder().encode("0123456789ABCDEFGHIJ");
+    const fileId = plantFileAtBucket({
+      ownerToken: userAToken,
+      ownerUserId: userAUserId,
+      dateBucket: BUCKET_YESTERDAY,
+      content,
+    });
+    // Whether Range is honoured is orthogonal to #509 and NOT decided by
+    // this codebase: the handler is `new Response(Bun.file(path), {status:200})`
+    // with no Range handling anywhere, so 200-vs-206 is decided purely by the
+    // Bun runtime. Measured 2026-07-30 with byte-identical code:
+    //   bun 1.2.22 → 200 + full body     bun 1.3.14 → 206 + correct slice
+    // So both statuses are legitimate and this test must pass on both.
+    //
+    // 🔴 But "accept either status" must NOT mean "assert nothing". The first
+    // version guarded the body check with `if (status === 200)`, so on the
+    // runtime production actually runs (206) the body assertion never
+    // executed — the test claimed to prove the blob path resolved correctly
+    // while only ever checking a status code. Each branch asserts its own
+    // bytes, and an unrecognised status fails loudly rather than silently
+    // skipping.
+    const res = await fetch(`${BASE}/api/files/${fileId}`, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${userAToken}`, Range: "bytes=0-4" },
+    });
+    expect([200, 206]).toContain(res.status);
+    if (res.status === 206) {
+      // Runtime honoured Range: body must be exactly the requested slice,
+      // and the slice must come from THIS file (total length 20 proves the
+      // resolved blob is the planted one, not some other bucket's file).
+      expect(await res.text()).toBe("01234");
+      expect(res.headers.get("content-range")).toBe(`bytes 0-4/${content.byteLength}`);
+    } else {
+      // Runtime ignored Range: body must be the complete planted blob.
+      expect(await res.text()).toBe("0123456789ABCDEFGHIJ");
+    }
+  });
+
+  test("Door 3 conditional: yesterday's file with If-None-Match → served or 304, never 404", async () => {
+    const content = new TextEncoder().encode("cond-cross-day");
+    const fileId = plantFileAtBucket({
+      ownerToken: userAToken,
+      ownerUserId: userAUserId,
+      dateBucket: BUCKET_YESTERDAY,
+      content,
+    });
+    const res = await downloadAs(userAToken, fileId, { "If-None-Match": '"never-matches-509"' });
+    expect([200, 304]).toContain(res.status);
+    expect(res.status).not.toBe(404);
+  });
+
+  test("Door 4: existing bucket-recorded blob is immediately readable without migration", async () => {
+    // Simulate the scenario Vincent hit: yesterday's PPT still on disk
+    // in yesterday's bucket, index intact — no re-upload, no data move,
+    // fix alone should make it readable.
+    const yesterdayBlob = new TextEncoder().encode("Vincents-actual-PPT-payload");
+    const fileId = plantFileAtBucket({
+      ownerToken: userAToken,
+      ownerUserId: userAUserId,
+      dateBucket: BUCKET_YESTERDAY,
+      content: yesterdayBlob,
+      ext: ".pptx",
+      name: "presentation.pptx",
+    });
+
+    // The blob file was NEVER moved after "plantFileAtBucket" wrote it
+    // to yesterday's bucket. Post-fix, the server must find it there.
+    const res = await downloadAs(userAToken, fileId);
+    expect(res.status).toBe(200);
+    expect(new Uint8Array(await res.arrayBuffer())).toEqual(yesterdayBlob);
+  });
+
+  test("Item 3 (副指挥 b1082017) — server TZ / UTC-boundary: entry bucket is authoritative regardless of runtime clock", async () => {
+    // 副指挥 7 硬门 ③: "覆盖服务时区与 UTC 日期边界".
+    //
+    // The read path is now structurally no-clock: pathForExistingBlob
+    // takes only the stored dateBucket, calls no getDateBucket / new
+    // Date() / Date.now(). This test pins that invariant with an
+    // explicit UTC-boundary scenario rather than leaving it as
+    // structural reasoning.
+    //
+    // Scenario: an entry recorded on 2026-07-29 (a hard-coded UTC
+    // date, unrelated to today's runtime clock). Even if the server
+    // process's runtime clock is anywhere in 2026-07-30..2026-08-01
+    // (i.e. one, two, or more midnights past the recorded bucket),
+    // the download must still resolve to the stored bucket path.
+    //
+    // The fixture uses a hard-coded date string (not offset from
+    // today) so the assertion is anchored on the invariant, not on
+    // "wall-clock happens to differ by exactly N days". If someone
+    // future-dates the runtime environment, this test still passes
+    // because the read path never consults the clock.
+    const hardcodedPastBucket = "2026-07-29";
+    const content = new TextEncoder().encode("tz-boundary-payload");
+    const fileId = plantFileAtBucket({
+      ownerToken: userAToken,
+      ownerUserId: userAUserId,
+      dateBucket: hardcodedPastBucket,
+      content,
+    });
+
+    // Precondition: blob is at the hard-coded bucket, NOT at any
+    // date derivable from `new Date()` at test time. If both paths
+    // happened to exist the test would not distinguish a
+    // stored-bucket read from a runtime-computed one.
+    expect(existsSync(join(UPLOADS_DIR, hardcodedPastBucket, fileId + ".txt"))).toBe(true);
+    // If today happens to be exactly 2026-07-29 (rare but possible
+    // when re-running the fixture), the today-bucket path exists too;
+    // the invariant we care about is the read succeeds because of the
+    // stored bucket, not because of a runtime coincidence.
+
+    const res = await downloadAs(userAToken, fileId);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("tz-boundary-payload");
+
+    // Additional invariant grep: the fixture's stored bucket is the
+    // ONLY bucket the read path should have visited. We can't observe
+    // the exact filesystem access here without instrumenting, but the
+    // structural property is enforced by pathForExistingBlob's API
+    // (no `now` parameter, no Date import). Combined with Door 1
+    // (yesterday-not-today) and this hard-coded case, the intent is
+    // pinned in tests, not just in the function name.
+  });
+
+  // Helper: plant an index entry with a poisoned/invalid date_bucket.
+  // Blob file is optional — the point is the bucket string itself.
+  function plantPoisonedBucketEntry(dateBucket: unknown): string {
+    const fileId = require("crypto").randomUUID().replace(/-/g, "");
+    const indexDir = join(UPLOADS_DIR, ".index");
+    mkdirSync(indexDir, { recursive: true });
+    const entry = {
+      file_id: fileId,
+      date_bucket: dateBucket,
+      ext: ".txt",
+      name: "poison.txt",
+      mime: "application/octet-stream",
+      size: 4,
+      owner: userAUserId,
+      owner_id: userAUserId,
+      uploaded_at: new Date().toISOString(),
+    };
+    writeFileSync(join(indexDir, fileId + ".json"), JSON.stringify(entry));
+    return fileId;
+  }
+
+  // 副指挥 66983a19 hard-door: 稳定 404 非 500 for
+  //   • path-escape poisoned buckets ("../etc", "..\\etc", etc.)
+  //   • non-calendar buckets ("2026-02-30", "2026-13-01", ...)
+  //   • shape-only-valid but semantically impossible dates
+  // 500 says "server failed to handle input"; 404 says "input refused
+  // at the boundary". The latter is a stronger, more auditable posture.
+  const invalidBuckets: Array<[string, unknown]> = [
+    ["path-escape ../etc", "../etc"],
+    ["path-escape .. only", ".."],
+    ["backslash traversal", "..\\etc"],
+    ["contains null byte", "date"],
+    ["contains slash", "2026/07/29"],
+    ["empty string", ""],
+    ["all-nines shape but not calendar", "9999-99-99"],
+    ["month 13 (impossible)", "2026-13-01"],
+    ["month 00 (impossible)", "2026-00-15"],
+    ["day 30 in February 2026 (non-leap-year rejected)", "2026-02-30"],
+    ["day 32 (impossible)", "2026-07-32"],
+    ["Feb 29 on non-leap year", "2025-02-29"],
+  ];
+
+  for (const [label, badBucket] of invalidBuckets) {
+    test(`Refinement (副指挥 66983a19) — invalid bucket "${label}" → 404 (not 500)`, async () => {
+      const fileId = plantPoisonedBucketEntry(badBucket);
+      const res = await downloadAs(userAToken, fileId);
+      // 稳定 404: pre-check via isValidCalendarBucket rejects at the
+      // boundary. 500 would signal a caught throw from deeper code —
+      // that is exactly the shape we're refusing to accept per副指挥
+      // b1082017 (可靠性差很远).
+      expect(res.status).toBe(404);
+      const body: any = await res.json();
+      expect(body.error).toBe("not_found");
+    });
+  }
+
+  test("Refinement (副指挥 66983a19) — valid Feb 29 on ACTUAL leap year 2024 is accepted (not over-rejected)", async () => {
+    // Sanity: the calendar validator must not accidentally reject
+    // legitimate leap-day buckets from a real leap year. Constructs
+    // an entry at 2024-02-29 (valid), blob at that path, downloads it.
+    const content = new TextEncoder().encode("leap-day-blob");
+    const fileId = plantFileAtBucket({
+      ownerToken: userAToken,
+      ownerUserId: userAUserId,
+      dateBucket: "2024-02-29",
+      content,
+    });
+    const res = await downloadAs(userAToken, fileId);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("leap-day-blob");
+  });
+});

package/src/health-redaction.test.ts

@@ -15,7 +15,7 @@ import { describe, expect, test, beforeAll, afterAll } from "bun:test";
 import { mkdtempSync, rmSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
-import { register } from "./auth.js";
+import { register, addNetworkMember, removeNetworkMember } from "./auth.js";
 import { db } from "./db.js";
 
 const SERVER_DB = mkdtempSync(join(tmpdir(), "anet-health-red-db-")) + "/commhub.db";
@@ -115,6 +115,76 @@ describe("#473 anonymous /health — watchdog contract intact, no topology leak"
   });
 });
 
+describe("f28a6c1b /health sse_sessions — auth-gated restoration for dashboard 'online' widget", () => {
+  // The dashboard's server-side Next.js proxy (agent-network-dashboard
+  // `app/api/hub/health/route.ts` → `hubFetch('/health')`) forwards the
+  // logged-in user's V3 utok_ as `Authorization: Bearer …`. Anonymous
+  // callers (public watchdog, internet strangers) still get NO
+  // sse_sessions — that leak stays closed. Authenticated callers get
+  // the sessions map scoped to their networks (ops sees all).
+
+  test("regular member with valid utok_: sse_sessions present, filtered to member's networks", async () => {
+    const res = await fetch(`${BASE}/health`, {
+      headers: { Authorization: `Bearer ${userToken}` },
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    // Field must be present when authenticated — otherwise dashboard
+    // "online" widget shows 0.
+    expect("sse_sessions" in body).toBe(true);
+    // Must contain the member's own SSE connection key.
+    const ownKey = `${userNetworkId}:${userName}`;
+    expect(body.sse_sessions[ownKey]).toBeGreaterThanOrEqual(1);
+    // Watchdog aggregate contract unchanged.
+    expect(body.sse_connections).toBeGreaterThanOrEqual(1);
+  });
+
+  test("admin with valid utok_: sse_sessions present, full unfiltered map (ops parity with /api/stats/sse)", async () => {
+    const res = await fetch(`${BASE}/health`, {
+      headers: { Authorization: `Bearer ${adminToken}` },
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect("sse_sessions" in body).toBe(true);
+    // Admin sees the member's key even though they live in a different
+    // network (admin scope spans everything, same as /api/stats/sse).
+    const memberKey = `${userNetworkId}:${userName}`;
+    expect(body.sse_sessions[memberKey]).toBeGreaterThanOrEqual(1);
+    // Sanity: admin's view must match the auth-gated ops endpoint.
+    const opsRes = await fetch(`${BASE}/api/stats/sse`, {
+      headers: { Authorization: `Bearer ${adminToken}` },
+    });
+    const ops = await opsRes.json() as any;
+    expect(body.sse_sessions).toEqual(ops.sessions);
+  });
+
+  test("anonymous still gets NO sse_sessions (leak stays closed, mutation-red witness)", async () => {
+    // This is the mutation-red assertion for the auth gate: if the
+    // handler stops distinguishing anonymous from authenticated and
+    // starts including sse_sessions unconditionally, this test turns
+    // RED. Distinct from the older `does NOT expose SSE key detail`
+    // test — that one guards against any regression restoring the
+    // OLD unconditional leak; this one guards against a well-meaning
+    // "just always send it if authenticated is optional" bug.
+    const res = await fetch(`${BASE}/health`);
+    const body = await res.json() as any;
+    expect("sse_sessions" in body).toBe(false);
+  });
+
+  test("invalid/garbage token: treated as anonymous — no sse_sessions", async () => {
+    const res = await fetch(`${BASE}/health`, {
+      headers: { Authorization: "Bearer utok_completely_fake_nonexistent" },
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    // resolveRequestAuth returns null for unresolvable tokens, so the
+    // handler must NOT fall through to "authenticated" branch. Otherwise
+    // a bad token would degrade to "anonymous with sse_sessions" — that
+    // would be the leak in a different disguise.
+    expect("sse_sessions" in body).toBe(false);
+  });
+});
+
 describe("#473 GET /api/stats/sse — detail survives, behind ops auth", () => {
   test("anonymous → 401", async () => {
     const res = await fetch(`${BASE}/api/stats/sse`);
@@ -174,3 +244,382 @@ describe("#473 GET /api/stats/sse — detail survives, behind ops auth", () => {
     expect(r.healthHasSseSessions).toBe(false); // /health still redacted with a token set
   }, 20_000);
 });
+
+// ─────────────────────────────────────────────────────────────────────
+// CR3 (4703b0e7) — M1-M7 matrix tests
+// ─────────────────────────────────────────────────────────────────────
+//
+// Independent audit on aef48a3d showed the existing f28a6c1b tests
+// pinned only the "anonymous vs authenticated" gate. The reviewer
+// mutated `scopedSessions = sse.sessions` (unconditional) and got
+// 11/11 green — meaning the *tenant-scope* invariant (a member sees
+// only their own networks, cross-network is invisible) was not
+// witnessed by any assertion, and a future refactor that broke the
+// filter would ship silently.
+//
+// This block adds explicit tests for every shape the fork's auth
+// decision distinguishes:
+//   M1: utok_ member sees own network's sessions
+//   M2: utok_ member does NOT see other network's sessions
+//   M3: ntok_ (network-scoped token) is forced to the token's bound
+//       network — the user's other networks are invisible even
+//       though the underlying user is a member
+//   M4: same user, utok_ vs ntok_ — utok_ sees union, ntok_ sees only
+//       the token's bound network (mutation-red for the ntok_
+//       "healthAuth.networkId ? [...] : db.all(...)" branch)
+//   M5: membership revocation invalidates visibility immediately —
+//       no cache; the next /health request reflects new membership
+//   M6: observer keys (shape `\0netobs:<networkId>`; the getSSEStats
+//       serializer renders leading NUL as printable `\\0`) are
+//       classified through the shared PRINTABLE_OBSERVER_KEY_PREFIX
+//       constant, not a re-typed literal. Mutation-red for the
+//       constant drift (server.ts had `"netobs:"` without `\\0`
+//       before this CR, so all observer keys silently fell through).
+//   M7: two networks with the same alias — invisibility survives
+//       key collision. Explicit assertion; M1/M2 hide-cover this
+//       implicitly but M7 makes the property visible in review.
+describe("f28a6c1b CR3 — network-scoped filter matrix (M1-M7)", () => {
+  let mUserAToken = "";
+  let mUserANet = "";
+  let mUserAName = "";
+  let mUserBToken = "";
+  let mUserBNet = "";
+  let mUserBName = "";
+  let mAliceToken = "";       // utok_ (user-scoped)
+  let mAliceNtok = "";        // ntok_ bound to mAliceNet
+  let mAliceNet = "";
+  let mAliceName = "";
+  let mCarolToken = "";
+  let mCarolNet = "";
+  let mCarolName = "";
+  let mUserAId = "";
+  let mAliceId = "";
+  let mCarolId = "";
+  let mSameAliasName = "";    // used by M7 — two sessions, one per network
+
+  const openReaders: ReadableStreamDefaultReader<Uint8Array>[] = [];
+
+  const startSse = async (base: string, name: string, netId: string, token: string) => {
+    const res = await fetch(`${base}/events/${encodeURIComponent(name)}?network_id=${netId}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (res.status !== 200) throw new Error(`SSE subscribe failed (${res.status}) for ${name}@${netId}`);
+    const reader = res.body!.getReader();
+    await reader.read();
+    openReaders.push(reader);
+    return reader;
+  };
+
+  const startObserverSse = async (base: string, netId: string, token: string) => {
+    // The observer endpoint is /events/network/:networkId — carries no
+    // per-agent alias; server registers with the special observer key
+    // shape `\0netobs:<networkId>` (see push.ts observerKey()).
+    const res = await fetch(`${base}/events/network/${encodeURIComponent(netId)}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (res.status !== 200) throw new Error(`observer SSE subscribe failed (${res.status}) for ${netId}`);
+    const reader = res.body!.getReader();
+    await reader.read();
+    openReaders.push(reader);
+    return reader;
+  };
+
+  beforeAll(async () => {
+    const suffix = `${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+    const pw = "BootstrapPw123Aa!";
+
+    // userA — own network, plain member
+    mUserAName = `cr3_userA_${suffix}`;
+    const rA = register(mUserAName, pw, undefined, "seed");
+    if (!rA.ok || !rA.token || !rA.network_id) throw new Error("userA register failed");
+    mUserAToken = rA.token;
+    mUserANet = rA.network_id;
+    db.run("UPDATE users SET role = 'user' WHERE username = ?1", [mUserAName]);
+    mUserAId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", [mUserAName])!.user_id;
+
+    // userB — different own network, plain member
+    mUserBName = `cr3_userB_${suffix}`;
+    const rB = register(mUserBName, pw, undefined, "seed");
+    if (!rB.ok || !rB.token || !rB.network_id) throw new Error("userB register failed");
+    mUserBToken = rB.token;
+    mUserBNet = rB.network_id;
+    db.run("UPDATE users SET role = 'user' WHERE username = ?1", [mUserBName]);
+
+    // alice — own network + will also be added to userA's N_A, so
+    // membership set = { mAliceNet (owner), mUserANet (member) }.
+    // Her ntok_ (from register) is bound to mAliceNet only — the M3/M4
+    // scope-enforcement test target.
+    mAliceName = `cr3_alice_${suffix}`;
+    const rAl = register(mAliceName, pw, undefined, "seed");
+    if (!rAl.ok || !rAl.token || !rAl.network_token || !rAl.network_id) throw new Error("alice register failed");
+    mAliceToken = rAl.token;
+    mAliceNtok = rAl.network_token;
+    mAliceNet = rAl.network_id;
+    db.run("UPDATE users SET role = 'user' WHERE username = ?1", [mAliceName]);
+    mAliceId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", [mAliceName])!.user_id;
+    const addAlice = addNetworkMember(mUserANet, mAliceId, "member", mUserAId);
+    if (!addAlice.ok) throw new Error("addNetworkMember(alice→N_A) failed: " + addAlice.error);
+
+    // carol — own network + will also be added to N_A, then revoked
+    // in M5.
+    mCarolName = `cr3_carol_${suffix}`;
+    const rC = register(mCarolName, pw, undefined, "seed");
+    if (!rC.ok || !rC.token || !rC.network_id) throw new Error("carol register failed");
+    mCarolToken = rC.token;
+    mCarolNet = rC.network_id;
+    db.run("UPDATE users SET role = 'user' WHERE username = ?1", [mCarolName]);
+    mCarolId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", [mCarolName])!.user_id;
+    const addCarol = addNetworkMember(mUserANet, mCarolId, "member", mUserAId);
+    if (!addCarol.ok) throw new Error("addNetworkMember(carol→N_A) failed: " + addCarol.error);
+
+    // Live SSE sessions — one per network — so the filter has real
+    // keys to include/exclude.
+    await startSse(BASE, mUserAName, mUserANet, mUserAToken);
+    await startSse(BASE, mUserBName, mUserBNet, mUserBToken);
+    await startSse(BASE, mAliceName, mAliceNet, mAliceToken);
+    await startSse(BASE, mCarolName, mCarolNet, mCarolToken);
+
+    // M6 — observer stream for N_A (produces `\0netobs:<mUserANet>` key)
+    await startObserverSse(BASE, mUserANet, mUserAToken);
+
+    // M7 note: The dashboard-user SSE gate only lets a caller subscribe
+    // as their own username (path 3, gate 4a). Standing up two sessions
+    // named the same alias in two different networks would need two
+    // separate "helper" users per network — significantly larger setup
+    // than the property we're testing. M1/M2 already witness the shape
+    // invariant (`<netId>:<alias>` keying) that would defeat collision:
+    // cross-network same-alias would land at `<N_A>:<alias>` vs
+    // `<N_B>:<alias>`, and M2's `expect(body.sse_sessions[<N_B>:...]).toBeUndefined()`
+    // pins exactly the "wrong-tenant key is invisible" property. M7 is
+    // therefore covered structurally; skipping the physical fixture.
+    mSameAliasName = "";
+  });
+
+  afterAll(() => {
+    for (const r of openReaders) { try { r.cancel(); } catch {} }
+  });
+
+  // ── M1 + M2 — utok_ member sees own network only ────────────────
+  test("M1: utok_ member of N_A sees N_A sessions", async () => {
+    const res = await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${mUserAToken}` } });
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect("sse_sessions" in body).toBe(true);
+    expect(body.sse_sessions[`${mUserANet}:${mUserAName}`]).toBeGreaterThanOrEqual(1);
+  });
+
+  test("M2: utok_ member of N_A does NOT see N_B sessions (cross-network invisibility)", async () => {
+    const res = await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${mUserAToken}` } });
+    const body = await res.json() as any;
+    expect("sse_sessions" in body).toBe(true);
+    // The N_B session (userB's own network) must not surface here —
+    // this is the assertion the reviewer's "delete member filter"
+    // mutation must break (currently was silently green).
+    expect(body.sse_sessions[`${mUserBNet}:${mUserBName}`]).toBeUndefined();
+  });
+
+  test("M2b: utok_ member of N_B sees own but not N_A (reverse of M2)", async () => {
+    const res = await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${mUserBToken}` } });
+    const body = await res.json() as any;
+    expect(body.sse_sessions[`${mUserBNet}:${mUserBName}`]).toBeGreaterThanOrEqual(1);
+    expect(body.sse_sessions[`${mUserANet}:${mUserAName}`]).toBeUndefined();
+  });
+
+  // ── M3 + M4 — ntok_ single-network enforce ──────────────────────
+  test("M3: alice utok_ (user-scoped) sees union — both mAliceNet and mUserANet", async () => {
+    const res = await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${mAliceToken}` } });
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.sse_sessions[`${mAliceNet}:${mAliceName}`]).toBeGreaterThanOrEqual(1);
+    expect(body.sse_sessions[`${mUserANet}:${mUserAName}`]).toBeGreaterThanOrEqual(1);
+  });
+
+  test("M4: alice ntok_ (network-scoped, bound to mAliceNet) sees ONLY mAliceNet — N_A invisible even though she is a member", async () => {
+    // This is the CR3 P1 fix's mutation-red target: if the /health
+    // filter falls through to the `db.all(...)` union for ntok_
+    // callers (i.e. drops the `healthAuth.networkId ? [...] : ...`
+    // branch), this test flips because alice would suddenly see
+    // mUserANet sessions through a token that only granted mAliceNet.
+    const res = await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${mAliceNtok}` } });
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect("sse_sessions" in body).toBe(true);
+    // Own network — must be present.
+    expect(body.sse_sessions[`${mAliceNet}:${mAliceName}`]).toBeGreaterThanOrEqual(1);
+    // The other network she belongs to — ntok_ must NOT show it.
+    expect(body.sse_sessions[`${mUserANet}:${mUserAName}`]).toBeUndefined();
+    // Sanity: an unrelated network she's not in must also be absent.
+    expect(body.sse_sessions[`${mUserBNet}:${mUserBName}`]).toBeUndefined();
+  });
+
+  // ── M5 — membership revocation invalidates visibility ───────────
+  test("M5: removing carol from N_A → next /health hides N_A sessions", async () => {
+    // Pre-revocation: carol utok_ sees own network + N_A (userA lives
+    // in N_A). Filter is per-request, no cache — so a revoke followed
+    // by an immediate /health must reflect the new state.
+    const before = await (await fetch(`${BASE}/health`, {
+      headers: { Authorization: `Bearer ${mCarolToken}` },
+    })).json() as any;
+    expect(before.sse_sessions[`${mCarolNet}:${mCarolName}`]).toBeGreaterThanOrEqual(1);
+    expect(before.sse_sessions[`${mUserANet}:${mUserAName}`]).toBeGreaterThanOrEqual(1);
+
+    const rm = removeNetworkMember(mUserANet, mCarolId);
+    if (!rm.ok) throw new Error("revoke failed: " + rm.error);
+
+    const after = await (await fetch(`${BASE}/health`, {
+      headers: { Authorization: `Bearer ${mCarolToken}` },
+    })).json() as any;
+    expect(after.sse_sessions[`${mCarolNet}:${mCarolName}`]).toBeGreaterThanOrEqual(1);
+    // The revoked N_A must be gone. Mutation-red for any caching of
+    // the memberNets Set across requests.
+    expect(after.sse_sessions[`${mUserANet}:${mUserAName}`]).toBeUndefined();
+  });
+
+  // ── M6 — observer key format via shared constant ────────────────
+  test("M6: observer keys (\\0netobs:<net>) are classified through the shared prefix constant, member sees own network's observer entry", async () => {
+    const res = await fetch(`${BASE}/health`, {
+      headers: { Authorization: `Bearer ${mUserAToken}` },
+    });
+    const body = await res.json() as any;
+    // Observer key surfaces with the printable prefix (`\\0netobs:`)
+    // because push.ts's printableKey renders the NUL byte as `\\0`.
+    // The filter must classify this as belonging to `mUserANet` and
+    // include it in userA's view.
+    const observerKey = `\\0netobs:${mUserANet}`;
+    expect(body.sse_sessions[observerKey]).toBeGreaterThanOrEqual(1);
+  });
+
+  test("M6b: userB (not in N_A) does NOT see N_A's observer key — mutation-red for prefix constant drift", async () => {
+    const res = await fetch(`${BASE}/health`, {
+      headers: { Authorization: `Bearer ${mUserBToken}` },
+    });
+    const body = await res.json() as any;
+    const observerKey = `\\0netobs:${mUserANet}`;
+    // If the prefix constant drifts (e.g. server.ts checks "netobs:"
+    // without `\\0`), the classifier falls through to `key.split(":")[0]`
+    // which for a `\\0netobs:` key returns the literal `\\0netobs` string
+    // — that would never match memberNets, so the observer key gets
+    // over-filtered but silently. That is the pre-CR3 bug shape;
+    // this assertion pins the "not in wrong tenant's view" side.
+    expect(body.sse_sessions[observerKey]).toBeUndefined();
+  });
+
+  // M7 removed — see beforeAll note. Cross-network same-alias
+  // invisibility is covered structurally by M1/M2: keys are
+  // `<netId>:<alias>`, so a `<N_A>:foo` vs `<N_B>:foo` collision
+  // resolves via network prefix, which is what M2's cross-network
+  // absence assertion already pins.
+});
+
+// ── #506 — same alias, two networks: /health sse_sessions must not cross ──
+//
+// #505 restored auth-gated `sse_sessions`. Its member filter parses the
+// `{networkId}:{alias}` key prefix and keeps only the caller's networks.
+// That was verified at merge time by a standalone validator, but a
+// validator does not re-run on future refactors — this pins it.
+//
+// Construction: the dashboard-user SSE gate only lets a caller subscribe
+// to its own username (gate 4a), so two users can never share one key that
+// way. Gate 4b is the usable path: any member may subscribe to an alias
+// that exists as a session IN THEIR network. So we seed a session row with
+// the SAME alias in two different networks and have each network's own
+// member subscribe to it — producing `{N_A}:{alias}` and `{N_B}:{alias}`
+// live at once, which is exactly the collision the filter must separate.
+//
+// Mutation-red (verified by hand, see the PR): replacing the member filter
+// with `scopedSessions = sse.sessions` turns the two "must NOT contain the
+// other network's key" assertions red.
+describe("#506 cross-network isolation of /health sse_sessions (same alias, two networks)", () => {
+  const SHARED_ALIAS = "shared-alias-506";
+  let aToken = "", aNet = "", aName = "";
+  let bToken = "", bNet = "", bName = "";
+  let readerA: ReadableStreamDefaultReader<Uint8Array> | null = null;
+  let readerB: ReadableStreamDefaultReader<Uint8Array> | null = null;
+
+  beforeAll(async () => {
+    const sfx = `${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+    const pw = "BootstrapPw123Aa!";
+
+    // Probe users are registered AFTER the suite's seed user, so neither is
+    // the auto-admin first user. Asserted below rather than assumed: an
+    // admin caller takes the unfiltered branch and would make these tests
+    // pass while proving nothing.
+    const ra = register(`h506_a_${sfx}`, pw, undefined, "seed");
+    const rb = register(`h506_b_${sfx}`, pw, undefined, "seed");
+    if (!ra.ok || !ra.token || !rb.ok || !rb.token) throw new Error("506 register failed");
+    aName = `h506_a_${sfx}`; aToken = ra.token; aNet = ra.network_id ?? "";
+    bName = `h506_b_${sfx}`; bToken = rb.token; bNet = rb.network_id ?? "";
+    if (!aNet || !bNet || aNet === bNet) throw new Error("506 needs two distinct networks");
+    db.run("UPDATE users SET role = 'user' WHERE username IN (?1, ?2)", [aName, bName]);
+
+    // Same alias name, one session row per network → gate 4b lets each
+    // network's own member subscribe to it.
+    for (const [net, tag] of [[aNet, "a"], [bNet, "b"]] as const) {
+      db.run(
+        `INSERT INTO sessions (resume_id, alias, network_id, last_seen_at, status)
+         VALUES (?1, ?2, ?3, datetime('now'), 'idle')`,
+        [`s_506_${tag}_${sfx}`, SHARED_ALIAS, net],
+      );
+    }
+
+    const sub = async (token: string, net: string) => {
+      const res = await fetch(
+        `${BASE}/events/${encodeURIComponent(SHARED_ALIAS)}?network_id=${encodeURIComponent(net)}`,
+        { headers: { Authorization: `Bearer ${token}` } },
+      );
+      if (res.status !== 200) throw new Error(`506 SSE subscribe failed (${net}): ${res.status}`);
+      const rd = res.body!.getReader();
+      await rd.read(); // connected frame → key registered
+      return rd;
+    };
+    readerA = await sub(aToken, aNet);
+    readerB = await sub(bToken, bNet);
+  });
+
+  afterAll(() => {
+    try { readerA?.cancel(); } catch {}
+    try { readerB?.cancel(); } catch {}
+  });
+
+  test("probe users are NOT admin (an admin caller would bypass the filter and prove nothing)", () => {
+    for (const n of [aName, bName]) {
+      const row = db.get<{ role: string }>("SELECT role FROM users WHERE username = ?1", n);
+      expect(row?.role).not.toBe("admin");
+    }
+  });
+
+  test("both same-alias keys are live at once (the collision actually exists)", async () => {
+    // Read through the ops endpoint with the admin token: if this shows only
+    // one of the two keys, the fixture never built the collision and the
+    // isolation assertions below would be vacuous.
+    const res = await fetch(`${BASE}/api/stats/sse`, { headers: { Authorization: `Bearer ${adminToken}` } });
+    expect(res.status).toBe(200);
+    const body = await res.json() as { sessions?: Record<string, number> };
+    const keys = Object.keys(body.sessions ?? {});
+    expect(keys).toContain(`${aNet}:${SHARED_ALIAS}`);
+    expect(keys).toContain(`${bNet}:${SHARED_ALIAS}`);
+  });
+
+  test("member of network A sees only A's copy of the shared alias", async () => {
+    const res = await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${aToken}` } });
+    expect(res.status).toBe(200);
+    const body = await res.json() as { sse_sessions?: Record<string, number> };
+    expect(body.sse_sessions).toBeDefined();
+    const keys = Object.keys(body.sse_sessions!);
+    expect(keys).toContain(`${aNet}:${SHARED_ALIAS}`);
+    expect(keys).not.toContain(`${bNet}:${SHARED_ALIAS}`);
+    // Nothing from the other network at all, by any key shape.
+    expect(keys.some((k) => k.startsWith(`${bNet}:`))).toBe(false);
+  });
+
+  test("member of network B sees only B's copy (reverse direction)", async () => {
+    const res = await fetch(`${BASE}/health`, { headers: { Authorization: `Bearer ${bToken}` } });
+    expect(res.status).toBe(200);
+    const body = await res.json() as { sse_sessions?: Record<string, number> };
+    expect(body.sse_sessions).toBeDefined();
+    const keys = Object.keys(body.sse_sessions!);
+    expect(keys).toContain(`${bNet}:${SHARED_ALIAS}`);
+    expect(keys).not.toContain(`${aNet}:${SHARED_ALIAS}`);
+    expect(keys.some((k) => k.startsWith(`${aNet}:`))).toBe(false);
+  });
+});

package/src/push.ts

@@ -110,6 +110,15 @@ function clientKey(sessionName: string, networkId?: string | null): string {
 // legacy ?network_id= path, and master token is root already.
 const OBSERVER_KEY_PREFIX = "\u0000netobs:";
 
+/** Printable form of `OBSERVER_KEY_PREFIX` — the shape emitted by
+ *  `printableKey()` (below) and therefore the shape callers see via
+ *  `getSSEStats().sessions`. Exported so downstream consumers (e.g.
+ *  `/health` filter in server.ts) key off the same literal instead of
+ *  each side re-writing the escape sequence — CR3 audit 4703b0e7
+ *  found server.ts had `"netobs:"` (no `\\0`) which never matched and
+ *  silently over-filtered observer keys. */
+export const PRINTABLE_OBSERVER_KEY_PREFIX = "\\0netobs:";
+
 function observerKey(networkId: string): string {
   return `${OBSERVER_KEY_PREFIX}${networkId}`;
 }

package/src/server.ts

@@ -3,7 +3,7 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import { z } from "zod/v4";
 import { registerTools } from "./tools.js";
 import { db, logTaskEvent, logAudit } from "./db.js";
-import { createSSEStream, createNetworkObserverStream, pushEvent, pushNetworkObserverEvent, getSSEStats } from "./push.js";
+import { createSSEStream, createNetworkObserverStream, pushEvent, pushNetworkObserverEvent, getSSEStats, PRINTABLE_OBSERVER_KEY_PREFIX } from "./push.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
 import { validateAvatarUrl } from "./avatar-validate.js";
 import { narrowTags, parseStoredTags, validateScalarAttr } from "./node-attrs-validate.js";
@@ -16,6 +16,8 @@ import {
   MAX_REQUEST_CONTENT_LENGTH,
   MAX_UPLOAD_BYTES,
   buildStoragePath,
+  pathForExistingBlob,
+  isValidCalendarBucket,
   generateFileId,
   getUploadsRoot,
   indexEntryPath,
@@ -1197,10 +1199,86 @@ return Bun.serve({
       // now lives behind auth at GET /api/stats/sse.
       // `version` stays: it does help fingerprinting, but ops needs it
       // to verify deploys land, and the tradeoff was accepted in review.
+      //
+      // #495-followup / f28a6c1b — auth-gated `sse_sessions` restored so
+      // the dashboard's own "online" widget can compute per-agent status
+      // in one round-trip. Rules:
+      //   - anonymous (no valid token): NO sse_sessions field → watchdog
+      //     contract untouched, no topology leak (mutation removing this
+      //     gate turns the anonymous test RED — see health-redaction.test)
+      //   - admin utok_ / legacy master / DEV_OPEN: full sessions map
+      //     (parity with /api/stats/sse ops path)
+      //   - regular utok_ member: sessions map FILTERED to network_ids
+      //     the caller is a member of — safe against the "any account
+      //     sees all-network topology" regression the #473 fix closed;
+      //     dashboard user proxies with the logged-in user's utok_ so
+      //     their own network's aliases surface; strangers' networks do
+      //     not
       const count = db.get<{ cnt: number }>("SELECT COUNT(*) as cnt FROM sessions");
       const sse = getSSEStats();
       const license = db.get<any>("SELECT type, expires_at FROM licenses LIMIT 1");
-      return withCors(req, Response.json({
+
+      // Non-fatal auth probe (no 401 — /health must stay 200 anonymous).
+      const healthAuth = resolveRequestAuth(req);
+      const healthIsMaster = !healthAuth && isLegacyAuthToken(req);
+      const healthIsDevOpen = !healthAuth && !AUTH_TOKEN && DEV_OPEN;
+      const healthIsAdmin = !!(healthAuth?.username && db.get<any>(
+        "SELECT role FROM users WHERE username = ?1", healthAuth.username,
+      )?.role === "admin");
+
+      let scopedSessions: Record<string, number> | undefined;
+      if (healthIsMaster || healthIsDevOpen || healthIsAdmin) {
+        // Ops parity with /api/stats/sse — full map.
+        scopedSessions = sse.sessions;
+      } else if (healthAuth?.userId) {
+        // Regular authenticated member — filter to networks they belong
+        // to. Keys are `{networkId}:{alias}` (or observer keys shaped
+        // `\0netobs:{networkId}`); parse the network prefix and keep
+        // only entries whose network is in the member's set.
+        //
+        // 🔴 ntok_ (network-scoped token) MUST be forced to its single
+        // bound network (parity with resolveRestNetworkScope L277:
+        // `if (authCtx.networkId) return { networkId: authCtx.networkId }`).
+        // Falling through to the utok_ union query would return
+        // sessions from every network the underlying user belongs to,
+        // silently escalating a network-scoped token to a user-scoped
+        // token — the exact "认证 ≠ 已授权" mistake this whole change
+        // is meant to prevent. Same shape as f28a6c1b root cause; see
+        // CR3 audit 4703b0e7.
+        const memberNets = new Set<string>(
+          healthAuth.networkId
+            ? [healthAuth.networkId]  // ntok_ single-network enforce
+            : db.all<{ network_id: string }>(
+                "SELECT network_id FROM network_members WHERE user_id = ?1",
+                healthAuth.userId,
+              ).map((r) => r.network_id),
+        );
+        // If member has no networks at all, keep field present but empty
+        // so the dashboard can distinguish "authenticated + none active"
+        // from "not authenticated at all".
+        const filtered: Record<string, number> = {};
+        for (const [key, n] of Object.entries(sse.sessions)) {
+          // Observer keys are shape `\0netobs:<networkId>` raw; keyed
+          // through `printableKey()` in push.ts, they surface here as
+          // the literal string `\\0netobs:<networkId>` (backslash-zero,
+          // not NUL byte). Use the shared `PRINTABLE_OBSERVER_KEY_PREFIX`
+          // export so this side and the emitter side stay locked to the
+          // same literal — CR3 audit 4703b0e7 caught prior check
+          // `startsWith("netobs:")` was always false → observer keys
+          // silently over-filtered out of member views.
+          const isObserver = key.startsWith(PRINTABLE_OBSERVER_KEY_PREFIX);
+          const netId = isObserver
+            ? key.slice(PRINTABLE_OBSERVER_KEY_PREFIX.length)
+            : key.split(":")[0];
+          if (memberNets.has(netId)) filtered[key] = n;
+        }
+        scopedSessions = filtered;
+      }
+      // healthAuth == null AND no legacy master AND no DEV_OPEN → leave
+      // scopedSessions undefined → sse_sessions field omitted entirely
+      // (watchdog + arbitrary internet strangers see aggregates only).
+
+      const body: Record<string, unknown> = {
         ok: true,
         version: SERVER_VERSION,
         api_version: "v3",
@@ -1214,7 +1292,9 @@ return Bun.serve({
         multi_network: true,
         license: license?.type || "none",
         uptime: Math.floor(process.uptime()),
-      }));
+      };
+      if (scopedSessions !== undefined) body.sse_sessions = scopedSessions;
+      return withCors(req, Response.json(body));
     }
 
     // ── All REST /api endpoints require auth (if token configured) ──
@@ -1695,10 +1775,15 @@ return Bun.serve({
 
       let entry: any;
       try { entry = JSON.parse(readFileSync(idxPath, "utf-8")); } catch {
-        return withCors(req, Response.json({ ok: false, error: "index_corrupt" }, { status: 500 }));
+        // #509 副指挥 66983a19: corrupted index must not leak "server
+        // failed" signal — 404 with same shape as unknown file_id
+        // (input refused at boundary, no enumeration).
+        return withCors(req, Response.json({ ok: false, error: "not_found" }, { status: 404 }));
       }
       if (!validateIndexEntry(entry)) {
-        return withCors(req, Response.json({ ok: false, error: "index_invalid" }, { status: 500 }));
+        // #509 副指挥 66983a19: schema-invalid index (bucket "../etc",
+        // missing fields, wrong types) is also 404 — same discipline.
+        return withCors(req, Response.json({ ok: false, error: "not_found" }, { status: 404 }));
       }
 
       // #495 ownership gate — placed AFTER file-exists so denied
@@ -1710,11 +1795,29 @@ return Bun.serve({
         return withCors(req, Response.json({ ok: false, error: "not_found" }, { status: 404 }));
       }
 
+      // #509 defence-in-depth: pre-check date_bucket against BOTH
+      // shape regex AND real-calendar semantics. A poisoned index (e.g.
+      // "../etc", "2026-02-30", "2026-13-01") must return 404 not 500
+      // — 500 says "server failed"; 404 says "input refused at boundary".
+      // 副指挥 b1082017 / 66983a19 hard doors:
+      //   • 稳定 404 非 500 for invalid/missing/poisoned date_bucket
+      //   • 真日历语义校验, 不仅 regex 形状
+      if (!isValidCalendarBucket(entry.date_bucket)) {
+        return withCors(req, Response.json({ ok: false, error: "not_found" }, { status: 404 }));
+      }
+
       let storage;
       try {
-        storage = buildStoragePath(entry.file_id, entry.ext);
+        // #509 fix: use the date_bucket recorded in the index at upload
+        // time, NOT today's date. buildStoragePath computes today; that is
+        // correct for new uploads only. Yesterday's file lives in
+        // yesterday's bucket forever — read path must respect that.
+        storage = pathForExistingBlob(entry.date_bucket, entry.file_id, entry.ext);
       } catch {
-        return withCors(req, Response.json({ ok: false, error: "index_invalid" }, { status: 500 }));
+        // Defence-in-depth: unreachable given the pre-check above, but
+        // keep as fallback. Return 404 not 500 to match the pre-check
+        // shape — caller sees the same code for all invalid-bucket cases.
+        return withCors(req, Response.json({ ok: false, error: "not_found" }, { status: 404 }));
       }
       if (!isPathInsideUploadsRoot(storage.absolutePath)) {
         // Defence: should be unreachable since buildStoragePath rejected

package/src/uploads.ts

@@ -94,10 +94,47 @@ export function sanitizeExt(filename: string | undefined | null): string {
   return match ? "." + match[1].toLowerCase() : "";
 }
 
+// YYYY-MM-DD bucket string regex — matches what getDateBucket produces
+// and what an index entry's `date_bucket` field is validated against.
+const DATE_BUCKET_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Validate a date_bucket string against BOTH shape (YYYY-MM-DD regex)
+ * AND real-calendar semantics: rejects "2026-02-30", "2026-13-01",
+ * "2026-00-15", leap-day-on-non-leap-year, etc. Shape-only check is not
+ * enough because the regex accepts any digit combination in each
+ * position.
+ *
+ * Used as a pre-check by the download handler before it calls into
+ * pathForExistingBlob — a non-calendar bucket is a 404 (invalid input
+ * rejected at the boundary), NOT a 500 (uncaught throw from deep in
+ * the read path). Distinguishing these matters: 500 says "server
+ * failed"; 404 says "we know your request is bad, refused early".
+ */
+export function isValidCalendarBucket(bucket: unknown): bucket is string {
+  if (typeof bucket !== "string") return false;
+  if (!DATE_BUCKET_REGEX.test(bucket)) return false;
+  // Round-trip via Date to reject non-calendar shapes like "2026-02-30"
+  // or "2026-13-01". `Date.UTC` coerces overflow ("2026-02-30" becomes
+  // "2026-03-02") — if the ISO round-trip doesn't equal the input, the
+  // caller supplied a non-calendar bucket.
+  const [yStr, mStr, dStr] = bucket.split("-");
+  const y = Number(yStr), m = Number(mStr), d = Number(dStr);
+  if (m < 1 || m > 12) return false;
+  if (d < 1 || d > 31) return false;
+  const roundtrip = new Date(Date.UTC(y, m - 1, d)).toISOString().slice(0, 10);
+  return roundtrip === bucket;
+}
+
 /**
- * Build the per-upload storage path. The file_id and ext are validated
- * against strict regexes; any path-separator or `..` segment from a
- * malicious client gets rejected at the regex layer before any I/O.
+ * Build the storage path for a NEW upload. Computes today's date bucket
+ * from the runtime clock (or `opts.now` for tests). Use ONLY for creating
+ * a fresh blob; for reading an existing blob whose bucket is already
+ * recorded in the index, use pathForExistingBlob() instead.
+ *
+ * The file_id and ext are validated against strict regexes; any
+ * path-separator or `..` segment from a malicious client gets rejected
+ * at the regex layer before any I/O.
  */
 export function buildStoragePath(fileId: string, ext: string, opts: { uploadsRoot?: string; now?: Date } = {}): GeneratedFile {
   if (!FILE_ID_REGEX.test(fileId)) throw new Error(`file_id "${fileId}" is invalid`);
@@ -109,6 +146,32 @@ export function buildStoragePath(fileId: string, ext: string, opts: { uploadsRoo
   return { fileId, ext, dateBucket, relativePath, absolutePath };
 }
 
+/**
+ * Build the storage path for an EXISTING blob, using the caller-supplied
+ * `dateBucket` (typically read from the index entry). Does NOT compute
+ * a date from the runtime clock — that is the write-side concern.
+ *
+ * This split exists because sharing one date-computing function between
+ * write and read semantics caused #509: yesterday's file downloaded
+ * today would look under today's bucket → blob_missing → 404, even
+ * though the blob was still sitting in yesterday's directory.
+ *
+ * The file_id, ext and dateBucket are validated against strict regexes
+ * before any I/O; a poisoned index bucket (e.g. `../etc`) is rejected
+ * here just as file_id path-escape attempts are.
+ */
+export function pathForExistingBlob(dateBucket: string, fileId: string, ext: string, opts: { uploadsRoot?: string } = {}): GeneratedFile {
+  if (!FILE_ID_REGEX.test(fileId)) throw new Error(`file_id "${fileId}" is invalid`);
+  if (ext && !/^\.[A-Za-z0-9]{1,16}$/.test(ext)) throw new Error(`ext "${ext}" is invalid`);
+  if (typeof dateBucket !== "string" || !DATE_BUCKET_REGEX.test(dateBucket)) {
+    throw new Error(`date_bucket "${dateBucket}" is invalid`);
+  }
+  const root = opts.uploadsRoot ?? getUploadsRoot();
+  const relativePath = join(dateBucket, fileId + ext);
+  const absolutePath = join(root, relativePath);
+  return { fileId, ext, dateBucket, relativePath, absolutePath };
+}
+
 export type UploadIndexEntry = {
   file_id: string;
   date_bucket: string; // YYYY-MM-DD