@openparachute/hub 0.5.7 → 0.5.9-rc.6

package/src/hub-server.ts

@@ -9,17 +9,62 @@
  * `tailscale serve … --set-path=/ http://127.0.0.1:<port>`. This shim is
  * that localhost backing.
  *
- * Routes (all bound to 127.0.0.1):
- *   /                                         → hub.html
- *   /hub.html                                 → hub.html
- *   /.well-known/parachute.json               → built dynamically from services.json
- *   /.well-known/jwks.json                    → JWKS from hub.db
- *   /.well-known/oauth-authorization-server   → RFC 8414 metadata (issuer, endpoints)
- *   /oauth/authorize  (GET + POST)            → login → consent → auth code
- *   /oauth/authorize/approve (POST)           → inline DCR approve form (#208)
- *   /oauth/token      (POST)                  → authorization_code + refresh_token grants
- *   /oauth/register   (POST)                  → RFC 7591 dynamic client registration
- *   anything else                             → 404
+ * Routes (all bound to 127.0.0.1) — listed in dispatch order. Order is
+ * load-bearing: 301 redirects fire before the proxies and SPA mount they
+ * preempt; admin API endpoints fire before the /admin/* SPA catch-all.
+ *
+ *   # Pre-rename 301 back-compat (hub#231 — first so they preempt any
+ *   # remaining handlers under /vault or /hub).
+ *   /vault, /vault/, /vault/new                → 301 → /admin/vaults[/new]
+ *   /hub/vaults*                               → 301 → /admin/vaults*
+ *   /hub/permissions                           → 301 → /admin/permissions
+ *   /hub/tokens                                → 301 → /admin/tokens
+ *   /hub, /hub/                                → 301 → /admin/vaults
+ *   /admin/login, /admin/logout                → 301 → /login, /logout
+ *
+ *   # Discovery + well-known.
+ *   /, /hub.html                               → hub.html (the discovery page)
+ *   /.well-known/parachute.json                → built dynamically from services.json
+ *   /.well-known/parachute-revocation.json     → revoked-jti list (hub#212 Phase 1)
+ *   /.well-known/jwks.json                     → JWKS from hub.db
+ *   /.well-known/oauth-authorization-server    → RFC 8414 metadata (issuer, endpoints)
+ *
+ *   # OAuth issuer.
+ *   /oauth/authorize  (GET + POST)             → login → consent → auth code
+ *   /oauth/authorize/approve (POST)            → inline DCR approve form (#208)
+ *   /oauth/token      (POST)                   → authorization_code + refresh_token grants
+ *   /oauth/register   (POST)                   → RFC 7591 dynamic client registration
+ *   /oauth/revoke     (POST)                   → RFC 7009 refresh-token revocation
+ *
+ *   # Admin API + bearer-mint surfaces (must precede /admin/* SPA mount).
+ *   /vaults                       (POST)       → create vault
+ *   /admin/host-admin-token       (GET)        → SPA bearer mint (cookie-gated)
+ *   /admin/vault-admin-token/<n>  (GET)        → per-vault bearer mint (cookie-gated)
+ *   /api/me                       (GET)        → who-am-I (session+CSRF or hasSession:false)
+ *   /api/auth/mint-token          (POST)       → CLI/automation token mint (bearer)
+ *   /api/auth/revoke-token        (POST)       → revoke registry-row token by jti
+ *   /api/auth/tokens              (GET)        → paginated registry list
+ *   /api/grants                   (GET)        → OAuth consent grants list
+ *   /api/grants/<client_id>       (DELETE)     → revoke a single OAuth grant
+ *   /api/oauth/clients/<id>       (GET)        → OAuth client details
+ *   /api/oauth/clients/<id>/approve (POST)     → flip a pending client to approved
+ *   /login                        (GET + POST) → operator password login
+ *   /logout                       (POST)       → end admin session
+ *   /admin/config*                             → 301 → /admin/vaults (legacy
+ *                                                portal retired post-SPA-rework)
+ *
+ *   # Per-vault content proxy (user-facing vault data: Notes PWA, MCP, etc.).
+ *   /vault/<name>/*                            → proxy to the vault backend
+ *
+ *   # Admin SPA mount (catch-all under /admin; runs after all admin API
+ *   # handlers above, so /admin/<known> reaches the right handler and
+ *   # /admin/<spa-route> serves the SPA shell).
+ *   /admin, /admin/, /admin/*                  → SPA shell (vaults / new / permissions / tokens)
+ *
+ *   # Generic services.json-driven proxy (non-vault modules: notes, scribe, agent).
+ *   /<service-mount>/*                         → proxy via services.json longest-prefix
+ *
+ *   anything else                              → 404
  *
  * Invoked as:
  *   bun <this-file> --port <n> --well-known-dir <path> [--db <path>] [--issuer <url>]
@@ -40,10 +85,9 @@ import type { Database } from "bun:sqlite";
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { handleApproveClient, handleGetClient } from "./admin-clients.ts";
 import { handleListGrants, handleRevokeGrant } from "./admin-grants.ts";
 import {
-  handleAdminConfigGet,
-  handleAdminConfigPost,
   handleAdminLoginGet,
   handleAdminLoginPost,
   handleAdminLogoutPost,
@@ -51,9 +95,17 @@ import {
 import { handleHostAdminToken } from "./admin-host-admin-token.ts";
 import { handleVaultAdminToken } from "./admin-vault-admin-token.ts";
 import { handleCreateVault } from "./admin-vaults.ts";
+import { handleApiMe } from "./api-me.ts";
+import { handleApiMintToken } from "./api-mint-token.ts";
+import { REVOCATION_LIST_MOUNT, handleRevocationList } from "./api-revocation-list.ts";
+import { handleApiRevokeToken } from "./api-revoke-token.ts";
+import { handleApiTokens } from "./api-tokens.ts";
 import { SERVICES_MANIFEST_PATH } from "./config.ts";
+import { ensureCsrfToken } from "./csrf.ts";
+import { readExposeState } from "./expose-state.ts";
 import { HUB_SVC, clearHubPort, writeHubPort } from "./hub-control.ts";
 import { hubDbPath, openHubDb } from "./hub-db.ts";
+import { type RenderHubOpts, renderHub } from "./hub.ts";
 import { pemToJwk } from "./jwks.ts";
 import {
   type ModuleManifest,
@@ -68,6 +120,7 @@ import {
   handleRevoke,
   handleToken,
 } from "./oauth-handlers.ts";
+import { buildHubBoundOrigins } from "./origin-check.ts";
 import { clearPid, writePid } from "./process-state.ts";
 import {
   FIRST_PARTY_FALLBACKS,
@@ -75,7 +128,9 @@ import {
   shortNameForManifest,
 } from "./service-spec.ts";
 import { type ServiceEntry, readManifest } from "./services-manifest.ts";
+import { findActiveSession } from "./sessions.ts";
 import { getAllPublicKeys } from "./signing-keys.ts";
+import { getUserById } from "./users.ts";
 import { buildWellKnown, isVaultEntry, vaultInstanceNameFor } from "./well-known.ts";
 
 interface Args {
@@ -458,6 +513,23 @@ export interface HubFetchDeps {
    * fixture installDirs.
    */
   readModuleManifest?: (installDir: string) => Promise<ModuleManifest | null>;
+  /**
+   * Hub's listening port. Threaded into the OAuth `hubBoundOrigins` set so
+   * the same-origin defense accepts loopback access (`http://localhost:<port>`,
+   * `http://127.0.0.1:<port>`) alongside the configured issuer. Closes #245
+   * Case A (operator on `localhost:1939` getting "Cross-origin request
+   * rejected" because Origin ≠ tailnet issuer).
+   */
+  loopbackPort?: number;
+  /**
+   * Test seam for reading `expose-state.json`. Production reads the operator's
+   * `~/.parachute/expose-state.json` via `readExposeState`; tests inject a
+   * fake to drive tailnet/funnel origins into the bound set without standing
+   * up real exposes. Returns `undefined` when no state file is present
+   * (pre-`parachute expose` state — fine, the issuer + loopback still cover
+   * legitimate access).
+   */
+  loadExposeHubOrigin?: () => string | undefined;
 }
 
 /**
@@ -490,6 +562,50 @@ async function loadManagementUrls(
   return out;
 }
 
+/**
+ * For each NON-vault `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).
+ *
+ * Why read at request time and not from services.json: services own the
+ * write side of services.json (`upsertService` replaces the whole entry
+ * on every boot), so any install-time copy of `uiUrl` / `displayName`
+ * would be clobbered the first time the service writes its own entry.
+ * Reading from `installDir/module.json` at request time avoids the gap
+ * and matches the established `managementUrl` precedent.
+ *
+ * Quiet on per-entry errors: a malformed module.json on one service
+ * shouldn't 500 the entire well-known doc — its row just renders without
+ * a Services tile. The validator already throws structured errors from
+ * `readModuleManifest`; logging them once here is the right floor.
+ */
+async function loadServiceUiMetadata(
+  services: readonly ServiceEntry[],
+  read: (installDir: string) => Promise<ModuleManifest | null>,
+): Promise<{ uiUrls: Map<string, string>; displayNames: Map<string, string> }> {
+  const uiUrls = new Map<string, string>();
+  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;
+      try {
+        const m = await read(s.installDir);
+        if (m?.uiUrl) uiUrls.set(s.name, m.uiUrl);
+        if (m?.displayName) displayNames.set(s.name, m.displayName);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`well-known: skipping uiUrl/displayName for ${s.name}: ${msg}`);
+      }
+    }),
+  );
+  return { uiUrls, displayNames };
+}
+
 /**
  * Resolve the SPA bundle dir. We anchor to this file's location so a
  * `bun src/hub-server.ts` from any cwd still finds `<repo>/web/ui/dist/`.
@@ -503,22 +619,23 @@ function defaultSpaDistDir(): string {
 }
 
 /**
- * The SPA serves at two mounts:
- *
- * - `/vault` — primary, since hub#168-realignment. Matches the operator
- *   pattern of `/<module>` as the entry point (alongside `/notes`, `/agent`,
- *   `/scribe`). VaultsList, NewVault, and per-vault detail routes hang off
- *   here.
- * - `/hub` — back-compat. `/hub/permissions` (cross-vault grants) is a hub
- *   concern and stays where bookmarks expect it. `/hub/vaults*` is a 301 to
- *   `/vault*` further up the dispatch — keeping it out of this mount.
- *
- * Both mounts serve the same SPA bundle. Asset URLs are origin-absolute
- * (`/vault/assets/...`) per the build base, so the HTML loads correctly
- * regardless of which mount served it. main.tsx detects the active mount
- * at runtime and configures react-router's `basename` accordingly.
+ * The admin SPA serves at a single mount: `/admin/*` (since hub#231).
+ *
+ * Routes:
+ *   - `/admin/vaults`       → vault list (the SPA's home)
+ *   - `/admin/vaults/new`   → vault create form
+ *   - `/admin/permissions`  → OAuth consent grant management
+ *   - `/admin/tokens`       → token registry: mint / list / revoke
+ *
+ * Asset URLs are origin-absolute (`/admin/assets/...`) per the Vite build
+ * base. main.tsx pins react-router's basename to `/admin`.
+ *
+ * Pre-rename mounts (the old `/vault` for the vault SPA, `/hub/*` for
+ * permissions+tokens) are 301-redirected further up the dispatch so cached
+ * operator URLs keep working. `/vault/<name>/*` (per-vault content proxy)
+ * stays — that's user-facing vault data, not part of this admin SPA.
  */
-type SpaMount = "/vault" | "/hub";
+type SpaMount = "/admin";
 
 /**
  * Pick a content type for static assets the SPA build produces. Vite's
@@ -565,8 +682,8 @@ function spaContentType(pathname: string): string {
  * filter rejects sub-paths containing "..", and the resolved absolute
  * path is checked to start with `dist/` before any read.
  *
- * `mount` is the prefix being served (`/vault` or `/hub`); we strip it
- * from `pathname` to land on the file path inside `dist/`.
+ * `mount` is the prefix being served (`/admin`); we strip it from
+ * `pathname` to land on the file path inside `dist/`.
  */
 async function serveSpa(spaDistDir: string, pathname: string, mount: SpaMount): Promise<Response> {
   if (!existsSync(spaDistDir)) {
@@ -575,7 +692,7 @@ async function serveSpa(spaDistDir: string, pathname: string, mount: SpaMount):
       { status: 503, headers: { "content-type": "text/plain; charset=utf-8" } },
     );
   }
-  // Strip the mount prefix; "/vault" → "", "/vault/" → "/", "/vault/x" → "/x".
+  // Strip the mount prefix; "/admin" → "", "/admin/" → "/", "/admin/x" → "/x".
   const sub = pathname === mount ? "" : pathname.slice(mount.length);
   const indexPath = join(spaDistDir, "index.html");
 
@@ -617,31 +734,137 @@ export function hubFetch(
   const configuredIssuer = deps?.issuer;
   const manifestPath = deps?.manifestPath ?? SERVICES_MANIFEST_PATH;
   const spaDistDir = deps?.spaDistDir ?? defaultSpaDistDir();
+  const loopbackPort = deps?.loopbackPort;
+  const loadExposeHubOrigin =
+    deps?.loadExposeHubOrigin ??
+    (() => {
+      try {
+        return readExposeState()?.hubOrigin;
+      } catch {
+        // Malformed expose-state.json shouldn't 500 hub on every same-origin
+        // check — the issuer + loopback already cover legitimate access.
+        return undefined;
+      }
+    });
 
-  const oauthDeps = (req: Request) => ({
-    issuer: configuredIssuer ?? new URL(req.url).origin,
-  });
+  const oauthDeps = (req: Request) => {
+    const issuer = configuredIssuer ?? new URL(req.url).origin;
+    return {
+      issuer,
+      // Per-request resolution (closes #245): expose-state.json can change
+      // mid-session (operator runs `parachute expose tailnet` while hub is
+      // up), so we re-read the bound origins on each call rather than
+      // capturing at hub start. Cheap — a single small JSON parse per OAuth
+      // request, only on the cookie-POST paths that consult it.
+      hubBoundOrigins: () =>
+        buildHubBoundOrigins({
+          issuer,
+          loopbackPort,
+          exposeHubOrigin: loadExposeHubOrigin(),
+        }),
+    };
+  };
 
   return async (req) => {
     const url = new URL(req.url);
     const pathname = url.pathname;
 
-    // 301 back-compat: `/hub/vaults*` was the SPA's vault-management entry
-    // before hub#168-realignment. Bookmarks and any cached operator-typed
-    // URLs land here; permanent redirect keeps them working without leaving
-    // a dangling SPA route. Query string preserved; fragment is client-side
-    // and survives the redirect at the browser. Method-agnostic — even a
-    // misrouted POST gets the redirect, since there's no /hub/vaults POST
-    // endpoint to protect.
+    // 301 back-compat for the pre-hub#231 admin-SPA mounts:
+    //
+    //   `/vault`            → `/admin/vaults`
+    //   `/vault/new`        → `/admin/vaults/new`
+    //   `/hub/vaults*`      → `/admin/vaults*` (this redirect predates #231;
+    //                        it now retargets at the new admin mount instead
+    //                        of the interim `/vault` mount)
+    //   `/hub/permissions`  → `/admin/permissions`
+    //   `/hub/tokens`       → `/admin/tokens`
+    //   `/hub` (bare)       → `/admin/vaults`
+    //
+    // Permanent redirect so cached operator URLs keep working without
+    // leaving dangling SPA routes. Query string preserved; fragment is
+    // client-side and survives the redirect at the browser. Method-agnostic
+    // — even a misrouted POST gets the redirect; none of these paths host a
+    // POST endpoint to protect.
+    //
+    // `/vault/<name>/*` is INTENTIONALLY excluded — that's the per-vault
+    // content proxy (Notes PWA, etc.), not the admin SPA. Stays where it is.
+    if (pathname === "/vault" || pathname === "/vault/" || pathname === "/vault/new") {
+      const sub = pathname === "/vault/new" ? "/new" : "";
+      return new Response("", {
+        status: 301,
+        headers: { location: `/admin/vaults${sub}${url.search}` },
+      });
+    }
     if (pathname === "/hub/vaults" || pathname.startsWith("/hub/vaults/")) {
-      const newPath = `/vault${pathname.slice("/hub/vaults".length)}`;
+      const newPath = `/admin/vaults${pathname.slice("/hub/vaults".length)}`;
       return new Response("", {
         status: 301,
         headers: { location: `${newPath}${url.search}` },
       });
     }
+    if (pathname === "/hub/permissions") {
+      return new Response("", {
+        status: 301,
+        headers: { location: `/admin/permissions${url.search}` },
+      });
+    }
+    if (pathname === "/hub/tokens") {
+      return new Response("", {
+        status: 301,
+        headers: { location: `/admin/tokens${url.search}` },
+      });
+    }
+    if (pathname === "/hub" || pathname === "/hub/") {
+      return new Response("", {
+        status: 301,
+        headers: { location: `/admin/vaults${url.search}` },
+      });
+    }
+
+    // Login surface rename: `/admin/login` and `/admin/logout` 301 to the
+    // canonical `/login` and `/logout`. The names were "admin" only by
+    // historical accident — the handlers serve every parachute auth flow
+    // (operator, OAuth user-redirect, future SPA sign-in). Renaming makes
+    // the surface name match its actual scope.
+    if (pathname === "/admin/login") {
+      return new Response("", {
+        status: 301,
+        headers: { location: `/login${url.search}` },
+      });
+    }
+    if (pathname === "/admin/logout") {
+      return new Response("", {
+        status: 301,
+        headers: { location: `/logout${url.search}` },
+      });
+    }
 
     if (pathname === "/" || pathname === "/hub.html") {
+      // When a DB is configured, render the discovery page dynamically so
+      // the header carries a "Signed in as <name>" affordance for the
+      // active session. Without a DB, fall back to the static disk file
+      // (signed-out shape) — the disk file is what `parachute expose`
+      // wrote out, used when the hub-server is running without state.
+      if (getDb) {
+        const db = getDb();
+        const session = findActiveSession(db, req);
+        let renderOpts: RenderHubOpts = {};
+        const headers: Record<string, string> = {
+          "content-type": "text/html; charset=utf-8",
+        };
+        if (session) {
+          const user = getUserById(db, session.userId);
+          if (user) {
+            const csrf = ensureCsrfToken(req);
+            renderOpts = {
+              session: { displayName: user.username, csrfToken: csrf.token },
+            };
+            if (csrf.setCookie) headers["set-cookie"] = csrf.setCookie;
+          }
+        }
+        return new Response(renderHub(renderOpts), { headers });
+      }
+      // No DB configured → fall back to static file (signed-out only).
       if (!existsSync(hubHtmlPath)) {
         return new Response("hub.html not found", { status: 404 });
       }
@@ -671,14 +894,17 @@ export function hubFetch(
       try {
         const manifest = readManifest(manifestPath);
         const canonicalOrigin = configuredIssuer ?? new URL(req.url).origin;
-        const managementUrlByName = await loadManagementUrls(
-          manifest.services,
-          deps?.readModuleManifest ?? defaultReadModuleManifest,
-        );
+        const readManifestFn = deps?.readModuleManifest ?? defaultReadModuleManifest;
+        const [managementUrlByName, serviceUiMeta] = await Promise.all([
+          loadManagementUrls(manifest.services, readManifestFn),
+          loadServiceUiMetadata(manifest.services, readManifestFn),
+        ]);
         const doc = buildWellKnown({
           services: manifest.services,
           canonicalOrigin,
           managementUrlFor: (entry) => managementUrlByName.get(entry.name),
+          uiUrlFor: (entry) => serviceUiMeta.uiUrls.get(entry.name),
+          displayNameFor: (entry) => serviceUiMeta.displayNames.get(entry.name),
         });
         return new Response(JSON.stringify(doc), {
           headers: { "content-type": "application/json", ...corsHeaders },
@@ -694,6 +920,30 @@ export function hubFetch(
       }
     }
 
+    if (pathname === REVOCATION_LIST_MOUNT) {
+      // Revocation list (hub#212 Phase 1). Public — same CORS posture as
+      // jwks.json since resource servers (vault/scribe/agent) fetch it
+      // cross-origin on the 60s polling cadence wired in Phase 4.
+      const corsHeaders = {
+        "access-control-allow-origin": "*",
+        "access-control-allow-methods": "GET, OPTIONS",
+      };
+      if (req.method === "OPTIONS") {
+        return new Response(null, { status: 204, headers: corsHeaders });
+      }
+      if (!getDb) {
+        return new Response('{"error":"revocation list unavailable: db not configured"}', {
+          status: 503,
+          headers: { "content-type": "application/json", ...corsHeaders },
+        });
+      }
+      const resp = handleRevocationList(req, { db: getDb() });
+      // Layer the wildcard CORS over whatever cache-control the handler set.
+      const merged = new Headers(resp.headers);
+      for (const [k, v] of Object.entries(corsHeaders)) merged.set(k, v);
+      return new Response(resp.body, { status: resp.status, headers: merged });
+    }
+
     if (pathname === "/.well-known/jwks.json") {
       // JWKS is also a cross-origin fetch target (browser-side OAuth
       // libraries pull this to verify access tokens). Same wildcard CORS
@@ -800,15 +1050,10 @@ export function hubFetch(
       });
     }
 
-    // /hub SPA mount (back-compat). Kept for `/hub/permissions` and any other
-    // hub-level admin surface that lived under /hub/ before the realignment.
-    // /hub/vaults* is a separate concern handled by the 301 redirect lower
-    // down — the redirect runs first so it never reaches here. Only GET —
-    // POSTs for vault create go to /vaults, not the SPA mount.
-    if (pathname === "/hub" || pathname.startsWith("/hub/")) {
-      if (req.method !== "GET") return new Response("method not allowed", { status: 405 });
-      return serveSpa(spaDistDir, pathname, "/hub");
-    }
+    // Note: the old `/hub/*` SPA mount has been retired. Known prefixes
+    // (`/hub`, `/hub/vaults*`, `/hub/permissions`, `/hub/tokens`) are
+    // 301-redirected at the top of dispatch. Any other `/hub/*` path falls
+    // through to the catch-all 404 — there's no admin surface left there.
 
     if (pathname === "/admin/host-admin-token") {
       if (!getDb) return new Response("hub db not configured", { status: 503 });
@@ -838,6 +1083,55 @@ export function hubFetch(
       });
     }
 
+    if (pathname === "/api/me") {
+      if (!getDb) {
+        return Response.json(
+          { error: "service_unavailable", error_description: "hub db not configured" },
+          { status: 503 },
+        );
+      }
+      return handleApiMe(req, { db: getDb() });
+    }
+
+    if (pathname === "/api/auth/mint-token") {
+      if (!getDb) {
+        return Response.json(
+          { error: "service_unavailable", error_description: "hub db not configured" },
+          { status: 503 },
+        );
+      }
+      return handleApiMintToken(req, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+      });
+    }
+
+    if (pathname === "/api/auth/revoke-token") {
+      if (!getDb) {
+        return Response.json(
+          { error: "service_unavailable", error_description: "hub db not configured" },
+          { status: 503 },
+        );
+      }
+      return handleApiRevokeToken(req, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+      });
+    }
+
+    if (pathname === "/api/auth/tokens") {
+      if (!getDb) {
+        return Response.json(
+          { error: "service_unavailable", error_description: "hub db not configured" },
+          { status: 503 },
+        );
+      }
+      return handleApiTokens(req, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+      });
+    }
+
     if (pathname === "/api/grants") {
       if (!getDb) return new Response("hub db not configured", { status: 503 });
       return handleListGrants(req, {
@@ -858,63 +1152,98 @@ export function hubFetch(
       });
     }
 
-    if (pathname === "/admin/login") {
+    // OAuth client lookup + approval. Both bearer-gated under host:admin.
+    // Two paths: `/api/oauth/clients/<id>` (GET, details) and
+    // `/api/oauth/clients/<id>/approve` (POST, flip to approved). The
+    // SPA approve-client deep link reads details from the first and
+    // submits approval to the second — keeps the surface easy to test
+    // and audit without overloading a single verb.
+    if (pathname.startsWith("/api/oauth/clients/")) {
+      if (!getDb) return new Response("hub db not configured", { status: 503 });
+      const tail = pathname.slice("/api/oauth/clients/".length);
+      if (!tail) return new Response("not found", { status: 404 });
+      const approveSuffix = "/approve";
+      if (tail.endsWith(approveSuffix)) {
+        const clientId = decodeURIComponent(tail.slice(0, -approveSuffix.length));
+        if (!clientId || clientId.includes("/")) {
+          return new Response("not found", { status: 404 });
+        }
+        return handleApproveClient(req, clientId, {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+        });
+      }
+      const clientId = decodeURIComponent(tail);
+      if (!clientId || clientId.includes("/")) {
+        return new Response("not found", { status: 404 });
+      }
+      return handleGetClient(req, clientId, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+      });
+    }
+
+    // Canonical login/logout. The handlers themselves are unchanged from
+    // when they lived at /admin/login + /admin/logout; the rename surfaced
+    // via #231-followup so the URL reflects the surface's actual scope
+    // (entry point for ALL parachute auth — not admin-only). The
+    // /admin/login and /admin/logout paths 301 to here, dispatched at the
+    // top of this fn alongside the other back-compat redirects.
+    if (pathname === "/login") {
       if (!getDb) return new Response("hub db not configured", { status: 503 });
       if (req.method === "GET") return handleAdminLoginGet(getDb(), req);
       if (req.method === "POST") return handleAdminLoginPost(getDb(), req);
       return new Response("method not allowed", { status: 405 });
     }
 
-    if (pathname === "/admin/logout") {
+    if (pathname === "/logout") {
       if (!getDb) return new Response("hub db not configured", { status: 503 });
       if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
       return handleAdminLogoutPost(getDb(), req);
     }
 
-    if (pathname === "/admin/config") {
-      if (!getDb) return new Response("hub db not configured", { status: 503 });
-      if (req.method !== "GET") return new Response("method not allowed", { status: 405 });
-      return handleAdminConfigGet(getDb(), req);
+    // Legacy `/admin/config` (server-rendered module-config portal, #46)
+    // retired post-SPA-rework. 301 → the SPA home so any bookmark or stale
+    // post-login redirect lands somewhere useful. The route stays here in
+    // dispatch order (above the /admin/* SPA catch-all) so the redirect
+    // wins over a SPA shell render.
+    if (pathname === "/admin/config" || pathname.startsWith("/admin/config/")) {
+      return new Response(null, {
+        status: 301,
+        headers: { location: "/admin/vaults" },
+      });
     }
 
-    if (pathname.startsWith("/admin/config/")) {
-      if (!getDb) return new Response("hub db not configured", { status: 503 });
-      if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
-      const name = decodeURIComponent(pathname.slice("/admin/config/".length));
-      if (!name || name.includes("/")) {
-        return new Response("not found", { status: 404 });
-      }
-      return handleAdminConfigPost(getDb(), req, name);
-    }
-
-    // /vault — primary SPA mount + dynamic per-vault proxy share this
-    // namespace. Order matters:
-    //   1. `/vault` exact → SPA shell (vault list).
-    //   2. `/vault/<known-vault>/...` → proxy to the vault backend, picked
-    //      from services.json by longest-mount-prefix. Read per request so a
-    //      `parachute vault create` performed after `parachute expose` is
-    //      immediately reachable (#144).
-    //   3. `/vault/<spa-route>` → SPA shell. Only single-segment paths
-    //      (`/vault/new`, `/vault/<name>`) and `/vault/assets/*` count as
-    //      SPA routes. Multi-segment requests like `/vault/<unknown>/health`
-    //      are vault-API shapes targeting a non-existent vault and 404 —
-    //      otherwise the SPA shell would mask backend 404s with HTML.
-    //      `new` and `assets` are reserved vault names (see
-    //      `RESERVED_VAULT_NAMES` in admin-vaults.ts) so an operator
-    //      can't register a vault that shadows the SPA's create route or
-    //      its static asset bundle.
-    if (pathname === "/vault") {
-      if (req.method !== "GET") return new Response("method not allowed", { status: 405 });
-      return serveSpa(spaDistDir, pathname, "/vault");
-    }
+    // /vault/<name>/* — per-vault content proxy. Stays as user-facing
+    // surface (the Notes PWA loads through here, etc.). The bare `/vault`
+    // and `/vault/new` paths were SPA routes pre-#231; they 301-redirect at
+    // the top of dispatch now. Multi-segment requests like
+    // `/vault/<unknown>/health` are vault-API shapes targeting a
+    // non-existent vault and 404 directly — there's no SPA-shell fallback
+    // here anymore (the SPA moved to /admin), so we can't accidentally
+    // mask a backend 404 with HTML.
     if (pathname.startsWith("/vault/")) {
       const proxied = await proxyToVault(req, manifestPath);
       if (proxied) return proxied;
-      const sub = pathname.slice("/vault/".length);
-      const isSpaRoute = !sub.includes("/") || sub.startsWith("assets/");
-      if (!isSpaRoute) return new Response("not found", { status: 404 });
-      if (req.method !== "GET") return new Response("not found", { status: 404 });
-      return serveSpa(spaDistDir, pathname, "/vault");
+      return new Response("not found", { status: 404 });
+    }
+
+    // /admin/* SPA mount. All non-SPA admin handlers (host-admin-token,
+    // vault-admin-token, login, logout, config, api/auth/*, api/grants,
+    // grants/*) ran above and either matched or returned. Anything that
+    // makes it here under /admin/* is a SPA route or asset request; the
+    // SPA's own router renders the page and handles 404 client-side for
+    // unknown sub-paths.
+    if (pathname === "/admin" || pathname === "/admin/") {
+      // Unprefixed /admin → SPA shell pointed at the vault list (its home).
+      // The SPA's basename is /admin, so the router will land on / and
+      // render VaultsList.
+      if (req.method !== "GET") return new Response("method not allowed", { status: 405 });
+      return serveSpa(spaDistDir, pathname, "/admin");
+    }
+    if (pathname.startsWith("/admin/")) {
+      if (req.method !== "GET") return new Response("method not allowed", { status: 405 });
+      return serveSpa(spaDistDir, pathname, "/admin");
     }
 
     // Generic services.json-driven dispatch for non-vault modules. Reaches
@@ -938,7 +1267,7 @@ if (import.meta.main) {
   Bun.serve({
     port,
     hostname: "127.0.0.1",
-    fetch: hubFetch(wellKnownDir, { getDb, issuer }),
+    fetch: hubFetch(wellKnownDir, { getDb, issuer, loopbackPort: port }),
   });
   // Register PID + port from the running hub itself so any startup path
   // (spawn-via-`ensureHubRunning` or a direct `bun src/hub-server.ts` from