@openparachute/vault 0.7.3-rc.9 → 0.7.4-rc.1

package/src/routing.test.ts

@@ -10,8 +10,10 @@
  *  3. `/vault/<name>/...` — per-vault routing (OAuth, MCP, view, API).
  *  4. The RFC 9728 WWW-Authenticate challenge that decorates MCP 401s.
  *
- * No unscoped `/mcp`, `/api/*`, `/oauth/*` routes exist — every per-vault
- * resource must name the vault it targets.
+ * No unscoped `/api/*` or `/oauth/*` routes exist — those per-vault resources
+ * must name the vault in the URL. The canonical root `/mcp` (U1) is the one
+ * vault-agnostic exception: it derives the target vault from the token, then
+ * re-dispatches through the same per-vault machinery.
  *
  * Uses PARACHUTE_HOME override so each test's vaults live in a tmp dir and
  * never touch ~/.parachute.
@@ -706,14 +708,27 @@ describe("per-vault routing under /vault/<name>/", () => {
     }
   });
 
-  test("no /mcp, /api, /oauth unscoped routes — all 404", async () => {
+  test("no /api, /oauth unscoped routes — all 404", async () => {
     createVault("journal");
-    for (const path of ["/mcp", "/api/notes", "/oauth/register", "/oauth/authorize"]) {
+    for (const path of ["/api/notes", "/oauth/register", "/oauth/authorize"]) {
       const res = await route(new Request(`http://localhost:1940${path}`), path);
       expect(res.status).toBe(404);
     }
   });
 
+  test("root /mcp is NOT a 404 — it's the token-derived MCP endpoint (401 unauthenticated)", async () => {
+    // The old unscoped `/mcp` compat prefix returned 404. The canonical root
+    // `/mcp` (U1) replaces it: unauthenticated it 401s + carries the root PRM
+    // challenge, exactly like the per-vault endpoint but pointed at the root
+    // metadata document.
+    createVault("journal");
+    const res = await route(new Request("http://localhost:1940/mcp", { method: "POST" }), "/mcp");
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toBe(
+      'Bearer resource_metadata="http://localhost:1940/.well-known/oauth-protected-resource/mcp"',
+    );
+  });
+
   test("bare /vault/<name> returns metadata for authenticated callers", async () => {
     createVault("journal", "My journal vault");
     const path = "/vault/journal";
@@ -810,6 +825,216 @@ describe("MCP 401 WWW-Authenticate challenge (RFC 9728)", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Canonical root MCP endpoint — token-derived vault dispatch (U1).
+//
+// `/mcp` at the origin root derives the target vault from the TOKEN, not the
+// URL, then re-dispatches through the identical per-vault machinery. These
+// tests pin the two load-bearing properties: (1) a token for vault A behaves
+// byte-identically at root `/mcp` and at `/vault/A/mcp` (equivalence), and
+// (2) the vault is ALWAYS the one the token names — a token can't be steered
+// to another vault, and an unnameable/ambiguous token is refused with the root
+// discovery challenge rather than a guess (derivation honesty).
+// ---------------------------------------------------------------------------
+
+describe("canonical root /mcp — token-derived vault dispatch (U1)", () => {
+  const INIT = {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+      protocolVersion: "2025-06-18",
+      capabilities: {},
+      clientInfo: { name: "u1-test", version: "0" },
+    },
+  };
+  const LIST = { jsonrpc: "2.0", id: 2, method: "tools/list" };
+  const QUERY = {
+    jsonrpc: "2.0",
+    id: 3,
+    method: "tools/call",
+    params: { name: "query-notes", arguments: {} },
+  };
+
+  async function mcpPost(path: string, token: string | null, rpc: object): Promise<Response> {
+    const headers: Record<string, string> = {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+    };
+    if (token) headers.authorization = `Bearer ${token}`;
+    return route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(rpc),
+      }),
+      path,
+    );
+  }
+
+  /** Parse a JSON-RPC frame off an MCP response, tolerating either the JSON
+   *  body (enableJsonResponse) or an SSE `data:` framing. */
+  async function rpcFrame(res: Response): Promise<unknown> {
+    const text = await res.text();
+    const trimmed = text.trimStart();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) return JSON.parse(trimmed);
+    const dataLine = text.split("\n").find((l) => l.startsWith("data:"));
+    return JSON.parse(dataLine!.slice("data:".length).trim());
+  }
+
+  /** Sign a token directly (bypassing `mintJwt`'s `aud=vault.<name>` coupling)
+   *  so a test can craft a token whose sources name no vault, or disagree. */
+  async function signRaw(payload: Record<string, unknown>, aud: string): Promise<string> {
+    const iat = Math.floor(Date.now() / 1000);
+    return new SignJWT({ client_id: "u1-test", ...payload })
+      .setProtectedHeader({ alg: "RS256", kid: KID })
+      .setIssuer(`http://127.0.0.1:${hubServer.port}`)
+      .setSubject("u1-test-user")
+      .setAudience(aud)
+      .setIssuedAt(iat)
+      .setExpirationTime(iat + 60)
+      .setJti(`jti-${Math.random().toString(36).slice(2)}`)
+      .sign(signingKey);
+  }
+
+  test("root PRM mirrors the per-vault PRM shape (root resource, un-narrowed scopes)", async () => {
+    createVault("journal");
+    const path = "/.well-known/oauth-protected-resource/mcp";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(200);
+    const prm = (await res.json()) as {
+      resource: string;
+      authorization_servers: string[];
+      scopes_supported: string[];
+      bearer_methods_supported: string[];
+    };
+    expect(prm.resource).toBe("http://localhost:1940/mcp");
+    // Un-narrowed forms — the hub's consent picker narrows them to a vault.
+    expect(prm.scopes_supported).toEqual(["vault:read", "vault:write"]);
+    expect(prm.bearer_methods_supported).toEqual(["header"]);
+    expect(Array.isArray(prm.authorization_servers)).toBe(true);
+    expect(prm.authorization_servers.length).toBe(1);
+  });
+
+  test("unauthenticated → 401 whose challenge names the root PRM (self-consistent pointer)", async () => {
+    createVault("journal");
+    const res = await mcpPost("/mcp", null, INIT);
+    expect(res.status).toBe(401);
+    const header = res.headers.get("WWW-Authenticate")!;
+    const prmUrl = header.match(/resource_metadata="([^"]+)"/)![1]!;
+    const prmPath = new URL(prmUrl).pathname;
+    expect(prmPath).toBe("/.well-known/oauth-protected-resource/mcp");
+    // The pointer resolves to a real PRM that names the root resource.
+    const prmRes = await route(new Request(prmUrl), prmPath);
+    expect(prmRes.status).toBe(200);
+    expect(((await prmRes.json()) as { resource: string }).resource).toBe(
+      "http://localhost:1940/mcp",
+    );
+  });
+
+  test("x-forwarded-* shape the root challenge URL", async () => {
+    createVault("journal");
+    const req = new Request("http://127.0.0.1:1940/mcp", {
+      method: "POST",
+      headers: {
+        "x-forwarded-host": "vault.example.com",
+        "x-forwarded-proto": "https",
+      },
+    });
+    const res = await route(req, "/mcp");
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toBe(
+      'Bearer resource_metadata="https://vault.example.com/.well-known/oauth-protected-resource/mcp"',
+    );
+  });
+
+  test("token for A at root /mcp === same token at /vault/A/mcp (initialize, tools/list, tool call)", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    await store.createNote("root-mcp equivalence fixture", { path: "fixture", tags: ["probe"] });
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:admin"] });
+
+    for (const rpc of [INIT, LIST, QUERY]) {
+      const rootRes = await mcpPost("/mcp", token, rpc);
+      const perVaultRes = await mcpPost("/vault/journal/mcp", token, rpc);
+      expect(rootRes.status).toBe(200);
+      expect(perVaultRes.status).toBe(200);
+      // Byte-identical JSON-RPC frame — the root path derived `journal`, so the
+      // server name, tool list, and tool result all match the URL-addressed
+      // endpoint exactly.
+      expect(await rpcFrame(rootRes)).toEqual(await rpcFrame(perVaultRes));
+    }
+  });
+
+  test("a read-only token narrows the root tool list identically to the per-vault endpoint", async () => {
+    createVault("journal");
+    getVaultStore("journal");
+    const readToken = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:read"] });
+    const rootList = await rpcFrame(await mcpPost("/mcp", readToken, LIST));
+    const perVaultList = await rpcFrame(await mcpPost("/vault/journal/mcp", readToken, LIST));
+    expect(rootList).toEqual(perVaultList);
+    // Sanity: a read token sees the read tools but not write/admin ones.
+    const names = (rootList as { result: { tools: { name: string }[] } }).result.tools.map(
+      (t) => t.name,
+    );
+    expect(names).toContain("query-notes");
+    expect(names).not.toContain("create-note");
+    expect(names).not.toContain("manage-token");
+  });
+
+  test("a vault-A token ALWAYS lands in A through root /mcp — never another vault's data", async () => {
+    createVault("alpha");
+    createVault("beta");
+    // Seed a secret in BETA. A token minted for ALPHA must never surface it.
+    await getVaultStore("beta").createNote("BETA-ONLY-SECRET", { path: "secret" });
+    getVaultStore("alpha");
+    const alphaToken = await mintJwt({ vaultName: "alpha", scopes: ["vault:alpha:admin"] });
+
+    const res = await mcpPost("/mcp", alphaToken, QUERY);
+    expect(res.status).toBe(200);
+    // The vault is derived from the token (alpha); beta's note is unreachable.
+    expect(JSON.stringify(await rpcFrame(res))).not.toContain("BETA-ONLY-SECRET");
+  });
+
+  test("scope and aud naming DIFFERENT vaults → 401 (disagreement, never guess)", async () => {
+    createVault("alpha");
+    createVault("beta");
+    // aud=vault.alpha (from vaultName) but the scope names beta — two sources
+    // disagree, so derivation refuses rather than picking a winner.
+    const token = await mintJwt({ vaultName: "alpha", scopes: ["vault:beta:admin"] });
+    const res = await mcpPost("/mcp", token, INIT);
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toContain("/.well-known/oauth-protected-resource/mcp");
+  });
+
+  test("a token that names NO vault (broad scope, non-vault aud, no vault_scope) → 401", async () => {
+    createVault("journal");
+    // Broad `vault:read` names no vault; aud is not `vault.<name>`; no
+    // vault_scope claim. Nothing derives a target → the discovery challenge.
+    const token = await signRaw({ scope: "vault:read" }, "some-other-resource");
+    const res = await mcpPost("/mcp", token, INIT);
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toContain("/.well-known/oauth-protected-resource/mcp");
+  });
+
+  test("an invalid / unverifiable token → 401 + root challenge (no vault leaked)", async () => {
+    createVault("journal");
+    const res = await mcpPost("/mcp", "not-a-real-jwt", INIT);
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toContain("/.well-known/oauth-protected-resource/mcp");
+  });
+
+  test("a validly-signed token naming a vault absent on THIS server → 404 (mirrors per-vault)", async () => {
+    createVault("journal");
+    // Token is real (signed by the fixture hub) but names a vault that isn't
+    // installed here. The per-vault URL 404s for a missing vault; root matches.
+    const token = await mintJwt({ vaultName: "ghost", scopes: ["vault:ghost:admin"] });
+    const res = await mcpPost("/mcp", token, INIT);
+    expect(res.status).toBe(404);
+    expect(((await res.json()) as { error: string }).error).toBe("Vault not found");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Per-vault OAuth discovery (RFC 8414 / RFC 9728, path-append form).
 //
@@ -2491,6 +2716,135 @@ describe("/vault/<name>/.parachute/mirror — auth + dispatch", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// /vault/<name>/.parachute/embeddings — semantic-search (embeddings) opt-in
+// toggle admin surface (0.7.3 fast-follow, vault#624).
+//
+// Pins the auth gate + GET/PUT dispatch at the routing layer: the endpoint is
+// `vault:admin`-only (a host-global setting reached through the same per-vault
+// admin surface as the sibling `.parachute/mirror` / `.parachute/config`
+// pages). Snapshot shape + the env-override / restart-required semantics are
+// covered in embeddings-routes.test.ts; here we pin the *security* property —
+// unauth → 401, read/write → 403, admin → 200 + the flip persists — so it
+// can't silently regress below the rest of the admin surface. Mirrors the
+// `.parachute/mirror` auth+dispatch describe above.
+// ---------------------------------------------------------------------------
+
+describe("/vault/<name>/.parachute/embeddings — auth + dispatch", () => {
+  const P = "/vault/journal/.parachute/embeddings";
+
+  test("unauthenticated GET → 401", async () => {
+    createVault("journal");
+    const res = await route(new Request(`http://localhost:1940${P}`), P);
+    expect(res.status).toBe(401);
+  });
+
+  test("unauthenticated PUT → 401", async () => {
+    createVault("journal");
+    const res = await route(
+      new Request(`http://localhost:1940${P}`, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ enabled: true }),
+      }),
+      P,
+    );
+    expect(res.status).toBe(401);
+  });
+
+  test("vault:read token PUT → 403 insufficient_scope", async () => {
+    createVault("journal");
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:read"] });
+    const res = await route(
+      new Request(`http://localhost:1940${P}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ enabled: true }),
+      }),
+      P,
+    );
+    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");
+  });
+
+  test("vault:write token PUT → 403 insufficient_scope (write ranks below admin)", async () => {
+    createVault("journal");
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:write"] });
+    const res = await route(
+      new Request(`http://localhost:1940${P}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ enabled: true }),
+      }),
+      P,
+    );
+    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");
+  });
+
+  test("cross-vault admin token → 403 (scope names a different vault)", async () => {
+    createVault("journal");
+    createVault("other");
+    // Audience is `journal` (auth passes) but the admin scope names `other`,
+    // so hasScopeForVault denies it against `journal`.
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:other:admin"] });
+    const res = await route(
+      new Request(`http://localhost:1940${P}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      P,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+  });
+
+  test("vault:admin token GET → 200 (default off); admin PUT persists the flip", async () => {
+    createVault("journal");
+    const token = await createAdminToken("journal");
+
+    // GET reaches the handler (auth + admin scope satisfied) → 200 snapshot,
+    // default-off (config seeded with `port` only).
+    const getRes = await route(
+      new Request(`http://localhost:1940${P}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      P,
+    );
+    expect(getRes.status).toBe(200);
+    const getBody = (await getRes.json()) as { enabled?: boolean };
+    expect(getBody.enabled).toBe(false);
+
+    // PUT flips the persisted setting → 200, echoing the new value.
+    const putRes = await route(
+      new Request(`http://localhost:1940${P}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ enabled: true }),
+      }),
+      P,
+    );
+    expect(putRes.status).toBe(200);
+    const putBody = (await putRes.json()) as { enabled?: boolean };
+    expect(putBody.enabled).toBe(true);
+
+    // A follow-up GET reads the persisted value back → the write stuck.
+    const reGet = await route(
+      new Request(`http://localhost:1940${P}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      P,
+    );
+    expect(reGet.status).toBe(200);
+    const reBody = (await reGet.json()) as { enabled?: boolean };
+    expect(reBody.enabled).toBe(true);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // /vault/<name>/.parachute/mirror/run-now — manual-trigger endpoint added
 // alongside the SPA UI. Tests pin the auth gate matches the parent

package/src/routing.ts

@@ -1,15 +1,23 @@
 /**
  * HTTP request router for the multi-vault server.
  *
- * All per-vault resources live under `/vault/<name>/...`. There is no
- * unscoped fallback — a request must name the vault it targets. A fresh
- * install creates a vault named `default`, so `/vault/default/...` is the
- * baseline URL for single-vault deployments.
+ * Per-vault resources live under `/vault/<name>/...` — a request names the
+ * vault it targets in the URL. The one exception is the canonical root `/mcp`
+ * endpoint (U1), which is vault-AGNOSTIC: the vault is derived from the token,
+ * not the URL. A fresh install creates a vault named `default`, so
+ * `/vault/default/...` is the baseline URL for single-vault deployments.
  *
  * Dispatch shape:
  *
  *   /.well-known/parachute.json        — NOT served here (CLI owns it at
  *                                        origin root; vault never handles it)
+ *   /.well-known/oauth-protected-resource/mcp
+ *                                      — root-endpoint PRM (RFC 9728) for the
+ *                                        canonical `/mcp` below (U1)
+ *   /mcp[/*]                           — canonical root MCP endpoint; the vault
+ *                                        is DERIVED FROM THE TOKEN, then the
+ *                                        request re-dispatches through the same
+ *                                        per-vault machinery (U1)
  *   /health                            — liveness ping, vault names leaked
  *                                        only to authenticated callers
  *   /vaults/list                       — public vault-name discovery (can be
@@ -21,15 +29,20 @@
  *   /vault/<name>/.well-known/oauth-*  — discovery forwarder; metadata names
  *                                        the hub as the authorization server
  *                                        (vault is resource-server only)
- *   /vault/<name>/mcp[/*]              — MCP endpoint (Bearer auth)
+ *   /vault/<name>/mcp[/*]              — MCP endpoint (Bearer auth); the
+ *                                        URL-addressed twin of root `/mcp`,
+ *                                        untouched and permanent
  *   /vault/<name>/view/<idOrPath>      — auth-aware HTML view
  *   /vault/<name>/public/<noteId>      — legacy alias → /view redirect
  *   /vault/<name>                      — vault metadata + stats (auth)
  *   /vault/<name>/api/...              — REST surface (auth)
  *
- * There is deliberately no compat for the old `/api/*`, `/mcp`, `/oauth/*`,
- * `/view/*`, or `/vaults/<name>/*` prefixes. Clients must re-authenticate
- * after the upgrade and point at the new URLs.
+ * The root `/mcp` here is NOT the old unscoped compat prefix (that pre-0.5.0
+ * `/mcp` — an alias for a single default vault — is gone). It's the token-
+ * derived door: same auth machinery as the per-vault endpoint, reached without
+ * the client having to know the vault's URL name. There is still deliberately
+ * no compat for the old `/api/*`, `/oauth/*`, `/view/*`, or `/vaults/<name>/*`
+ * prefixes; clients using those must re-authenticate and point at the new URLs.
  *
  * **No standalone OAuth issuer.** vault does not mint OAuth tokens or
  * render a consent UI. Hub is the issuer; vault validates hub-signed
@@ -50,6 +63,7 @@ import {
 import {
   authenticateVaultRequest,
   authenticateGlobalRequest,
+  deriveVaultFromToken,
   extractApiKey,
 } from "./auth.ts";
 import { hasScopeForVault, hasMigrateScopeForVault, SCOPE_ADMIN, SCOPE_READ, scopeForMethod, verbForMethod } from "./scopes.ts";
@@ -78,6 +92,7 @@ import { handleTriggers } from "./triggers-api.ts";
 import { expandTokenTagScope } from "./tag-scope.ts";
 import {
   handleProtectedResource,
+  handleRootProtectedResource,
   handleAuthorizationServer,
   getBaseUrl,
 } from "./oauth-discovery.ts";
@@ -101,6 +116,7 @@ import {
   handleMirrorPut,
   handleMirrorRunNow,
 } from "./mirror-routes.ts";
+import { handleEmbeddingsGet, handleEmbeddingsPut } from "./embeddings-routes.ts";
 import { getMirrorManager } from "./mirror-registry.ts";
 import { buildUsageReport } from "./usage.ts";
 import { handleTicketSpend } from "./attachment-tickets.ts";
@@ -135,6 +151,58 @@ async function withMcpChallenge(
   return new Response(body, { status: 401, headers });
 }
 
+/**
+ * 401 + RFC 9728 challenge for the canonical ROOT `/mcp` endpoint (U1), when
+ * the token is absent / invalid / names no single vault. Mirrors
+ * `withMcpChallenge` but points at the ROOT protected-resource metadata
+ * (`/.well-known/oauth-protected-resource/mcp`) rather than a vault-scoped one,
+ * since the root resource is vault-agnostic. A spec-following MCP client
+ * follows this pointer to the root PRM, discovers the hub, and requests the
+ * un-narrowed scopes the hub's consent picker narrows to a chosen vault.
+ */
+function rootMcpChallenge(req: Request): Response {
+  const base = getBaseUrl(req);
+  return Response.json(
+    { error: "Unauthorized", message: "API key required" },
+    {
+      status: 401,
+      headers: {
+        "WWW-Authenticate": `Bearer resource_metadata="${base}/.well-known/oauth-protected-resource/mcp"`,
+      },
+    },
+  );
+}
+
+/**
+ * Shared scoped-MCP dispatch tail used by BOTH the URL-addressed per-vault
+ * endpoint (`/vault/<name>/mcp`) and the token-derived root endpoint (`/mcp`,
+ * U1). Runs the FULL per-vault auth machinery via `authenticateVaultRequest`
+ * (audience strict-check, `vault_scope` pin, broad-scope rejection, tag-scope
+ * parse) and, on success, hands off to `handleScopedMcp`. A 401 is decorated
+ * with the per-vault RFC 9728 challenge. Because both entry points funnel
+ * through this one function, a root request behaves byte-identically to the
+ * same token at the per-vault URL — and, for the root, the re-validation here
+ * is the authoritative gate: a derivation that named the wrong vault fails the
+ * audience strict-check, it never bypasses it.
+ */
+async function dispatchScopedMcp(
+  req: Request,
+  vaultName: string,
+  vaultConfig: VaultConfig,
+): Promise<Response> {
+  const auth = await authenticateVaultRequest(req, vaultConfig);
+  if ("error" in auth) return withMcpChallenge(auth.error, req, vaultName);
+  // Thread the RAW caller bearer (the exact credential the session presented)
+  // into the MCP layer so the manage-token tool can forward it to hub's
+  // mint-token attenuation proxy (vault#403, MGT). Only the raw validated
+  // bearer — never a fabricated one. extractApiKey returns the same value
+  // `authenticateVaultRequest` validated above; non-forwardable credentials
+  // (env-var secret, legacy pvt_*) are handled by manage-token itself (it only
+  // forwards JWT-shaped bearers).
+  const callerBearer = extractApiKey(req);
+  return handleScopedMcp(req, vaultName, auth, callerBearer);
+}
+
 /**
  * Check if a /view request has a valid API key (header or ?key= query param).
  * Returns true if authenticated, false if not. Never rejects — unauthenticated
@@ -260,6 +328,18 @@ export async function route(
     return handleAuthorizationServer(req, vaultName);
   }
 
+  // Root-endpoint protected-resource metadata (RFC 9728 §3.1 path-insertion)
+  // for the canonical `/mcp` endpoint (U1). The root resource is vault-
+  // agnostic — the target vault is derived from the token, not the URL — so
+  // this document carries no vault name and advertises the un-narrowed
+  // `vault:read` / `vault:write` scopes; the hub's consent picker narrows them
+  // to a chosen vault at authorization time. Distinct from the per-vault
+  // insertion shapes above (which require a `/vault/<name>` segment), so there
+  // is no overlap. The `rootMcpChallenge` 401 points clients here.
+  if (path === "/.well-known/oauth-protected-resource/mcp") {
+    return handleRootProtectedResource(req);
+  }
+
   // ---------------------------------------------------------------------
   // Cross-vault / origin-root endpoints
   // ---------------------------------------------------------------------
@@ -368,6 +448,43 @@ export async function route(
     return Response.json({ vaults });
   }
 
+  // ---------------------------------------------------------------------
+  // Canonical root MCP endpoint — token-derived vault dispatch (U1).
+  //
+  // `POST /mcp` (plus the GET/DELETE the streamable-HTTP transport uses, and
+  // the `/mcp/*` subpaths) is the vault-AGNOSTIC entry point: the target vault
+  // is derived from the TOKEN, not the URL. We validate the bearer with the
+  // same scope-guard trust kernel the per-vault path uses, read the vault name
+  // from the token's claims, then RE-DISPATCH through the identical per-vault
+  // machinery (`dispatchScopedMcp` → `authenticateVaultRequest` →
+  // `handleScopedMcp`). The re-dispatch re-validates WITH the audience pin, so
+  // a bad derivation fails the inner check rather than bypassing it (defense in
+  // depth). The legacy URL-addressed `/vault/<name>/mcp` is untouched and lives
+  // forever.
+  //
+  // No / invalid / unnameable token → 401 whose `WWW-Authenticate` points at
+  // the ROOT PRM (`/.well-known/oauth-protected-resource/mcp`), so a spec-
+  // following MCP client discovers the hub and requests the un-narrowed scopes
+  // its consent picker narrows to a chosen vault.
+  if (path === "/mcp" || path.startsWith("/mcp/")) {
+    const derived = await deriveVaultFromToken(req);
+    if ("error" in derived) {
+      return rootMcpChallenge(req);
+    }
+    const vaultConfig = readVaultConfig(derived.vaultName);
+    if (!vaultConfig) {
+      // A validly-signed hub token naming a vault that isn't on THIS server.
+      // Mirror the per-vault 404 (`/vault/<name>/mcp` on a missing vault) — the
+      // holder knows which vault their token targets; nothing is leaked to an
+      // anonymous caller (they never validate a token to reach here).
+      return Response.json(
+        { error: "Vault not found", vault: derived.vaultName },
+        { status: 404 },
+      );
+    }
+    return dispatchScopedMcp(req, derived.vaultName, vaultConfig);
+  }
+
   // ---------------------------------------------------------------------
   // Per-vault routing: /vault/<name>/...
   // ---------------------------------------------------------------------
@@ -507,28 +624,24 @@ export async function route(
     return handleTicketSpend(req, ticketId, vaultName, store);
   }
 
+  // MCP (per-vault, single-vault session) — the URL names the vault. Shares
+  // the exact dispatch tail with the token-derived root `/mcp` (U1), so both
+  // behave identically. Handled BEFORE the shared authenticated-surface auth
+  // below because `dispatchScopedMcp` owns its own auth + 401 challenge; a
+  // non-MCP 401 further down never carries the RFC 9728 challenge (it's
+  // MCP-only).
+  if (subpath === "/mcp" || subpath.startsWith("/mcp/")) {
+    return dispatchScopedMcp(req, vaultName, vaultConfig);
+  }
+
   // ---------------------------------------------------------------------
   // Authenticated surface
   // ---------------------------------------------------------------------
 
   const store = getVaultStore(vaultName);
   const auth = await authenticateVaultRequest(req, vaultConfig);
-  const isScopedMcp = subpath === "/mcp" || subpath.startsWith("/mcp/");
   if ("error" in auth) {
-    return isScopedMcp ? withMcpChallenge(auth.error, req, vaultName) : auth.error;
-  }
-
-  // MCP (per-vault, single-vault session).
-  if (isScopedMcp) {
-    // Thread the RAW caller bearer (the exact credential the session
-    // presented) into the MCP layer so the manage-token tool can forward it
-    // to hub's mint-token attenuation proxy (vault#403, MGT). Only the raw
-    // validated bearer — never a fabricated one. extractApiKey returns the
-    // same value `authenticateVaultRequest` validated above; non-forwardable
-    // credentials (env-var secret, legacy pvt_*) are handled by manage-token
-    // itself (it only forwards JWT-shaped bearers).
-    const callerBearer = extractApiKey(req);
-    return handleScopedMcp(req, vaultName, auth, callerBearer);
+    return auth.error;
   }
 
   // Bare `/vault/<name>` — single-vault root. Returns name, description,
@@ -575,6 +688,33 @@ export async function route(
     return Response.json(buildUsageReport(vaultName, stats, { fresh }));
   }
 
+  // /.parachute/embeddings — Admin-gated read+write of the semantic-search
+  // (embeddings) opt-in toggle. The 0.7.3 fast-follow: gives the admin SPA a
+  // real toggle over the persisted `embeddings_enabled` config.yaml setting so
+  // an operator flips semantic search on from the UI instead of hand-editing
+  // config or setting an env var. Host-global setting (affects every vault),
+  // reached through the same per-vault admin surface as the other settings
+  // pages. Activation is restart-to-apply — the endpoint persists the setting
+  // and reports `restart_required`; see embeddings-routes.ts for why the boot-
+  // captured provider isn't hot-reconfigured.
+  if (subpath === "/.parachute/embeddings") {
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    if (req.method === "GET") return handleEmbeddingsGet();
+    if (req.method === "PUT") return handleEmbeddingsPut(req);
+    return Response.json({ error: "Method not allowed" }, { status: 405 });
+  }
+
   // 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`