@openparachute/hub 0.7.2 → 0.7.3-rc.2

package/package.json

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

package/src/__tests__/admin-agent-grants.test.ts

@@ -1353,6 +1353,119 @@ describe("GET /oauth/agent-grant/callback", () => {
   });
 });
 
+// === returnTo: send the operator back to where they started ================
+//
+// The OAuth-consent round-trip used to dead-end on a "close this tab" page. A
+// same-origin (hub-relative) `returnTo` on the approve body is stashed on the
+// flow + 302'd to on success (with `?mcp_connected=1`). The open-redirect guard
+// (`isSafeHubReturnTo`, reused) is the load-bearing property: an off-origin /
+// scheme-relative value is dropped at stash time and never lands in Location.
+describe("approve(mcp) + callback — returnTo round-trip", () => {
+  async function startFlowWithBody(body: Record<string, unknown>): Promise<string> {
+    const bearer = await moduleBearer();
+    const cookie = await operatorCookie();
+    const created = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "a",
+          connection: { kind: "mcp", target: "https://remote.test/mcp" },
+        }),
+      ),
+    );
+    const id = created.id as string;
+    await dispatch(cookieReq("POST", `/admin/grants/${id}/approve`, cookie, body));
+    return id;
+  }
+
+  test("approve stashes a valid same-origin returnTo on the flow", async () => {
+    currentOAuth = fakeOAuth();
+    await startFlowWithBody({ returnTo: "/admin/grants" });
+    const flow = getFlowByState(harness.flowsStorePath, "fixed-state");
+    expect(flow?.returnTo).toBe("/admin/grants");
+  });
+
+  test("approve drops an off-origin returnTo (absolute URL) — open-redirect guard", async () => {
+    currentOAuth = fakeOAuth();
+    await startFlowWithBody({ returnTo: "https://evil.example/steal" });
+    const flow = getFlowByState(harness.flowsStorePath, "fixed-state");
+    expect(flow?.returnTo).toBeUndefined();
+  });
+
+  test("approve drops a scheme-relative returnTo (//host) — open-redirect guard", async () => {
+    currentOAuth = fakeOAuth();
+    await startFlowWithBody({ returnTo: "//evil.example/steal" });
+    const flow = getFlowByState(harness.flowsStorePath, "fixed-state");
+    expect(flow?.returnTo).toBeUndefined();
+  });
+
+  test("approve drops a `..` path-traversal returnTo — open-redirect guard", async () => {
+    currentOAuth = fakeOAuth();
+    await startFlowWithBody({ returnTo: "/admin/../../etc/passwd" });
+    const flow = getFlowByState(harness.flowsStorePath, "fixed-state");
+    expect(flow?.returnTo).toBeUndefined();
+  });
+
+  test("approve drops a PERCENT-ENCODED `..` returnTo (%2e%2e) — open-redirect guard", async () => {
+    // `new URL()` decodes %2e%2e before emitting the redirect path, so the guard
+    // must reject the encoded form too, not just the literal `..`.
+    currentOAuth = fakeOAuth();
+    await startFlowWithBody({ returnTo: "/%2e%2e/etc/passwd" });
+    const flow = getFlowByState(harness.flowsStorePath, "fixed-state");
+    expect(flow?.returnTo).toBeUndefined();
+  });
+
+  test("callback 302-redirects to a valid returnTo (with mcp_connected=1) on success", async () => {
+    currentOAuth = fakeOAuth();
+    const id = await startFlowWithBody({ returnTo: "/admin/grants?agent=a" });
+    const res = await callback("?code=ok&state=fixed-state");
+    expect(res.status).toBe(302);
+    const location = res.headers.get("location") ?? "";
+    expect(location).toContain("/admin/grants");
+    expect(location).toContain("agent=a");
+    expect(location).toContain("mcp_connected=1");
+    // Same-origin only — never a host/scheme in Location.
+    expect(location.startsWith("/")).toBe(true);
+    expect(location.startsWith("//")).toBe(false);
+    // The grant still flipped to approved (the success side-effects all ran).
+    expect(readGrants(harness.storePath).find((r) => r.id === id)?.status).toBe("approved");
+  });
+
+  test("callback overwrites a pre-existing mcp_connected param rather than duplicating it", async () => {
+    currentOAuth = fakeOAuth();
+    await startFlowWithBody({ returnTo: "/admin/grants?mcp_connected=0" });
+    const res = await callback("?code=ok&state=fixed-state");
+    expect(res.status).toBe(302);
+    const location = res.headers.get("location") ?? "";
+    expect(location).toContain("mcp_connected=1");
+    expect(location).not.toContain("mcp_connected=0");
+    // exactly one occurrence (searchParams.set semantics, not append)
+    expect(location.match(/mcp_connected=/g)?.length).toBe(1);
+  });
+
+  test("callback falls back to the close-tab HTML when no returnTo was stashed", async () => {
+    currentOAuth = fakeOAuth();
+    const id = await startFlowWithBody({}); // no returnTo
+    const res = await callback("?code=ok&state=fixed-state");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    expect(await res.text()).toContain("Connected");
+    expect(readGrants(harness.storePath).find((r) => r.id === id)?.status).toBe("approved");
+  });
+
+  test("callback falls back to the close-tab HTML for an unsafe returnTo (never 302s off-origin)", async () => {
+    currentOAuth = fakeOAuth();
+    // The unsafe value was already dropped at stash time, so the callback has no
+    // returnTo to honor — it renders the back-compat page rather than redirecting.
+    const id = await startFlowWithBody({ returnTo: "https://evil.example/steal" });
+    const res = await callback("?code=ok&state=fixed-state");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    expect(res.headers.get("location")).toBeNull();
+    expect(await res.text()).toContain("Connected");
+    expect(readGrants(harness.storePath).find((r) => r.id === id)?.status).toBe("approved");
+  });
+});
+
 describe("material(mcp) — auto-refresh", () => {
   // Drive a grant to approved-via-OAuth, with expiry in the (near) past/future.
   async function approvedViaOAuth(expiresAt: string): Promise<string> {

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/admin-agent-grants.ts

@@ -80,6 +80,7 @@ import {
 } from "./jwt-sign.ts";
 import { type OAuthClient, deriveVaultScopeFromMcpUrl, realOAuthClient } from "./oauth-client.ts";
 import { type PendingFlow, deleteFlow, getFlowByState, putFlow } from "./oauth-flows-store.ts";
+import { isSafeHubReturnTo } from "./oauth-handlers.ts";
 import { findSession, parseSessionCookie } from "./sessions.ts";
 import { isFirstAdmin } from "./users.ts";
 import { validateVaultName } from "./vault-name.ts";
@@ -630,10 +631,15 @@ async function approveGrant(req: Request, id: string, deps: AgentGrantsDeps): Pr
   const grant = getGrant(deps.storePath, id);
   if (!grant) return jsonError(404, "not_found", `no grant ${id}`);
 
-  let body: { token?: unknown } = {};
+  // `returnTo` is consumed ONLY by the mcp/OAuth path (approveMcpGrant), which
+  // is the one approve flow that hands the browser off to a remote consent
+  // screen and needs somewhere to land on return. vault/service approvals
+  // complete synchronously and return JSON — there's no redirect, so they
+  // ignore `returnTo` by design.
+  let body: { token?: unknown; returnTo?: unknown } = {};
   try {
     const raw = await req.text();
-    if (raw.trim().length > 0) body = JSON.parse(raw) as { token?: unknown };
+    if (raw.trim().length > 0) body = JSON.parse(raw) as { token?: unknown; returnTo?: unknown };
   } catch {
     return jsonError(400, "invalid_request", "body must be JSON when present");
   }
@@ -748,7 +754,7 @@ async function approveGrant(req: Request, id: string, deps: AgentGrantsDeps): Pr
  */
 async function approveMcpGrant(
   grant: GrantRecord,
-  body: { token?: unknown },
+  body: { token?: unknown; returnTo?: unknown },
   deps: AgentGrantsDeps,
   approvedAt: string,
 ): Promise<Response> {
@@ -850,6 +856,16 @@ async function approveMcpGrant(
       ? discovery.scopesSupported.join(" ")
       : undefined;
 
+  // OPTIONAL `returnTo` — the same-origin (hub-relative) page the operator
+  // started from (the agent ops surface / admin grants page). Stash it on the
+  // flow ONLY when it passes the shared open-redirect guard; absent/invalid →
+  // omit it (the callback then renders the back-compat close-tab page). This is
+  // the open-redirect-load-bearing check — reuse, don't reinvent.
+  const returnTo =
+    typeof body.returnTo === "string" && isSafeHubReturnTo(body.returnTo)
+      ? body.returnTo
+      : undefined;
+
   const flow: PendingFlow = {
     state,
     grantId: grant.id,
@@ -861,6 +877,7 @@ async function approveMcpGrant(
     mcpUrl,
     ...(scope ? { scope } : {}),
     redirectUri,
+    ...(returnTo ? { returnTo } : {}),
     createdAt: (deps.now?.() ?? new Date()).toISOString(),
   };
   putFlow(deps.flowsStorePath, flow, (deps.now?.() ?? new Date()).getTime());
@@ -1040,6 +1057,17 @@ export async function handleOAuthGrantCallback(
   // NEVER log a token.
   console.log(`agent grant approved: id=${grant.id} agent=${grant.agent} kind=mcp mode=oauth`);
 
+  // If the operator started from a hub page (agent ops surface / admin grants),
+  // send them back there instead of a dead-end "close this tab" screen. Re-run
+  // the open-redirect guard DEFENSIVELY at redirect time (the value was already
+  // gated at stash time; this is belt-and-suspenders against a tampered store).
+  // Append `?mcp_connected=1` (preserving any existing query) so the SPA can
+  // react (toast / refetch the grant). Absent/invalid returnTo → the
+  // back-compat close-tab page.
+  if (flow.returnTo && isSafeHubReturnTo(flow.returnTo)) {
+    return redirectToReturn(flow.returnTo);
+  }
+
   return htmlPage(
     200,
     "Connected",
@@ -1047,6 +1075,26 @@ export async function handleOAuthGrantCallback(
   );
 }
 
+/**
+ * 302 back to a same-origin (hub-relative) `returnTo`, appending
+ * `mcp_connected=1` so the SPA can show a success toast / refetch. The caller
+ * MUST have already passed `returnTo` through `isSafeHubReturnTo` — this builds
+ * the URL against a fixed dummy origin purely to merge the query param
+ * correctly, then emits only the path+query (never the origin), so a
+ * scheme-relative value can't leak through into the Location header.
+ */
+function redirectToReturn(returnTo: string): Response {
+  // Parse against a fixed base so query-string merging is correct even when
+  // returnTo already carries `?...`. Only `pathname + search + hash` is emitted.
+  const u = new URL(returnTo, "http://hub.invalid");
+  u.searchParams.set("mcp_connected", "1");
+  const location = `${u.pathname}${u.search}${u.hash}`;
+  return new Response(null, {
+    status: 302,
+    headers: { location, "cache-control": "no-store" },
+  });
+}
+
 /** Minimal server-rendered HTML — NEVER carries a token. */
 function htmlPage(status: number, heading: string, message: string): Response {
   const html = `<!doctype html>

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

package/src/oauth-flows-store.ts

@@ -52,6 +52,14 @@ export interface PendingFlow {
   readonly scope?: string;
   /** The hub's callback URL registered for this flow. */
   readonly redirectUri: string;
+  /**
+   * OPTIONAL same-origin (hub-relative) page the operator should be sent back
+   * to after a SUCCESSFUL consent — the agent ops surface / admin grants page
+   * they started from. Validated with `isSafeHubReturnTo` at stash time and
+   * (defensively) again at redirect time. Absent for flows started without one
+   * (and for all pre-existing on-disk flows — additive + back-compat).
+   */
+  readonly returnTo?: string;
   readonly createdAt: string;
 }
 
@@ -62,6 +70,10 @@ interface FlowsFile {
 function isPendingFlow(v: unknown): v is PendingFlow {
   if (!v || typeof v !== "object") return false;
   const f = v as Record<string, unknown>;
+  // `returnTo` is OPTIONAL + additive — absent on every pre-existing on-disk
+  // flow. Accept undefined; if present it must be a string (validated for
+  // open-redirect safety at the call sites, not here).
+  if (f.returnTo !== undefined && typeof f.returnTo !== "string") return false;
   return (
     typeof f.state === "string" &&
     typeof f.grantId === "string" &&

package/src/oauth-handlers.ts

@@ -1883,6 +1883,39 @@ export async function handleApproveClientPost(
   return redirectResponse(returnTo);
 }
 
+/**
+ * The load-bearing open-redirect guard, shared by every hub `return_to` gate.
+ * A safe hub-relative target is a SINGLE-slash root-relative path: same-origin
+ * to the hub, no scheme, no `//host` scheme-relative escape. Empty string is
+ * rejected.
+ *
+ * This is the same-origin core that `isSafeAuthorizeReturnTo` (OAuth-resume)
+ * builds on, and that broader same-origin gates (the agent-grant OAuth
+ * callback's `returnTo`) reuse directly — they need to return the operator to
+ * a `/admin/...` page, not specifically `/oauth/authorize`. Single source of
+ * truth for "is this an open redirect?" — do NOT reimplement the
+ * `startsWith("/") && !startsWith("//")` check elsewhere.
+ */
+export function isSafeHubReturnTo(value: string): boolean {
+  if (!value) return false;
+  // Reject scheme-relative ("//evil.example/foo") and absolute URLs. Only
+  // single-slash root-relative paths are allowed.
+  if (!value.startsWith("/") || value.startsWith("//")) return false;
+  // Reject `..` traversal sequences — literal AND percent-encoded (`%2e%2e`),
+  // since redirectToReturn's `new URL()` parse decodes them before emitting the
+  // path. They stay same-origin but a target that walks the path tree is never a
+  // legitimate return-to and lets a crafted value reach an unexpected hub path.
+  // (`/oauth/authorize?…` callers never carry `..`, so this is free for them.)
+  if (value.includes("..")) return false;
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    return false; // malformed percent-encoding → reject rather than guess
+  }
+  return !decoded.includes("..");
+}
+
 /**
  * Validate a form-submitted `return_to` value. Must be a hub-relative URL
  * (no scheme, no double-slash) targeting `/oauth/authorize` with a query
@@ -1895,13 +1928,10 @@ export async function handleApproveClientPost(
  * valid OAuth-resume target?" for the whole hub.
  */
 export function isSafeAuthorizeReturnTo(value: string): boolean {
-  if (!value) return false;
-  // Reject scheme-relative ("//evil.example/foo") and absolute URLs. Only
-  // single-slash root-relative paths are allowed.
-  if (!value.startsWith("/") || value.startsWith("//")) return false;
-  // Must target the authorize endpoint with a query string. The OAuth flow
-  // re-enters via GET /oauth/authorize?<original-params>; anything off-path
-  // is a misuse.
+  // Same-origin open-redirect guard first (shared single source of truth)…
+  if (!isSafeHubReturnTo(value)) return false;
+  // …then the authorize-specific path constraint: the OAuth flow re-enters
+  // via GET /oauth/authorize?<original-params>; anything off-path is a misuse.
   return value.startsWith("/oauth/authorize?");
 }