@openparachute/hub 0.7.2 → 0.7.3-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.2",
+  "version": "0.7.3-rc.1",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

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

@@ -126,6 +126,81 @@ describe("discover", () => {
     const { fn } = fakeFetch({});
     await expect(discover("not-a-url", fn)).rejects.toBeInstanceOf(OAuthClientError);
   });
+
+  test("RFC 9728 path-inserted PRM + auth server on a SEPARATE host (the Read.ai shape)", async () => {
+    // The PRM lives ONLY at the path-inserted location (host root 404s) and
+    // points at an auth server on a DIFFERENT host. The pre-fix discover()
+    // probed only the host-root PRM, fell back to mcp-origin-as-issuer, and
+    // 404'd on the (nonexistent) authorization-server doc — this is the
+    // regression that blocked connecting Read.ai.
+    const { fn, calls } = fakeFetch({
+      "https://api.example.ai/.well-known/oauth-protected-resource/mcp": () =>
+        json({
+          resource: "https://api.example.ai/mcp",
+          authorization_servers: ["https://authn.example.ai/"],
+          scopes_supported: ["mcp:execute", "meeting:read"],
+        }),
+      "https://authn.example.ai/.well-known/oauth-authorization-server": () =>
+        json({
+          issuer: "https://authn.example.ai/",
+          authorization_endpoint: "https://authn.example.ai/oauth2/auth",
+          token_endpoint: "https://authn.example.ai/oauth2/token",
+          registration_endpoint: "https://api.example.ai/oauth/register",
+        }),
+    });
+    const d = await discover("https://api.example.ai/mcp/", fn);
+    expect(d.issuer).toBe("https://authn.example.ai/");
+    expect(d.authorizationEndpoint).toBe("https://authn.example.ai/oauth2/auth");
+    expect(d.tokenEndpoint).toBe("https://authn.example.ai/oauth2/token");
+    expect(d.registrationEndpoint).toBe("https://api.example.ai/oauth/register");
+    // 9728 scopes win
+    expect(d.scopesSupported).toEqual(["mcp:execute", "meeting:read"]);
+    // proves the path-inserted PRM probe was used (host-root PRM isn't defined)
+    expect(
+      calls.some((c) => c.url === "https://api.example.ai/.well-known/oauth-protected-resource/mcp"),
+    ).toBe(true);
+  });
+
+  test("AS discovery falls back to openid-configuration when oauth-authorization-server is absent", async () => {
+    const { fn } = fakeFetch({
+      "https://api.example.ai/.well-known/oauth-protected-resource/mcp": () =>
+        json({ authorization_servers: ["https://authn.example.ai/"] }),
+      // No RFC 8414 doc — only OIDC discovery.
+      "https://authn.example.ai/.well-known/openid-configuration": () =>
+        json({
+          issuer: "https://authn.example.ai/",
+          authorization_endpoint: "https://authn.example.ai/oauth2/auth",
+          token_endpoint: "https://authn.example.ai/oauth2/token",
+        }),
+    });
+    const d = await discover("https://api.example.ai/mcp", fn);
+    expect(d.tokenEndpoint).toBe("https://authn.example.ai/oauth2/token");
+  });
+
+  test("malformed authorization_servers issuer throws OAuthClientError (not a raw TypeError)", async () => {
+    const { fn } = fakeFetch({
+      "https://api.example.ai/.well-known/oauth-protected-resource/mcp": () =>
+        json({ authorization_servers: ["not-a-url"] }),
+    });
+    await expect(discover("https://api.example.ai/mcp", fn)).rejects.toBeInstanceOf(OAuthClientError);
+  });
+
+  test("AS discovery uses the OIDC-append form for a path-ful issuer", async () => {
+    const { fn } = fakeFetch({
+      "https://api.example.ai/.well-known/oauth-protected-resource/mcp": () =>
+        json({ authorization_servers: ["https://idp.example.ai/tenant1"] }),
+      // ONLY the OIDC-append URL exists (issuer-path + /.well-known/openid-configuration),
+      // not the RFC 8414 insert form — proves the append candidate is generated.
+      "https://idp.example.ai/tenant1/.well-known/openid-configuration": () =>
+        json({
+          issuer: "https://idp.example.ai/tenant1",
+          authorization_endpoint: "https://idp.example.ai/tenant1/auth",
+          token_endpoint: "https://idp.example.ai/tenant1/token",
+        }),
+    });
+    const d = await discover("https://api.example.ai/mcp", fn);
+    expect(d.tokenEndpoint).toBe("https://idp.example.ai/tenant1/token");
+  });
 });
 
 // === DCR ====================================================================

package/src/oauth-client.ts

@@ -28,6 +28,15 @@ export type FetchFn = typeof fetch;
 /** Default outbound timeout for every OAuth-client request. */
 const DEFAULT_TIMEOUT_MS = 15_000;
 
+/**
+ * Shorter timeout for best-effort DISCOVERY probes. Discovery tries several
+ * well-known candidates in priority order (path-inserted, host-root, OIDC), so a
+ * full 15s per probe could stack into a long wall-clock wait on a slow/firewalled
+ * remote. These metadata GETs are quick when they exist; a tight ceiling bounds
+ * the worst case while still tolerating a sluggish responder.
+ */
+const DISCOVERY_PROBE_TIMEOUT_MS = 6_000;
+
 /**
  * `fetch` with an AbortController timeout. The hub has no shared fetch wrapper,
  * so this lives here for all outbound OAuth-client calls — a slow/hung remote
@@ -93,10 +102,15 @@ async function fetchJson(
   url: string,
   fetchFn: FetchFn,
   what: string,
+  timeoutMs?: number,
 ): Promise<Record<string, unknown>> {
   let res: Response;
   try {
-    res = await fetchWithTimeout(url, { headers: { accept: "application/json" } }, fetchFn);
+    res = await fetchWithTimeout(
+      url,
+      { headers: { accept: "application/json" }, ...(timeoutMs ? { timeout: timeoutMs } : {}) },
+      fetchFn,
+    );
   } catch (err) {
     throw new OAuthClientError(`${what}: request to ${url} failed`, err);
   }
@@ -125,44 +139,120 @@ function asStringArray(v: unknown): string[] | undefined {
   return out.length > 0 ? out : undefined;
 }
 
+/**
+ * RFC 9728 §3.1 / RFC 8414 §3.1 well-known URL candidates for a resource or
+ * issuer URL. The spec INSERTS the well-known segment after the host while
+ * PRESERVING the URL's path: `https://h/p` → `https://h/.well-known/<seg>/p`.
+ * We try the path-inserted form FIRST (correct when the resource/issuer carries
+ * a path — e.g. an MCP served at `/mcp`, or a multi-tenant issuer at `/tenant`),
+ * then the host-root form (`https://h/.well-known/<seg>`) as a fallback for
+ * path-less deployments + older servers. De-duplicated, in priority order.
+ */
+function wellKnownCandidates(url: string, segment: string): string[] {
+  const u = new URL(url);
+  // The query string is intentionally excluded (u.pathname omits it) — RFC 9728
+  // §3.1 builds the well-known URL from the resource PATH only.
+  const path = u.pathname.replace(/\/+$/, ""); // drop trailing slash(es)
+  const root = `${u.origin}/.well-known/${segment}`;
+  const out = path ? [`${u.origin}/.well-known/${segment}${path}`, root] : [root];
+  return [...new Set(out)];
+}
+
+/**
+ * Fetch the first candidate URL (in priority order) that returns a valid JSON
+ * object. Lets discovery probe the path-inserted well-known location first, then
+ * fall back to the host root. If EVERY candidate fails, throws an
+ * OAuthClientError naming all tried locations (so a failure points at every
+ * probe, not just the last).
+ */
+async function fetchJsonFirst(
+  urls: string[],
+  fetchFn: FetchFn,
+  what: string,
+  timeoutMs?: number,
+): Promise<Record<string, unknown>> {
+  const errors: string[] = [];
+  for (const url of urls) {
+    try {
+      return await fetchJson(url, fetchFn, what, timeoutMs);
+    } catch (err) {
+      errors.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+  throw new OAuthClientError(
+    `${what}: no metadata found — tried ${urls.length} location(s): ${errors.join(" | ")}`,
+  );
+}
+
 /**
  * Discover the issuer + endpoints for a remote MCP URL.
  *
- *   1. RFC 9728: GET <mcp-origin>/.well-known/oauth-protected-resource →
- *      authorization_servers[0] = issuer (+ scopes_supported).
- *   2. RFC 8414: GET <issuer>/.well-known/oauth-authorization-server →
+ *   1. RFC 9728: GET <mcp>/.well-known/oauth-protected-resource[/<path>] →
+ *      authorization_servers[0] = issuer (+ scopes_supported). The path-inserted
+ *      location is tried first (the modern MCP shape: an MCP at `/mcp` advertises
+ *      at `/.well-known/oauth-protected-resource/mcp`, and its auth server often
+ *      lives on a SEPARATE host), then the host root.
+ *   2. RFC 8414 / OIDC: GET <issuer>/.well-known/oauth-authorization-server then
+ *      /.well-known/openid-configuration (each path-inserted then host-root) →
  *      authorization_endpoint, token_endpoint, registration_endpoint,
  *      revocation_endpoint (+ scopes_supported fallback).
  *
  * If the resource has no 9728 doc, falls back to treating the MCP origin itself
- * as the issuer and reading its 8414 doc directly (8414-only resources).
+ * as the issuer and reading its 8414/OIDC doc directly (8414-only resources).
  */
 export async function discover(mcpUrl: string, fetchFn: FetchFn = fetch): Promise<DiscoveryResult> {
   const origin = originOf(mcpUrl);
 
-  // Step 1 — RFC 9728 (best-effort; some resources only expose 8414).
+  // Step 1 — RFC 9728 protected-resource metadata (best-effort; some resources
+  // only expose 8414). Probe the PATH-INSERTED location first (an MCP served at
+  // `/mcp` advertises at `/.well-known/oauth-protected-resource/mcp`), then the
+  // host root — this is what lets a resource whose auth server lives on a
+  // SEPARATE host be discovered at all.
   let issuer: string | undefined;
   let prScopes: string[] | undefined;
   try {
-    const pr = await fetchJson(
-      `${origin}/.well-known/oauth-protected-resource`,
+    const pr = await fetchJsonFirst(
+      wellKnownCandidates(mcpUrl, "oauth-protected-resource"),
       fetchFn,
       "protected-resource discovery",
+      DISCOVERY_PROBE_TIMEOUT_MS,
     );
     const servers = asStringArray(pr.authorization_servers);
     issuer = servers?.[0];
     prScopes = asStringArray(pr.scopes_supported);
   } catch {
-    // No 9728 doc — fall back to the MCP origin as issuer.
+    // No 9728 doc anywhere — fall back to the MCP origin as issuer.
     issuer = undefined;
   }
   if (!issuer) issuer = origin;
 
-  // Step 2 — RFC 8414 on the issuer.
-  const as = await fetchJson(
-    `${issuer.replace(/\/+$/, "")}/.well-known/oauth-authorization-server`,
+  // The issuer comes from the (attacker-influenceable) PRM doc — validate it
+  // parses as a URL so a malformed value surfaces as an OAuthClientError rather
+  // than a raw TypeError out of the candidate construction below.
+  let issuerUrl: URL;
+  try {
+    issuerUrl = new URL(issuer);
+  } catch {
+    throw new OAuthClientError(`authorization_servers[0] is not a valid URL: ${issuer}`);
+  }
+
+  // Step 2 — RFC 8414 / OIDC metadata on the issuer. Path-inserted before host
+  // root, and `oauth-authorization-server` before `openid-configuration`, so an
+  // issuer that sits at a path or only serves OIDC discovery still resolves. Plus
+  // the OIDC Discovery 1.0 §4.1 APPEND form (`<issuer-with-path>/.well-known/
+  // openid-configuration`) for a path-ful issuer — distinct from the 8414 INSERT.
+  const asCandidates = [
+    ...wellKnownCandidates(issuer, "oauth-authorization-server"),
+    ...wellKnownCandidates(issuer, "openid-configuration"),
+  ];
+  if (issuerUrl.pathname.replace(/\/+$/, "")) {
+    asCandidates.push(`${issuer.replace(/\/+$/, "")}/.well-known/openid-configuration`);
+  }
+  const as = await fetchJsonFirst(
+    [...new Set(asCandidates)],
     fetchFn,
     "authorization-server discovery",
+    DISCOVERY_PROBE_TIMEOUT_MS,
   );
 
   const authorizationEndpoint = asString(as.authorization_endpoint);