@openparachute/vault 0.6.0-rc.1 → 0.6.1

package/src/routing.ts

@@ -15,6 +15,9 @@
  *   /vaults/list                       — public vault-name discovery (can be
  *                                        disabled globally via config)
  *   /vaults                            — authenticated vault metadata list
+ *   /vault/admin[/*]                   — daemon-level multi-vault admin SPA
+ *                                        (B3; `admin` is a reserved vault
+ *                                        name, dispatched BEFORE per-vault)
  *   /vault/<name>/.well-known/oauth-*  — discovery forwarder; metadata names
  *                                        the hub as the authorization server
  *                                        (vault is resource-server only)
@@ -49,10 +52,16 @@ 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";
+import {
+  defaultAdminSpaDistDir,
+  isAdminSpaPath,
+  isDaemonAdminSpaPath,
+  serveAdminSpa,
+  serveDaemonAdminSpa,
+} from "./admin-spa.ts";
 import {
   handleNotes,
   handleTags,
@@ -63,6 +72,8 @@ import {
   handleViewNote,
   type TagScopeCtx,
 } from "./routes.ts";
+import { handleSubscribe } from "./subscribe.ts";
+import { handleTriggers } from "./triggers-api.ts";
 import { expandTokenTagScope } from "./tag-scope.ts";
 import {
   handleProtectedResource,
@@ -76,6 +87,7 @@ import {
   handleAuthGet,
   handleAuthGithubCreateRepo,
   handleAuthGithubDeviceCode,
+  handleAuthGithubInstallations,
   handleAuthGithubPoll,
   handleAuthGithubRepos,
   handleAuthGithubSelectRepo,
@@ -87,6 +99,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
@@ -179,6 +192,23 @@ function handleParachuteIcon(): Response {
   });
 }
 
+/**
+ * Filter a server-wide vault-name list for a caller's per-vault binding
+ * (vault#259). `vaultName === null` is the operator / admin-channel caller
+ * (server-wide VAULT_AUTH_TOKEN or legacy cross-vault config.yaml key) — they
+ * keep the FULL list. A non-null binding reduces the list to just that vault
+ * (empty if the bound vault isn't in the listing). Pure + exported so the
+ * policy is unit-testable independent of the auth path. See the `/vaults`
+ * handler for the full rationale.
+ */
+export function filterVaultListForBinding(
+  names: string[],
+  vaultName: string | null,
+): string[] {
+  if (vaultName === null) return names;
+  return names.filter((name) => name === vaultName);
+}
+
 export async function route(
   req: Request,
   path: string,
@@ -269,6 +299,26 @@ export async function route(
     });
   }
 
+  // Daemon-level multi-vault admin SPA — `/vault/admin[/*]` (B3 of the
+  // 2026-06-09 hub-module-boundary migration). The vault MODULE's own home
+  // surface: list / create / delete vaults, deep-link into each instance's
+  // per-vault admin. Same static bundle as the per-vault mount below —
+  // `web/ui/src/lib/mount.ts` detects the basename at runtime.
+  //
+  // MUST dispatch BEFORE `isAdminSpaPath`: the per-vault regex also matches
+  // `/vault/admin/admin` (capturing name="admin"), which must NOT boot
+  // per-vault mode — `admin` is a reserved vault name (B2) and this mount is
+  // daemon-owned. Hub#637's `/vault/admin` route forwards the FULL path here
+  // (no stripPrefix on vault's services row). A pre-reservation squatter
+  // vault named "admin" is fully shadowed by this branch — server boot
+  // warns with the recovery procedure (see vault-name.ts).
+  if (isDaemonAdminSpaPath(path)) {
+    if (req.method !== "GET") {
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    return serveDaemonAdminSpa(defaultAdminSpaDistDir(), path);
+  }
+
   // Admin SPA — per-vault at `/vault/<name>/admin/*` (vault#252). Static-
   // file serving only (index.html + Vite asset bundle); no auth at this
   // seam since the bundle reveals nothing privileged. The SPA's data
@@ -285,10 +335,24 @@ export async function route(
   }
 
   // Authenticated vault metadata list.
+  //
+  // Vault-binding filter (vault#259, info-leak follow-up): `/vaults` is a
+  // cross-vault DISCOVERY endpoint, not a single-vault operational one (unlike
+  // /mcp, which legitimately routes a vault-bound token back into its own
+  // vault). A caller bound to one vault shouldn't learn that OTHER vaults exist
+  // on this server. So when the authenticated caller carries a per-vault
+  // binding (`auth.vault_name !== null`), the listing is reduced to just that
+  // vault. Operator / admin-channel callers — the server-wide VAULT_AUTH_TOKEN
+  // and legacy cross-vault config.yaml keys — have `vault_name === null` and
+  // keep the full listing (they're explicitly the cross-vault management
+  // channel). `authenticateGlobalRequest` already 401s hub JWTs here, so the
+  // only callers that reach this point today are operator-channel
+  // (`vault_name === null`); this filter is the security-correct shape for any
+  // future vault-bound credential that becomes accepted on this surface.
   if (path === "/vaults" && req.method === "GET") {
     const auth = await authenticateGlobalRequest(req);
     if ("error" in auth) return auth.error;
-    const names = listVaults();
+    const names = filterVaultListForBinding(listVaults(), auth.vault_name);
     const vaults = names.map((name) => {
       const config = readVaultConfig(name);
       return {
@@ -462,8 +526,37 @@ 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.6.0 (vault#282 Stage 2 — vault is a pure hub resource-server). Hub
+  // 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`
   // request now falls through to the catch-all 404 below.
 
@@ -643,6 +736,13 @@ export async function route(
       if (req.method === "POST") return handleAuthGithubPoll(req, manager);
       return Response.json({ error: "Method not allowed" }, { status: 405 });
     }
+    if (subpath === "/.parachute/mirror/auth/github/installations") {
+      // Install state (vault#480) — which app, installed-anywhere?, install
+      // link, per-account installations. Explicitly-network (probes GitHub);
+      // the offline status read stays on GET /.parachute/mirror/auth.
+      if (req.method === "GET") return handleAuthGithubInstallations(manager);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
     if (subpath === "/.parachute/mirror/auth/github/repos") {
       if (req.method === "GET") return handleAuthGithubRepos(manager);
       return Response.json({ error: "Method not allowed" }, { status: 405 });
@@ -667,6 +767,18 @@ export async function route(
     return Response.json({ error: "Not found" }, { status: 404 });
   }
 
+  // /api/triggers — runtime trigger-registration API. Dispatched BEFORE the
+  // generic method→verb scope gate below because it's ADMIN-scoped on EVERY
+  // method (a webhook trigger exfiltrates note data; even GET is admin). The
+  // gate lives inside `handleTriggers`. Subpath is everything after
+  // `/api/triggers`. See src/triggers-api.ts.
+  {
+    const triggersPath = apiMatch[1] ?? "";
+    if (triggersPath === "/triggers" || triggersPath.startsWith("/triggers/")) {
+      return handleTriggers(req, store, triggersPath.slice("/triggers".length), vaultName, auth);
+    }
+  }
+
   // REST API — scope gate. GET/HEAD/OPTIONS → vault:read,
   // POST/PATCH/PUT/DELETE → vault:write. Inheritance (admin ⊇ write ⊇ read)
   // and the broad-vs-narrowed shape (`vault:<verb>` from pvt_*, or
@@ -701,6 +813,10 @@ export async function route(
   };
 
   if (apiPath.startsWith("/notes")) return handleNotes(req, store, apiPath.slice(6), vaultName, tagScope);
+  // Live-query SSE subscription (design 2026-06-08). Snapshot + scoped live
+  // upsert/remove events over text/event-stream. Auth + tag-scope already
+  // resolved above and threaded through, mirroring the /notes branch.
+  if (apiPath === "/subscribe") return handleSubscribe(req, store, vaultName, tagScope);
   if (apiPath.startsWith("/tags")) return handleTags(req, store, apiPath.slice(5), tagScope);
   if (apiPath === "/find-path") return handleFindPath(req, store, tagScope);
   if (apiPath === "/vault") {
@@ -708,7 +824,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/scopes.ts

@@ -7,7 +7,7 @@
  *     VAULT_AUTH_TOKEN operator bearer, which are vault-pinned by context
  *     (the YAML key lives under a specific vault; the operator bearer is
  *     server-wide full-admin). (The `pvt_*` vault-DB token that also used
- *     this shape was dropped at 0.6.0 — vault#282 Stage 2.)
+ *     this shape was dropped at 0.5.0 — vault#282 Stage 2.)
  *   - **Narrowed** `vault:<name>:<verb>` — used by hub-issued JWTs, which are
  *     not pinned by storage and so MUST name the resource they grant access
  *     to. Hub JWTs carrying broad `vault:<verb>` are rejected at validation

package/src/server.ts

@@ -15,13 +15,14 @@
  * The request pipeline lives in ./routing.ts (exported for unit testing).
  */
 
-import { readVaultConfig, readGlobalConfig, writeGlobalConfig, writeVaultConfig, listVaults, DEFAULT_PORT, ensureConfigDirSync, loadEnvFile, generateApiKey, hashKey, stopSignalPath } from "./config.ts";
+import { readVaultConfig, readGlobalConfig, writeGlobalConfig, writeVaultConfig, listVaults, DEFAULT_PORT, ensureConfigDirSync, loadEnvFile, generateApiKey, hashKey, stopSignalPath, bootAutoCreateAllowed } from "./config.ts";
 import { existsSync, rmSync } from "fs";
 import { migrateVaultKeys } from "./token-store.ts";
-import { resolveFirstBootVaultName } from "./vault-name.ts";
+import { resolveFirstBootVaultName, reservedNameSquatWarnings } from "./vault-name.ts";
 import { getVaultStore, getVaultNameForStore } from "./vault-store.ts";
 import { defaultHookRegistry } from "../core/src/hooks.ts";
 import { registerTriggers } from "./triggers.ts";
+import { loadVaultTriggers } from "./triggers-api.ts";
 import { route } from "./routing.ts";
 import { startTranscriptionWorker, registerTranscriptionHook, type TranscriptionWorker } from "./transcription-worker.ts";
 import { setTranscriptionWorker } from "./transcription-registry.ts";
@@ -45,6 +46,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,13 +146,30 @@ 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
 // an operator-chosen name via this env var.
+//
+// Gated on the `auto_create: false` marker (2026-06-09 hub-module-boundary
+// migration): `parachute-vault remove` writes it when the operator deletes
+// their LAST vault, so an explicit empty-the-server action isn't silently
+// undone by a resurrection with fresh credentials on the next boot. Fresh
+// installs have no config.yaml — no marker — so Docker first-run still
+// auto-creates.
 if (listVaults().length === 0) {
   const globalConfig = readGlobalConfig();
-  if (!globalConfig.default_vault) {
+  if (!bootAutoCreateAllowed(globalConfig)) {
+    console.log(
+      '[vault first-boot] auto-create disabled (auto_create: false in config.yaml — the last vault was removed deliberately). Create one with: parachute-vault create <name>',
+    );
+  } else if (!globalConfig.default_vault) {
     const firstBoot = resolveFirstBootVaultName(process.env.PARACHUTE_VAULT_NAME);
     if (firstBoot.source === "env") {
       console.log(`[vault first-boot] using PARACHUTE_VAULT_NAME=${firstBoot.name}`);
@@ -197,6 +216,15 @@ if (listVaults().length === 0) {
 // survive — see self-register.ts header for the v0.6 vs v0.7 design note.
 selfRegister({ version: pkg.version });
 
+// Loud boot warning for vaults squatting a shadowed reserved name (B2 of the
+// 2026-06-09 hub-module-boundary migration). A vault named `admin`/`new`/
+// `assets` (created before the names were reserved) has its entire
+// `/vault/<name>/*` data plane shadowed by reserved hub/daemon routes — warn
+// with the recovery procedure rather than silently serving nothing.
+for (const warning of reservedNameSquatWarnings(listVaults())) {
+  console.warn(warning);
+}
+
 // Migrate tag schemas from vault.yaml → DB for each vault.
 // Only inserts schemas that don't already exist in the DB (safe across restarts).
 for (const vaultName of listVaults()) {
@@ -237,6 +265,31 @@ for (const vaultName of listVaults()) {
   }
 }
 
+// Load persisted runtime triggers for each vault and register them
+// vault-scoped on the shared hook registry (frictionless-channel-setup PR 1).
+// Runs alongside the config.yaml trigger registration above; config.yaml
+// triggers stay global, these fire only for their own vault. Survives
+// restart — the `triggers` table is the source of truth. Per-vault failure
+// is isolated so one bad vault can't block the others.
+{
+  let totalTriggers = 0;
+  for (const vaultName of listVaults()) {
+    try {
+      const store = getVaultStore(vaultName);
+      const n = loadVaultTriggers(vaultName, store);
+      totalTriggers += n;
+      if (n > 0) {
+        console.log(`[triggers] loaded ${n} runtime trigger(s) for vault "${vaultName}"`);
+      }
+    } catch (err) {
+      console.error(`[triggers] failed to load runtime triggers for vault "${vaultName}":`, err);
+    }
+  }
+  if (totalTriggers === 0) {
+    console.log("[triggers] no persisted runtime triggers");
+  }
+}
+
 const globalConfig = readGlobalConfig();
 const port = parseInt(process.env.PORT ?? "") || globalConfig.port || DEFAULT_PORT;
 const hostname = resolveBindHostname();
@@ -345,8 +398,17 @@ const server = Bun.serve({
 
     const corsHeaders = {
       "Access-Control-Allow-Origin": "*",
-      "Access-Control-Allow-Methods": "GET, POST, PATCH, DELETE, OPTIONS",
+      "Access-Control-Allow-Methods": "GET, POST, PUT, PATCH, DELETE, OPTIONS",
       "Access-Control-Allow-Headers": "Content-Type, Authorization, X-API-Key, Mcp-Session-Id",
+      // Expose response headers a BROWSER-based MCP client (e.g. claude.ai) must
+      // read cross-origin: `WWW-Authenticate` carries the RFC 9728 auth challenge
+      // (the `resource_metadata` PRM URL) the client follows to discover the auth
+      // server — without exposing it, the browser's fetch() can't see it and the
+      // OAuth flow never starts ("Couldn't register with the sign-in service").
+      // `Mcp-Session-Id` is the streamable-HTTP MCP session the client echoes
+      // back. (Claude Code is a CLI → no CORS → unaffected. The hub already
+      // exposes WWW-Authenticate; this matches it on the resource server.)
+      "Access-Control-Expose-Headers": "WWW-Authenticate, Mcp-Session-Id",
     };
 
     if (req.method === "OPTIONS") {

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);
+  });
+});