npm - @openparachute/hub - Versions diffs - 0.7.1 → 0.7.2-rc.1 - Mend

@openparachute/hub 0.7.1 → 0.7.2-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (73) hide show

package/README.md +13 -14
package/package.json +1 -1
package/src/__tests__/admin-agent-grants.test.ts +1547 -0
package/src/__tests__/{admin-channel-token.test.ts → admin-agent-token.test.ts} +32 -32
package/src/__tests__/admin-connections-credentials.test.ts +8 -4
package/src/__tests__/admin-connections.test.ts +211 -57
package/src/__tests__/admin-csrf-belt.test.ts +7 -7
package/src/__tests__/admin-lock.test.ts +600 -0
package/src/__tests__/admin-module-token.test.ts +36 -8
package/src/__tests__/admin-vaults.test.ts +8 -8
package/src/__tests__/api-modules-ops.test.ts +17 -16
package/src/__tests__/api-modules.test.ts +35 -36
package/src/__tests__/api-ready.test.ts +2 -2
package/src/__tests__/clients.test.ts +91 -0
package/src/__tests__/grants-store.test.ts +219 -0
package/src/__tests__/hub-server.test.ts +9 -5
package/src/__tests__/migrate.test.ts +1 -1
package/src/__tests__/module-manifest.test.ts +11 -11
package/src/__tests__/oauth-client.test.ts +446 -0
package/src/__tests__/oauth-flows-store.test.ts +141 -0
package/src/__tests__/oauth-handlers.test.ts +124 -26
package/src/__tests__/operator-token.test.ts +2 -2
package/src/__tests__/scope-explanations.test.ts +3 -3
package/src/__tests__/serve-boot.test.ts +14 -14
package/src/__tests__/serve.test.ts +26 -0
package/src/__tests__/service-spec-discovery.test.ts +26 -18
package/src/__tests__/services-manifest.test.ts +60 -48
package/src/__tests__/setup-gate.test.ts +52 -3
package/src/__tests__/setup-wizard.test.ts +86 -280
package/src/__tests__/setup.test.ts +1 -1
package/src/__tests__/upgrade.test.ts +276 -0
package/src/__tests__/vault-remove.test.ts +393 -0
package/src/admin-agent-grants.ts +1365 -0
package/src/admin-agent-token.ts +147 -0
package/src/admin-connections.ts +67 -50
package/src/admin-host-admin-token.ts +14 -1
package/src/admin-lock.ts +281 -0
package/src/admin-module-token.ts +15 -7
package/src/admin-vault-admin-token.ts +8 -1
package/src/admin-vaults.ts +12 -12
package/src/api-admin-lock.ts +335 -0
package/src/api-modules-ops.ts +3 -2
package/src/api-modules.ts +9 -9
package/src/cli.ts +13 -1
package/src/clients.ts +88 -0
package/src/commands/install.ts +7 -0
package/src/commands/serve-boot.ts +5 -4
package/src/commands/serve.ts +45 -19
package/src/commands/setup.ts +4 -3
package/src/commands/upgrade.ts +118 -2
package/src/commands/vault-remove.ts +361 -0
package/src/commands/wizard.ts +4 -4
package/src/connections-store.ts +3 -3
package/src/grants-store.ts +272 -0
package/src/help.ts +4 -1
package/src/hub-server.ts +209 -27
package/src/hub-settings.ts +23 -8
package/src/jwt-sign.ts +5 -1
package/src/module-manifest.ts +2 -2
package/src/oauth-client.ts +497 -0
package/src/oauth-flows-store.ts +163 -0
package/src/oauth-handlers.ts +40 -13
package/src/operator-token.ts +1 -1
package/src/origin-check.ts +7 -2
package/src/resource-binding.ts +4 -4
package/src/scope-explanations.ts +3 -3
package/src/service-spec.ts +56 -43
package/src/setup-wizard.ts +56 -240
package/web/ui/dist/assets/index-B5AUE359.js +61 -0
package/web/ui/dist/assets/{index-E_9wqjEm.css → index-DR6R8EFf.css} +1 -1
package/web/ui/dist/index.html +2 -2
package/src/admin-channel-token.ts +0 -135
package/web/ui/dist/assets/index-Cxtod68O.js +0 -61

package/src/__tests__/hub-server.test.ts CHANGED Viewed

@@ -1576,8 +1576,10 @@ describe("hubFetch routing", () => {
   });
   // Pre-admin lockout (hub#258). When no admin row exists, operator-
-  // facing surfaces (admin/api/login) 503 with a JSON body pointing at
-  // /admin/setup. Public surfaces (health, well-known, /, oauth, vault,
+  // facing API surfaces (admin/api) 503 with a JSON body pointing at
+  // /admin/setup. The browser-facing `/login` GET 302s to the wizard
+  // instead (hub#644) — a JSON 503 there would render as raw text in the
+  // visitor's tab. Public surfaces (health, well-known, /, oauth, vault,
   // /admin/setup itself) stay open so the container is reachable and
   // OAuth third parties aren't held hostage by admin onboarding.
   test("pre-admin lockout: /admin/vaults returns 503 setup_required", async () => {
@@ -1615,7 +1617,7 @@ describe("hubFetch routing", () => {
     }
   });
-  test("pre-admin lockout: /login is gated, /admin/setup + /health + well-known stay open, / funnels to /admin/setup", async () => {
+  test("pre-admin lockout: /login GET funnels to /admin/setup, /admin/setup + /health + well-known stay open, / funnels to /admin/setup", async () => {
     const h = makeHarness();
     try {
       writeFileSync(join(h.dir, "hub.html"), "<html>discovery</html>");
@@ -1623,9 +1625,11 @@ describe("hubFetch routing", () => {
       const db = openHubDb(hubDbPath(h.dir));
       try {
         const handler = hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath });
-        // /login gated
+        // /login GET funnels to the wizard (hub#644) — the browser-facing
+        // sign-in surface 302s to /admin/setup instead of a raw JSON 503.
         const loginRes = await handler(req("/login"));
-        expect(loginRes.status).toBe(503);
+        expect(loginRes.status).toBe(302);
+        expect(loginRes.headers.get("location")).toBe("/admin/setup");
         // /admin/setup open
         const setupRes = await handler(req("/admin/setup"));
         expect(setupRes.status).toBe(200);

package/src/__tests__/migrate.test.ts CHANGED Viewed

@@ -56,7 +56,7 @@ describe("safelistEntries", () => {
     expect(s.has("vault")).toBe(true);
     expect(s.has("notes")).toBe(true);
     expect(s.has("scribe")).toBe(true);
-    expect(s.has("channel")).toBe(true);
+    expect(s.has("agent")).toBe(true);
     // Internal
     expect(s.has("hub")).toBe(true);
     // CLI state

package/src/__tests__/module-manifest.test.ts CHANGED Viewed

@@ -40,13 +40,13 @@ describe("validateModuleManifest", () => {
             key: "link-to-vault",
             title: "Link a channel to a vault",
             description: "Back a channel with a vault.",
-            requestedBy: "channel",
+            requestedBy: "agent",
             source: {
               module: "vault",
               event: "note.created",
-              filter: { tags: ["#channel-message/inbound"] },
+              filter: { tags: ["#agent-message/inbound"] },
             },
-            sink: { module: "channel", action: "message.deliver" },
+            sink: { module: "agent", action: "message.deliver" },
             parameters: [
               { key: "vault", target: "source.vault", title: "Vault" },
               { key: "channel", target: "sink.params.channel", example: "eng" },
@@ -61,9 +61,9 @@ describe("validateModuleManifest", () => {
     expect(t?.source).toEqual({
       module: "vault",
       event: "note.created",
-      filter: { tags: ["#channel-message/inbound"] },
+      filter: { tags: ["#agent-message/inbound"] },
     });
-    expect(t?.sink).toEqual({ module: "channel", action: "message.deliver" });
+    expect(t?.sink).toEqual({ module: "agent", action: "message.deliver" });
     expect(t?.parameters?.[1]).toEqual({
       key: "channel",
       target: "sink.params.channel",
@@ -119,7 +119,7 @@ describe("validateModuleManifest", () => {
               key: "k",
               title: "T",
               source: { module: "vault", event: "note.created" },
-              sink: { module: "channel", action: "message.deliver" },
+              sink: { module: "agent", action: "message.deliver" },
               parameters: [{ key: "p" }],
             },
           ],
@@ -417,24 +417,24 @@ describe("validateModuleManifest", () => {
         "x",
       ),
     ).toThrow(/must be namespaced as "<name>:<verb>"/);
-    // A matching-namespace scope still validates — the real channel case
-    // (channel.message.deliver → channel:send).
+    // A matching-namespace scope still validates — the real agent case
+    // (message.deliver → agent:send).
     const okm = validateModuleManifest(
       {
         ...VALID,
-        name: "channel",
+        name: "agent",
         actions: [
           {
             key: "message.deliver",
             title: "Deliver",
             endpoint: "/api/vault/inbound",
-            scope: "channel:send",
+            scope: "agent:send",
           },
         ],
       },
       "x",
     );
-    expect(okm.actions?.[0]?.scope).toBe("channel:send");
+    expect(okm.actions?.[0]?.scope).toBe("agent:send");
   });
   test("uiUrl accepts a leading-slash path (Phase D)", () => {

package/src/__tests__/oauth-client.test.ts ADDED Viewed

@@ -0,0 +1,446 @@
+/**
+ * Tests for the hub-as-OAuth-CLIENT engine (`oauth-client.ts`, 4b-2).
+ *
+ * Fully offline — every network call goes through an injected `fetchFn`. No real
+ * fetch is ever made. Covers: discovery (9728→8414 + 8414-only fallback), DCR,
+ * authorize-URL building (S256 + state + challenge), code exchange + refresh
+ * (form body + expiresAt computation), best-effort revoke, and the
+ * fetchWithTimeout abort.
+ */
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import {
+  OAuthClientError,
+  buildAuthorizeUrl,
+  deriveVaultScopeFromMcpUrl,
+  discover,
+  exchangeCode,
+  fetchWithTimeout,
+  generateCodeChallenge,
+  generateCodeVerifier,
+  refreshToken,
+  registerClient,
+  revokeRemote,
+} from "../oauth-client.ts";
+type FetchFn = typeof fetch;
+/** A tiny router-style fake fetch. Maps URL → a handler returning a Response. */
+function fakeFetch(routes: Record<string, (req: { url: string; init?: RequestInit }) => Response>) {
+  const calls: { url: string; init?: RequestInit }[] = [];
+  const fn = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input.toString();
+    calls.push({ url, init });
+    // Match by pathname (ignore query) OR full url.
+    const path = new URL(url).pathname;
+    const handler = routes[url] ?? routes[path];
+    if (!handler) return new Response("not found", { status: 404 });
+    return handler({ url, init });
+  }) as unknown as FetchFn;
+  return { fn, calls };
+}
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+// === PKCE ===================================================================
+describe("PKCE", () => {
+  test("verifier is base64url, challenge is its S256", () => {
+    const v = generateCodeVerifier();
+    expect(v).toMatch(/^[A-Za-z0-9_-]+$/);
+    const c = generateCodeChallenge(v);
+    expect(c).toBe(createHash("sha256").update(v).digest("base64url"));
+  });
+  test("verifiers are distinct (random)", () => {
+    expect(generateCodeVerifier()).not.toBe(generateCodeVerifier());
+  });
+});
+// === Discovery ==============================================================
+describe("discover", () => {
+  test("RFC 9728 → 8414 (resource advertises authorization_servers)", async () => {
+    const { fn } = fakeFetch({
+      "https://remote.test/.well-known/oauth-protected-resource": () =>
+        json({
+          resource: "https://remote.test",
+          authorization_servers: ["https://issuer.test"],
+          scopes_supported: ["vault:eng:read", "vault:eng:write"],
+        }),
+      "https://issuer.test/.well-known/oauth-authorization-server": () =>
+        json({
+          issuer: "https://issuer.test",
+          authorization_endpoint: "https://issuer.test/oauth/authorize",
+          token_endpoint: "https://issuer.test/oauth/token",
+          registration_endpoint: "https://issuer.test/oauth/register",
+          revocation_endpoint: "https://issuer.test/oauth/revoke",
+        }),
+    });
+    const d = await discover("https://remote.test/vault/eng/mcp", fn);
+    expect(d.issuer).toBe("https://issuer.test");
+    expect(d.authorizationEndpoint).toBe("https://issuer.test/oauth/authorize");
+    expect(d.tokenEndpoint).toBe("https://issuer.test/oauth/token");
+    expect(d.registrationEndpoint).toBe("https://issuer.test/oauth/register");
+    expect(d.revocationEndpoint).toBe("https://issuer.test/oauth/revoke");
+    // 9728 scopes win
+    expect(d.scopesSupported).toEqual(["vault:eng:read", "vault:eng:write"]);
+  });
+  test("8414-only fallback (no 9728 doc → MCP origin is the issuer)", async () => {
+    const { fn, calls } = fakeFetch({
+      "https://solo.test/.well-known/oauth-protected-resource": () =>
+        new Response("nope", { status: 404 }),
+      "https://solo.test/.well-known/oauth-authorization-server": () =>
+        json({
+          issuer: "https://solo.test",
+          authorization_endpoint: "https://solo.test/authorize",
+          token_endpoint: "https://solo.test/token",
+          scopes_supported: ["mcp:read"],
+        }),
+    });
+    const d = await discover("https://solo.test/mcp", fn);
+    expect(d.issuer).toBe("https://solo.test");
+    expect(d.authorizationEndpoint).toBe("https://solo.test/authorize");
+    // scopes from 8414 (no 9728)
+    expect(d.scopesSupported).toEqual(["mcp:read"]);
+    // it DID try the 9728 doc first
+    expect(calls.some((c) => c.url.includes("oauth-protected-resource"))).toBe(true);
+  });
+  test("throws OAuthClientError when the 8414 doc lacks endpoints", async () => {
+    const { fn } = fakeFetch({
+      "https://bad.test/.well-known/oauth-protected-resource": () =>
+        json({ authorization_servers: ["https://bad.test"] }),
+      "https://bad.test/.well-known/oauth-authorization-server": () => json({ issuer: "x" }),
+    });
+    await expect(discover("https://bad.test/mcp", fn)).rejects.toBeInstanceOf(OAuthClientError);
+  });
+  test("throws on an invalid mcp url", async () => {
+    const { fn } = fakeFetch({});
+    await expect(discover("not-a-url", fn)).rejects.toBeInstanceOf(OAuthClientError);
+  });
+});
+// === DCR ====================================================================
+describe("registerClient", () => {
+  test("posts RFC 7591 body, returns client_id", async () => {
+    const { fn, calls } = fakeFetch({
+      "https://issuer.test/oauth/register": () => json({ client_id: "dcr-abc123" }, 201),
+    });
+    const r = await registerClient(
+      "https://issuer.test/oauth/register",
+      "https://hub.test/oauth/agent-grant/callback",
+      fn,
+    );
+    expect(r.clientId).toBe("dcr-abc123");
+    const body = JSON.parse((calls[0]?.init?.body as string) ?? "{}");
+    expect(body.redirect_uris).toEqual(["https://hub.test/oauth/agent-grant/callback"]);
+    expect(body.token_endpoint_auth_method).toBe("none");
+    expect(body.grant_types).toEqual(["authorization_code", "refresh_token"]);
+    expect(body.response_types).toEqual(["code"]);
+  });
+  test("throws when the response lacks client_id", async () => {
+    const { fn } = fakeFetch({
+      "https://issuer.test/oauth/register": () => json({ nope: true }),
+    });
+    await expect(
+      registerClient("https://issuer.test/oauth/register", "https://hub.test/cb", fn),
+    ).rejects.toBeInstanceOf(OAuthClientError);
+  });
+  test("throws on a non-2xx", async () => {
+    const { fn } = fakeFetch({
+      "https://issuer.test/oauth/register": () => new Response("forbidden", { status: 403 }),
+    });
+    await expect(
+      registerClient("https://issuer.test/oauth/register", "https://hub.test/cb", fn),
+    ).rejects.toBeInstanceOf(OAuthClientError);
+  });
+});
+// === buildAuthorizeUrl ======================================================
+describe("buildAuthorizeUrl", () => {
+  test("includes S256, state, challenge, and scope", () => {
+    const url = new URL(
+      buildAuthorizeUrl({
+        authorizationEndpoint: "https://issuer.test/oauth/authorize",
+        clientId: "cid",
+        redirectUri: "https://hub.test/oauth/agent-grant/callback",
+        scope: "vault:eng:read vault:eng:write",
+        state: "st-123",
+        codeChallenge: "chal-xyz",
+      }),
+    );
+    expect(url.origin + url.pathname).toBe("https://issuer.test/oauth/authorize");
+    expect(url.searchParams.get("response_type")).toBe("code");
+    expect(url.searchParams.get("client_id")).toBe("cid");
+    expect(url.searchParams.get("redirect_uri")).toBe(
+      "https://hub.test/oauth/agent-grant/callback",
+    );
+    expect(url.searchParams.get("scope")).toBe("vault:eng:read vault:eng:write");
+    expect(url.searchParams.get("state")).toBe("st-123");
+    expect(url.searchParams.get("code_challenge")).toBe("chal-xyz");
+    expect(url.searchParams.get("code_challenge_method")).toBe("S256");
+  });
+  test("omits scope when not provided", () => {
+    const url = new URL(
+      buildAuthorizeUrl({
+        authorizationEndpoint: "https://issuer.test/oauth/authorize",
+        clientId: "cid",
+        redirectUri: "https://hub.test/cb",
+        state: "st",
+        codeChallenge: "ch",
+      }),
+    );
+    expect(url.searchParams.has("scope")).toBe(false);
+  });
+});
+// === exchangeCode + refreshToken ============================================
+describe("exchangeCode", () => {
+  test("posts the form, computes expiresAt from expires_in", async () => {
+    const fixedNow = new Date("2026-06-18T12:00:00.000Z");
+    const { fn, calls } = fakeFetch({
+      "https://issuer.test/oauth/token": () =>
+        json({
+          access_token: "at-1",
+          refresh_token: "rt-1",
+          expires_in: 3600,
+          token_type: "Bearer",
+          scope: "vault:eng:read",
+        }),
+    });
+    const res = await exchangeCode(
+      {
+        tokenEndpoint: "https://issuer.test/oauth/token",
+        code: "code-1",
+        redirectUri: "https://hub.test/cb",
+        codeVerifier: "verifier-1",
+        clientId: "cid",
+        now: () => fixedNow,
+      },
+      fn,
+    );
+    expect(res.access_token).toBe("at-1");
+    expect(res.refresh_token).toBe("rt-1");
+    expect(res.expiresAt).toBe(new Date(fixedNow.getTime() + 3600 * 1000).toISOString());
+    expect(res.scope).toBe("vault:eng:read");
+    // form body assertions
+    const body = new URLSearchParams((calls[0]?.init?.body as string) ?? "");
+    expect(body.get("grant_type")).toBe("authorization_code");
+    expect(body.get("code")).toBe("code-1");
+    expect(body.get("code_verifier")).toBe("verifier-1");
+    expect(body.get("redirect_uri")).toBe("https://hub.test/cb");
+    expect(body.get("client_id")).toBe("cid");
+    expect((calls[0]?.init?.headers as Record<string, string>)["content-type"]).toBe(
+      "application/x-www-form-urlencoded",
+    );
+  });
+  test("throws OAuthClientError on an error response", async () => {
+    const { fn } = fakeFetch({
+      "https://issuer.test/oauth/token": () =>
+        json({ error: "invalid_grant", error_description: "code expired" }, 400),
+    });
+    await expect(
+      exchangeCode(
+        {
+          tokenEndpoint: "https://issuer.test/oauth/token",
+          code: "x",
+          redirectUri: "https://hub.test/cb",
+          codeVerifier: "v",
+          clientId: "cid",
+        },
+        fn,
+      ),
+    ).rejects.toBeInstanceOf(OAuthClientError);
+  });
+  test("throws when access_token is missing", async () => {
+    const { fn } = fakeFetch({
+      "https://issuer.test/oauth/token": () => json({ token_type: "Bearer" }),
+    });
+    await expect(
+      exchangeCode(
+        {
+          tokenEndpoint: "https://issuer.test/oauth/token",
+          code: "x",
+          redirectUri: "https://hub.test/cb",
+          codeVerifier: "v",
+          clientId: "cid",
+        },
+        fn,
+      ),
+    ).rejects.toBeInstanceOf(OAuthClientError);
+  });
+});
+describe("refreshToken", () => {
+  test("posts grant_type=refresh_token, returns new tokens", async () => {
+    const fixedNow = new Date("2026-06-18T12:00:00.000Z");
+    const { fn, calls } = fakeFetch({
+      "https://issuer.test/oauth/token": () =>
+        json({ access_token: "at-2", refresh_token: "rt-2", expires_in: 1800 }),
+    });
+    const res = await refreshToken(
+      {
+        tokenEndpoint: "https://issuer.test/oauth/token",
+        refreshToken: "rt-1",
+        clientId: "cid",
+        now: () => fixedNow,
+      },
+      fn,
+    );
+    expect(res.access_token).toBe("at-2");
+    expect(res.refresh_token).toBe("rt-2");
+    expect(res.expiresAt).toBe(new Date(fixedNow.getTime() + 1800 * 1000).toISOString());
+    const body = new URLSearchParams((calls[0]?.init?.body as string) ?? "");
+    expect(body.get("grant_type")).toBe("refresh_token");
+    expect(body.get("refresh_token")).toBe("rt-1");
+    expect(body.get("client_id")).toBe("cid");
+  });
+  test("rejects on a revoked/expired refresh token", async () => {
+    const { fn } = fakeFetch({
+      "https://issuer.test/oauth/token": () => json({ error: "invalid_grant" }, 400),
+    });
+    await expect(
+      refreshToken(
+        { tokenEndpoint: "https://issuer.test/oauth/token", refreshToken: "dead", clientId: "c" },
+        fn,
+      ),
+    ).rejects.toBeInstanceOf(OAuthClientError);
+  });
+});
+// === revokeRemote (best-effort) =============================================
+describe("revokeRemote", () => {
+  test("posts the revocation form", async () => {
+    const { fn, calls } = fakeFetch({
+      "https://issuer.test/oauth/revoke": () => new Response(null, { status: 200 }),
+    });
+    await revokeRemote(
+      {
+        revocationEndpoint: "https://issuer.test/oauth/revoke",
+        refreshToken: "rt-1",
+        clientId: "cid",
+      },
+      fn,
+    );
+    const body = new URLSearchParams((calls[0]?.init?.body as string) ?? "");
+    expect(body.get("token")).toBe("rt-1");
+    expect(body.get("token_type_hint")).toBe("refresh_token");
+  });
+  test("swallows errors (network failure must not throw)", async () => {
+    const fn = (async () => {
+      throw new Error("network down");
+    }) as unknown as FetchFn;
+    // Must resolve, not reject.
+    await expect(
+      revokeRemote(
+        {
+          revocationEndpoint: "https://issuer.test/oauth/revoke",
+          refreshToken: "x",
+          clientId: "c",
+        },
+        fn,
+      ),
+    ).resolves.toBeUndefined();
+  });
+  test("swallows a non-2xx response", async () => {
+    const { fn } = fakeFetch({
+      "https://issuer.test/oauth/revoke": () => new Response("nope", { status: 500 }),
+    });
+    await expect(
+      revokeRemote(
+        {
+          revocationEndpoint: "https://issuer.test/oauth/revoke",
+          refreshToken: "x",
+          clientId: "c",
+        },
+        fn,
+      ),
+    ).resolves.toBeUndefined();
+  });
+});
+// === fetchWithTimeout =======================================================
+describe("fetchWithTimeout", () => {
+  test("aborts a hung request after the timeout", async () => {
+    // A fetch that never resolves until aborted.
+    const fn = ((_url: string, init?: RequestInit) =>
+      new Promise((_resolve, reject) => {
+        const signal = init?.signal;
+        signal?.addEventListener("abort", () => reject(new Error("aborted")));
+      })) as unknown as FetchFn;
+    await expect(fetchWithTimeout("https://slow.test", { timeout: 10 }, fn)).rejects.toBeTruthy();
+  });
+  test("passes through a fast response", async () => {
+    const fn = (async () => new Response("ok", { status: 200 })) as unknown as FetchFn;
+    const res = await fetchWithTimeout("https://fast.test", { timeout: 1000 }, fn);
+    expect(res.status).toBe(200);
+  });
+});
+// === deriveVaultScopeFromMcpUrl (#671) ======================================
+describe("deriveVaultScopeFromMcpUrl", () => {
+  test("a Parachute vault MCP URL → least-privilege vault:<name>:read", () => {
+    expect(deriveVaultScopeFromMcpUrl("https://hub.test/vault/research/mcp")).toBe(
+      "vault:research:read",
+    );
+  });
+  test("a trailing slash after /mcp still matches", () => {
+    expect(deriveVaultScopeFromMcpUrl("https://hub.test/vault/research/mcp/")).toBe(
+      "vault:research:read",
+    );
+  });
+  test("a vault name with dot/dash/underscore is captured", () => {
+    expect(deriveVaultScopeFromMcpUrl("https://hub.test/vault/my-team_v2.0/mcp")).toBe(
+      "vault:my-team_v2.0:read",
+    );
+  });
+  test("a query string / fragment does not break the match", () => {
+    expect(deriveVaultScopeFromMcpUrl("https://hub.test/vault/research/mcp?x=1#frag")).toBe(
+      "vault:research:read",
+    );
+  });
+  test("a non-vault MCP URL → null (caller falls back to scopes_supported)", () => {
+    expect(deriveVaultScopeFromMcpUrl("https://remote.test/mcp")).toBeNull();
+    expect(deriveVaultScopeFromMcpUrl("https://remote.test/some/other/mcp")).toBeNull();
+  });
+  test("a deeper path after /mcp is NOT a vault MCP (anchored) → null", () => {
+    expect(deriveVaultScopeFromMcpUrl("https://hub.test/vault/research/mcp/extra")).toBeNull();
+  });
+  test("a /vault/ path with no name segment → null", () => {
+    expect(deriveVaultScopeFromMcpUrl("https://hub.test/vault//mcp")).toBeNull();
+  });
+  test("an unparseable URL → null", () => {
+    expect(deriveVaultScopeFromMcpUrl("not a url")).toBeNull();
+  });
+});