@openparachute/hub 0.5.13-rc.37 → 0.5.13-rc.38

package/package.json

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

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

@@ -3970,13 +3970,20 @@ describe("inline approve button on pending /oauth/authorize (#208)", () => {
     });
   }
 
-  test("session absent → page renders Sign-in CTA + shareable deep link (no CLI message)", async () => {
-    // Approval-UX rc.19: the unauthenticated viewer no longer sees a
-    // "Ask the operator to run `parachute auth approve-client <id>`"
-    // message. The web approval path (#277) is the canonical recovery
-    // now — render a primary Sign-in CTA wired to /login?next=/admin/...
-    // and a shareable deep link the operator can send to whoever runs
-    // the hub.
+  test("session absent → Sign-in CTA preserves the authorize URL through login + shareable deep link", async () => {
+    // Approval-UX rc.19: the unauthenticated viewer sees no CLI hint —
+    // the web approval path (#277) is the canonical recovery now. The
+    // primary Sign-in CTA wires `/login?next=<authorize URL>` so post-
+    // login the operator lands BACK on the same `/oauth/authorize?...`
+    // request — now authenticated, they see the inline approve form, one
+    // click resumes the OAuth flow through consent → redirect_uri. The
+    // shareable secondary deep link still points at the SPA approve page
+    // (it's for sharing with another admin, not for the in-flight flow).
+    //
+    // Pre-fix the Sign-in CTA also pointed at the SPA approve page —
+    // approving the client but discarding the authorize URL params, so
+    // the calling app (e.g. Claude.ai MCP) was never told and the user
+    // looped on retry. Caught by Aaron on the Render deploy.
     const { db, cleanup } = await makeDb();
     try {
       const reg = registerClient(db, {
@@ -3984,19 +3991,34 @@ describe("inline approve button on pending /oauth/authorize (#208)", () => {
         clientName: "MyApp",
         status: "pending",
       });
-      const req = new Request(pendingAuthorizeUrl(reg.client.clientId));
+      const authorizePath = pendingAuthorizeUrl(reg.client.clientId);
+      const req = new Request(authorizePath);
       const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
       expect(res.status).toBe(403);
       const html = await res.text();
       expect(html).toContain("App not yet approved");
-      // Primary CTA: Sign-in link wired to land the admin directly on
-      // the approval page after authenticating.
+      // Primary CTA: Sign-in link wired to round-trip the operator back
+      // to the original /oauth/authorize?... URL after login (resumes the
+      // OAuth flow rather than dead-ending at the SPA approve page).
       expect(html).toContain("Sign in as admin to approve");
-      const expectedLoginHref = `/login?next=${encodeURIComponent(
+      const requestUrl = new URL(authorizePath);
+      const returnTo = `${requestUrl.pathname}${requestUrl.search}`;
+      const expectedLoginHref = `/login?next=${encodeURIComponent(returnTo)}`;
+      expect(html).toContain(`href="${expectedLoginHref}"`);
+      // Sanity: the next= target carries the authorize path + the
+      // client_id + state so the flow can resume verbatim post-login.
+      expect(returnTo).toContain("/oauth/authorize");
+      expect(returnTo).toContain(encodeURIComponent(reg.client.clientId));
+      expect(returnTo).toContain("state=rt-208");
+      // The legacy SPA approve path is NOT what the Sign-in CTA points
+      // at any more (regression guard for the fix).
+      const legacyHref = `/login?next=${encodeURIComponent(
         `/admin/approve-client/${encodeURIComponent(reg.client.clientId)}`,
       )}`;
-      expect(html).toContain(`href="${expectedLoginHref}"`);
-      // Secondary CTA: shareable, fully-qualified deep link + Copy button.
+      expect(html).not.toContain(`href="${legacyHref}"`);
+      // Secondary CTA: shareable, fully-qualified deep link + Copy button
+      // — still points at the SPA approve page (no OAuth flow context to
+      // preserve for the share-with-another-admin case).
       expect(html).toContain(
         `${ISSUER}/admin/approve-client/${encodeURIComponent(reg.client.clientId)}`,
       );

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

@@ -408,13 +408,43 @@ describe("renderApprovePending unauthenticated CTAs", () => {
     hubOrigin: "https://hub.example.com",
   };
 
-  test("renders Sign in CTA wired to /login?next=/admin/approve-client/<id>", () => {
+  test("without loginNextUrl: Sign in CTA falls back to /admin/approve-client/<id>", () => {
+    // Back-compat fallback for callers that don't have an in-flight OAuth
+    // URL to resume (e.g. direct share-page entry). The SPA approve path
+    // approves the client but discards any OAuth context — fine here
+    // because there's no OAuth flow to discard.
     const html = renderApprovePending(COMMON);
     expect(html).toContain("Sign in as admin to approve");
     const expectedHref = `/login?next=${encodeURIComponent("/admin/approve-client/client-xyz")}`;
     expect(html).toContain(`href="${expectedHref}"`);
   });
 
+  test("with loginNextUrl set: Sign in CTA preserves the authorize URL through login", () => {
+    // The OAuth-flow entry case (the bug fix): the page is rendered for an
+    // `/oauth/authorize?...` GET, the operator isn't signed in, the CTA
+    // sends them through `/login?next=<authorize URL>` so post-login they
+    // land BACK on the OAuth flow — now authenticated, see the inline
+    // approve form, click once, OAuth flow resumes through consent →
+    // redirect_uri callback. Without this the SPA approves the client but
+    // the calling app (Claude MCP) is never told and the user loops on
+    // retry. Caught when Aaron tested via Claude.ai's MCP connector
+    // against the Render deploy.
+    const authorizeUrl =
+      "/oauth/authorize?client_id=client-xyz&redirect_uri=https%3A%2F%2Fapp.example%2Fcb" +
+      "&response_type=code&code_challenge=abc&code_challenge_method=S256&state=rt";
+    const html = renderApprovePending({ ...COMMON, loginNextUrl: authorizeUrl });
+    expect(html).toContain("Sign in as admin to approve");
+    const expectedHref = `/login?next=${encodeURIComponent(authorizeUrl)}`;
+    expect(html).toContain(`href="${expectedHref}"`);
+    // Sanity: the legacy SPA approve path is NOT what `next` points at.
+    const legacyHref = `/login?next=${encodeURIComponent("/admin/approve-client/client-xyz")}`;
+    expect(html).not.toContain(`href="${legacyHref}"`);
+    // The shareable deep link (secondary CTA, not Sign-in) still uses
+    // the SPA approve path — it's for sharing with another admin who
+    // isn't in an OAuth flow.
+    expect(html).toContain("https://hub.example.com/admin/approve-client/client-xyz");
+  });
+
   test("renders fully-qualified shareable deep link + Copy button + clipboard JS", () => {
     const html = renderApprovePending(COMMON);
     expect(html).toContain("https://hub.example.com/admin/approve-client/client-xyz");

package/src/oauth-handlers.ts

@@ -417,21 +417,34 @@ function parseAuthorizeFormParams(url: URL): AuthorizeFormParams | { error: stri
  * "App not yet approved" page (#74) for /oauth/authorize. When the request
  * carries a valid operator session AND a same-origin Origin/Referer, render
  * the inline approve form (#208) so one click flips the client to `approved`
- * and the OAuth flow re-enters at consent. Otherwise fall back to the
- * pre-#208 CLI-only message ("ask operator to run `parachute auth
- * approve-client <id>`").
+ * and the OAuth flow re-enters at consent. Otherwise render the unauth CTAs
+ * (Sign-in primary + shareable deep link secondary; the CLI fallback was
+ * retired in rc.19).
  *
  * The session-bound approve gate mirrors the same-origin DCR auto-approve
  * gate on `/oauth/register` (#199, #200): valid session cookie + matching
  * Origin/Referer = trusted operator action. Cross-origin or session-less
- * GETs see the CLI-fallback message; the button never renders for them, so
- * the POST handler can't be tricked into approving via a hand-crafted form
- * either (CSRF token won't match).
+ * GETs see the unauth CTA; the button never renders for them, so the POST
+ * handler can't be tricked into approving via a hand-crafted form either
+ * (CSRF token won't match).
  *
- * The form's `return_to` carries the original `/oauth/authorize?...` URL so
- * the post-approve redirect lands the operator back on the same flow with
- * the now-approved client. The POST handler validates `return_to` is a
- * hub-relative path before following it (open-redirect defense).
+ * BOTH branches plumb the original `/oauth/authorize?...` URL into the
+ * rendered page so the OAuth flow can resume after the operator's action:
+ *
+ *   - Authed branch: form's `return_to` is the authorize URL; the approve
+ *     POST handler 302s there after flipping status (open-redirect defense
+ *     in the POST handler validates `return_to` is hub-relative).
+ *   - Unauth branch: CTA's `next` is the authorize URL; `/login` 302s there
+ *     after sign-in (`safeNext` in admin-handlers.ts gates the target to
+ *     hub-relative paths). The operator lands back on this same page,
+ *     now authenticated → enters the authed branch above → one-click
+ *     approve resumes the OAuth flow.
+ *
+ * Pre-fix the unauth CTA pointed at `/admin/approve-client/<id>` (the SPA
+ * approve page) — which approves the client but discards the in-flight
+ * authorize URL, so the calling app (e.g. Claude MCP via Claude.ai) is
+ * never told and the user loops on retry. Caught when Aaron hit it on the
+ * Render deploy via Claude.ai's MCP connector.
  */
 function pendingClientResponse(
   db: Database,
@@ -453,8 +466,18 @@ function pendingClientResponse(
   const sameOrigin = isSameOriginRequest(req, resolveBoundOrigins(deps));
   const csrf = ensureCsrfToken(req);
   const extra: Record<string, string> = csrf.setCookie ? { "set-cookie": csrf.setCookie } : {};
+  // Hub-relative URL of the original `/oauth/authorize?...` request. Used in
+  // BOTH branches so the post-approve path (authed: form's `return_to`) and
+  // the post-login path (unauthed: CTA's `next`) round-trip the operator
+  // back to the same OAuth flow. Without `loginNextUrl` on the unauth
+  // branch, the operator post-login would land on the SPA approve page
+  // with no knowledge of the in-flight authorize URL — the SPA approves
+  // the client but the OAuth flow never completes, the calling app (e.g.
+  // Claude MCP) is never told, and the user loops on retry. Fix lands the
+  // unauth flow on the same authorize URL, post-login the operator hits
+  // the authed branch's inline approve form, and the flow resumes.
+  const returnTo = `${authorizeUrl.pathname}${authorizeUrl.search}`;
   if (session && sameOrigin) {
-    const returnTo = `${authorizeUrl.pathname}${authorizeUrl.search}`;
     return htmlResponse(
       renderApprovePending({
         clientName: client.clientName ?? client.clientId,
@@ -464,6 +487,7 @@ function pendingClientResponse(
         ...(requestedVault !== undefined && { requestedVault }),
         hubOrigin: deps.issuer,
         approveForm: { csrfToken: csrf.token, returnTo },
+        loginNextUrl: returnTo,
       }),
       403,
       extra,
@@ -477,6 +501,7 @@ function pendingClientResponse(
       requestedScopes,
       ...(requestedVault !== undefined && { requestedVault }),
       hubOrigin: deps.issuer,
+      loginNextUrl: returnTo,
     }),
     403,
     extra,

package/src/oauth-ui.ts

@@ -169,11 +169,29 @@ export interface ErrorViewProps {
  *     `approved` and re-enters the OAuth flow at consent.
  *   - Unauthenticated viewer — render TWO CTAs (no terminal mention):
  *       1. Primary: "Sign in as admin to approve" → links to
- *          `/login?next=/admin/approve-client/<client_id>` so the admin
- *          lands directly on the approval page after sign-in.
+ *          `/login?next=<loginNextUrl>`. When the page was rendered in
+ *          response to an `/oauth/authorize?...` request, `loginNextUrl`
+ *          is that same authorize URL (pathname+search) so the operator
+ *          lands BACK on the OAuth flow after sign-in — now authenticated,
+ *          they see the inline "Approve and continue" form, click once,
+ *          and the OAuth flow resumes through consent → redirect_uri.
+ *          Without this, post-login the operator lands on the SPA approve
+ *          page, which approves the client but discards the original
+ *          authorize URL and its params — Claude is never told, the user
+ *          retries, and the prompt loop never closes (the bug Aaron hit
+ *          via Claude.ai MCP on the Render deploy).
+ *
+ *          Callers that don't pass `loginNextUrl` (the deep-link share-
+ *          page entry point, or hand-crafted callers) fall back to the
+ *          legacy SPA approve path; that's still useful for the
+ *          "share with another admin" case, just not for resuming an
+ *          in-flight OAuth flow.
  *       2. Secondary: a fully-qualified shareable deep link to
  *          `<hub_origin>/admin/approve-client/<client_id>` with a copy
  *          button — the operator can send it to whoever runs the hub.
+ *          This deep link intentionally stays SPA-routed (it has no
+ *          authorize-URL context to preserve — the recipient isn't in
+ *          an OAuth flow).
  *
  *   The CLI fallback (`parachute auth approve-client <id>`) was retired —
  *   the web path is the path now. Operators who want the CLI still have it
@@ -212,6 +230,24 @@ export interface ApprovePendingViewProps {
     csrfToken: string;
     returnTo: string;
   };
+  /**
+   * Same-origin hub-relative URL (path + search) to send the operator to
+   * after they sign in via the unauthenticated "Sign in as admin to
+   * approve" CTA. When this page is rendered in response to an
+   * `/oauth/authorize?...` GET, the caller should pass that authorize
+   * URL here so post-login the operator lands BACK on the OAuth flow
+   * (now authenticated → sees inline approve form → one click → consent →
+   * redirect_uri callback). Omitted → CTA falls back to the legacy
+   * `/login?next=/admin/approve-client/<id>` path which dead-ends the
+   * OAuth flow at the SPA approve page (kept only for back-compat with
+   * non-authorize callers).
+   *
+   * The path is validated server-side at `/login` via `safeNext`
+   * (`src/admin-handlers.ts`), which only honors hub-relative paths
+   * starting with `/` and excluding `//` — so an attacker-controlled
+   * authorize URL can't be wielded for open-redirect.
+   */
+  loginNextUrl?: string;
 }
 
 export function renderLogin(props: LoginViewProps): string {
@@ -424,6 +460,7 @@ export function renderApprovePending(props: ApprovePendingViewProps): string {
     requestedVault,
     hubOrigin,
     approveForm,
+    loginNextUrl,
   } = props;
   const redirectList = redirectUris.map((u) => `<li><code>${escapeHtml(u)}</code></li>`).join("");
   // Substitute unnamed `vault:<verb>` rows with the wildcard display form
@@ -470,7 +507,7 @@ export function renderApprovePending(props: ApprovePendingViewProps): string {
         <input type="hidden" name="return_to" value="${escapeHtml(approveForm.returnTo)}" />
         <button type="submit" class="btn btn-primary">Approve and continue</button>
       </form>`
-    : renderUnauthenticatedApproveCtas(hubOrigin, clientId);
+    : renderUnauthenticatedApproveCtas(hubOrigin, clientId, loginNextUrl);
   const body = `
     <div class="card">
       <div class="card-header">
@@ -512,20 +549,41 @@ export function renderApprovePending(props: ApprovePendingViewProps): string {
  * Unauthenticated branch of `renderApprovePending`. Two CTAs:
  *
  *   1. Primary: "Sign in as admin to approve" → links to
- *      `/login?next=/admin/approve-client/<client_id>` so the admin lands
- *      on the approval page after sign-in.
+ *      `/login?next=<loginNextUrl>`. When `loginNextUrl` is provided,
+ *      that's the URL the operator lands on after sign-in — for the
+ *      OAuth-flow entry point that's the original `/oauth/authorize?...`
+ *      URL, so the operator resumes the in-flight OAuth flow (now
+ *      authenticated → inline approve form → consent → redirect_uri)
+ *      instead of dead-ending at the SPA approve page with the OAuth
+ *      params discarded. When `loginNextUrl` is absent, fall back to
+ *      `/admin/approve-client/<id>` (the legacy SPA path) — useful for
+ *      non-authorize entry points where there's no OAuth flow to resume.
  *   2. Secondary: a fully-qualified shareable deep-link to
  *      `<hub_origin>/admin/approve-client/<client_id>` with a Copy button
- *      so the operator can send it to whoever runs the hub.
+ *      so the operator can send it to whoever runs the hub. This stays
+ *      SPA-routed because the recipient isn't in an OAuth flow — the
+ *      deep-link is for the share-with-another-admin case where there's
+ *      no in-flight authorize URL context to preserve.
  *
  * Inline JS is scoped to the Copy button only — `navigator.clipboard.writeText`
  * with a brief "Copied!" affordance. The button degrades gracefully when
  * scripting is unavailable (the URL is still selectable + copyable from the
  * `<code>` block via the OS clipboard).
  */
-function renderUnauthenticatedApproveCtas(hubOrigin: string, clientId: string): string {
+function renderUnauthenticatedApproveCtas(
+  hubOrigin: string,
+  clientId: string,
+  loginNextUrl?: string,
+): string {
   const approvalPath = `/admin/approve-client/${encodeURIComponent(clientId)}`;
-  const loginHref = `/login?next=${encodeURIComponent(approvalPath)}`;
+  // Prefer the caller-supplied loginNextUrl (the original authorize URL when
+  // this page was rendered for an OAuth-flow GET) so post-login resumes the
+  // flow. Fall back to the SPA approve path for entry points that don't have
+  // an authorize URL to resume. `/login`'s `safeNext` (admin-handlers.ts)
+  // gates the redirect target to hub-relative paths only — open-redirect is
+  // not reachable here regardless of caller.
+  const loginNext = loginNextUrl ?? approvalPath;
+  const loginHref = `/login?next=${encodeURIComponent(loginNext)}`;
   const trimmedOrigin = hubOrigin.replace(/\/+$/, "");
   const deepLink = `${trimmedOrigin}${approvalPath}`;
   return `