@openparachute/vault 0.6.0-rc.1 → 0.6.0

package/src/routing.test.ts

@@ -30,7 +30,7 @@ const testDir = join(
 process.env.PARACHUTE_HOME = testDir;
 
 // Dynamic import after env override so modules pick up the tmp dir.
-const { route } = await import("./routing.ts");
+const { route, filterVaultListForBinding } = await import("./routing.ts");
 const {
   readGlobalConfig,
   writeGlobalConfig,
@@ -44,6 +44,7 @@ const {
 const { clearVaultStoreCache, getVaultStore } = await import("./vault-store.ts");
 const { vaultDbPath } = await import("./config.ts");
 const { resetJwksCache, resetRevocationCache } = await import("./hub-jwt.ts");
+const { invalidateUsageCache } = await import("./usage.ts");
 
 // ---------------------------------------------------------------------------
 // Hub-JWT mint fixture (vault#282 Stage 2 — vault is a pure hub
@@ -100,8 +101,8 @@ function createVault(name: string, description?: string): void {
 
 /**
  * Seed a vestigial row directly into a vault's `tokens` table (raw INSERT).
- * Post-0.6.0 (vault#282 Stage 2) vault no longer mints these, but the table
- * survives + `/auth/status` probes it for leftover pre-0.6.0 rows. This is how
+ * Post-0.5.0 (vault#282 Stage 2) vault no longer mints these, but the table
+ * survives + `/auth/status` probes it for leftover pre-0.5.0 rows. This is how
  * we exercise the `hasTokens=true` branch now that there's no mint path.
  */
 function seedVestigialTokenRow(vaultName: string): void {
@@ -114,7 +115,7 @@ function seedVestigialTokenRow(vaultName: string): void {
 /**
  * Seed a vestigial tag-scoped row (raw INSERT, `scoped_tags` JSON populated).
  * The tag-delete / -rename / -merge fail-closed guard (`findTokensReferencingTag`)
- * reads this column. Post-0.6.0 hub-JWT tag scopes live in the JWT claim, not
+ * reads this column. Post-0.5.0 hub-JWT tag scopes live in the JWT claim, not
  * the DB, so the guard now protects only these vestigial rows — these tests
  * pin that the DB-row guard still fires.
  */
@@ -135,6 +136,12 @@ function seedTagScopedRow(vaultName: string, scopedTags: string[], label = "test
 
 function reset(): void {
   clearVaultStoreCache();
+  // The usage dir-walk cache is module-level (process-wide) and survives the
+  // testDir wipe; its 60s TTL would otherwise leak a prior test's `journal`
+  // entry into the next test and flip a "first read" to cached:true. Clear
+  // the vault names these tests reuse so each test starts cache-cold.
+  invalidateUsageCache("journal");
+  invalidateUsageCache("other");
   if (existsSync(testDir)) rmSync(testDir, { recursive: true, force: true });
   mkdirSync(testDir, { recursive: true });
   mkdirSync(join(testDir, "vault", "data"), { recursive: true });
@@ -142,7 +149,12 @@ function reset(): void {
   // Default every test to the fixture hub origin so the hub-JWT mint path
   // resolves JWKS + validates `iss`. Describes that assert the loopback
   // default (OAuth discovery metadata) override this in their own beforeEach.
-  if (hubFixtureOrigin) process.env.PARACHUTE_HUB_ORIGIN = hubFixtureOrigin;
+  if (hubFixtureOrigin) {
+    process.env.PARACHUTE_HUB_ORIGIN = hubFixtureOrigin;
+    // Post-vault#464 the JWKS fetch origin resolves separately (loopback by
+    // default); point it at the fixture so the mint path's JWKS fetch resolves.
+    process.env.PARACHUTE_HUB_JWKS_ORIGIN = hubFixtureOrigin;
+  }
   resetJwksCache();
   resetRevocationCache();
 }
@@ -176,6 +188,7 @@ afterAll(() => {
   clearVaultStoreCache();
   hubServer?.stop(true);
   delete process.env.PARACHUTE_HUB_ORIGIN;
+  delete process.env.PARACHUTE_HUB_JWKS_ORIGIN;
   if (existsSync(testDir)) rmSync(testDir, { recursive: true, force: true });
 });
 
@@ -311,6 +324,56 @@ describe("GET /vaults/list (public discovery)", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// GET /vaults — authenticated metadata listing, filtered by vault binding
+// (vault#259). Operator / admin-channel callers (vault_name === null) see the
+// full list; a vault-bound caller sees only its own vault.
+// ---------------------------------------------------------------------------
+
+describe("GET /vaults (binding filter — vault#259)", () => {
+  // Pure policy helper — drives the filtering decision independent of the
+  // auth path (no current credential yields a non-null vault_name HERE, since
+  // authenticateGlobalRequest 401s hub JWTs; the helper pins the correct
+  // shape for any future vault-bound credential on this surface).
+  test("filterVaultListForBinding: null binding (operator) keeps the full list", () => {
+    const names = ["work", "boulder", "default"];
+    expect(filterVaultListForBinding(names, null)).toEqual(names);
+  });
+
+  test("filterVaultListForBinding: a vault-bound caller sees only its own vault", () => {
+    const names = ["work", "boulder", "default"];
+    expect(filterVaultListForBinding(names, "work")).toEqual(["work"]);
+    // No cross-vault info-leak: boulder/default are not disclosed.
+    expect(filterVaultListForBinding(names, "work")).not.toContain("boulder");
+    expect(filterVaultListForBinding(names, "work")).not.toContain("default");
+  });
+
+  test("filterVaultListForBinding: binding to a vault absent from the list yields empty", () => {
+    expect(filterVaultListForBinding(["work", "default"], "ghost")).toEqual([]);
+  });
+
+  test("operator token (VAULT_AUTH_TOKEN) gets the UNFILTERED full listing", async () => {
+    createVault("work");
+    createVault("boulder");
+    createVault("default");
+    const prev = process.env.VAULT_AUTH_TOKEN;
+    process.env.VAULT_AUTH_TOKEN = "op-secret-token-259";
+    try {
+      const req = new Request("http://localhost:1940/vaults", {
+        headers: { authorization: "Bearer op-secret-token-259" },
+      });
+      const res = await route(req, "/vaults");
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { vaults: { name: string }[] };
+      const names = body.vaults.map((v) => v.name);
+      expect(new Set(names)).toEqual(new Set(["work", "boulder", "default"]));
+    } finally {
+      if (prev === undefined) delete process.env.VAULT_AUTH_TOKEN;
+      else process.env.VAULT_AUTH_TOKEN = prev;
+    }
+  });
+});
+
 // ---------------------------------------------------------------------------
 // /vault/<name>/admin/* — admin SPA static-file mount. Detailed tests live
 // in admin-spa.test.ts (with a tmp dist dir); these pin the dispatch — i.e.
@@ -368,6 +431,70 @@ describe("/vault/<name>/admin/* SPA mount", () => {
     expect(res.status).toBe(401);
   });
 
+  // ---------------------------------------------------------------------
+  // /vault/admin[/*] — DAEMON-LEVEL multi-vault SPA mount (B3, 2026-06-09
+  // hub-module-boundary migration). `admin` is a reserved vault name (B2),
+  // and this branch dispatches BEFORE both the per-vault SPA mount and the
+  // per-vault dispatcher. Detailed serving behavior (the bare-mount 301,
+  // asset strip) is pinned in admin-spa.test.ts with a tmp dist dir.
+  // ---------------------------------------------------------------------
+
+  test("/vault/admin/ fires the SPA layer, never the per-vault 'Vault not found' JSON", async () => {
+    // No vault named "admin" exists (it can't — reserved). Without the
+    // daemon-level branch this path would fall to the per-vault dispatcher
+    // and 404 as JSON.
+    const req = new Request("http://localhost:1940/vault/admin/");
+    const res = await route(req, "/vault/admin/");
+    expect(res.status === 200 || res.status === 503).toBe(true);
+    expect(res.headers.get("content-type") ?? "").not.toContain("application/json");
+  });
+
+  test("/vault/admin/admin does NOT boot per-vault mode for a vault named 'admin'", async () => {
+    // The per-vault regex would capture name="admin" here. The daemon-level
+    // branch must win — the regexes are deliberately not merged.
+    const req = new Request("http://localhost:1940/vault/admin/admin");
+    const res = await route(req, "/vault/admin/admin");
+    expect(res.status === 200 || res.status === 503).toBe(true);
+    expect(res.headers.get("content-type") ?? "").not.toContain("application/json");
+  });
+
+  test("a squatted vault named 'admin' is shadowed — its data plane serves the SPA layer", async () => {
+    // A vault created before the reservation landed. The daemon mount wins
+    // over its entire /vault/admin/* surface (server boot warns with the
+    // recovery procedure — see vault-name.ts:reservedNameSquatWarnings).
+    createVault("admin");
+    const req = new Request("http://localhost:1940/vault/admin/api/notes");
+    const res = await route(req, "/vault/admin/api/notes");
+    // The per-vault API would 401 (auth wall); the SPA layer serves the
+    // static shell (200) or the unbuilt-dist 503 — never the API's JSON.
+    expect(res.status === 200 || res.status === 503).toBe(true);
+    expect(res.headers.get("content-type") ?? "").not.toContain("application/json");
+  });
+
+  test("POST /vault/admin/ returns 405 (daemon mount is GET-only)", async () => {
+    const req = new Request("http://localhost:1940/vault/admin/", { method: "POST" });
+    const res = await route(req, "/vault/admin/");
+    expect(res.status).toBe(405);
+  });
+
+  test("/vault/adminx/* does NOT match the daemon mount — routes per-vault", async () => {
+    // Exact-segment match only: a real vault whose name merely starts with
+    // "admin" keeps its normal per-vault surface (the API auth wall 401s,
+    // proving the per-vault dispatcher handled it).
+    createVault("adminx");
+    const req = new Request("http://localhost:1940/vault/adminx/api/notes");
+    const res = await route(req, "/vault/adminx/api/notes");
+    expect(res.status).toBe(401);
+  });
+
+  test("per-vault /vault/<real>/admin/ is unaffected by the daemon mount", async () => {
+    createVault("work");
+    const req = new Request("http://localhost:1940/vault/work/admin/");
+    const res = await route(req, "/vault/work/admin/");
+    expect(res.status === 200 || res.status === 503).toBe(true);
+    expect(res.headers.get("content-type") ?? "").not.toContain("application/json");
+  });
+
   test("origin-rooted /admin (legacy mount retired) returns 404", async () => {
     // Pre-vault#252 the SPA was at /admin/*. Routing now lets that fall
     // through to the catch-all — hub's directory page should link to
@@ -1633,6 +1760,147 @@ describe("scope enforcement on /api/*", () => {
     expect(res.status).toBe(201);
   });
 
+  // ----- vault#439: near[] BFS is a WALL, not a sieve --------------------
+  // For a tag-scoped token the graph traversal must refuse to walk THROUGH
+  // an out-of-scope note. So an in-scope note reachable ONLY via an
+  // out-of-scope intermediary is unreachable — symmetric with find-path.
+  // Topology: A(#work) --link--> P(#personal) --link--> B(#work).
+  // A token scoped to ["work"] anchored at A, depth 2:
+  //   - sieve (old): B survives (reached via P, then output-filtered to keep B)
+  //   - wall (new):  P is the wall; B is never reached.
+
+  test("vault#439: tag-scoped near[] cannot reach an in-scope note through an out-of-scope hop", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    const a = await store.createNote("anchor-work", { tags: ["work"] });
+    const p = await store.createNote("bridge-personal", { tags: ["personal"] });
+    const b = await store.createNote("far-work", { tags: ["work"] });
+    await store.createLink(a.id, p.id, "relates");
+    await store.createLink(p.id, b.id, "relates");
+    const token = await mintTagScopedToken("journal", ["vault:read"], ["work"]);
+
+    // `route`'s second arg is the pathname only; the query rides on req.url.
+    const pathname = "/vault/journal/api/notes";
+    const full = `${pathname}?near[note_id]=${a.id}&near[depth]=2`;
+    const res = await route(authed(token, "GET", full), pathname);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { notes?: { id: string }[] } | { id: string }[];
+    const list = Array.isArray(body) ? body : (body.notes ?? []);
+    const ids = list.map((n) => n.id);
+    // B is in-scope (#work) but only reachable via the out-of-scope #personal
+    // bridge — the wall makes it unreachable.
+    expect(ids).not.toContain(b.id);
+    // P itself never leaks (it's out of scope).
+    expect(ids).not.toContain(p.id);
+  });
+
+  test("vault#439: tag-scoped near[] still reaches in-scope notes via in-scope hops", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    const a = await store.createNote("anchor-work", { tags: ["work"] });
+    const mid = await store.createNote("mid-work", { tags: ["work"] });
+    const far = await store.createNote("far-work", { tags: ["work"] });
+    await store.createLink(a.id, mid.id, "relates");
+    await store.createLink(mid.id, far.id, "relates");
+    const token = await mintTagScopedToken("journal", ["vault:read"], ["work"]);
+
+    const pathname = "/vault/journal/api/notes";
+    const full = `${pathname}?near[note_id]=${a.id}&near[depth]=2`;
+    const res = await route(authed(token, "GET", full), pathname);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { notes?: { id: string }[] } | { id: string }[];
+    const list = Array.isArray(body) ? body : (body.notes ?? []);
+    const ids = list.map((n) => n.id);
+    // All-in-scope path: both mid (depth 1) and far (depth 2) are reachable.
+    expect(ids).toContain(mid.id);
+    expect(ids).toContain(far.id);
+  });
+
+  test("vault#439: UNSCOPED token near[] still walks the full graph (behavior unchanged)", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    const a = await store.createNote("anchor-work", { tags: ["work"] });
+    const p = await store.createNote("bridge-personal", { tags: ["personal"] });
+    const b = await store.createNote("far-work", { tags: ["work"] });
+    await store.createLink(a.id, p.id, "relates");
+    await store.createLink(p.id, b.id, "relates");
+    // No scopedTags → unscoped admin token; no wall installed.
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:admin"] });
+
+    const pathname = "/vault/journal/api/notes";
+    const full = `${pathname}?near[note_id]=${a.id}&near[depth]=2`;
+    const res = await route(authed(token, "GET", full), pathname);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { notes?: { id: string }[] } | { id: string }[];
+    const list = Array.isArray(body) ? body : (body.notes ?? []);
+    const ids = list.map((n) => n.id);
+    // Unscoped: the full neighborhood is visible, including the #personal
+    // bridge and the note beyond it.
+    expect(ids).toContain(p.id);
+    expect(ids).toContain(b.id);
+  });
+
+  // ----- vault#404: REST-path hub-JWT tag-scoping enforcement (C0) --------
+  // The MCP path's tag-scope enforcement is covered end-to-end; pin that a
+  // tag-scoped HUB JWT (allowlist carried in the `permissions.scoped_tags`
+  // claim, NOT a vestigial DB row) hitting the REST surface enforces the
+  // same allowlist on both read and write. `mintTagScopedToken` mints a real
+  // hub JWT, so these tests exercise the hub-JWT-sourced `scoped_tags` path.
+
+  test("vault#404: hub-JWT tag-scoped READ via REST enforces the allowlist (list + single)", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    const inScope = await store.createNote("h", { tags: ["health"] });
+    const outOfScope = await store.createNote("w", { tags: ["work"] });
+    const token = await mintTagScopedToken("journal", ["vault:read"], ["health"]);
+
+    // List: only in-scope notes.
+    const listPath = "/vault/journal/api/notes";
+    const listRes = await route(authed(token, "GET", listPath), listPath);
+    expect(listRes.status).toBe(200);
+    const listBody = (await listRes.json()) as { notes?: { id: string }[] } | { id: string }[];
+    const list = Array.isArray(listBody) ? listBody : (listBody.notes ?? []);
+    const ids = list.map((n) => n.id);
+    expect(ids).toContain(inScope.id);
+    expect(ids).not.toContain(outOfScope.id);
+
+    // Single in-scope → 200; single out-of-scope → 404 (no existence leak).
+    const okPath = `/vault/journal/api/notes/${inScope.id}`;
+    expect((await route(authed(token, "GET", okPath), okPath)).status).toBe(200);
+    const denyPath = `/vault/journal/api/notes/${outOfScope.id}`;
+    expect((await route(authed(token, "GET", denyPath), denyPath)).status).toBe(404);
+  });
+
+  test("vault#404: hub-JWT tag-scoped WRITE via REST enforces the allowlist", async () => {
+    createVault("journal");
+    const token = await mintTagScopedToken("journal", ["vault:read", "vault:write"], ["health"]);
+
+    // In-scope write → 201.
+    const path = "/vault/journal/api/notes";
+    const okRes = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ content: "ok", tags: ["health"] }),
+      }),
+      path,
+    );
+    expect(okRes.status).toBe(201);
+
+    // Out-of-scope write → 403 tag_scope_violation.
+    const denyRes = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ content: "denied", tags: ["work"] }),
+      }),
+      path,
+    );
+    expect(denyRes.status).toBe(403);
+    const denyBody = (await denyRes.json()) as { error_type?: string };
+    expect(denyBody.error_type).toBe("tag_scope_violation");
+  });
+
   // ----- Q5: tag-delete dependency check ---------------------------------
   // Deleting a tag referenced by any token's scoped_tags would silently
   // orphan the token's allowlist; fail closed with 409 + referenced_by.
@@ -1980,3 +2248,181 @@ describe("/vault/<name>/.parachute/mirror/run-now — auth + dispatch", () => {
     expect([405, 503]).toContain(res.status);
   });
 });
+
+// ---------------------------------------------------------------------------
+// /vault/<name>/.parachute/usage — per-vault data-footprint endpoint.
+//
+// READ-scoped (a vault's own user must see their own vault's size; the
+// operator inherits read via broad/admin). Reports counts + byte sizes; the
+// two dir-walks (assets, mirror) are TTL-cached, `?fresh=1` bypasses, and an
+// attachment upload invalidates the cache. These tests exercise the auth
+// gate, the response shape, the cache hit/bypass, and upload-invalidation
+// end-to-end through `route()` against the real (tmp) filesystem.
+// ---------------------------------------------------------------------------
+
+describe("/vault/<name>/.parachute/usage — data-footprint endpoint", () => {
+  const USAGE_PATH = "/vault/journal/.parachute/usage";
+
+  function authedGet(token: string, path = USAGE_PATH): Request {
+    return new Request(`http://localhost:1940${path}`, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+  }
+
+  /** Upload an attachment through the real storage route (write-scoped). */
+  async function uploadAttachment(token: string, bytes: number): Promise<Response> {
+    const form = new FormData();
+    const file = new File([new Uint8Array(bytes).fill(7)], "photo.png", { type: "image/png" });
+    form.set("file", file);
+    const p = "/vault/journal/api/storage/upload";
+    return route(
+      new Request(`http://localhost:1940${p}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}` },
+        body: form,
+      }),
+      p,
+    );
+  }
+
+  test("unauthenticated → 401", async () => {
+    createVault("journal");
+    const res = await route(new Request(`http://localhost:1940${USAGE_PATH}`), USAGE_PATH);
+    expect(res.status).toBe(401);
+  });
+
+  test("read-scoped token → 200 with the full shape (owner sees own vault)", async () => {
+    createVault("journal");
+    // Seed two notes so counts + contentBytes are non-trivial.
+    const store = getVaultStore("journal");
+    await store.createNote("hello");
+    await store.createNote("world!");
+
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:read"] });
+    const res = await route(authedGet(token), USAGE_PATH);
+    expect(res.status).toBe(200);
+
+    const body = (await res.json()) as {
+      counts: { notes: number; attachments: number; links: number; tags: number };
+      bytes: { content: number; db: number; assets: number; total: number; mirror?: number };
+      computedAt: string;
+      cached: boolean;
+    };
+
+    // counts match getVaultStats
+    const stats = await store.getVaultStats();
+    expect(body.counts.notes).toBe(stats.totalNotes);
+    expect(body.counts.notes).toBe(2);
+    expect(body.counts.attachments).toBe(stats.attachmentCount);
+    expect(body.counts.links).toBe(stats.linkCount);
+    expect(body.counts.tags).toBe(stats.tagCount);
+
+    // bytes shape
+    expect(body.bytes.content).toBe(stats.contentBytes);
+    expect(body.bytes.content).toBe(11); // "hello"(5) + "world!"(6)
+    expect(body.bytes.db).toBeGreaterThan(0); // a real SQLite file exists
+    expect(body.bytes.assets).toBe(0); // no uploads yet
+    // total = db + assets (NOT content, NOT mirror)
+    expect(body.bytes.total).toBe(body.bytes.db + body.bytes.assets);
+    // no mirror configured → omitted
+    expect(body.bytes).not.toHaveProperty("mirror");
+
+    expect(typeof body.computedAt).toBe("string");
+    expect(typeof body.cached).toBe("boolean");
+  });
+
+  test("insufficient scope is impossible at read — but no vault: scope at all → 403", async () => {
+    createVault("journal");
+    // A token carrying only a non-vault scope satisfies neither read nor any
+    // vault verb → 403 insufficient_scope.
+    const token = await mintJwt({ vaultName: "journal", scopes: ["openid"] });
+    const res = await route(authedGet(token), USAGE_PATH);
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string; required_scope?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+    expect(body.required_scope).toBe("vault:read");
+  });
+
+  test("wrong-vault scope is denied (narrowed scope names a different vault)", async () => {
+    createVault("journal");
+    createVault("other");
+    // Token scoped to `other`, used against `journal` → denied.
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:other:read"] });
+    const res = await route(authedGet(token), USAGE_PATH);
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+  });
+
+  test("write/admin scope inherits read → 200", async () => {
+    createVault("journal");
+    const token = await createAdminToken("journal");
+    const res = await route(authedGet(token), USAGE_PATH);
+    expect(res.status).toBe(200);
+  });
+
+  test("non-GET method → 405", async () => {
+    createVault("journal");
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:read"] });
+    const res = await route(
+      new Request(`http://localhost:1940${USAGE_PATH}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      USAGE_PATH,
+    );
+    expect(res.status).toBe(405);
+  });
+
+  test("second read within TTL is served from cache (cached:true)", async () => {
+    createVault("journal");
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:read"] });
+
+    const first = (await (await route(authedGet(token), USAGE_PATH)).json()) as { cached: boolean };
+    expect(first.cached).toBe(false);
+
+    const second = (await (await route(authedGet(token), USAGE_PATH)).json()) as { cached: boolean };
+    expect(second.cached).toBe(true);
+  });
+
+  test("?fresh=1 bypasses the cache (cached:false even on a warm cache)", async () => {
+    createVault("journal");
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:read"] });
+
+    // Prime the cache.
+    await route(authedGet(token), USAGE_PATH);
+
+    // ?fresh=1 must recompute regardless. The server passes `url.pathname`
+    // (query stripped) as the `path` arg while the Request URL retains the
+    // query — the route reads `fresh` from `req.url`, not `path`. Mirror that.
+    const reqWithQuery = new Request(`http://localhost:1940${USAGE_PATH}?fresh=1`, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    const res = await route(reqWithQuery, USAGE_PATH);
+    const body = (await res.json()) as { cached: boolean };
+    expect(body.cached).toBe(false);
+  });
+
+  test("attachment upload invalidates the cache → assets bytes update", async () => {
+    createVault("journal");
+    const writeToken = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:write"] });
+
+    // Prime: assets empty.
+    const before = (await (await route(authedGet(writeToken), USAGE_PATH)).json()) as {
+      bytes: { assets: number };
+    };
+    expect(before.bytes.assets).toBe(0);
+
+    // Upload a 4096-byte attachment (write-scoped) — this invalidates usage.
+    const up = await uploadAttachment(writeToken, 4096);
+    expect(up.status).toBe(201);
+
+    // Next read must re-walk (cache was invalidated) and reflect the new file.
+    const after = (await (await route(authedGet(writeToken), USAGE_PATH)).json()) as {
+      bytes: { assets: number };
+      cached: boolean;
+    };
+    expect(after.cached).toBe(false); // invalidated → recomputed
+    expect(after.bytes.assets).toBeGreaterThanOrEqual(4096);
+  });
+});