@openparachute/vault 0.2.4 → 0.3.0-rc.1

package/src/routing.test.ts

@@ -1,19 +1,17 @@
 /**
  * Tests for the HTTP routing layer (src/routing.ts).
  *
- * Two surfaces under test here:
+ * The server exposes four root-level endpoints and everything else under
+ * `/vault/<name>/...`. These tests pin the dispatcher's behaviour:
  *
- *  1. `/vaults/list` — public, unauthenticated discovery endpoint.
- *     Intended for the Daily vault-picker dropdown pre-OAuth.
- *     Must never leak anything beyond vault names; must return 404 when
- *     the operator disables discovery in config.yaml.
+ *  1. `/vaults/list` — public, unauthenticated discovery. Returns vault
+ *     names only, 404 when operator disables discovery.
+ *  2. `/vaults` — authenticated metadata listing.
+ *  3. `/vault/<name>/...` — per-vault routing (OAuth, MCP, view, API).
+ *  4. The RFC 9728 WWW-Authenticate challenge that decorates MCP 401s.
  *
- *  2. Single-vault auto-default. A user with exactly one vault (named
- *     anything — not necessarily "default") should be able to hit unscoped
- *     routes (/mcp, /api/*, /oauth/*) and have them transparently target
- *     their sole vault. Previously `/mcp` tried to look up a vault literally
- *     named "default" and failed. The coherence invariant from PR #111 says
- *     `/mcp` and `/vaults/:name/mcp` must behave identically for that vault.
+ * No unscoped `/mcp`, `/api/*`, `/oauth/*` routes exist — every per-vault
+ * resource must name the vault it targets.
  *
  * Uses PARACHUTE_HOME override so each test's vaults live in a tmp dir and
  * never touch ~/.parachute.
@@ -42,7 +40,8 @@ const {
 // clearVaultStoreCache was added in #111 for exactly this kind of test
 // that wipes its PARACHUTE_HOME between runs — it closes stores silently
 // even when the DB files are already gone.
-const { clearVaultStoreCache } = await import("./vault-store.ts");
+const { clearVaultStoreCache, getVaultStore } = await import("./vault-store.ts");
+const { generateToken, createToken } = await import("./token-store.ts");
 
 function createVault(name: string, description?: string): void {
   writeVaultConfig({
@@ -53,11 +52,26 @@ function createVault(name: string, description?: string): void {
   });
 }
 
+/**
+ * Mint an admin-scoped token for `vaultName` and return its bearer value.
+ * Used by tests that hit admin-gated endpoints (e.g. /.parachute/config).
+ */
+function createAdminToken(vaultName: string): string {
+  const store = getVaultStore(vaultName);
+  const { fullToken } = generateToken();
+  createToken(store.db, fullToken, {
+    label: "test-admin",
+    permission: "full",
+    scopes: ["vault:read", "vault:write", "vault:admin"],
+  });
+  return fullToken;
+}
+
 function reset(): void {
   clearVaultStoreCache();
   if (existsSync(testDir)) rmSync(testDir, { recursive: true, force: true });
   mkdirSync(testDir, { recursive: true });
-  mkdirSync(join(testDir, "vaults"), { recursive: true });
+  mkdirSync(join(testDir, "vault", "data"), { recursive: true });
   writeGlobalConfig({ port: 1940 });
 }
 
@@ -71,7 +85,8 @@ afterAll(() => {
 });
 
 // ---------------------------------------------------------------------------
-// resolveDefaultVault — the function that powers every "unscoped" route.
+// resolveDefaultVault — used by the CLI to pick the vault to wire into
+// `~/.claude.json`, not on the request path (which is always scoped).
 // ---------------------------------------------------------------------------
 
 describe("resolveDefaultVault", () => {
@@ -84,13 +99,10 @@ describe("resolveDefaultVault", () => {
 
   test("returns the sole vault when default_vault is unset", () => {
     createVault("journal");
-    // No default_vault in global config.
     expect(resolveDefaultVault()).toBe("journal");
   });
 
   test("returns the sole vault even if default_vault points to a deleted one", () => {
-    // Simulates: user had two vaults, removed the one that was the default,
-    // but config.yaml still references the old name.
     createVault("journal");
     writeGlobalConfig({ port: 1940, default_vault: "deleted-vault" });
     expect(resolveDefaultVault()).toBe("journal");
@@ -107,19 +119,16 @@ describe("resolveDefaultVault", () => {
     expect(resolveDefaultVault()).toBeNull();
   });
 
-  test("does not special-case the name 'default' — a vault named 'journal' alone is the default", () => {
-    // This is the Aaron-acked bug: having to go to /vaults/journal/mcp
-    // when it's the only vault was confusing. Now the name doesn't matter.
+  test("does not special-case the name 'default'", () => {
     createVault("journal");
     expect(resolveDefaultVault()).toBe("journal");
     expect(listVaults()).toEqual(["journal"]);
-    // And explicitly: "default" is NOT synthesized when it doesn't exist.
     expect(resolveDefaultVault()).not.toBe("default");
   });
 });
 
 // ---------------------------------------------------------------------------
-// /vaults/list — Task 1: public discovery endpoint for the Daily picker.
+// /vaults/list — public discovery endpoint for the Daily picker.
 // ---------------------------------------------------------------------------
 
 describe("GET /vaults/list (public discovery)", () => {
@@ -183,8 +192,6 @@ describe("GET /vaults/list (public discovery)", () => {
   });
 
   test("ignores Authorization header (endpoint is public)", async () => {
-    // Even with an obviously-wrong token, the endpoint must still succeed.
-    // This catches a regression where we'd accidentally gate it behind auth.
     createVault("journal");
     const req = new Request("http://localhost:1940/vaults/list", {
       headers: { Authorization: "Bearer not-a-real-token" },
@@ -193,25 +200,16 @@ describe("GET /vaults/list (public discovery)", () => {
     expect(res.status).toBe(200);
   });
 
-  test("rejects non-GET methods (falls through to vault-scoped 404 path)", async () => {
-    // Non-GET methods on /vaults/list fall through to the /vaults/:name
-    // matcher with name="list". Since no vault named "list" can exist
-    // (reserved name), we get a 404. This is the expected behavior —
-    // the endpoint is GET-only.
+  test("rejects non-GET methods (falls through to 404)", async () => {
     createVault("journal");
     const req = new Request("http://localhost:1940/vaults/list", { method: "POST" });
     const res = await route(req, "/vaults/list");
     expect(res.status).toBe(404);
   });
 
-  test("discovery disabled still allows authenticated /vaults listing (they are separate concerns)", async () => {
-    // /vaults (authenticated, with metadata) is orthogonal to /vaults/list
-    // (public, names only). Disabling discovery hides the public endpoint
-    // but not the authenticated one.
+  test("discovery disabled still allows authenticated /vaults listing (separate concerns)", async () => {
     createVault("journal");
     writeGlobalConfig({ port: 1940, discovery: "disabled" });
-    // We can at least assert that /vaults still returns 401 (auth required)
-    // rather than 404 (disabled). Past that, auth is covered elsewhere.
     const req = new Request("http://localhost:1940/vaults");
     const res = await route(req, "/vaults");
     expect(res.status).toBe(401);
@@ -219,131 +217,69 @@ describe("GET /vaults/list (public discovery)", () => {
 });
 
 // ---------------------------------------------------------------------------
-// Single-vault auto-default — Task 2: /mcp, /api/*, /oauth/* target the
-// only vault regardless of its name.
+// Per-vault routing: /vault/<name>/... is the only URL shape for vault
+// resources. Unscoped routes (/mcp, /api/*, /oauth/*) no longer exist.
 // ---------------------------------------------------------------------------
 
-describe("single-vault auto-default", () => {
-  test("one vault named 'journal' → /mcp requires auth (would error if vault not resolvable)", async () => {
-    // With one vault named "journal" and no default_vault set, /mcp must
-    // still hit the MCP handler. The handler itself requires a valid
-    // Bearer token — we assert 401 (auth failure), proving the request
-    // reached the MCP layer and did NOT bail out with "Default vault not
-    // found". Before this fix, /mcp would error because the code
-    // hardcoded the fallback name "default".
-    createVault("journal");
-    // Deliberately no default_vault — single-vault fallback should kick in.
-    const req = new Request("http://localhost:1940/mcp");
-    const res = await route(req, "/mcp");
+describe("per-vault routing under /vault/<name>/", () => {
+  test("/vault/<name>/mcp reaches the MCP handler (401 unauthenticated)", async () => {
+    createVault("journal");
+    const path = "/vault/journal/mcp";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
     expect(res.status).toBe(401);
   });
 
-  test("one vault named 'journal' → /api/notes reaches auth (not 404'd)", async () => {
+  test("/vault/<name>/api/notes reaches per-vault auth (401 unauthenticated)", async () => {
     createVault("journal");
-    const req = new Request("http://localhost:1940/api/notes");
-    const res = await route(req, "/api/notes");
-    // Unauthenticated: 401 from per-vault auth. Before the fix, it would
-    // have 404'd with "Default vault not found".
+    const path = "/vault/journal/api/notes";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
     expect(res.status).toBe(401);
   });
 
-  test("one vault named 'journal' → /oauth/register reaches the OAuth handler (not 500'd)", async () => {
+  test("/vault/<name>/oauth/register reaches the OAuth handler", async () => {
     createVault("journal");
-    const req = new Request("http://localhost:1940/oauth/register", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ client_name: "test", redirect_uris: ["https://x.example/cb"] }),
-    });
-    const res = await route(req, "/oauth/register");
-    // Successful registration (201) or 400 from a validation issue —
-    // either way, we're PAST the "Default vault not configured" path.
+    const path = "/vault/journal/oauth/register";
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ client_name: "test", redirect_uris: ["https://x.example/cb"] }),
+      }),
+      path,
+    );
     expect(res.status).not.toBe(500);
     expect([201, 400]).toContain(res.status);
   });
 
-  test("one vault named 'journal' → /vaults/journal/mcp still works identically (coherence invariant)", async () => {
-    // This is the invariant from PR #111: the scoped and unscoped MCP paths
-    // must behave identically for a single-vault deployment. Both should
-    // land on the MCP auth gate and return 401 unauthenticated.
+  test("unknown vault returns 404 before hitting auth", async () => {
     createVault("journal");
-    const unscopedReq = new Request("http://localhost:1940/mcp");
-    const unscopedRes = await route(unscopedReq, "/mcp");
-    const scopedReq = new Request("http://localhost:1940/vaults/journal/mcp");
-    const scopedRes = await route(scopedReq, "/vaults/journal/mcp");
-    expect(unscopedRes.status).toBe(scopedRes.status);
-    expect(unscopedRes.status).toBe(401);
+    for (const path of [
+      "/vault/nonexistent/mcp",
+      "/vault/nonexistent/api/notes",
+      "/vault/nonexistent/oauth/register",
+    ]) {
+      const res = await route(new Request(`http://localhost:1940${path}`), path);
+      expect(res.status).toBe(404);
+      const body = (await res.json()) as { error: string };
+      expect(body.error).toBe("Vault not found");
+    }
   });
 
-  test("multiple vaults, no default_vault → /mcp returns a clear error, not a silent guess", async () => {
-    createVault("journal");
-    createVault("work");
-    // No default_vault set.
-    const req = new Request("http://localhost:1940/mcp");
-    const res = await route(req, "/mcp");
-    // We refuse to guess when multiple vaults exist. Hitting /mcp here
-    // must NOT silently target one of them. We expect a non-200 status
-    // that is not the auth gate (since resolveDefaultVault returns null,
-    // we return 401 because auth runs first, but the underlying MCP
-    // handler never runs — the previous test guarantees that). For the
-    // /api/ path, which checks the vault before auth, we get 404.
-    const apiReq = new Request("http://localhost:1940/api/notes");
-    const apiRes = await route(apiReq, "/api/notes");
-    expect(apiRes.status).toBe(404);
-  });
-
-  test("multiple vaults, default_vault='journal' → /api/notes targets journal", async () => {
+  test("no /mcp, /api, /oauth unscoped routes — all 404", async () => {
     createVault("journal");
-    createVault("work");
-    writeGlobalConfig({ port: 1940, default_vault: "journal" });
-    const req = new Request("http://localhost:1940/api/notes");
-    const res = await route(req, "/api/notes");
-    // Reaches auth (401) rather than "Default vault not found" (404).
-    expect(res.status).toBe(401);
+    for (const path of ["/mcp", "/api/notes", "/oauth/register", "/oauth/authorize"]) {
+      const res = await route(new Request(`http://localhost:1940${path}`), path);
+      expect(res.status).toBe(404);
+    }
   });
 
-  test("default_vault points to a deleted vault but one other exists → fall back to the survivor", async () => {
-    createVault("journal");
-    writeGlobalConfig({ port: 1940, default_vault: "deleted-vault" });
-    // resolveDefaultVault ignores the stale pointer and returns journal.
-    expect(resolveDefaultVault()).toBe("journal");
-    // And /api/notes now routes to it — 401 from per-vault auth, not 404.
-    const req = new Request("http://localhost:1940/api/notes");
-    const res = await route(req, "/api/notes");
+  test("bare /vault/<name> returns metadata for authenticated callers", async () => {
+    createVault("journal", "My journal vault");
+    const path = "/vault/journal";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    // No auth → 401 from per-vault auth gate.
     expect(res.status).toBe(401);
   });
-
-  test("default_vault points to a deleted vault and multiple others exist → error (no guessing)", async () => {
-    createVault("journal");
-    createVault("work");
-    writeGlobalConfig({ port: 1940, default_vault: "deleted-vault" });
-    expect(resolveDefaultVault()).toBeNull();
-    const req = new Request("http://localhost:1940/api/notes");
-    const res = await route(req, "/api/notes");
-    expect(res.status).toBe(404);
-  });
-
-  test("no vaults exist → /mcp returns auth error (MCP handler short-circuits on empty global config)", async () => {
-    // Edge case: /mcp runs global auth first. With no vaults and no keys,
-    // auth fails → 401. This is fine — the handler never sees the empty
-    // state. We assert we never return 500.
-    const req = new Request("http://localhost:1940/mcp");
-    const res = await route(req, "/mcp");
-    expect(res.status).not.toBe(500);
-  });
-
-  test("empty config file (no default_vault) with single vault — existing deployments keep working", async () => {
-    // Migration concern: users with a config.yaml that never had
-    // default_vault set (pre-#111 deployments) should not break.
-    // Drop a minimal config.yaml that only specifies port.
-    writeGlobalConfig({ port: 1940 });
-    createVault("my-only-vault");
-    const cfg = readGlobalConfig();
-    expect(cfg.default_vault).toBeUndefined();
-    // /api/notes still routes to my-only-vault via single-vault fallback.
-    const req = new Request("http://localhost:1940/api/notes");
-    const res = await route(req, "/api/notes");
-    expect(res.status).toBe(401); // reached per-vault auth
-  });
 });
 
 // ---------------------------------------------------------------------------
@@ -352,104 +288,60 @@ describe("single-vault auto-default", () => {
 // Claude Code's MCP SDK (and any other strict RFC 9728 client) requires the
 // server to emit `WWW-Authenticate: Bearer resource_metadata="..."` on 401
 // so the client knows which protected-resource metadata document applies to
-// the endpoint it just hit. Without it, clients fall back to probing the
-// root `/.well-known/oauth-protected-resource`, get `resource: <base>/mcp`,
-// and reject any connection to `/vaults/<name>/mcp` as a resource mismatch.
+// the endpoint it just hit.
 // ---------------------------------------------------------------------------
 
 describe("MCP 401 WWW-Authenticate challenge (RFC 9728)", () => {
-  test("unscoped /mcp 401 carries the root protected-resource pointer", async () => {
+  test("/vault/<name>/mcp 401 carries the vault-scoped pointer", async () => {
     createVault("journal");
-    const req = new Request("http://localhost:1940/mcp");
-    const res = await route(req, "/mcp");
-    expect(res.status).toBe(401);
-    const header = res.headers.get("WWW-Authenticate");
-    expect(header).toBe(
-      'Bearer resource_metadata="http://localhost:1940/.well-known/oauth-protected-resource"',
-    );
-  });
-
-  test("scoped /vaults/{name}/mcp 401 carries the vault-scoped pointer", async () => {
-    createVault("journal");
-    const req = new Request("http://localhost:1940/vaults/journal/mcp");
-    const res = await route(req, "/vaults/journal/mcp");
+    const path = "/vault/journal/mcp";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
     expect(res.status).toBe(401);
     const header = res.headers.get("WWW-Authenticate");
     expect(header).toBe(
-      'Bearer resource_metadata="http://localhost:1940/vaults/journal/.well-known/oauth-protected-resource"',
+      'Bearer resource_metadata="http://localhost:1940/vault/journal/.well-known/oauth-protected-resource"',
     );
   });
 
-  test("challenge points at the same PRM document the server actually serves", async () => {
+  test("challenge points at the PRM document the server actually serves", async () => {
     // Belt-and-braces: whatever we advertise in the header MUST line up with
     // what `/.well-known/oauth-protected-resource` actually returns. If these
     // drift, a conforming client will chase the pointer, fetch the PRM, then
-    // reject on resource mismatch anyway. Test both directions.
+    // reject on resource mismatch anyway.
     createVault("journal");
 
-    // Scoped: header points at /vaults/journal/.well-known/...
-    const scopedReq = new Request("http://localhost:1940/vaults/journal/mcp");
-    const scopedRes = await route(scopedReq, "/vaults/journal/mcp");
-    const scopedHeader = scopedRes.headers.get("WWW-Authenticate")!;
-    const scopedPrmUrl = scopedHeader.match(/resource_metadata="([^"]+)"/)![1];
-    // Fetch that PRM. Bypass the full URL by extracting the path.
-    const prmPath = new URL(scopedPrmUrl).pathname;
+    const mcpPath = "/vault/journal/mcp";
+    const mcpRes = await route(new Request(`http://localhost:1940${mcpPath}`), mcpPath);
+    const header = mcpRes.headers.get("WWW-Authenticate")!;
+    const prmUrl = header.match(/resource_metadata="([^"]+)"/)![1];
+    const prmPath = new URL(prmUrl).pathname;
     const prmRes = await route(new Request(`http://localhost:1940${prmPath}`), prmPath);
     expect(prmRes.status).toBe(200);
     const prm = (await prmRes.json()) as { resource: string };
-    expect(prm.resource).toBe("http://localhost:1940/vaults/journal/mcp");
-
-    // Unscoped: header points at root /.well-known/...
-    const unscopedReq = new Request("http://localhost:1940/mcp");
-    const unscopedRes = await route(unscopedReq, "/mcp");
-    const unscopedHeader = unscopedRes.headers.get("WWW-Authenticate")!;
-    const unscopedPrmUrl = unscopedHeader.match(/resource_metadata="([^"]+)"/)![1];
-    const unscopedPrmPath = new URL(unscopedPrmUrl).pathname;
-    const unscopedPrmRes = await route(
-      new Request(`http://localhost:1940${unscopedPrmPath}`),
-      unscopedPrmPath,
-    );
-    expect(unscopedPrmRes.status).toBe(200);
-    const unscopedPrm = (await unscopedPrmRes.json()) as { resource: string };
-    expect(unscopedPrm.resource).toBe("http://localhost:1940/mcp");
+    expect(prm.resource).toBe("http://localhost:1940/vault/journal/mcp");
   });
 
   test("MCP 401 with invalid token still carries the challenge", async () => {
-    // The no-token case is one 401 code path (extractApiKey returns null);
-    // the invalid-token case is another (extractApiKey returns a string but
-    // resolveToken / validateKey all fail). Both must emit the header.
     createVault("journal");
-    const req = new Request("http://localhost:1940/vaults/journal/mcp", {
+    const path = "/vault/journal/mcp";
+    const req = new Request(`http://localhost:1940${path}`, {
       headers: { Authorization: "Bearer pvt_not-a-real-token" },
     });
-    const res = await route(req, "/vaults/journal/mcp");
+    const res = await route(req, path);
     expect(res.status).toBe(401);
     expect(res.headers.get("WWW-Authenticate")).toBe(
-      'Bearer resource_metadata="http://localhost:1940/vaults/journal/.well-known/oauth-protected-resource"',
+      'Bearer resource_metadata="http://localhost:1940/vault/journal/.well-known/oauth-protected-resource"',
     );
   });
 
   test("non-MCP 401s do NOT carry the challenge (spec is MCP-only)", async () => {
-    // The RFC 9728 challenge header is specific to the MCP resource; plain
-    // REST endpoints are not OAuth resources in the same sense. A spurious
-    // challenge here could confuse non-MCP clients and makes the /api
-    // surface look OAuth-gated when it is not.
-    createVault("journal");
-
-    // /api/notes (unscoped) — 401, no challenge.
-    const unscopedApi = await route(new Request("http://localhost:1940/api/notes"), "/api/notes");
-    expect(unscopedApi.status).toBe(401);
-    expect(unscopedApi.headers.get("WWW-Authenticate")).toBeNull();
-
-    // /vaults/journal/api/notes (scoped) — 401, no challenge. This is the
-    // code path that shares the auth check with the scoped MCP branch, so
-    // if we leak the header here the isScopedMcp gate has regressed.
-    const scopedApi = await route(
-      new Request("http://localhost:1940/vaults/journal/api/notes"),
-      "/vaults/journal/api/notes",
-    );
-    expect(scopedApi.status).toBe(401);
-    expect(scopedApi.headers.get("WWW-Authenticate")).toBeNull();
+    createVault("journal");
+
+    // /vault/journal/api/notes — 401, no challenge.
+    const apiPath = "/vault/journal/api/notes";
+    const apiRes = await route(new Request(`http://localhost:1940${apiPath}`), apiPath);
+    expect(apiRes.status).toBe(401);
+    expect(apiRes.headers.get("WWW-Authenticate")).toBeNull();
 
     // /vaults (authenticated listing) — 401, no challenge.
     const vaultsList = await route(new Request("http://localhost:1940/vaults"), "/vaults");
@@ -460,40 +352,37 @@ describe("MCP 401 WWW-Authenticate challenge (RFC 9728)", () => {
   test("x-forwarded-host and x-forwarded-proto shape the challenge URL", async () => {
     // Remote deployments behind Cloudflare Tunnel / Tailscale Funnel / any
     // reverse proxy need the challenge URL to match the external origin,
-    // not the 127.0.0.1:1940 the server actually binds. Parallels how the
-    // /.well-known/* endpoints already honor these headers.
+    // not the 127.0.0.1:1940 the server actually binds.
     createVault("journal");
-    const req = new Request("http://127.0.0.1:1940/vaults/journal/mcp", {
+    const path = "/vault/journal/mcp";
+    const req = new Request(`http://127.0.0.1:1940${path}`, {
       headers: {
         "x-forwarded-host": "vault.example.com",
         "x-forwarded-proto": "https",
       },
     });
-    const res = await route(req, "/vaults/journal/mcp");
+    const res = await route(req, path);
     expect(res.status).toBe(401);
     expect(res.headers.get("WWW-Authenticate")).toBe(
-      'Bearer resource_metadata="https://vault.example.com/vaults/journal/.well-known/oauth-protected-resource"',
+      'Bearer resource_metadata="https://vault.example.com/vault/journal/.well-known/oauth-protected-resource"',
     );
   });
 });
 
 // ---------------------------------------------------------------------------
-// RFC 8414 §3.1 / RFC 9728 §3 path-insertion discovery.
+// Per-vault OAuth discovery (RFC 8414 / RFC 9728, path-append form).
 //
-// For a resource at `/vaults/<name>/mcp`, the spec-mandated metadata URLs are
-//   /.well-known/oauth-authorization-server/vaults/<name>[/mcp]
-//   /.well-known/oauth-protected-resource/vaults/<name>[/mcp]
-// rather than the path-append form
-//   /vaults/<name>/.well-known/<type>
-// that PR #111 also ships. Strict clients (including Claude Code's MCP OAuth
-// SDK) probe only the path-insertion form; lax clients try path-append. We
-// serve both so any conformant probe hits a live endpoint.
+// For a resource at `/vault/<name>/mcp`, clients fetch metadata from
+//   /vault/<name>/.well-known/oauth-protected-resource
+//   /vault/<name>/.well-known/oauth-authorization-server
+// All endpoints in the AS metadata are vault-scoped so a client that
+// discovers the AS at that URL can drive the full authorization flow.
 // ---------------------------------------------------------------------------
 
-describe("path-insertion OAuth discovery (RFC 8414 §3.1 / RFC 9728 §3)", () => {
-  test("/.well-known/oauth-authorization-server/vaults/<name> returns vault-scoped AS metadata", async () => {
+describe("per-vault OAuth discovery", () => {
+  test("/vault/<name>/.well-known/oauth-authorization-server returns vault-scoped AS metadata", async () => {
     createVault("journal");
-    const path = "/.well-known/oauth-authorization-server/vaults/journal";
+    const path = "/vault/journal/.well-known/oauth-authorization-server";
     const res = await route(new Request(`http://localhost:1940${path}`), path);
     expect(res.status).toBe(200);
     const body = (await res.json()) as {
@@ -502,90 +391,207 @@ describe("path-insertion OAuth discovery (RFC 8414 §3.1 / RFC 9728 §3)", () =>
       token_endpoint: string;
       registration_endpoint: string;
     };
-    // All four endpoints must be vault-scoped — otherwise Claude Code's
-    // registration_endpoint falls back to root `/register` and cascades 404.
-    expect(body.issuer).toBe("http://localhost:1940/vaults/journal");
-    expect(body.authorization_endpoint).toBe("http://localhost:1940/vaults/journal/oauth/authorize");
-    expect(body.token_endpoint).toBe("http://localhost:1940/vaults/journal/oauth/token");
-    expect(body.registration_endpoint).toBe("http://localhost:1940/vaults/journal/oauth/register");
+    expect(body.issuer).toBe("http://localhost:1940/vault/journal");
+    expect(body.authorization_endpoint).toBe("http://localhost:1940/vault/journal/oauth/authorize");
+    expect(body.token_endpoint).toBe("http://localhost:1940/vault/journal/oauth/token");
+    expect(body.registration_endpoint).toBe("http://localhost:1940/vault/journal/oauth/register");
   });
 
-  test("/.well-known/oauth-authorization-server/vaults/<name>/mcp (longer form) also returns AS metadata", async () => {
-    // Aaron's log shows Claude Code probes this longer form too; cheap to
-    // support since it resolves to the same AS for the same vault.
+  test("/vault/<name>/.well-known/oauth-protected-resource returns vault-scoped PRM", async () => {
     createVault("journal");
-    const path = "/.well-known/oauth-authorization-server/vaults/journal/mcp";
+    const path = "/vault/journal/.well-known/oauth-protected-resource";
     const res = await route(new Request(`http://localhost:1940${path}`), path);
     expect(res.status).toBe(200);
+    const body = (await res.json()) as { resource: string; authorization_servers: string[] };
+    expect(body.resource).toBe("http://localhost:1940/vault/journal/mcp");
+    expect(body.authorization_servers).toEqual(["http://localhost:1940/vault/journal"]);
+  });
+
+  test("unknown vault returns 404 rather than boilerplate metadata", async () => {
+    createVault("journal");
+    for (const path of [
+      "/vault/nonexistent/.well-known/oauth-authorization-server",
+      "/vault/nonexistent/.well-known/oauth-protected-resource",
+    ]) {
+      const res = await route(new Request(`http://localhost:1940${path}`), path);
+      expect(res.status).toBe(404);
+    }
+  });
+
+  test("x-forwarded-* headers propagate into the generated metadata URLs", async () => {
+    createVault("journal");
+    const path = "/vault/journal/.well-known/oauth-authorization-server";
+    const res = await route(
+      new Request(`http://127.0.0.1:1940${path}`, {
+        headers: {
+          "x-forwarded-host": "vault.example.com",
+          "x-forwarded-proto": "https",
+        },
+      }),
+      path,
+    );
+    expect(res.status).toBe(200);
     const body = (await res.json()) as { issuer: string; registration_endpoint: string };
-    expect(body.issuer).toBe("http://localhost:1940/vaults/journal");
-    expect(body.registration_endpoint).toBe("http://localhost:1940/vaults/journal/oauth/register");
+    expect(body.issuer).toBe("https://vault.example.com/vault/journal");
+    expect(body.registration_endpoint).toBe(
+      "https://vault.example.com/vault/journal/oauth/register",
+    );
+  });
+
+  test("end-to-end flow: WWW-Authenticate → PRM → AS metadata → registration_endpoint is live", async () => {
+    // On 401, follow the challenge to the PRM, then follow
+    // PRM.authorization_servers[0] to the AS metadata, then hit the
+    // `registration_endpoint`. Every hop must resolve.
+    createVault("journal");
+
+    // Step 1: unauthenticated MCP → 401 + WWW-Authenticate.
+    const mcpPath = "/vault/journal/mcp";
+    const mcpRes = await route(new Request(`http://localhost:1940${mcpPath}`), mcpPath);
+    expect(mcpRes.status).toBe(401);
+    const challenge = mcpRes.headers.get("WWW-Authenticate")!;
+    const prmUrl = challenge.match(/resource_metadata="([^"]+)"/)![1];
+
+    // Step 2: fetch PRM.
+    const prmPath = new URL(prmUrl).pathname;
+    const prmRes = await route(new Request(`http://localhost:1940${prmPath}`), prmPath);
+    expect(prmRes.status).toBe(200);
+    const prm = (await prmRes.json()) as { authorization_servers: string[] };
+    const asBase = prm.authorization_servers[0]; // "http://localhost:1940/vault/journal"
+
+    // Step 3: AS metadata lives at `{asBase}/.well-known/oauth-authorization-server`.
+    const asBasePath = new URL(asBase).pathname; // "/vault/journal"
+    const asMetaPath = `${asBasePath}/.well-known/oauth-authorization-server`;
+    const asRes = await route(new Request(`http://localhost:1940${asMetaPath}`), asMetaPath);
+    expect(asRes.status).toBe(200);
+    const asMeta = (await asRes.json()) as { registration_endpoint: string };
+
+    // Step 4: the advertised registration_endpoint must be live.
+    const regPath = new URL(asMeta.registration_endpoint).pathname;
+    const regRes = await route(
+      new Request(`http://localhost:1940${regPath}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          client_name: "Test",
+          redirect_uris: ["https://example.com/cb"],
+        }),
+      }),
+      regPath,
+    );
+    expect(regRes.status).toBe(201);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// RFC 8414 §3.1 / RFC 9728 §3 path-insertion discovery URLs.
+//
+// For a resource at `/vault/<name>/mcp`, conformant clients (including
+// Claude Code's MCP OAuth SDK) probe metadata at
+//
+//   /.well-known/oauth-authorization-server/vault/<name>[/mcp]
+//   /.well-known/oauth-protected-resource/vault/<name>[/mcp]
+//
+// These routes MUST return the same document as the path-append form —
+// otherwise mixed-toolchain clients see drifted metadata. Coherence check
+// below asserts deep equality.
+// ---------------------------------------------------------------------------
+
+describe("OAuth discovery (RFC 8414/9728 path-insertion form)", () => {
+  test("AS metadata at path-insertion short form returns vault-scoped endpoints", async () => {
+    createVault("journal");
+    const path = "/.well-known/oauth-authorization-server/vault/journal";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      issuer: string;
+      authorization_endpoint: string;
+      token_endpoint: string;
+      registration_endpoint: string;
+    };
+    expect(body.issuer).toBe("http://localhost:1940/vault/journal");
+    expect(body.authorization_endpoint).toBe("http://localhost:1940/vault/journal/oauth/authorize");
+    expect(body.token_endpoint).toBe("http://localhost:1940/vault/journal/oauth/token");
+    expect(body.registration_endpoint).toBe("http://localhost:1940/vault/journal/oauth/register");
   });
 
-  test("/.well-known/oauth-protected-resource/vaults/<name> returns vault-scoped PRM", async () => {
+  test("AS metadata at path-insertion long form (/mcp suffix) also works", async () => {
+    // Some SDKs probe with the exact resource path appended. The optional
+    // `/mcp` suffix covers that.
     createVault("journal");
-    const path = "/.well-known/oauth-protected-resource/vaults/journal";
+    const path = "/.well-known/oauth-authorization-server/vault/journal/mcp";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { issuer: string };
+    expect(body.issuer).toBe("http://localhost:1940/vault/journal");
+  });
+
+  test("PRM at path-insertion short form returns vault-scoped resource", async () => {
+    createVault("journal");
+    const path = "/.well-known/oauth-protected-resource/vault/journal";
     const res = await route(new Request(`http://localhost:1940${path}`), path);
     expect(res.status).toBe(200);
     const body = (await res.json()) as { resource: string; authorization_servers: string[] };
-    expect(body.resource).toBe("http://localhost:1940/vaults/journal/mcp");
-    expect(body.authorization_servers).toEqual(["http://localhost:1940/vaults/journal"]);
+    expect(body.resource).toBe("http://localhost:1940/vault/journal/mcp");
+    expect(body.authorization_servers).toEqual(["http://localhost:1940/vault/journal"]);
   });
 
-  test("/.well-known/oauth-protected-resource/vaults/<name>/mcp (longer form) also returns PRM", async () => {
+  test("PRM at path-insertion long form (/mcp suffix) also works", async () => {
     createVault("journal");
-    const path = "/.well-known/oauth-protected-resource/vaults/journal/mcp";
+    const path = "/.well-known/oauth-protected-resource/vault/journal/mcp";
     const res = await route(new Request(`http://localhost:1940${path}`), path);
     expect(res.status).toBe(200);
     const body = (await res.json()) as { resource: string };
-    expect(body.resource).toBe("http://localhost:1940/vaults/journal/mcp");
+    expect(body.resource).toBe("http://localhost:1940/vault/journal/mcp");
   });
 
-  test("path-insertion and path-append forms return identical metadata", async () => {
-    // The coherence guarantee: a client that follows either spec shape MUST
-    // land on the same AS config. If these drift, a mixed-toolchain deploy
-    // (CLI using one form, daemon using the other) would mint tokens
-    // against inconsistent endpoints.
+  test("path-insertion and path-append forms return deep-equal JSON (coherence)", async () => {
+    // Belt-and-braces: a client that probes one form and validates against
+    // the other (or a proxy that caches based on URL) must see identical
+    // bytes. If these drift, strict/lax clients will disagree on reality.
     createVault("journal");
+    const asPaths = [
+      "/.well-known/oauth-authorization-server/vault/journal",
+      "/vault/journal/.well-known/oauth-authorization-server",
+    ];
+    const [asInsert, asAppend] = await Promise.all(
+      asPaths.map(async (p) => {
+        const r = await route(new Request(`http://localhost:1940${p}`), p);
+        return r.json();
+      }),
+    );
+    expect(asInsert).toEqual(asAppend);
 
-    // AS metadata
-    const insertAsPath = "/.well-known/oauth-authorization-server/vaults/journal";
-    const appendAsPath = "/vaults/journal/.well-known/oauth-authorization-server";
-    const insertAsRes = await route(new Request(`http://localhost:1940${insertAsPath}`), insertAsPath);
-    const appendAsRes = await route(new Request(`http://localhost:1940${appendAsPath}`), appendAsPath);
-    expect(await insertAsRes.json()).toEqual(await appendAsRes.json());
-
-    // PRM
-    const insertPrmPath = "/.well-known/oauth-protected-resource/vaults/journal";
-    const appendPrmPath = "/vaults/journal/.well-known/oauth-protected-resource";
-    const insertPrmRes = await route(new Request(`http://localhost:1940${insertPrmPath}`), insertPrmPath);
-    const appendPrmRes = await route(new Request(`http://localhost:1940${appendPrmPath}`), appendPrmPath);
-    expect(await insertPrmRes.json()).toEqual(await appendPrmRes.json());
+    const prmPaths = [
+      "/.well-known/oauth-protected-resource/vault/journal",
+      "/vault/journal/.well-known/oauth-protected-resource",
+    ];
+    const [prmInsert, prmAppend] = await Promise.all(
+      prmPaths.map(async (p) => {
+        const r = await route(new Request(`http://localhost:1940${p}`), p);
+        return r.json();
+      }),
+    );
+    expect(prmInsert).toEqual(prmAppend);
   });
 
-  test("unknown vault in path-insertion URL returns 404, not boilerplate metadata", async () => {
-    // Don't leak metadata for phantom vaults. The equivalent path-append
-    // route also 404s when the vault doesn't exist (`readVaultConfig` miss
-    // at the vault-scoped routes branch); path-insertion must match.
+  test("unknown vault → 404 on all four path-insertion shapes (no phantom metadata)", async () => {
     createVault("journal");
     for (const path of [
-      "/.well-known/oauth-authorization-server/vaults/nonexistent",
-      "/.well-known/oauth-authorization-server/vaults/nonexistent/mcp",
-      "/.well-known/oauth-protected-resource/vaults/nonexistent",
-      "/.well-known/oauth-protected-resource/vaults/nonexistent/mcp",
+      "/.well-known/oauth-authorization-server/vault/nonexistent",
+      "/.well-known/oauth-authorization-server/vault/nonexistent/mcp",
+      "/.well-known/oauth-protected-resource/vault/nonexistent",
+      "/.well-known/oauth-protected-resource/vault/nonexistent/mcp",
     ]) {
       const res = await route(new Request(`http://localhost:1940${path}`), path);
       expect(res.status).toBe(404);
+      const body = (await res.json()) as { error: string };
+      expect(body.error).toBe("Vault not found");
     }
   });
 
-  test("x-forwarded-* headers propagate into the generated metadata URLs", async () => {
-    // Same contract as the WWW-Authenticate challenge and the root/append
-    // discovery endpoints: metadata must match the public-facing origin so
-    // a Cloudflare Tunnel / Tailscale Funnel deployment doesn't advertise
-    // internal localhost:1940 URLs.
+  test("x-forwarded-* headers propagate through path-insertion URLs", async () => {
     createVault("journal");
-    const path = "/.well-known/oauth-authorization-server/vaults/journal";
+    const path = "/.well-known/oauth-authorization-server/vault/journal";
     const res = await route(
       new Request(`http://127.0.0.1:1940${path}`, {
         headers: {
@@ -597,52 +603,49 @@ describe("path-insertion OAuth discovery (RFC 8414 §3.1 / RFC 9728 §3)", () =>
     );
     expect(res.status).toBe(200);
     const body = (await res.json()) as { issuer: string; registration_endpoint: string };
-    expect(body.issuer).toBe("https://vault.example.com/vaults/journal");
+    expect(body.issuer).toBe("https://vault.example.com/vault/journal");
     expect(body.registration_endpoint).toBe(
-      "https://vault.example.com/vaults/journal/oauth/register",
+      "https://vault.example.com/vault/journal/oauth/register",
     );
   });
 
-  test("end-to-end flow: WWW-Authenticate → PRM → AS metadata → registration_endpoint is live", async () => {
-    // The actual Claude-Code bug: on 401, follow the challenge to the PRM,
-    // then follow PRM.authorization_servers[0] to the AS metadata (via
-    // path-insertion), then hit the `registration_endpoint`. Every hop
-    // must resolve — before the fix, the AS-metadata-via-path-insertion
-    // step 404'd and the SDK fell back to `/register` which also 404'd.
+  test("end-to-end: 401 → PRM (path-insertion) → AS (path-insertion) → DCR lands", async () => {
+    // Exact handshake Claude Code's MCP OAuth SDK performs. If any hop
+    // 404s, auth cascade-fails — this is the launch-blocker regression
+    // we're fixing.
     createVault("journal");
 
-    // Step 1: unauthenticated MCP → 401 + WWW-Authenticate.
-    const mcpRes = await route(
-      new Request("http://localhost:1940/vaults/journal/mcp"),
-      "/vaults/journal/mcp",
-    );
+    // Step 1: unauth MCP → 401 + WWW-Authenticate with PRM pointer.
+    const mcpPath = "/vault/journal/mcp";
+    const mcpRes = await route(new Request(`http://localhost:1940${mcpPath}`), mcpPath);
     expect(mcpRes.status).toBe(401);
     const challenge = mcpRes.headers.get("WWW-Authenticate")!;
     const prmUrl = challenge.match(/resource_metadata="([^"]+)"/)![1];
 
-    // Step 2: fetch PRM. The challenge points at the path-append form, but
-    // a strict client might also try path-insertion — both must work.
-    // Follow the advertised URL (path-append in this case) and note the
-    // authorization_servers pointer.
-    const prmPath = new URL(prmUrl).pathname;
-    const prmRes = await route(new Request(`http://localhost:1940${prmPath}`), prmPath);
+    // The challenge still points at the path-append PRM (we emit one URL
+    // in the header). Strict clients ignore the hint and probe the
+    // path-insertion form regardless — that's the path we care about here.
+    const prmInsertPath = "/.well-known/oauth-protected-resource/vault/journal";
+    const prmRes = await route(
+      new Request(`http://localhost:1940${prmInsertPath}`),
+      prmInsertPath,
+    );
     expect(prmRes.status).toBe(200);
     const prm = (await prmRes.json()) as { authorization_servers: string[] };
-    const asBase = prm.authorization_servers[0]; // "http://localhost:1940/vaults/journal"
+    const asBase = prm.authorization_servers[0]; // http://localhost:1940/vault/journal
 
-    // Step 3: strict-client path-insertion probe for AS metadata.
-    const asBasePath = new URL(asBase).pathname; // "/vaults/journal"
+    // Step 2: fetch AS metadata via path-insertion. The issuer path is
+    // everything after the host — here, `/vault/journal`.
+    const asBasePath = new URL(asBase).pathname;
     const asInsertPath = `/.well-known/oauth-authorization-server${asBasePath}`;
     const asRes = await route(
       new Request(`http://localhost:1940${asInsertPath}`),
       asInsertPath,
     );
-    // This was the 404 before the fix — the reason Claude Code's SDK gave
-    // up and cascade-404'd on `/register`.
     expect(asRes.status).toBe(200);
     const asMeta = (await asRes.json()) as { registration_endpoint: string };
 
-    // Step 4: the advertised registration_endpoint must be live (POST-only).
+    // Step 3: registration_endpoint must be live.
     const regPath = new URL(asMeta.registration_endpoint).pathname;
     const regRes = await route(
       new Request(`http://localhost:1940${regPath}`, {
@@ -655,7 +658,521 @@ describe("path-insertion OAuth discovery (RFC 8414 §3.1 / RFC 9728 §3)", () =>
       }),
       regPath,
     );
-    // Successful DCR is 201; anything but 404 proves the endpoint is wired.
     expect(regRes.status).toBe(201);
+
+    // Path-append PRM URL in the challenge header must still resolve —
+    // we haven't broken the back-compat path.
+    const prmAppendRes = await route(
+      new Request(prmUrl),
+      new URL(prmUrl).pathname,
+    );
+    expect(prmAppendRes.status).toBe(200);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// /.parachute/info + /.parachute/icon.svg — public service-info card for the
+// CLI hub page at the ecosystem root. The hub fetches these per service to
+// render tiles, so the endpoints are public (no auth), CORS `*`, and zero
+// PII. Shape is locked so all services line up in the aggregator UI.
+// ---------------------------------------------------------------------------
+
+describe("/.parachute/info + /.parachute/icon.svg", () => {
+  test("info returns the locked card shape with version from package.json", async () => {
+    createVault("journal");
+    const pkg = (await import("../package.json", { with: { type: "json" } })).default;
+    const path = "/vault/journal/.parachute/info";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toContain("application/json");
+    expect(res.headers.get("Access-Control-Allow-Origin")).toBe("*");
+    const body = (await res.json()) as {
+      name: string;
+      displayName: string;
+      tagline: string;
+      version: string;
+      iconUrl: string;
+      kind: string;
+    };
+    expect(body).toEqual({
+      name: "parachute-vault",
+      displayName: "Vault",
+      tagline: expect.stringContaining("knowledge graph"),
+      version: pkg.version,
+      iconUrl: "/vault/journal/.parachute/icon.svg",
+      kind: "api",
+    });
+  });
+
+  test("info iconUrl is vault-scoped and points at a live icon handler", async () => {
+    createVault("work");
+    const infoPath = "/vault/work/.parachute/info";
+    const infoRes = await route(new Request(`http://localhost:1940${infoPath}`), infoPath);
+    const info = (await infoRes.json()) as { iconUrl: string };
+    expect(info.iconUrl).toBe("/vault/work/.parachute/icon.svg");
+
+    // Follow the pointer — the advertised iconUrl must resolve.
+    const iconRes = await route(
+      new Request(`http://localhost:1940${info.iconUrl}`),
+      info.iconUrl,
+    );
+    expect(iconRes.status).toBe(200);
+  });
+
+  test("icon.svg returns an SVG body with the right content-type + CORS", async () => {
+    createVault("journal");
+    const path = "/vault/journal/.parachute/icon.svg";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/svg+xml");
+    expect(res.headers.get("Access-Control-Allow-Origin")).toBe("*");
+    // Pin nosniff so older Edge/IE can't sniff the inline SVG as HTML.
+    expect(res.headers.get("X-Content-Type-Options")).toBe("nosniff");
+    const body = await res.text();
+    expect(body).toContain("<svg");
+    expect(body).toContain("</svg>");
+  });
+
+  test("both endpoints are public — no auth header required, none honored", async () => {
+    createVault("journal");
+    for (const path of [
+      "/vault/journal/.parachute/info",
+      "/vault/journal/.parachute/icon.svg",
+    ]) {
+      // No Authorization header.
+      const resAnon = await route(new Request(`http://localhost:1940${path}`), path);
+      expect(resAnon.status).toBe(200);
+
+      // Bogus Authorization header — still 200, auth is not consulted.
+      const resWithHeader = await route(
+        new Request(`http://localhost:1940${path}`, {
+          headers: { Authorization: "Bearer pvt_nonsense" },
+        }),
+        path,
+      );
+      expect(resWithHeader.status).toBe(200);
+    }
+  });
+
+  test("unknown vault returns 404 before reaching the info/icon handlers", async () => {
+    createVault("journal");
+    for (const path of [
+      "/vault/nonexistent/.parachute/info",
+      "/vault/nonexistent/.parachute/icon.svg",
+    ]) {
+      const res = await route(new Request(`http://localhost:1940${path}`), path);
+      expect(res.status).toBe(404);
+    }
+  });
+
+  test("non-GET methods return 405 (and never trigger auth — stays public)", async () => {
+    createVault("journal");
+    for (const path of [
+      "/vault/journal/.parachute/info",
+      "/vault/journal/.parachute/icon.svg",
+    ]) {
+      const res = await route(
+        new Request(`http://localhost:1940${path}`, { method: "POST" }),
+        path,
+      );
+      expect(res.status).toBe(405);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// /.parachute/config/schema + /.parachute/config — module config (Phase 2).
+// ---------------------------------------------------------------------------
+
+describe("/.parachute/config/schema + /.parachute/config", () => {
+  test("schema returns JSON Schema draft-07 shape with the documented properties", async () => {
+    createVault("journal");
+    const path = "/vault/journal/.parachute/config/schema";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toContain("application/json");
+    expect(res.headers.get("Access-Control-Allow-Origin")).toBe("*");
+    const body = (await res.json()) as {
+      $schema: string;
+      type: string;
+      title: string;
+      properties: Record<string, { type?: string; enum?: string[]; writeOnly?: boolean; readOnly?: boolean }>;
+    };
+    expect(body.$schema).toBe("http://json-schema.org/draft-07/schema#");
+    expect(body.type).toBe("object");
+    expect(body.properties.audio_retention?.type).toBe("string");
+    expect(body.properties.audio_retention?.enum).toEqual(["keep", "until_transcribed", "never"]);
+    expect(body.properties.scribe_url?.type).toBe("string");
+    expect(body.properties.scribe_token?.writeOnly).toBe(true);
+    expect(body.properties.port?.readOnly).toBe(true);
+  });
+
+  test("config returns current values with writeOnly fields excluded", async () => {
+    createVault("journal");
+    const token = createAdminToken("journal");
+    const path = "/vault/journal/.parachute/config";
+    const origScribeToken = process.env.SCRIBE_TOKEN;
+    const origScribeUrl = process.env.SCRIBE_URL;
+    process.env.SCRIBE_TOKEN = "super-secret-should-never-appear";
+    process.env.SCRIBE_URL = "https://scribe.example/v1";
+    try {
+      const res = await route(
+        new Request(`http://localhost:1940${path}`, {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        path,
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.audio_retention).toBe("keep"); // default when unset
+      expect(body.scribe_url).toBe("https://scribe.example/v1");
+      expect(body.port).toBe(1940);
+      // writeOnly field must not appear in GET.
+      expect(body).not.toHaveProperty("scribe_token");
+      // Defense in depth: grep the raw body for the token value.
+      expect(JSON.stringify(body)).not.toContain("super-secret-should-never-appear");
+    } finally {
+      if (origScribeToken === undefined) delete process.env.SCRIBE_TOKEN;
+      else process.env.SCRIBE_TOKEN = origScribeToken;
+      if (origScribeUrl === undefined) delete process.env.SCRIBE_URL;
+      else process.env.SCRIBE_URL = origScribeUrl;
+    }
+  });
+
+  test("config reflects per-vault audio_retention override", async () => {
+    writeVaultConfig({
+      name: "journal",
+      api_keys: [],
+      created_at: new Date().toISOString(),
+      audio_retention: "until_transcribed",
+    });
+    const token = createAdminToken("journal");
+    const path = "/vault/journal/.parachute/config";
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      path,
+    );
+    const body = (await res.json()) as { audio_retention: string };
+    expect(body.audio_retention).toBe("until_transcribed");
+  });
+
+  test("config scribe_url falls back to empty string when SCRIBE_URL env is unset", async () => {
+    createVault("journal");
+    const token = createAdminToken("journal");
+    const orig = process.env.SCRIBE_URL;
+    delete process.env.SCRIBE_URL;
+    try {
+      const path = "/vault/journal/.parachute/config";
+      const res = await route(
+        new Request(`http://localhost:1940${path}`, {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+        path,
+      );
+      const body = (await res.json()) as { scribe_url: string };
+      expect(body.scribe_url).toBe("");
+    } finally {
+      if (orig !== undefined) process.env.SCRIBE_URL = orig;
+    }
+  });
+
+  test("unknown vault returns 404 before reaching the config handlers", async () => {
+    createVault("journal");
+    for (const path of [
+      "/vault/nonexistent/.parachute/config/schema",
+      "/vault/nonexistent/.parachute/config",
+    ]) {
+      const res = await route(new Request(`http://localhost:1940${path}`), path);
+      expect(res.status).toBe(404);
+    }
+  });
+
+  test("non-GET methods return 405 — PUT lands in Phase 3, not silently accepted now", async () => {
+    createVault("journal");
+    for (const path of [
+      "/vault/journal/.parachute/config/schema",
+      "/vault/journal/.parachute/config",
+    ]) {
+      for (const method of ["POST", "PUT", "PATCH", "DELETE"]) {
+        const res = await route(
+          new Request(`http://localhost:1940${path}`, { method }),
+          path,
+        );
+        expect(res.status).toBe(405);
+      }
+    }
+  });
+
+  test("schema endpoint is public — hub form renders without auth", async () => {
+    createVault("journal");
+    const path = "/vault/journal/.parachute/config/schema";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(200);
+  });
+
+  test("config endpoint requires vault:admin — unauthenticated GET returns 401", async () => {
+    createVault("journal");
+    const path = "/vault/journal/.parachute/config";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(401);
+  });
+
+  test("config endpoint rejects a vault:read token with 403 + insufficient_scope", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    const { fullToken } = generateToken();
+    createToken(store.db, fullToken, {
+      label: "reader",
+      permission: "read",
+      scopes: ["vault:read"],
+    });
+    const path = "/vault/journal/.parachute/config";
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        headers: { authorization: `Bearer ${fullToken}` },
+      }),
+      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:admin");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scope enforcement on /api/* — PR D (task #97).
+//
+// The REST surface picks the required scope per method (GET → vault:read,
+// POST/PATCH/DELETE → vault:write). These tests pin the full matrix:
+// read-only rejected on writes, write succeeds on GET via inheritance, admin
+// succeeds everywhere, legacy DB rows with NULL scopes keep working, and the
+// 403 body names the required scope so agents can diagnose without tracing.
+// ---------------------------------------------------------------------------
+
+describe("scope enforcement on /api/*", () => {
+  /** Mint a token with the given scopes and return its bearer value. */
+  function mintToken(
+    vaultName: string,
+    opts: {
+      permission: "full" | "read";
+      scopes?: string[];
+      legacyNullScopes?: boolean;
+    },
+  ): string {
+    const store = getVaultStore(vaultName);
+    const { fullToken } = generateToken();
+    if (opts.legacyNullScopes) {
+      // Simulate a pre-v12 token row: NULL scopes column, legacy permission
+      // value. resolveToken should fall back via legacyPermissionToScopes.
+      const { hashKey } = require("./config.ts");
+      const hash = hashKey(fullToken);
+      store.db.prepare(
+        "INSERT INTO tokens (token_hash, label, permission, created_at) VALUES (?, ?, ?, ?)",
+      ).run(hash, `legacy-${opts.permission}`, opts.permission, new Date().toISOString());
+    } else {
+      createToken(store.db, fullToken, {
+        label: `test-${opts.permission}`,
+        permission: opts.permission,
+        scopes: opts.scopes,
+      });
+    }
+    return fullToken;
+  }
+
+  function authed(token: string, method = "GET", path: string): Request {
+    return new Request(`http://localhost:1940${path}`, {
+      method,
+      headers: { authorization: `Bearer ${token}` },
+    });
+  }
+
+  test("vault:read token permits GET /api/vault", async () => {
+    createVault("journal");
+    const token = mintToken("journal", {
+      permission: "read",
+      scopes: ["vault:read"],
+    });
+    const path = "/vault/journal/api/vault";
+    const res = await route(authed(token, "GET", path), path);
+    expect(res.status).toBe(200);
+  });
+
+  test("vault:read token rejected on POST /api/notes with 403 insufficient_scope", async () => {
+    createVault("journal");
+    const token = mintToken("journal", {
+      permission: "read",
+      scopes: ["vault:read"],
+    });
+    const path = "/vault/journal/api/notes";
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${token}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({ content: "nope" }),
+      }),
+      path,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string; required_scope?: string; granted_scopes?: string[] };
+    expect(body.error_type).toBe("insufficient_scope");
+    expect(body.required_scope).toBe("vault:write");
+    expect(body.granted_scopes).toEqual(["vault:read"]);
+  });
+
+  test("vault:write token permits GET (inheritance: write ⊇ read)", async () => {
+    createVault("journal");
+    const token = mintToken("journal", {
+      permission: "full",
+      scopes: ["vault:write"],
+    });
+    const path = "/vault/journal/api/vault";
+    const res = await route(authed(token, "GET", path), path);
+    expect(res.status).toBe(200);
+  });
+
+  test("vault:write token permits POST /api/notes", async () => {
+    createVault("journal");
+    const token = mintToken("journal", {
+      permission: "full",
+      scopes: ["vault:write"],
+    });
+    const path = "/vault/journal/api/notes";
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${token}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({ content: "hi" }),
+      }),
+      path,
+    );
+    // 200/201 means scope gate allowed through — we don't care about the
+    // shape of the note here, just that we got past auth.
+    expect(res.status).toBeLessThan(400);
+  });
+
+  test("vault:admin token permits admin-only /.parachute/config", async () => {
+    createVault("journal");
+    const token = mintToken("journal", {
+      permission: "full",
+      scopes: ["vault:admin"],
+    });
+    const path = "/vault/journal/.parachute/config";
+    const res = await route(authed(token, "GET", path), path);
+    expect(res.status).toBe(200);
+  });
+
+  test("vault:admin token permits GET + POST via inheritance", async () => {
+    createVault("journal");
+    const token = mintToken("journal", {
+      permission: "full",
+      scopes: ["vault:admin"],
+    });
+    const getPath = "/vault/journal/api/vault";
+    const getRes = await route(authed(token, "GET", getPath), getPath);
+    expect(getRes.status).toBe(200);
+
+    const postPath = "/vault/journal/api/notes";
+    const postRes = await route(
+      new Request(`http://localhost:1940${postPath}`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${token}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({ content: "hi" }),
+      }),
+      postPath,
+    );
+    expect(postRes.status).toBeLessThan(400);
+  });
+
+  test("legacy token (NULL scopes, permission='full') still works on writes", async () => {
+    createVault("journal");
+    const token = mintToken("journal", {
+      permission: "full",
+      legacyNullScopes: true,
+    });
+    const path = "/vault/journal/api/notes";
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${token}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({ content: "legacy" }),
+      }),
+      path,
+    );
+    expect(res.status).toBeLessThan(400);
+  });
+
+  test("legacy token (NULL scopes, permission='read') rejected on writes", async () => {
+    createVault("journal");
+    const token = mintToken("journal", {
+      permission: "read",
+      legacyNullScopes: true,
+    });
+    const path = "/vault/journal/api/notes";
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${token}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({ content: "nope" }),
+      }),
+      path,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { required_scope?: string };
+    expect(body.required_scope).toBe("vault:write");
+  });
+
+  test("unauthenticated request to /api returns 401 (not 403)", async () => {
+    createVault("journal");
+    const path = "/vault/journal/api/vault";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(401);
+  });
+
+  test("CLI --read equivalent token (permission='read', scopes=[vault:read]) is read-only at the HTTP boundary", async () => {
+    // This pins the end-to-end contract: a token minted the way
+    // `parachute-vault tokens create --read` mints them actually refuses
+    // writes. Without this, a cosmetic `--read` flag could silently allow
+    // mutations — the whole point of the review item.
+    createVault("journal");
+    const token = mintToken("journal", {
+      permission: "read",
+      scopes: ["vault:read"],
+    });
+
+    const readPath = "/vault/journal/api/vault";
+    const readRes = await route(authed(token, "GET", readPath), readPath);
+    expect(readRes.status).toBe(200);
+
+    const writePath = "/vault/journal/api/notes";
+    const writeRes = await route(
+      new Request(`http://localhost:1940${writePath}`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${token}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({ content: "nope" }),
+      }),
+      writePath,
+    );
+    expect(writeRes.status).toBe(403);
   });
 });