@openparachute/hub 0.5.7 → 0.5.10-rc.10

package/src/hub-server.ts

@@ -9,17 +9,69 @@
  * `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/modules                  (GET)        → curated + installed module catalog (host:auth)
+ *   /api/modules/channel          (PUT)        → operator channel toggle (host:admin)
+ *   /api/modules/:short/install   (POST)       → bun add + spawn (async op)
+ *   /api/modules/:short/restart   (POST)       → supervisor restart (sync)
+ *   /api/modules/:short/upgrade   (POST)       → bun add @<channel> + restart (async op)
+ *   /api/modules/:short/uninstall (POST)       → stop child + bun remove + drop row (sync)
+ *   /api/modules/operations/:id   (GET)        → poll async op status
+ *   /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 +92,10 @@ import type { Database } from "bun:sqlite";
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import pkg from "../package.json" with { type: "json" };
+import { handleApproveClient, handleGetClient } from "./admin-clients.ts";
 import { handleListGrants, handleRevokeGrant } from "./admin-grants.ts";
 import {
-  handleAdminConfigGet,
-  handleAdminConfigPost,
   handleAdminLoginGet,
   handleAdminLoginPost,
   handleAdminLogoutPost,
@@ -51,9 +103,27 @@ import {
 import { handleHostAdminToken } from "./admin-host-admin-token.ts";
 import { handleVaultAdminToken } from "./admin-vault-admin-token.ts";
 import { handleCreateVault } from "./admin-vaults.ts";
-import { SERVICES_MANIFEST_PATH } from "./config.ts";
-import { HUB_SVC, clearHubPort, writeHubPort } from "./hub-control.ts";
+import { handleApiMe } from "./api-me.ts";
+import { handleApiMintToken } from "./api-mint-token.ts";
+import {
+  getDefaultOperationsRegistry,
+  handleInstall,
+  handleOperationGet,
+  handleRestart,
+  handleUninstall,
+  handleUpgrade,
+  parseModulesPath,
+} from "./api-modules-ops.ts";
+import { handleApiModules, handleApiModulesChannel } from "./api-modules.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 { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "./config.ts";
+import { ensureCsrfToken } from "./csrf.ts";
+import { readExposeState } from "./expose-state.ts";
+import { HUB_DEFAULT_PORT, 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 +138,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,18 +146,48 @@ import {
   shortNameForManifest,
 } from "./service-spec.ts";
 import { type ServiceEntry, readManifest } from "./services-manifest.ts";
+import { findActiveSession } from "./sessions.ts";
+import {
+  type SetupWizardDeps,
+  handleSetupAccountPost,
+  handleSetupExposePost,
+  handleSetupGet,
+  handleSetupInstallPost,
+  handleSetupVaultPost,
+} from "./setup-wizard.ts";
 import { getAllPublicKeys } from "./signing-keys.ts";
-import { buildWellKnown, isVaultEntry, vaultInstanceNameFor } from "./well-known.ts";
+import type { Supervisor } from "./supervisor.ts";
+import { getUserById, userCount } from "./users.ts";
+import {
+  WELL_KNOWN_DIR,
+  buildWellKnown,
+  isVaultEntry,
+  vaultInstanceNameFor,
+} from "./well-known.ts";
 
 interface Args {
   port: number;
+  hostname: string;
   wellKnownDir: string;
   dbPath: string;
   issuer: string | undefined;
 }
 
-function parseArgs(argv: string[]): Args {
+/**
+ * Parse hub-server flags. Container hosts (Render, Docker) configure us
+ * entirely via env vars — no flags. The `parachute expose` spawn path passes
+ * everything as flags. Flags beat env, env beats defaults.
+ *
+ *   PORT                       — bind port (Render injects this)
+ *   PARACHUTE_BIND_HOST        — bind hostname; default 127.0.0.1 to keep
+ *                                the historical loopback posture safe.
+ *                                Containers should set 0.0.0.0.
+ *   PARACHUTE_HUB_ORIGIN       — canonical https://… origin used as the
+ *                                OAuth issuer claim.
+ */
+function parseArgs(argv: string[], env: NodeJS.ProcessEnv = process.env): Args {
   let port: number | undefined;
+  let hostname: string | undefined;
   let wellKnownDir: string | undefined;
   let dbPath: string | undefined;
   let issuer: string | undefined;
@@ -95,11 +196,11 @@ function parseArgs(argv: string[]): Args {
     if (a === "--port") {
       const v = argv[++i];
       if (!v) throw new Error("--port requires a value");
-      const n = Number.parseInt(v, 10);
-      if (!Number.isInteger(n) || n <= 0 || n > 65535) {
-        throw new Error(`--port must be 1..65535, got "${v}"`);
-      }
-      port = n;
+      port = parsePort(v);
+    } else if (a === "--hostname") {
+      const v = argv[++i];
+      if (!v) throw new Error("--hostname requires a value");
+      hostname = v;
     } else if (a === "--well-known-dir") {
       const v = argv[++i];
       if (!v) throw new Error("--well-known-dir requires a value");
@@ -116,9 +217,22 @@ function parseArgs(argv: string[]): Args {
       throw new Error(`unknown argument: ${a}`);
     }
   }
-  if (port === undefined) throw new Error("--port is required");
-  if (wellKnownDir === undefined) throw new Error("--well-known-dir is required");
-  return { port, wellKnownDir, dbPath: dbPath ?? hubDbPath(), issuer };
+  if (port === undefined && env.PORT) port = parsePort(env.PORT);
+  if (port === undefined) port = HUB_DEFAULT_PORT;
+  if (hostname === undefined) hostname = env.PARACHUTE_BIND_HOST || "127.0.0.1";
+  if (wellKnownDir === undefined) wellKnownDir = WELL_KNOWN_DIR;
+  if (issuer === undefined && env.PARACHUTE_HUB_ORIGIN) {
+    issuer = env.PARACHUTE_HUB_ORIGIN.replace(/\/+$/, "");
+  }
+  return { port, hostname, wellKnownDir, dbPath: dbPath ?? hubDbPath(), issuer };
+}
+
+function parsePort(v: string): number {
+  const n = Number.parseInt(v, 10);
+  if (!Number.isInteger(n) || n <= 0 || n > 65535) {
+    throw new Error(`port must be 1..65535, got "${v}"`);
+  }
+  return n;
 }
 
 /**
@@ -458,6 +572,32 @@ 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;
+  /**
+   * Container-mode child supervisor. When present (under `parachute serve`),
+   * `/api/modules/*` handlers drive install/restart/upgrade/uninstall through
+   * it. Absent under the on-box CLI path (`parachute expose`) where
+   * `commands/lifecycle.ts` owns the detached-pidfile lifecycle instead —
+   * the module-mgmt API in that mode returns 503 with a hint to use the
+   * CLI commands directly.
+   */
+  supervisor?: Supervisor;
 }
 
 /**
@@ -490,6 +630,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 +687,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 +750,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 +760,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");
 
@@ -608,6 +793,64 @@ async function serveSpa(spaDistDir: string, pathname: string, mount: SpaMount):
   });
 }
 
+/**
+ * Routes that fall through the pre-admin lockout (503 → /admin/setup).
+ *
+ * Gated (operator-facing) when no admin row exists:
+ *   - `/admin/*` (except `/admin/setup*`) — vault admin, permissions, tokens
+ *   - `/api/*`                            — host-admin API surface
+ *   - `/login`, `/logout`                 — pointless without an account
+ *
+ * Open through the gate (so the container is reachable and discoverable
+ * the moment it boots, even before an admin is seeded):
+ *   - `/health`                           — platform liveness check
+ *   - `/.well-known/*`                    — public discovery + JWKS
+ *   - `/admin/setup`, `/admin/setup/*`    — the first-boot wizard (hub#259)
+ *                                            and its POST endpoints; the
+ *                                            wizard is the *only* browser
+ *                                            path to exit the lockout
+ *   - `/` and `/hub.html`                 — static discovery page
+ *   - `/oauth/*`                          — third-party OAuth surface; clients
+ *                                            can register/refresh independent
+ *                                            of admin onboarding
+ *   - `/vault/*`, `/<service>/*`          — content proxies; service-level auth
+ *                                            handles its own failure modes
+ *
+ * The function is called only when an admin row is missing; in the
+ * normal-running case (any admin row exists) this gate is a no-op and the
+ * regular dispatch continues.
+ */
+function shouldGateForSetup(pathname: string): boolean {
+  if (pathname === "/login" || pathname === "/logout") return true;
+  // The wizard itself + its POST endpoints are the *only* way to exit
+  // the pre-admin lockout from a browser — they must pass through. Any
+  // path under `/admin/setup` (including `/admin/setup/account` and
+  // `/admin/setup/vault`) is fair game for an un-authed operator on a
+  // fresh hub.
+  if (pathname === "/admin/setup" || pathname.startsWith("/admin/setup/")) return false;
+  if (pathname === "/admin" || pathname.startsWith("/admin/")) return true;
+  if (pathname.startsWith("/api/")) return true;
+  return false;
+}
+
+// hub#259 replaced the static placeholder with a real three-step wizard.
+// The handlers (account creation + vault provisioning) live in
+// `src/setup-wizard.ts` so the dispatch in this file stays a one-liner per
+// route. The env-var seed path (PARACHUTE_INITIAL_ADMIN_*) still works on
+// first boot — see `src/commands/serve.ts` — and is surfaced as the
+// "alt-path" disclosure on the wizard's welcome screen.
+
+// Canonical 503 body for "getDb is unset, hub is unconfigured." Shape matches
+// the OAuth error vocabulary used by /api/auth/* (`service_unavailable`) so a
+// consumer never has to branch on content-type to extract a message. See
+// hub#227 for the migration from plain-text bodies.
+function dbNotConfigured(): Response {
+  return Response.json(
+    { error: "service_unavailable", error_description: "hub db not configured" },
+    { status: 503 },
+  );
+}
+
 export function hubFetch(
   wellKnownDir: string,
   deps?: HubFetchDeps,
@@ -617,31 +860,252 @@ 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}` },
+      });
+    }
+
+    // Platform health check (Render, Fly, Kubernetes, etc.). Plain JSON,
+    // no DB required — the route reports liveness, not readiness. Anything
+    // more invasive (DB ping, schema check) would let a transient lock turn
+    // into a restart loop on the platform side. 200 always while the
+    // process is up.
+    if (pathname === "/health") {
+      return new Response(
+        JSON.stringify({ status: "ok", service: "parachute-hub", version: pkg.version }),
+        {
+          headers: {
+            "content-type": "application/json",
+            "cache-control": "no-store",
+          },
+        },
+      );
+    }
+
+    // First-boot setup wizard (hub#259). Three steps server-rendered:
+    //   GET  /admin/setup            — derive state, render the right step
+    //   POST /admin/setup/account    — create the admin row, set session
+    //   POST /admin/setup/vault      — provision the first vault
+    //
+    // The wizard owns the "should I 301 to /login now?" decision: setup is
+    // complete only when admin AND a vault entry both exist. A re-visit
+    // after partial setup picks up at the next step. See
+    // src/setup-wizard.ts for the renderer + handler internals.
+    if (pathname === "/admin/setup" || pathname.startsWith("/admin/setup/")) {
+      if (!getDb) return dbNotConfigured();
+      const wizardDeps: SetupWizardDeps = {
+        db: getDb(),
+        manifestPath,
+        configDir: CONFIG_DIR,
+        issuer: oauthDeps(req).issuer,
+        registry: getDefaultOperationsRegistry(),
+      };
+      if (deps?.supervisor !== undefined) wizardDeps.supervisor = deps.supervisor;
+      if (pathname === "/admin/setup") {
+        if (req.method !== "GET") return new Response("method not allowed", { status: 405 });
+        return handleSetupGet(req, wizardDeps);
+      }
+      if (pathname === "/admin/setup/account") {
+        if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+        return handleSetupAccountPost(req, wizardDeps);
+      }
+      if (pathname === "/admin/setup/vault") {
+        if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+        return handleSetupVaultPost(req, wizardDeps);
+      }
+      if (pathname === "/admin/setup/expose") {
+        if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+        return handleSetupExposePost(req, wizardDeps);
+      }
+      // hub#272 Item B: post-wizard direct module-install POSTs from
+      // the done-screen "What's next?" tiles. Path shape is
+      // `/admin/setup/install/<short>`; the handler rejects on
+      // unknown shorts, on `vault` (the wizard's own step owns that),
+      // and on missing session/CSRF — same gates as the vault POST.
+      if (pathname.startsWith("/admin/setup/install/")) {
+        if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+        const short = pathname.slice("/admin/setup/install/".length);
+        return handleSetupInstallPost(req, short, wizardDeps);
+      }
+      return new Response("not found", { status: 404 });
+    }
+
+    // Fresh-hub redirect: on a hub with no admin row yet, the discovery
+    // page (`/`, `/hub.html`) funnels straight to the wizard. The static
+    // portal isn't useful pre-setup — nothing's installed, the
+    // "Signed in" affordance has no session to surface — and the
+    // operator landing on `/` in a browser otherwise has to manually
+    // type `/admin/setup` to escape. 302 (not 301) so the redirect
+    // disappears the moment the wizard finishes.
+    //
+    // Sits before the JSON-shaped 503 gate below because `/` is an
+    // HTML surface — a JSON 503 there would render as raw text in the
+    // operator's browser tab. The 503 gate handles API + admin SPA +
+    // OAuth callers that branch on the structured body.
+    if (getDb && (pathname === "/" || pathname === "/hub.html") && userCount(getDb()) === 0) {
+      return new Response(null, {
+        status: 302,
+        headers: { location: "/admin/setup" },
+      });
+    }
+
+    // Pre-admin lockout. When the hub has booted with no admin row (the
+    // fresh-container case before PARACHUTE_INITIAL_ADMIN_* is set or
+    // /admin/setup is walked), every operator-facing surface that requires
+    // identity is meaningless — auth flows can't validate, the SPA can't
+    // mint a host-admin token, OAuth can't issue codes. Route those to a
+    // 503 that points at /admin/setup. Health, well-known, /admin/setup
+    // itself, OAuth third-party endpoints, and content proxies pass
+    // through; the fresh-hub `/` and `/hub.html` redirect above handled
+    // the discovery-page case.
+    //
+    // `shouldGateForSetup` runs first so non-gated paths (well-known, /,
+    // /health, /admin/setup) never touch getDb — keeping the
+    // existing OPTIONS-preflight contract that those routes are db-free.
+    if (getDb && shouldGateForSetup(pathname) && userCount(getDb()) === 0) {
+      return new Response(
+        JSON.stringify({
+          error: "setup_required",
+          error_description:
+            "no admin configured. Visit /admin/setup, or set PARACHUTE_INITIAL_ADMIN_USERNAME + PARACHUTE_INITIAL_ADMIN_PASSWORD and restart.",
+          setup_url: "/admin/setup",
+        }),
+        {
+          status: 503,
+          headers: {
+            "content-type": "application/json",
+            "cache-control": "no-store",
+          },
+        },
+      );
+    }
 
     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 });
       }
@@ -656,9 +1120,17 @@ export function hubFetch(
       // cross-origin from their own loopback port. Wildcard CORS is the
       // shape it needs. Browsers send an OPTIONS preflight when the request
       // adds non-simple headers; answer it with 204 + the same allow-list.
+      //
+      // `cache-control: no-store` matters here: the discovery page (`/`)
+      // fetches this doc and renders Service tiles from it; without
+      // no-store, the browser's HTTP cache returns the stale services list
+      // the next time the operator navigates back to `/` after installing
+      // a module via the admin SPA. The doc is small and built per-request
+      // anyway, so giving up cacheability has no real cost (hub#268 Item 1).
       const corsHeaders = {
         "access-control-allow-origin": "*",
         "access-control-allow-methods": "GET, OPTIONS",
+        "cache-control": "no-store",
       };
       if (req.method === "OPTIONS") {
         return new Response(null, { status: 204, headers: corsHeaders });
@@ -671,14 +1143,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 +1169,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
@@ -746,9 +1245,7 @@ export function hubFetch(
     }
 
     if (pathname === "/oauth/authorize") {
-      if (!getDb) {
-        return new Response("hub db not configured", { status: 503 });
-      }
+      if (!getDb) return dbNotConfigured();
       if (req.method === "GET") return handleAuthorizeGet(getDb(), req, oauthDeps(req));
       if (req.method === "POST") return handleAuthorizePost(getDb(), req, oauthDeps(req));
       return new Response("method not allowed", { status: 405 });
@@ -759,59 +1256,44 @@ export function hubFetch(
     // by handleAuthorizeGet when the operator hits a pending client. Three
     // gates inside the handler: CSRF, active session, same-origin Origin.
     if (pathname === "/oauth/authorize/approve") {
-      if (!getDb) {
-        return new Response("hub db not configured", { status: 503 });
-      }
+      if (!getDb) return dbNotConfigured();
       if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
       return handleApproveClientPost(getDb(), req, oauthDeps(req));
     }
 
     if (pathname === "/oauth/token") {
-      if (!getDb) {
-        return new Response("hub db not configured", { status: 503 });
-      }
+      if (!getDb) return dbNotConfigured();
       if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
       return handleToken(getDb(), req, oauthDeps(req));
     }
 
     if (pathname === "/oauth/register") {
-      if (!getDb) {
-        return new Response("hub db not configured", { status: 503 });
-      }
+      if (!getDb) return dbNotConfigured();
       if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
       return handleRegister(getDb(), req, oauthDeps(req));
     }
 
     if (pathname === "/oauth/revoke") {
-      if (!getDb) {
-        return new Response("hub db not configured", { status: 503 });
-      }
+      if (!getDb) return dbNotConfigured();
       if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
       return handleRevoke(getDb(), req, oauthDeps(req));
     }
 
     if (pathname === "/vaults") {
-      if (!getDb) {
-        return new Response("hub db not configured", { status: 503 });
-      }
+      if (!getDb) return dbNotConfigured();
       return handleCreateVault(req, {
         db: getDb(),
         issuer: oauthDeps(req).issuer,
       });
     }
 
-    // /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 });
+      if (!getDb) return dbNotConfigured();
       return handleHostAdminToken(req, {
         db: getDb(),
         issuer: oauthDeps(req).issuer,
@@ -819,7 +1301,7 @@ export function hubFetch(
     }
 
     if (pathname.startsWith("/admin/vault-admin-token/")) {
-      if (!getDb) return new Response("hub db not configured", { status: 503 });
+      if (!getDb) return dbNotConfigured();
       const vaultName = decodeURIComponent(pathname.slice("/admin/vault-admin-token/".length));
       // The vault name must correspond to an actual vault instance — same
       // shape the well-known doc derives. Source from services.json so a
@@ -838,8 +1320,122 @@ export function hubFetch(
       });
     }
 
+    if (pathname === "/api/me") {
+      if (!getDb) return dbNotConfigured();
+      return handleApiMe(req, { db: getDb() });
+    }
+
+    if (pathname === "/api/modules") {
+      if (!getDb) return dbNotConfigured();
+      const modulesDeps: Parameters<typeof handleApiModules>[1] = {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+        manifestPath: deps?.manifestPath ?? SERVICES_MANIFEST_PATH,
+      };
+      if (deps?.supervisor !== undefined) modulesDeps.supervisor = deps.supervisor;
+      return handleApiModules(req, modulesDeps);
+    }
+
+    // Channel toggle (hub#275) — pre-empts the /api/modules/:short/*
+    // routes below so `/api/modules/channel` doesn't accidentally match
+    // `parseModulesPath` (which would reject it as a non-curated short
+    // anyway, but precedence makes the intent explicit).
+    if (pathname === "/api/modules/channel") {
+      if (!getDb) return dbNotConfigured();
+      return handleApiModulesChannel(req, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+      });
+    }
+
+    // Module operation poll surface — pre-empts the /api/modules/:short/*
+    // routes below so `/api/modules/operations/<uuid>` doesn't accidentally
+    // match a parseModulesPath("/operations") and fall through.
+    if (pathname.startsWith("/api/modules/operations/")) {
+      if (!getDb) return dbNotConfigured();
+      if (!deps?.supervisor) {
+        return new Response(
+          JSON.stringify({
+            error: "supervisor_unavailable",
+            error_description:
+              "module operations require `parachute serve` (supervisor mode); on-box CLI uses `parachute install/upgrade/restart`",
+          }),
+          { status: 503, headers: { "content-type": "application/json" } },
+        );
+      }
+      const opId = decodeURIComponent(pathname.slice("/api/modules/operations/".length));
+      if (!opId || opId.includes("/")) return new Response("not found", { status: 404 });
+      return handleOperationGet(req, opId, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+        manifestPath: deps?.manifestPath ?? SERVICES_MANIFEST_PATH,
+        configDir: CONFIG_DIR,
+        supervisor: deps.supervisor,
+      });
+    }
+
+    // Per-module action endpoints: /api/modules/:short/{install,restart,upgrade,uninstall}.
+    if (pathname.startsWith("/api/modules/")) {
+      if (!getDb) return dbNotConfigured();
+      if (!deps?.supervisor) {
+        return new Response(
+          JSON.stringify({
+            error: "supervisor_unavailable",
+            error_description:
+              "module operations require `parachute serve` (supervisor mode); on-box CLI uses `parachute install/upgrade/restart`",
+          }),
+          { status: 503, headers: { "content-type": "application/json" } },
+        );
+      }
+      const match = parseModulesPath(pathname);
+      if (!match) return new Response("not found", { status: 404 });
+      const opsDeps = {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+        manifestPath: deps?.manifestPath ?? SERVICES_MANIFEST_PATH,
+        configDir: CONFIG_DIR,
+        supervisor: deps.supervisor,
+      };
+      switch (match.rest) {
+        case "install":
+          return handleInstall(req, match.short, opsDeps);
+        case "restart":
+          return handleRestart(req, match.short, opsDeps);
+        case "upgrade":
+          return handleUpgrade(req, match.short, opsDeps);
+        case "uninstall":
+          return handleUninstall(req, match.short, opsDeps);
+        default:
+          return new Response("not found", { status: 404 });
+      }
+    }
+
+    if (pathname === "/api/auth/mint-token") {
+      if (!getDb) return dbNotConfigured();
+      return handleApiMintToken(req, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+      });
+    }
+
+    if (pathname === "/api/auth/revoke-token") {
+      if (!getDb) return dbNotConfigured();
+      return handleApiRevokeToken(req, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+      });
+    }
+
+    if (pathname === "/api/auth/tokens") {
+      if (!getDb) return dbNotConfigured();
+      return handleApiTokens(req, {
+        db: getDb(),
+        issuer: oauthDeps(req).issuer,
+      });
+    }
+
     if (pathname === "/api/grants") {
-      if (!getDb) return new Response("hub db not configured", { status: 503 });
+      if (!getDb) return dbNotConfigured();
       return handleListGrants(req, {
         db: getDb(),
         issuer: oauthDeps(req).issuer,
@@ -847,7 +1443,7 @@ export function hubFetch(
     }
 
     if (pathname.startsWith("/api/grants/")) {
-      if (!getDb) return new Response("hub db not configured", { status: 503 });
+      if (!getDb) return dbNotConfigured();
       const clientId = decodeURIComponent(pathname.slice("/api/grants/".length));
       if (!clientId || clientId.includes("/")) {
         return new Response("not found", { status: 404 });
@@ -858,63 +1454,98 @@ export function hubFetch(
       });
     }
 
-    if (pathname === "/admin/login") {
-      if (!getDb) return new Response("hub db not configured", { status: 503 });
+    // 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 dbNotConfigured();
+      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 dbNotConfigured();
       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 (!getDb) return new Response("hub db not configured", { status: 503 });
+    if (pathname === "/logout") {
+      if (!getDb) return dbNotConfigured();
       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
@@ -929,7 +1560,7 @@ export function hubFetch(
 }
 
 if (import.meta.main) {
-  const { port, wellKnownDir, dbPath, issuer } = parseArgs(process.argv.slice(2));
+  const { port, hostname, wellKnownDir, dbPath, issuer } = parseArgs(process.argv.slice(2));
   let cachedDb: Database | undefined;
   const getDb = () => {
     if (!cachedDb) cachedDb = openHubDb(dbPath);
@@ -937,8 +1568,8 @@ if (import.meta.main) {
   };
   Bun.serve({
     port,
-    hostname: "127.0.0.1",
-    fetch: hubFetch(wellKnownDir, { getDb, issuer }),
+    hostname,
+    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
@@ -961,7 +1592,7 @@ if (import.meta.main) {
   });
   process.on("exit", cleanup);
   console.log(
-    `parachute-hub listening on http://127.0.0.1:${port} (dir=${wellKnownDir}, db=${dbPath}${
+    `parachute-hub listening on http://${hostname}:${port} (dir=${wellKnownDir}, db=${dbPath}${
       issuer ? `, issuer=${issuer}` : ""
     })`,
   );