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

package/package.json

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

package/src/hub.ts

@@ -9,15 +9,17 @@ import { CSRF_FIELD_NAME } from "./csrf.ts";
  * The page is split into two sections, organized by **ownership**:
  *
  *   - **Services** — surfaces provided by the modules running on this
- *     hub. Browse notes (the Notes PWA); transcribe audio (Scribe); run
- *     agents (Agent). Each entry points at the service's own UI; the
- *     service owns what's behind the link (use, config, admin —
- *     whatever it chooses to surface). Entries are dynamic, derived
- *     from `/.well-known/parachute.json`; only installed services show
- *     up. Vault deliberately doesn't have its own Services entry — its
- *     content is browsed via Notes, so a separate "Vault" tile would
- *     just send the operator to the admin SPA, which is exactly the
- *     friction Aaron flagged ("clicked Vault, took me to hub management").
+ *     hub. Browse notes (the Notes PWA); transcribe audio (Scribe);
+ *     administer a vault (Vault admin SPA); run agents (Agent). Each
+ *     entry points at the service's own UI; the service owns what's
+ *     behind the link (use, config, admin — whatever it chooses to
+ *     surface). Entries are dynamic, derived from
+ *     `/.well-known/parachute.json`; only installed services show up.
+ *     Vault declares `uiUrl` per workstream C (patterns#96, 2026-05-25)
+ *     — the earlier "vault has no tile because content browses via
+ *     Notes" rule split: Notes covers end-user content browsing; the
+ *     vault tile covers operator admin (per-vault tokens, config, MCP).
+ *     Both deserve discovery presence.
  *
  *   - **Admin** — hub-owned admin surfaces for cross-cutting host
  *     concerns. Always visible: even with zero vaults installed, an
@@ -455,17 +457,25 @@ const HTML_TEMPLATE = `<!doctype html>
   /**
    * Render the "Get started" section (hub#342) above the Services grid.
    *
-   * Two hardcoded targets, each conditional on its prerequisite being
-   * installed:
+   * One hardcoded target, conditional on its prerequisite being installed:
    *   - "Open Notes" → /app/notes/  (requires parachute-app installed;
    *     App auto-bootstraps Notes-as-UI per parachute-app §17, so the
    *     mere presence of App means /app/notes/ is live)
-   *   - "Browse Vault" → /vault/<first-vault-name>/admin/  (requires
-   *     parachute-vault installed; uses the first vault's name from
-   *     its services.json mount path tail)
    *
-   * If neither prerequisite is met (fresh install pre-wizard) the
-   * section stays hidden. The hardcoded shape mirrors the wizard's
+   * The earlier "Browse Vault" tile retired in workstream C (2026-05-25)
+   * once vault declared uiUrl in its module.json (per patterns#96). With
+   * the multi-instance prefix lifted into buildWellKnown, every vault
+   * instance now renders its own tile in the Services grid below — one
+   * per instance, with the actual instance name in the discovery doc
+   * rather than a hub-side guess at "first vault."
+   *
+   * Notes stays here because Notes is the end-user CTA (the audience
+   * that needs the strongest above-the-fold prompt); the Services grid
+   * positions it equally with admin tiles, which underweights the
+   * "browse my content" path for a returning operator.
+   *
+   * If the prerequisite is not met (fresh install pre-wizard, no app)
+   * the section stays hidden. The hardcoded shape mirrors the wizard's
    * own done-screen "Start using your vault" tile — same architectural
    * shape (single obvious entry point) at a different surface.
    *
@@ -478,11 +488,6 @@ const HTML_TEMPLATE = `<!doctype html>
     if (!getStartedGrid || !getStartedSection) return;
     const tiles = [];
     const hasApp = services.some((s) => s && s.name === 'parachute-app');
-    // services[] is fanned out per-vault for parachute-vault rows (see
-    // well-known.ts emitVaultRows) — "path" is the per-instance mount
-    // "/vault/<name>". Pick the first vault entry; the order matches
-    // services.json's paths[] order, so this is deterministic.
-    const vault = services.find((s) => s && s.name === 'parachute-vault');
     if (hasApp) {
       tiles.push({
         title: 'Open Notes',
@@ -490,25 +495,6 @@ const HTML_TEMPLATE = `<!doctype html>
         href: '/app/notes/',
       });
     }
-    if (vault) {
-      // vault.path is the per-instance mount "/vault/<name>". Extract
-      // the tail as the display name; mirror the wizard's own
-      // firstVaultName() shape.
-      let vaultName = 'default';
-      if (typeof vault.path === 'string' && vault.path.startsWith('/vault/')) {
-        // Character class for the slash so the template literal can't eat
-        // the backslash-escape — \/ collapses to / inside backticks, and
-        // /\/+$/ degenerates to a // line comment that breaks the whole
-        // IIFE. [/]+$ keeps the same semantics with no escape needed.
-        const tail = vault.path.slice('/vault/'.length).replace(/[/]+$/, '');
-        if (tail.length > 0) vaultName = tail;
-      }
-      tiles.push({
-        title: 'Browse Vault',
-        desc: "Open your vault's admin UI — content, settings, MCP.",
-        href: '/vault/' + encodeURIComponent(vaultName) + '/admin/',
-      });
-    }
     if (tiles.length === 0) {
       getStartedSection.setAttribute('hidden', '');
       return;
@@ -520,11 +506,21 @@ const HTML_TEMPLATE = `<!doctype html>
 
   function renderServices(services) {
     // Render one tile per service that declares a uiUrl. Entries without
-    // uiUrl are intentionally omitted — vault is the canonical example
-    // (its content is browsed via Notes, which has its own uiUrl row).
-    // Multiple entries with the same shortName collapse into one tile;
-    // operators with two scribe instances pick the first arbitrarily,
-    // and they'd know which they meant.
+    // uiUrl are intentionally omitted — API-only modules with no
+    // operator surface. The shortName-collapse below picks the first row
+    // per service short-name; for multi-instance services, this matters
+    // only when the services.json entry name is shared across instances.
+    //
+    // Today: vault registers as parachute-vault with multiple paths[] —
+    // shortName is "vault", one tile points at the first instance's admin.
+    // Same effective behavior the retired hardcoded "Browse Vault" tile
+    // had (workstream C, 2026-05-25).
+    //
+    // If a future multi-vault setup ever uses distinct entry names per
+    // instance (e.g. parachute-vault-default, parachute-vault-techne),
+    // the shortName collapse will yield "vault-default" and "vault-techne"
+    // and the operator gets one tile per named vault automatically — no
+    // disambiguation code needed.
     const byShort = new Map();
     for (const svc of services) {
       if (!svc || !svc.uiUrl) continue;

package/src/oauth-handlers.ts

@@ -1251,8 +1251,13 @@ export async function handleApproveClientPost(
  * (no scheme, no double-slash) targeting `/oauth/authorize` with a query
  * string — anything else is either an open-redirect attempt or a misuse of
  * the endpoint. Empty string is rejected (the form always supplies one).
+ *
+ * Exported so the SPA approve-client endpoint (`handleApproveClient` in
+ * admin-clients.ts) can apply the same gate when echoing a `return_to` back
+ * to the caller — workstream D. Single helper = single shape of "what's a
+ * valid OAuth-resume target?" for the whole hub.
  */
-function isSafeAuthorizeReturnTo(value: string): boolean {
+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.