@openparachute/hub 0.7.3-rc.1 → 0.7.3-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.3-rc.1",
+  "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/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-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?");
 }