@openparachute/vault 0.5.1 → 0.5.2-rc.1

package/src/routing.test.ts

@@ -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
@@ -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 });
@@ -1980,3 +1987,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);
+  });
+});

package/src/routing.ts

@@ -49,7 +49,7 @@ import {
   authenticateGlobalRequest,
   extractApiKey,
 } from "./auth.ts";
-import { hasScopeForVault, SCOPE_ADMIN, scopeForMethod, verbForMethod } from "./scopes.ts";
+import { hasScopeForVault, SCOPE_ADMIN, SCOPE_READ, scopeForMethod, verbForMethod } from "./scopes.ts";
 import { getVaultStore } from "./vault-store.ts";
 import { handleScopedMcp } from "./mcp-http.ts";
 import { defaultAdminSpaDistDir, isAdminSpaPath, serveAdminSpa } from "./admin-spa.ts";
@@ -87,6 +87,7 @@ import {
   handleMirrorRunNow,
 } from "./mirror-routes.ts";
 import { getMirrorManager } from "./mirror-registry.ts";
+import { buildUsageReport } from "./usage.ts";
 
 /**
  * Decorate a 401 response from the MCP endpoint with the RFC 9728 challenge
@@ -462,6 +463,35 @@ export async function route(
     });
   }
 
+  // /.parachute/usage — per-vault data-footprint report ("how big is this
+  // vault"). READ-scoped, deliberately: a vault's own user must be able to
+  // see their own vault's size, and the operator (who holds broad/admin)
+  // inherits read. This mirrors the bare-root stats precedent above (also
+  // read-gated by the method) — same data-disclosure class (counts + sizes,
+  // no note content). The expensive part (two dir-walks) is TTL-cached inside
+  // usage.ts; `?fresh=1` bypasses the cache. Hub-side aggregation/UI is a
+  // separate follow-up; this endpoint is the load-bearing primitive.
+  if (subpath === "/.parachute/usage") {
+    if (req.method !== "GET") {
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (!hasScopeForVault(auth.scopes, vaultName, "read")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_READ}' scope (or '${SCOPE_READ.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_READ,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    const fresh = new URL(req.url).searchParams.get("fresh") === "1";
+    const stats = await store.getVaultStats();
+    return Response.json(buildUsageReport(vaultName, stats, { fresh }));
+  }
+
   // The per-vault `/tokens` REST surface (pvt_* mint/list/revoke) was removed
   // at 0.5.0 (vault#282 Stage 2 — vault is a pure hub resource-server). Hub
   // JWTs are minted via hub's registry (`/api/auth/mint-token`); a `/tokens`
@@ -708,7 +738,7 @@ export async function route(
       writeVaultConfig(vaultConfig);
     });
   }
-  if (apiPath === "/unresolved-wikilinks") return handleUnresolvedWikilinks(req, store);
+  if (apiPath === "/unresolved-wikilinks") return handleUnresolvedWikilinks(req, store, tagScope);
   if (apiPath.startsWith("/storage")) return handleStorage(req, apiPath.slice(8), vaultName, store, tagScope);
   if (apiPath === "/health") return Response.json({ status: "ok", vault: vaultName });
 

package/src/server.ts

@@ -45,6 +45,7 @@ import {
 } from "./mirror-config.ts";
 import { GLOBAL_CONFIG_PATH } from "./config.ts";
 import { selfRegister } from "./self-register.ts";
+import { warnLegacyGlobalApiKeys } from "./auth.ts";
 import pkg from "../package.json" with { type: "json" };
 
 // Register webhook triggers from global config. Replaces the old hardcoded
@@ -144,6 +145,12 @@ if (process.env.VAULT_AUTH_TOKEN?.trim()) {
   console.log("[auth] VAULT_AUTH_TOKEN set — server-wide operator bearer active");
 }
 
+// Legacy GLOBAL api_keys warning (security review — multi-user hardening).
+// Surfaced at boot so the operator rotates/removes cross-vault credentials
+// before multi-user sharing. Warning only — never touches the keys. The
+// logic lives in auth.ts (import-safe + unit-tested); see warnLegacyGlobalApiKeys.
+warnLegacyGlobalApiKeys(readGlobalConfig().api_keys);
+
 // Auto-init: create a default vault if none exist (first run in Docker).
 // The vault name comes from PARACHUTE_VAULT_NAME when set + valid; otherwise
 // falls back to "default". Hub's first-boot wizard (hub#267) passes through

package/src/storage.test.ts

@@ -215,3 +215,165 @@ describe("storage GET tag-scope enforcement", () => {
     expect(res.status).toBe(403);
   });
 });
+
+// ---------------------------------------------------------------------------
+// GET percent-encoded-slash handling (feedback finding D).
+//
+// `path` reaches handleStorage from `url.pathname`, which keeps an encoded
+// `%2F` slash LITERAL (WHATWG). The old `path.match(/^\/([^/]+)\/(.+)$/)`
+// required a literal slash, so `/api/storage/<date>%2F<file>` fell to the
+// unconditional 404 — a trap-grade asymmetry with the single-note routes,
+// which decode their first segment and therefore REQUIRE `%2F`. The fix
+// decodes `path` before matching, accepting BOTH forms; the decoded path is
+// also what the DB stores (`${date}/${filename}`), so tag-scope lookup and
+// the traversal guard keep working. These tests pin both forms + the
+// guard-safety of the decode.
+// ---------------------------------------------------------------------------
+
+describe("storage GET percent-encoded slash (finding D)", () => {
+  const VAULT = "encode-vault";
+
+  async function setup(): Promise<{
+    store: SqliteStore;
+    assets: string;
+    inScopePath: string;
+    outScopePath: string;
+  }> {
+    const store = freshStore();
+    const assets = join(testDir, "assets", VAULT, "data");
+    mkdirSync(join(assets, "2026-05-28"), { recursive: true });
+    process.env.ASSETS_DIR = assets;
+
+    const workNote = await store.createNote("work note", { tags: ["work"] });
+    const healthNote = await store.createNote("health note", { tags: ["health"] });
+
+    const inScopePath = "2026-05-28/work-asset.pdf";
+    const outScopePath = "2026-05-28/health-asset.pdf";
+    writeFileSync(join(assets, inScopePath), Buffer.from([0x25, 0x50, 0x44, 0x46])); // %PDF
+    writeFileSync(join(assets, outScopePath), Buffer.from([0x25, 0x50, 0x44, 0x46]));
+
+    await store.addAttachment(workNote.id, inScopePath, "application/pdf");
+    await store.addAttachment(healthNote.id, outScopePath, "application/pdf");
+
+    return { store, assets, inScopePath, outScopePath };
+  }
+
+  // The request URL carries the encoded form; the `path` arg mirrors what the
+  // dispatcher hands the handler (derived from url.pathname, %2F kept literal).
+  function getReqEncoded(reqPath: string): { req: Request; path: string } {
+    const encoded = reqPath.replace(/\//g, "%2F");
+    return {
+      req: new Request(`http://localhost:1940/storage/${encoded}`, { method: "GET" }),
+      path: `/${encoded}`,
+    };
+  }
+
+  test("encoded %2F path serves the same bytes as the literal form (200)", async () => {
+    const { store, inScopePath } = await setup();
+    const ctx = await tagScopeCtx(store, ["work"]);
+    const { req, path } = getReqEncoded(inScopePath);
+    const res = await handleStorage(req, path, VAULT, store, ctx);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("application/pdf");
+    expect((await res.arrayBuffer()).byteLength).toBe(4);
+  });
+
+  test("literal-slash path still serves (regression)", async () => {
+    const { store, inScopePath } = await setup();
+    const ctx = await tagScopeCtx(store, ["work"]);
+    const res = await handleStorage(
+      new Request(`http://localhost:1940/storage/${inScopePath}`, { method: "GET" }),
+      `/${inScopePath}`,
+      VAULT,
+      store,
+      ctx,
+    );
+    expect(res.status).toBe(200);
+    expect((await res.arrayBuffer()).byteLength).toBe(4);
+  });
+
+  test("encoded traversal %2E%2E%2F… → 403 (decoded `..` hits the traversal guard)", async () => {
+    const { store } = await setup();
+    const ctx = await tagScopeCtx(store, ["work"]);
+    // Fully percent-encoded `/a/../../../../../../etc/passwd`. Decode yields
+    // the literal traversal, which resolves outside assetsDir → 403.
+    const evilDecoded = "/a/../../../../../../etc/passwd";
+    const evilEncoded = "/a%2F%2E%2E%2F%2E%2E%2F%2E%2E%2F%2E%2E%2F%2E%2E%2F%2E%2E%2Fetc%2Fpasswd";
+    expect(decodeURIComponent(evilEncoded)).toBe(evilDecoded);
+    const res = await handleStorage(
+      new Request(`http://localhost:1940/storage${evilEncoded}`, { method: "GET" }),
+      evilEncoded,
+      VAULT,
+      store,
+      ctx,
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test("tag-scoped token + out-of-scope owning note → still 404 with an encoded path", async () => {
+    const { store, outScopePath } = await setup();
+    const ctx = await tagScopeCtx(store, ["work"]);
+    const { req, path } = getReqEncoded(outScopePath);
+    const res = await handleStorage(req, path, VAULT, store, ctx);
+    expect(res.status).toBe(404);
+  });
+
+  test("malformed `%` (e.g. /api/storage/2026%2) → 404, not 500", async () => {
+    const { store } = await setup();
+    const ctx = await tagScopeCtx(store, ["work"]);
+    // `%2` is not a valid percent-escape → decodeURIComponent throws → 404.
+    const bad = "/2026%2";
+    expect(() => decodeURIComponent(bad)).toThrow();
+    const res = await handleStorage(
+      new Request(`http://localhost:1940/storage${bad}`, { method: "GET" }),
+      bad,
+      VAULT,
+      store,
+      ctx,
+    );
+    expect(res.status).toBe(404);
+  });
+
+  test("double-encoded %252F → 404 (decodes ONCE to literal %2F, no slash, no second decode)", async () => {
+    const { store } = await setup();
+    const ctx = await tagScopeCtx(store, ["work"]);
+    // `%252F` → decodeURIComponent once → `%2F` (a literal `%2F`, NOT a slash).
+    // The single decode is deliberate: a second decode would turn this into a
+    // real slash and risk serving / re-looping. With one decode the path has
+    // no `/` separator, so the date/file match fails → 404.
+    const doubleEncoded = "/2026-05-28%252Ffile.bin";
+    expect(decodeURIComponent(doubleEncoded)).toBe("/2026-05-28%2Ffile.bin");
+    const res = await handleStorage(
+      new Request(`http://localhost:1940/storage${doubleEncoded}`, { method: "GET" }),
+      doubleEncoded,
+      VAULT,
+      store,
+      ctx,
+    );
+    expect(res.status).toBe(404);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// POST parity (finding D — decode block must not change upload behavior).
+//
+// The `POST /upload` branch returns BEFORE the decode block, so a real upload
+// is untouched. A POST to a non-`/upload` storage path with a malformed `%`
+// falls past the upload branch into the decode (the `try/catch` is not method-
+// gated), where the throw → 404 — the same status the pre-fix unconditional
+// final 404 produced for this request. Pins that the decode doesn't turn a
+// malformed-`%` POST into a 500 and keeps POST behavior at parity.
+// ---------------------------------------------------------------------------
+
+describe("storage POST parity (finding D)", () => {
+  test("POST to a malformed-`%` storage path → 404, unchanged by the GET-side decode", async () => {
+    const bad = "/2026%2";
+    const res = await handleStorage(
+      new Request(`http://localhost:1940/storage${bad}`, { method: "POST" }),
+      bad,
+      "default",
+      uploadStore,
+    );
+    expect(res.status).toBe(404);
+  });
+});

package/src/tag-scope.ts

@@ -19,7 +19,7 @@
  * `rootOf` walk is needed at the boundary.
  */
 
-import type { Store, Note } from "../core/src/types.ts";
+import type { Store, Note, HydratedLink, NoteSummary } from "../core/src/types.ts";
 
 /**
  * Build the effective tag-allowlist for a token: union of `{root} ∪
@@ -100,6 +100,73 @@ export function tagsWithinScope(
   return false;
 }
 
+/**
+ * Build a per-note visibility predicate for wikilink expansion
+ * (`ExpandContext.isVisible` in core/src/expand.ts). When the token is
+ * unscoped (`rawRoots === null`) this returns `undefined` so the expander
+ * keeps its original scope-unaware behavior (no predicate installed). When
+ * scoped, it returns a closure over the SAME `noteWithinTagScope` allowlist
+ * logic every other read path uses — so a wikilink whose target is outside
+ * the token's tag scope is left unresolved during inlining, never embedded.
+ *
+ * This is the seam that keeps core scope-unaware: the predicate is built
+ * server-side from the tag-scope machinery and injected into the context;
+ * core only calls it.
+ */
+export function buildExpandVisibility(
+  allowed: Set<string> | null,
+  rawRoots: string[] | null,
+): ((note: Note) => boolean) | undefined {
+  if (rawRoots === null) return undefined;
+  return (note: Note) => noteWithinTagScope(note, allowed, rawRoots);
+}
+
+/**
+ * Treat a hydrated link's endpoint summary as a scope-checkable note. The
+ * summary carries `id` + `tags`, which is all `noteWithinTagScope` needs.
+ * A summary with no tags is out of scope under a tag-scoped token (same as
+ * a real note with no tags).
+ */
+function summaryWithinTagScope(
+  summary: NoteSummary | undefined,
+  allowed: Set<string> | null,
+  rawRoots: string[] | null,
+): boolean {
+  if (!summary) return true; // no summary → no out-of-scope info to leak (dangling/deleted)
+  return noteWithinTagScope({ id: summary.id, tags: summary.tags ?? [] } as Note, allowed, rawRoots);
+}
+
+/**
+ * Filter hydrated links for a tag-scoped token so no out-of-scope NEIGHBOR
+ * metadata leaks (security review — MINOR). A `query-notes`/REST response
+ * with `include_links=true` returns `sourceNote`/`targetNote` summaries
+ * ({id, path, tags, metadata, …}) for every link touching the returned
+ * note — INCLUDING links to notes the token can't otherwise see. Those
+ * summaries leak the out-of-scope neighbor's id, path, and tags.
+ *
+ * Policy: drop any link whose source OR target endpoint summary is outside
+ * the token's tag scope. The queried note itself is always in-scope (it had
+ * to be visible to be returned), so dropping out-of-scope-neighbor links
+ * removes exactly the leak while keeping every link between in-scope notes
+ * fully hydrated. Dropping the whole row (vs. just nulling the summary) is
+ * required because the raw row still carries the neighbor's note id.
+ *
+ * No-op when the token is unscoped (`rawRoots === null`) — identical to the
+ * pre-fix behavior.
+ */
+export function filterHydratedLinksByTagScope(
+  links: HydratedLink[],
+  allowed: Set<string> | null,
+  rawRoots: string[] | null,
+): HydratedLink[] {
+  if (rawRoots === null) return links;
+  return links.filter(
+    (link) =>
+      summaryWithinTagScope(link.sourceNote, allowed, rawRoots) &&
+      summaryWithinTagScope(link.targetNote, allowed, rawRoots),
+  );
+}
+
 /**
  * Standard 403 response shape for tag-scope rejections. Mirrors the
  * `insufficient_scope` 403 shape used elsewhere in the API so clients