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

package/package.json

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

package/src/__tests__/admin-clients.test.ts

@@ -298,4 +298,165 @@ describe("handleApproveClient", () => {
     const res = await handleApproveClient(req, id, { db: harness.db, issuer: ISSUER });
     expect(res.status).toBe(405);
   });
+
+  // Workstream D — OAuth resume via `return_to`. The SPA approve page
+  // can pass a hub-relative authorize URL as JSON body; the response
+  // echoes it as `redirect_to` so the SPA can navigate the browser there
+  // and resume the parked OAuth flow. The pre-D no-body shape continues
+  // to work (no `redirect_to` field, share-link dead-end case).
+  describe("workstream D — return_to / redirect_to", () => {
+    function jsonApproveReq(clientId: string, bearer: string, body: unknown): Request {
+      return new Request(`${ISSUER}/api/oauth/clients/${encodeURIComponent(clientId)}/approve`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${bearer}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(body),
+      });
+    }
+
+    test("echoes a same-origin /oauth/authorize?... return_to as redirect_to", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      const returnTo =
+        "/oauth/authorize?client_id=" +
+        encodeURIComponent(id) +
+        "&response_type=code&scope=vault%3Awork%3Aread";
+      const res = await handleApproveClient(
+        jsonApproveReq(id, bearer, { return_to: returnTo }),
+        id,
+        { db: harness.db, issuer: ISSUER },
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.redirect_to).toBe(returnTo);
+      expect(body.status).toBe("approved");
+      expect(getClient(harness.db, id)?.status).toBe("approved");
+    });
+
+    test("omits redirect_to entirely when return_to is missing (share-link case preserved)", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      // No body — the pre-D shape. The endpoint must continue to work.
+      const res = await handleApproveClient(approveReq(id, bearer), id, {
+        db: harness.db,
+        issuer: ISSUER,
+      });
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body).not.toHaveProperty("redirect_to");
+      expect(body.status).toBe("approved");
+    });
+
+    test("drops an off-origin return_to (scheme-relative) silently, still approves", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      const res = await handleApproveClient(
+        jsonApproveReq(id, bearer, { return_to: "//evil.example/oauth/authorize?foo=1" }),
+        id,
+        { db: harness.db, issuer: ISSUER },
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      // No redirect_to — server refuses to echo a bad value. The client
+      // is still approved (we don't fail an otherwise-legitimate approve
+      // over a malformed return_to).
+      expect(body).not.toHaveProperty("redirect_to");
+      expect(getClient(harness.db, id)?.status).toBe("approved");
+    });
+
+    test("drops a non-authorize return_to (off-path) silently", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      const res = await handleApproveClient(
+        jsonApproveReq(id, bearer, { return_to: "/admin/vaults" }),
+        id,
+        { db: harness.db, issuer: ISSUER },
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      // `/admin/vaults` is same-origin but isn't a `/oauth/authorize?...`
+      // URL — the server-side gate is "authorize URL only" so the SPA
+      // can't be used as a redirect gadget for arbitrary in-SPA navigation.
+      expect(body).not.toHaveProperty("redirect_to");
+    });
+
+    test("drops absolute URL return_to silently", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      const res = await handleApproveClient(
+        jsonApproveReq(id, bearer, {
+          return_to: "https://evil.example/oauth/authorize?foo=1",
+        }),
+        id,
+        { db: harness.db, issuer: ISSUER },
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body).not.toHaveProperty("redirect_to");
+    });
+
+    test("non-JSON body is treated as 'no return_to' (no parser explosion)", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      // text/plain body — pre-D / unknown clients send anything. The
+      // endpoint must NOT throw on parse and must NOT echo a redirect_to.
+      const req = new Request(`${ISSUER}/api/oauth/clients/${id}/approve`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${bearer}`,
+          "content-type": "text/plain",
+        },
+        body: "garbage",
+      });
+      const res = await handleApproveClient(req, id, {
+        db: harness.db,
+        issuer: ISSUER,
+      });
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body).not.toHaveProperty("redirect_to");
+    });
+
+    test("malformed JSON body is treated as 'no return_to'", async () => {
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      const req = new Request(`${ISSUER}/api/oauth/clients/${id}/approve`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${bearer}`,
+          "content-type": "application/json",
+        },
+        body: "{not json",
+      });
+      const res = await handleApproveClient(req, id, {
+        db: harness.db,
+        issuer: ISSUER,
+      });
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body).not.toHaveProperty("redirect_to");
+    });
+
+    test("re-approve with return_to echoes redirect_to (idempotent path)", async () => {
+      // The OAuth resume flow can legitimately race: operator opens the
+      // approve link, an automated path approves the same client, then
+      // operator clicks. We still want the redirect to fire so the
+      // operator's flow resumes — not dead-end on already_approved.
+      const { bearer } = await makeOperatorBearer();
+      const id = regPending();
+      approveClient(harness.db, id);
+      const returnTo = `/oauth/authorize?client_id=${encodeURIComponent(id)}&response_type=code&scope=vault%3Awork%3Aread`;
+      const res = await handleApproveClient(
+        jsonApproveReq(id, bearer, { return_to: returnTo }),
+        id,
+        { db: harness.db, issuer: ISSUER },
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.already_approved).toBe(true);
+      expect(body.redirect_to).toBe(returnTo);
+    });
+  });
 });

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

@@ -370,14 +370,16 @@ describe("hubFetch routing", () => {
     }
   });
 
-  test("/.well-known/parachute.json: uiUrl resolver is skipped for vault entries (loadManagementUrls handles vault)", async () => {
+  test("/.well-known/parachute.json: vault entry uiUrl is prefixed with the per-instance mount path", async () => {
     const h = makeHarness();
     try {
       const vaultWithDir: ServiceEntry = { ...vaultEntry("default"), installDir: "/fake/vault" };
       writeManifest({ services: [vaultWithDir] }, h.manifestPath);
-      // The fake module.json declares uiUrl, but vault is supposed to be
-      // skipped by loadServiceUiMetadata (it has its own managementUrl
-      // path). So doc.services[vault] should NOT carry uiUrl.
+      // Workstream C (patterns#96 + vault PR 367): vault declares
+      // `uiUrl: "/admin/"` as a per-instance path. loadServiceUiMetadata
+      // no longer skips vault entries; buildWellKnown prefixes the
+      // declared path with the per-instance mount on emission, yielding
+      // `/vault/default/admin/` for a vault mounted at `/vault/default`.
       const res = await hubFetch(h.dir, {
         manifestPath: h.manifestPath,
         readModuleManifest: async () => ({
@@ -386,12 +388,48 @@ describe("hubFetch routing", () => {
           port: 1940,
           paths: ["/vault/default"],
           health: "/health",
-          uiUrl: "/should-be-ignored",
+          uiUrl: "/admin/",
         }),
       })(req("/.well-known/parachute.json"));
       const body = (await res.json()) as { services: Array<{ name: string; uiUrl?: string }> };
-      const vaultSvc = body.services.find((s) => s.name === "parachute-vault");
-      expect(vaultSvc).not.toHaveProperty("uiUrl");
+      const vaultSvc = body.services.find((s) => s.name === "parachute-vault-default");
+      expect(vaultSvc?.uiUrl).toMatch(/\/vault\/default\/admin\/$/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("/.well-known/parachute.json: vault with multiple paths emits one row per instance with its own prefixed uiUrl", async () => {
+    const h = makeHarness();
+    try {
+      const multi: ServiceEntry = {
+        name: "parachute-vault",
+        port: 1940,
+        paths: ["/vault/default", "/vault/techne"],
+        health: "/vault/default/health",
+        version: "0.4.8",
+        installDir: "/fake/vault",
+      };
+      writeManifest({ services: [multi] }, h.manifestPath);
+      const res = await hubFetch(h.dir, {
+        manifestPath: h.manifestPath,
+        readModuleManifest: async () => ({
+          name: "vault",
+          manifestName: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default", "/vault/techne"],
+          health: "/health",
+          uiUrl: "/admin/",
+        }),
+      })(req("/.well-known/parachute.json"));
+      const body = (await res.json()) as {
+        services: Array<{ name: string; path?: string; uiUrl?: string }>;
+      };
+      const vaultRows = body.services.filter((s) => s.name === "parachute-vault");
+      expect(vaultRows.length).toBe(2);
+      const uiUrls = vaultRows.map((r) => r.uiUrl).sort();
+      expect(uiUrls[0]).toMatch(/\/vault\/default\/admin\/$/);
+      expect(uiUrls[1]).toMatch(/\/vault\/techne\/admin\/$/);
     } finally {
       h.cleanup();
     }

package/src/__tests__/hub.test.ts

@@ -78,10 +78,11 @@ describe("renderHub", () => {
     expect(html).not.toContain("['notes', 'scribe', 'agent']");
   });
 
-  test("Services skip rule emerges from data, not name-checks (vault has no uiUrl)", () => {
-    // The previous `isVaultName` hardcoded skip is gone — vault doesn't
-    // declare uiUrl, so it naturally doesn't render. Other API-only
-    // modules (current or future) get the same treatment for free.
+  test("Services skip rule emerges from data, not name-checks (any service without uiUrl skipped)", () => {
+    // The previous `isVaultName` hardcoded skip is gone — vault now
+    // declares uiUrl per workstream C (patterns#96), so it renders too;
+    // API-only modules (current or future) without uiUrl get omitted
+    // for free under the same data-driven rule.
     expect(html).toContain("if (!svc || !svc.uiUrl) continue;");
     // The function definition is gone (the comment may still mention the
     // name as historical context — we only care about the active code).

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/__tests__/well-known.test.ts

@@ -324,7 +324,7 @@ describe("buildWellKnown", () => {
     expect(svc?.uiUrl).toBe("https://notes.example.com/app");
   });
 
-  test("uiUrl absent when the resolver returns undefined (vault case)", () => {
+  test("uiUrl absent when the resolver returns undefined (API-only service)", () => {
     const doc = buildWellKnown({
       services: [vault, notes],
       canonicalOrigin: "https://x.example",
@@ -336,6 +336,44 @@ describe("buildWellKnown", () => {
     expect(notesSvc?.uiUrl).toBe("https://x.example/notes");
   });
 
+  // Workstream C (patterns#96): vault declares `uiUrl: "/admin/"` as a
+  // per-instance path. buildWellKnown applies the per-instance mount-path
+  // prefix on emission, yielding one tile per vault instance pointing at
+  // `<origin>/vault/<name>/admin/`. Non-vault uiUrl behavior is unchanged.
+  test("vault uiUrl is prefixed with the per-instance mount path (single instance)", () => {
+    const doc = buildWellKnown({
+      services: [vault],
+      canonicalOrigin: "https://x.example",
+      uiUrlFor: () => "/admin/",
+    });
+    const svc = doc.services.find((s) => s.name === "parachute-vault");
+    expect(svc?.uiUrl).toBe("https://x.example/vault/default/admin/");
+  });
+
+  test("vault uiUrl is prefixed per-instance for multi-path vault entries", () => {
+    const multi: ServiceEntry = { ...vault, paths: ["/vault/default", "/vault/techne"] };
+    const doc = buildWellKnown({
+      services: [multi],
+      canonicalOrigin: "https://x.example",
+      uiUrlFor: () => "/admin/",
+    });
+    const rows = doc.services.filter((s) => s.name === "parachute-vault");
+    expect(rows.length).toBe(2);
+    const uiUrls = rows.map((r) => r.uiUrl).sort();
+    expect(uiUrls[0]).toBe("https://x.example/vault/default/admin/");
+    expect(uiUrls[1]).toBe("https://x.example/vault/techne/admin/");
+  });
+
+  test("vault uiUrl absolute URL still passes through verbatim (no prefix)", () => {
+    const doc = buildWellKnown({
+      services: [vault],
+      canonicalOrigin: "https://x.example",
+      uiUrlFor: () => "https://vault.example.com/admin",
+    });
+    const svc = doc.services.find((s) => s.name === "parachute-vault");
+    expect(svc?.uiUrl).toBe("https://vault.example.com/admin");
+  });
+
   test("displayName resolver overrides services.json displayName", () => {
     const notesWithName: ServiceEntry = { ...notes, displayName: "FromServicesJson" };
     const doc = buildWellKnown({

package/src/admin-clients.ts

@@ -18,6 +18,33 @@
  * the API path logs because cross-machine "who approved this" is the
  * audit-grade signal we'd want when the operator approves from a browser
  * rather than a terminal they own.
+ *
+ * ## OAuth resume via `return_to` (workstream D, AUDIT-UI-UX.md §5 row D)
+ *
+ * The SPA approve page (`web/ui/src/routes/ApproveClient.tsx`) was a
+ * documented dead-end pre-D: it flipped the client to approved, then told
+ * the operator to "return to the app and retry" — the parked OAuth flow
+ * had no way to resume.
+ *
+ * D adds the affordance, not a behaviour change for existing callers. If
+ * the POST body carries a `return_to` JSON field that's a hub-relative
+ * `/oauth/authorize?...` URL, the response echoes it back as `redirect_to`
+ * and the SPA navigates the browser there to resume the flow. Callers
+ * that don't pass `return_to` (the "share this link with another admin"
+ * case the unauth pending-client CTA renders) get the unchanged response
+ * shape; the SPA renders its dead-end success state and the deep-link
+ * UX is preserved.
+ *
+ * Two cases, one route — `return_to` is the discriminator. The pattern
+ * doc is `parachute-patterns/patterns/oauth-dcr-approval.md` §"SPA
+ * approve page (two cases, one route)".
+ *
+ * Validation reuses `isSafeAuthorizeReturnTo` from oauth-handlers.ts so
+ * the SPA endpoint and the inline `/oauth/authorize/approve` endpoint
+ * apply the same gate — single source of truth for "what's a valid OAuth
+ * resume target?" Off-origin or non-authorize values are silently dropped
+ * (the response omits `redirect_to`) rather than 4xx'ing — a bad
+ * `return_to` shouldn't block an otherwise-legitimate approve.
  */
 import type { Database } from "bun:sqlite";
 import {
@@ -28,6 +55,7 @@ import {
 } from "./admin-auth.ts";
 import { HOST_ADMIN_SCOPE } from "./admin-vaults.ts";
 import { approveClient, getClient } from "./clients.ts";
+import { isSafeAuthorizeReturnTo } from "./oauth-handlers.ts";
 
 export interface AdminClientsDeps {
   db: Database;
@@ -102,6 +130,11 @@ export async function handleApproveClient(
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
+  // Parse the body OPTIONALLY — pre-D callers send no body at all, so a
+  // missing / empty / non-JSON body is fine. Only fish out `return_to` when
+  // the caller actually provided a parseable JSON object; everything else
+  // is treated as "no return_to specified," same as pre-D.
+  const returnTo = await readReturnTo(req);
   const before = getClient(deps.db, clientId);
   if (!before) {
     return jsonError(404, "not_found", `no client registered with id ${clientId}`);
@@ -123,20 +156,63 @@ export async function handleApproveClient(
       `client approved: client_id=${clientId} client_name=${before.clientName ?? ""} approver_sub=${ctx.sub}`,
     );
   }
-  return new Response(
-    JSON.stringify({
-      client_id: clientId,
-      status: "approved",
-      already_approved: !wasPending,
-    }),
-    {
-      status: 200,
-      headers: {
-        "content-type": "application/json",
-        "cache-control": "no-store",
-      },
+  // Only echo `redirect_to` when the caller's `return_to` passed the gate.
+  // Bad / missing values just drop off the response — the SPA falls back
+  // to its dead-end success state. We don't 4xx an otherwise-legitimate
+  // approve over a bad return_to (the client is now approved either way).
+  const body: ApproveClientResponse = {
+    client_id: clientId,
+    status: "approved",
+    already_approved: !wasPending,
+  };
+  if (returnTo !== null && isSafeAuthorizeReturnTo(returnTo)) {
+    body.redirect_to = returnTo;
+  }
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store",
     },
-  );
+  });
+}
+
+interface ApproveClientResponse {
+  client_id: string;
+  status: "approved";
+  already_approved: boolean;
+  /**
+   * Hub-relative `/oauth/authorize?...` URL the SPA should navigate to
+   * after approving, to resume a parked OAuth flow. Only present when the
+   * POST body's `return_to` passed `isSafeAuthorizeReturnTo`. Absent for
+   * the share-link case (no `return_to` provided) so the SPA's dead-end
+   * success state still renders.
+   */
+  redirect_to?: string;
+}
+
+/**
+ * Pull `return_to` out of the request body if present. Tolerant by design:
+ * pre-D callers (and tests, and curl probes) send no body or a non-JSON
+ * body, and the endpoint MUST continue to work in those shapes. Any parse
+ * failure or missing field returns null; the response omits `redirect_to`
+ * accordingly.
+ *
+ * Only `application/json` bodies are inspected — keeping the format
+ * restricted to JSON matches the existing API conventions (the SPA's
+ * other admin POSTs use JSON throughout) and avoids parser ambiguity
+ * over form-encoded variants on a deliberately optional field.
+ */
+async function readReturnTo(req: Request): Promise<string | null> {
+  const ct = req.headers.get("content-type") ?? "";
+  if (!ct.toLowerCase().includes("application/json")) return null;
+  try {
+    const body = (await req.json()) as { return_to?: unknown };
+    if (typeof body?.return_to !== "string") return null;
+    return body.return_to;
+  } catch {
+    return null;
+  }
 }
 
 function jsonError(status: number, error: string, description: string): Response {

package/src/hub-server.ts

@@ -719,12 +719,24 @@ async function loadManagementUrls(
 }
 
 /**
- * For each NON-vault `ServiceEntry` with a known `installDir`, read its
+ * For each `ServiceEntry` with a known `installDir`, read its
  * `.parachute/module.json` and surface the optional `uiUrl` and
  * `displayName`. Returns two `name → value` maps keyed by services.json
- * entry name. Mirrors `loadManagementUrls` (vault is the analog there;
- * non-vault services are the analog here — vaults are user-facing via
- * Notes, not their own UI).
+ * entry name.
+ *
+ * Vaults are NOT skipped — as of patterns#96 (workstream C) vault declares
+ * its own `uiUrl: "/admin/"` (multi-instance form). `buildWellKnown`
+ * applies the per-instance mount-path prefix for vault rows so each
+ * instance gets a discovery tile pointing at `/vault/<name>/admin/`. The
+ * earlier "vaults browse via Notes — no tile" rule retired with PR 1 of
+ * workstream C; operators administer per-vault tokens / config / MCP via
+ * the vault admin SPA, which is a different audience from Notes' content
+ * browse. See [`module-ui-declaration.md` §"Use vs admin"](https://github.com/ParachuteComputer/parachute-patterns/blob/main/patterns/module-ui-declaration.md#use-vs-admin--both-can-be-true).
+ *
+ * `loadManagementUrls` continues to handle vault's `managementUrl` for
+ * the hub admin SPA's vault-list "Manage" link — a different surface
+ * (admin SPA, not discovery), even when the target path happens to
+ * collide (`/admin/` for both).
  *
  * Why read at request time and not from services.json: services own the
  * write side of services.json (`upsertService` replaces the whole entry
@@ -746,9 +758,7 @@ async function loadServiceUiMetadata(
   const displayNames = new Map<string, string>();
   await Promise.all(
     services.map(async (s) => {
-      // Skip vaults — they have their own loadManagementUrls path and no
-      // operator-facing user UI of their own (content browses via Notes).
-      if (isVaultEntry(s) || !s.installDir) return;
+      if (!s.installDir) return;
       try {
         const m = await read(s.installDir);
         if (m?.uiUrl) uiUrls.set(s.name, m.uiUrl);