npm - @openparachute/hub - Versions diffs - 0.5.7 → 0.5.10-rc.10 - Mend

@openparachute/hub 0.5.7 → 0.5.10-rc.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (85) hide show

package/package.json +1 -1
package/src/__tests__/admin-clients.test.ts +275 -0
package/src/__tests__/admin-handlers.test.ts +70 -323
package/src/__tests__/admin-host-admin-token.test.ts +52 -4
package/src/__tests__/api-me.test.ts +149 -0
package/src/__tests__/api-mint-token.test.ts +381 -0
package/src/__tests__/api-modules-ops.test.ts +658 -0
package/src/__tests__/api-modules.test.ts +426 -0
package/src/__tests__/api-revocation-list.test.ts +198 -0
package/src/__tests__/api-revoke-token.test.ts +320 -0
package/src/__tests__/api-tokens.test.ts +629 -0
package/src/__tests__/auth.test.ts +680 -16
package/src/__tests__/csrf.test.ts +40 -1
package/src/__tests__/expose-2fa-warning.test.ts +3 -5
package/src/__tests__/expose-cloudflare.test.ts +1 -1
package/src/__tests__/expose.test.ts +2 -2
package/src/__tests__/hub-server.test.ts +584 -67
package/src/__tests__/hub-settings.test.ts +377 -0
package/src/__tests__/hub.test.ts +123 -53
package/src/__tests__/install-source.test.ts +249 -0
package/src/__tests__/jwt-sign.test.ts +205 -0
package/src/__tests__/module-manifest.test.ts +48 -0
package/src/__tests__/oauth-handlers.test.ts +522 -5
package/src/__tests__/operator-token.test.ts +427 -3
package/src/__tests__/origin-check.test.ts +220 -0
package/src/__tests__/request-protocol.test.ts +54 -0
package/src/__tests__/serve-boot.test.ts +193 -0
package/src/__tests__/serve.test.ts +100 -0
package/src/__tests__/sessions.test.ts +25 -2
package/src/__tests__/setup-gate.test.ts +222 -0
package/src/__tests__/setup-wizard.test.ts +2089 -0
package/src/__tests__/status.test.ts +199 -0
package/src/__tests__/supervisor.test.ts +482 -0
package/src/__tests__/upgrade.test.ts +247 -4
package/src/__tests__/vault-name.test.ts +79 -0
package/src/__tests__/well-known.test.ts +69 -0
package/src/admin-clients.ts +139 -0
package/src/admin-handlers.ts +37 -254
package/src/admin-host-admin-token.ts +25 -10
package/src/admin-login-ui.ts +256 -0
package/src/admin-vault-admin-token.ts +1 -1
package/src/api-me.ts +124 -0
package/src/api-mint-token.ts +239 -0
package/src/api-modules-ops.ts +585 -0
package/src/api-modules.ts +367 -0
package/src/api-revocation-list.ts +59 -0
package/src/api-revoke-token.ts +153 -0
package/src/api-tokens.ts +224 -0
package/src/cli.ts +28 -0
package/src/commands/auth.ts +408 -51
package/src/commands/expose-2fa-warning.ts +6 -6
package/src/commands/serve-boot.ts +133 -0
package/src/commands/serve.ts +214 -0
package/src/commands/status.ts +74 -10
package/src/commands/upgrade.ts +33 -6
package/src/csrf.ts +34 -13
package/src/help.ts +55 -5
package/src/hub-control.ts +1 -0
package/src/hub-db.ts +87 -0
package/src/hub-server.ts +767 -136
package/src/hub-settings.ts +259 -0
package/src/hub.ts +298 -150
package/src/install-source.ts +291 -0
package/src/jwt-sign.ts +265 -5
package/src/module-manifest.ts +48 -10
package/src/oauth-handlers.ts +262 -56
package/src/oauth-ui.ts +23 -2
package/src/operator-token.ts +349 -18
package/src/origin-check.ts +127 -0
package/src/rate-limit.ts +5 -2
package/src/request-protocol.ts +48 -0
package/src/scope-explanations.ts +33 -2
package/src/sessions.ts +30 -18
package/src/setup-wizard.ts +2009 -0
package/src/supervisor.ts +411 -0
package/src/vault-name.ts +71 -0
package/src/well-known.ts +54 -1
package/web/ui/dist/assets/index-BDSEsaBY.css +1 -0
package/web/ui/dist/assets/index-CP07NbdF.js +61 -0
package/web/ui/dist/index.html +2 -2
package/src/__tests__/admin-config.test.ts +0 -281
package/src/admin-config-ui.ts +0 -534
package/src/admin-config.ts +0 -226
package/web/ui/dist/assets/index-BKzPDdB0.js +0 -60
package/web/ui/dist/assets/index-Dyk6g7vT.css +0 -1

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

@@ -9,6 +9,7 @@ import { findServiceUpstream, findVaultUpstream, hubFetch, layerOf } from "../hu
 import { pidPath } from "../process-state.ts";
 import { type ServiceEntry, writeManifest } from "../services-manifest.ts";
 import { rotateSigningKey } from "../signing-keys.ts";
+import { createUser } from "../users.ts";
 interface Harness {
   dir: string;
@@ -57,7 +58,7 @@ describe("hubFetch routing", () => {
     }
   });
-  test("/hub.html serves the same file as /", async () => {
+  test("/hub.html serves the same file as / (no DB → static fallback)", async () => {
     const h = makeHarness();
     try {
       writeFileSync(join(h.dir, "hub.html"), "<html>x</html>");
@@ -69,6 +70,64 @@ describe("hubFetch routing", () => {
     }
   });
+  test("/ renders the signed-out indicator dynamically when DB is configured but no session cookie (rc.13)", async () => {
+    // The dynamic path takes over from the static disk file the moment a
+    // DB is configured. With no session cookie, we still render — just
+    // with the "Sign in" affordance.
+    //
+    // hub#259 rc.6: requires an admin row to bypass the fresh-hub
+    // funnel redirect to /admin/setup (Bug 2 fix). Seed one so this
+    // test continues to exercise the signed-out-but-setup-done branch.
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { createUser } = await import("../users.ts");
+        await createUser(db, "owner", "pw");
+        const res = await hubFetch(h.dir, { getDb: () => db })(req("/"));
+        expect(res.status).toBe(200);
+        expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+        const body = await res.text();
+        expect(body).toContain('class="auth-indicator"');
+        expect(body).toContain("Sign in");
+        expect(body).not.toContain("Signed in as");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/ renders 'Signed in as <name>' + sign-out form when session cookie is active (rc.13)", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const { createUser } = await import("../users.ts");
+        const { createSession, buildSessionCookie, SESSION_TTL_MS } = await import(
+          "../sessions.ts"
+        );
+        const user = await createUser(db, "aaron", "pw");
+        const session = createSession(db, { userId: user.id });
+        const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
+        const res = await hubFetch(h.dir, { getDb: () => db })(req("/", { headers: { cookie } }));
+        expect(res.status).toBe(200);
+        const body = await res.text();
+        expect(body).toContain("Signed in as");
+        expect(body).toContain("aaron");
+        expect(body).toContain('action="/logout"');
+        expect(body).toContain('name="__csrf"');
+        // CSRF cookie was minted on the response (no prior cookie present).
+        expect(res.headers.get("set-cookie") ?? "").toContain("parachute_hub_csrf=");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
   test("/.well-known/parachute.json builds the doc dynamically from services.json", async () => {
     const h = makeHarness();
     try {
@@ -106,6 +165,29 @@ describe("hubFetch routing", () => {
     }
   });
+  test("/.well-known/parachute.json sets cache-control: no-store (hub#268 Item 1)", async () => {
+    // The discovery page (/) fetches this doc and renders Service tiles
+    // from it. Without no-store, the browser HTTP cache returns the
+    // stale services list the next time the operator clicks back to /
+    // after installing a module via /admin/modules. The doc is built
+    // per-request anyway, so giving up cacheability has no real cost.
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [] }, h.manifestPath);
+      const getRes = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/.well-known/parachute.json"),
+      );
+      expect(getRes.headers.get("cache-control")).toBe("no-store");
+      // Preflight gets the same header (same corsHeaders object).
+      const optRes = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/.well-known/parachute.json", { method: "OPTIONS" }),
+      );
+      expect(optRes.headers.get("cache-control")).toBe("no-store");
+    } finally {
+      h.cleanup();
+    }
+  });
   test("OPTIONS preflight on /.well-known/parachute.json returns 204 + CORS", async () => {
     const h = makeHarness();
     try {
@@ -194,6 +276,105 @@ describe("hubFetch routing", () => {
     }
   });
+  // Phase D consumer-side: each non-vault service entry's
+  // module.json:uiUrl + displayName ride through to doc.services. The
+  // discovery page (`/`) reads them to render data-driven Service tiles.
+  test("/.well-known/parachute.json surfaces uiUrl + displayName from non-vault module manifests", async () => {
+    const h = makeHarness();
+    try {
+      const notesEntry: ServiceEntry = {
+        name: "parachute-notes",
+        port: 5173,
+        paths: ["/notes"],
+        health: "/health",
+        version: "0.0.1",
+        installDir: "/fake/notes",
+      };
+      writeManifest({ services: [notesEntry] }, h.manifestPath);
+      const res = await hubFetch(h.dir, {
+        manifestPath: h.manifestPath,
+        readModuleManifest: async () => ({
+          name: "notes",
+          manifestName: "parachute-notes",
+          kind: "frontend",
+          port: 5173,
+          paths: ["/notes"],
+          health: "/health",
+          uiUrl: "/notes",
+          displayName: "Notes",
+        }),
+      })(req("/.well-known/parachute.json"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as {
+        services: Array<{ name: string; uiUrl?: string; displayName?: string }>;
+      };
+      const svc = body.services.find((s) => s.name === "parachute-notes");
+      expect(svc?.uiUrl).toMatch(/\/notes$/);
+      expect(svc?.displayName).toBe("Notes");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/.well-known/parachute.json omits uiUrl when the non-vault manifest has none", async () => {
+    const h = makeHarness();
+    try {
+      const notesEntry: ServiceEntry = {
+        name: "parachute-notes",
+        port: 5173,
+        paths: ["/notes"],
+        health: "/health",
+        version: "0.0.1",
+        installDir: "/fake/notes",
+      };
+      writeManifest({ services: [notesEntry] }, h.manifestPath);
+      const res = await hubFetch(h.dir, {
+        manifestPath: h.manifestPath,
+        readModuleManifest: async () => ({
+          name: "notes",
+          manifestName: "parachute-notes",
+          kind: "frontend",
+          port: 5173,
+          paths: ["/notes"],
+          health: "/health",
+          // no uiUrl declared — discovery page will skip the tile.
+        }),
+      })(req("/.well-known/parachute.json"));
+      const body = (await res.json()) as { services: Array<{ uiUrl?: string }> };
+      expect(body.services[0]).not.toHaveProperty("uiUrl");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/.well-known/parachute.json: uiUrl resolver is skipped for vault entries (loadManagementUrls handles vault)", 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.
+      const res = await hubFetch(h.dir, {
+        manifestPath: h.manifestPath,
+        readModuleManifest: async () => ({
+          name: "vault",
+          manifestName: "parachute-vault",
+          kind: "api",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/health",
+          uiUrl: "/should-be-ignored",
+        }),
+      })(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");
+    } finally {
+      h.cleanup();
+    }
+  });
   // The bug this PR fixes: `parachute vault create techne` updates
   // services.json but the old code only re-derived parachute.json on
   // `parachute expose`. With the dynamic build, the second GET reflects
@@ -398,15 +579,12 @@ describe("hubFetch routing", () => {
     }
   });
-  // SPA mounts after hub#168-realignment:
-  //   /vault — primary (vault list, NewVault, etc.)
-  //   /hub   — back-compat (only /hub/permissions; /hub/vaults* is 301'd
-  //            below, /hub/ root falls through to the SPA's 404 route)
-  //
-  // Same bundle at both mounts. Build base is /vault/, so asset URLs are
-  // origin-absolute and resolve regardless of which mount served the HTML.
+  // SPA mount after hub#231: single `/admin/*` mount serves vault
+  // provisioning + permissions + tokens. Pre-rename `/vault` and `/hub/*`
+  // SPA URLs are 301-redirected; the per-vault content proxy at
+  // `/vault/<name>/*` stays where it is.
-  test("/vault serves index.html when the SPA bundle exists", async () => {
+  test("/admin/vaults serves the SPA shell when the bundle exists", async () => {
     const h = makeHarness();
     try {
       const dist = join(h.dir, "dist");
@@ -414,7 +592,7 @@ describe("hubFetch routing", () => {
       writeFileSync(join(dist, "index.html"), "<!doctype html><div id=root></div>");
       writeManifest({ services: [] }, h.manifestPath);
       const res = await hubFetch(h.dir, { spaDistDir: dist, manifestPath: h.manifestPath })(
-        req("/vault"),
+        req("/admin/vaults"),
       );
       expect(res.status).toBe(200);
       expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
@@ -424,10 +602,7 @@ describe("hubFetch routing", () => {
     }
   });
-  test("/vault/new (client-side route, no matching vault) falls back to index.html", async () => {
-    // Routing-order check: `new` isn't a known vault, so proxyToVault
-    // returns undefined and we fall through to the SPA shell. The router
-    // takes over client-side and renders the NewVault form.
+  test("/admin/vaults/new serves the SPA shell (client-side route)", async () => {
     const h = makeHarness();
     try {
       const dist = join(h.dir, "dist");
@@ -435,7 +610,7 @@ describe("hubFetch routing", () => {
       writeFileSync(join(dist, "index.html"), "<!doctype html><div id=root></div>");
       writeManifest({ services: [] }, h.manifestPath);
       const res = await hubFetch(h.dir, { spaDistDir: dist, manifestPath: h.manifestPath })(
-        req("/vault/new"),
+        req("/admin/vaults/new"),
       );
       expect(res.status).toBe(200);
       expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
@@ -445,7 +620,34 @@ describe("hubFetch routing", () => {
     }
   });
-  test("/vault/assets/*.js is served with the matching content-type", async () => {
+  test("/admin/permissions serves the SPA shell", async () => {
+    const h = makeHarness();
+    try {
+      const dist = join(h.dir, "dist");
+      mkdirIfMissing(dist);
+      writeFileSync(join(dist, "index.html"), "<!doctype html><div id=root></div>");
+      const res = await hubFetch(h.dir, { spaDistDir: dist })(req("/admin/permissions"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/admin/tokens serves the SPA shell", async () => {
+    const h = makeHarness();
+    try {
+      const dist = join(h.dir, "dist");
+      mkdirIfMissing(dist);
+      writeFileSync(join(dist, "index.html"), "<!doctype html><div id=root></div>");
+      const res = await hubFetch(h.dir, { spaDistDir: dist })(req("/admin/tokens"));
+      expect(res.status).toBe(200);
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/admin/assets/*.js is served with the matching content-type", async () => {
     const h = makeHarness();
     try {
       const dist = join(h.dir, "dist");
@@ -456,7 +658,7 @@ describe("hubFetch routing", () => {
       writeFileSync(join(assets, "main.js"), "console.log('hi');");
       writeManifest({ services: [] }, h.manifestPath);
       const res = await hubFetch(h.dir, { spaDistDir: dist, manifestPath: h.manifestPath })(
-        req("/vault/assets/main.js"),
+        req("/admin/assets/main.js"),
       );
       expect(res.status).toBe(200);
       expect(res.headers.get("content-type")).toBe("application/javascript; charset=utf-8");
@@ -466,14 +668,14 @@ describe("hubFetch routing", () => {
     }
   });
-  test("/vault/* returns 503 with build hint when dist is missing", async () => {
+  test("/admin/* returns 503 with build hint when dist is missing", async () => {
     const h = makeHarness();
     try {
       writeManifest({ services: [] }, h.manifestPath);
       const res = await hubFetch(h.dir, {
         spaDistDir: join(h.dir, "missing"),
         manifestPath: h.manifestPath,
-      })(req("/vault"));
+      })(req("/admin/vaults"));
       expect(res.status).toBe(503);
       expect(await res.text()).toContain("bun run build");
     } finally {
@@ -481,125 +683,251 @@ describe("hubFetch routing", () => {
     }
   });
-  test("/vault rejects non-GET methods with 405", async () => {
+  test("/admin/vaults rejects non-GET methods with 405", async () => {
     const h = makeHarness();
     try {
       const dist = join(h.dir, "dist");
       mkdirIfMissing(dist);
       writeFileSync(join(dist, "index.html"), "<!doctype html>");
-      const res = await hubFetch(h.dir, { spaDistDir: dist })(req("/vault", { method: "POST" }));
+      const res = await hubFetch(h.dir, { spaDistDir: dist })(
+        req("/admin/vaults", { method: "POST" }),
+      );
       expect(res.status).toBe(405);
     } finally {
       h.cleanup();
     }
   });
-  test("/hub/permissions serves the SPA shell (back-compat mount)", async () => {
+  // 301 back-compat redirects (closes hub#231): pre-rename SPA URLs
+  // 301-redirect to the new /admin/* mount. Tests cover every entry in the
+  // dispatch — operator bookmarks landing on any of these still work.
+  test("301: /vault → /admin/vaults", async () => {
     const h = makeHarness();
     try {
-      const dist = join(h.dir, "dist");
-      mkdirIfMissing(dist);
-      writeFileSync(join(dist, "index.html"), "<!doctype html><div id=root></div>");
-      const res = await hubFetch(h.dir, { spaDistDir: dist })(req("/hub/permissions"));
-      expect(res.status).toBe(200);
-      expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
-      expect(await res.text()).toContain("<div id=root>");
+      const res = await hubFetch(h.dir)(req("/vault"));
+      expect(res.status).toBe(301);
+      expect(res.headers.get("location")).toBe("/admin/vaults");
     } finally {
       h.cleanup();
     }
   });
-  test("/hub/* returns 503 with build hint when dist is missing", async () => {
+  test("301: /vault/new → /admin/vaults/new", async () => {
     const h = makeHarness();
     try {
-      const res = await hubFetch(h.dir, { spaDistDir: join(h.dir, "missing") })(
-        req("/hub/permissions"),
-      );
-      expect(res.status).toBe(503);
-      expect(await res.text()).toContain("bun run build");
+      const res = await hubFetch(h.dir)(req("/vault/new"));
+      expect(res.status).toBe(301);
+      expect(res.headers.get("location")).toBe("/admin/vaults/new");
     } finally {
       h.cleanup();
     }
   });
-  test("/hub rejects non-GET methods with 405", async () => {
+  test("301: /vault preserves query string", async () => {
     const h = makeHarness();
     try {
-      const dist = join(h.dir, "dist");
-      mkdirIfMissing(dist);
-      writeFileSync(join(dist, "index.html"), "<!doctype html>");
-      const res = await hubFetch(h.dir, { spaDistDir: dist })(
-        req("/hub/permissions", { method: "POST" }),
-      );
-      expect(res.status).toBe(405);
+      const res = await hubFetch(h.dir)(req("/vault?next=foo"));
+      expect(res.status).toBe(301);
+      expect(res.headers.get("location")).toBe("/admin/vaults?next=foo");
     } finally {
       h.cleanup();
     }
   });
-  test("/hub/vaults issues a 301 redirect to /vault", async () => {
-    // Back-compat for bookmarks. The exact mount path used to be /hub/vaults
-    // before the realignment; permanent redirect keeps stale URLs working.
+  test("301: /hub/vaults → /admin/vaults (chain through the rename)", async () => {
+    // The /hub/vaults redirect predates #231 — it used to land at /vault.
+    // Now it lands at the final /admin/vaults so old bookmarks don't bounce
+    // through two redirects.
     const h = makeHarness();
     try {
       const res = await hubFetch(h.dir)(req("/hub/vaults"));
       expect(res.status).toBe(301);
-      expect(res.headers.get("location")).toBe("/vault");
+      expect(res.headers.get("location")).toBe("/admin/vaults");
     } finally {
       h.cleanup();
     }
   });
-  test("/hub/vaults/new redirects to /vault/new", async () => {
+  test("301: /hub/vaults/new → /admin/vaults/new", async () => {
     const h = makeHarness();
     try {
       const res = await hubFetch(h.dir)(req("/hub/vaults/new"));
       expect(res.status).toBe(301);
-      expect(res.headers.get("location")).toBe("/vault/new");
+      expect(res.headers.get("location")).toBe("/admin/vaults/new");
     } finally {
       h.cleanup();
     }
   });
-  test("/hub/vaults/* preserves the query string in the redirect", async () => {
+  test("301: /hub/vaults/* preserves the query string", async () => {
     const h = makeHarness();
     try {
       const res = await hubFetch(h.dir)(req("/hub/vaults/foo?bar=1&baz=2"));
       expect(res.status).toBe(301);
-      expect(res.headers.get("location")).toBe("/vault/foo?bar=1&baz=2");
+      expect(res.headers.get("location")).toBe("/admin/vaults/foo?bar=1&baz=2");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("301: /hub/permissions → /admin/permissions", async () => {
+    const h = makeHarness();
+    try {
+      const res = await hubFetch(h.dir)(req("/hub/permissions"));
+      expect(res.status).toBe(301);
+      expect(res.headers.get("location")).toBe("/admin/permissions");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("301: /hub/tokens → /admin/tokens", async () => {
+    const h = makeHarness();
+    try {
+      const res = await hubFetch(h.dir)(req("/hub/tokens"));
+      expect(res.status).toBe(301);
+      expect(res.headers.get("location")).toBe("/admin/tokens");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("301: /hub bare → /admin/vaults", async () => {
+    const h = makeHarness();
+    try {
+      const res = await hubFetch(h.dir)(req("/hub"));
+      expect(res.status).toBe(301);
+      expect(res.headers.get("location")).toBe("/admin/vaults");
+    } finally {
+      h.cleanup();
+    }
+  });
+  // Login surface rename redirects (auth-UX cleanup): /admin/login and
+  // /admin/logout 301 to /login and /logout. Path-only test — the
+  // handlers themselves are exercised through the existing
+  // handleAdminLoginGet/Post + handleAdminLogoutPost test files.
+  test("301: /admin/login → /login", async () => {
+    const h = makeHarness();
+    try {
+      const res = await hubFetch(h.dir)(req("/admin/login"));
+      expect(res.status).toBe(301);
+      expect(res.headers.get("location")).toBe("/login");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("301: /admin/login preserves the next= query param", async () => {
+    const h = makeHarness();
+    try {
+      const res = await hubFetch(h.dir)(req("/admin/login?next=/admin/permissions"));
+      expect(res.status).toBe(301);
+      expect(res.headers.get("location")).toBe("/login?next=/admin/permissions");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("301: /admin/config → /admin/vaults (legacy server-rendered portal retired)", async () => {
+    const h = makeHarness();
+    try {
+      const res = await hubFetch(h.dir)(req("/admin/config"));
+      expect(res.status).toBe(301);
+      expect(res.headers.get("location")).toBe("/admin/vaults");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("301: /admin/config/<name> → /admin/vaults", async () => {
+    const h = makeHarness();
+    try {
+      const res = await hubFetch(h.dir)(req("/admin/config/vault"));
+      expect(res.status).toBe(301);
+      expect(res.headers.get("location")).toBe("/admin/vaults");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("301: /admin/logout → /logout", async () => {
+    const h = makeHarness();
+    try {
+      const res = await hubFetch(h.dir)(req("/admin/logout"));
+      expect(res.status).toBe(301);
+      expect(res.headers.get("location")).toBe("/logout");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/hub/<unknown> (no SPA mount anymore) → 404", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [] }, h.manifestPath);
+      const res = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/hub/unknown-thing"),
+      );
+      expect(res.status).toBe(404);
     } finally {
       h.cleanup();
     }
   });
-  test("/oauth/authorize without configured db returns 503", async () => {
+  test("/oauth/authorize without configured db returns 503 JSON", async () => {
     const h = makeHarness();
     try {
       const res = await hubFetch(h.dir)(req("/oauth/authorize?client_id=x"));
       expect(res.status).toBe(503);
+      const body = (await res.json()) as { error: string; error_description: string };
+      expect(body.error).toBe("service_unavailable");
+      expect(body.error_description).toBe("hub db not configured");
     } finally {
       h.cleanup();
     }
   });
-  test("every DB-dependent route returns 503 when getDb is absent (closes #139)", async () => {
+  test("every DB-dependent route returns 503 when getDb is absent (closes #139, JSON shape closes #227)", async () => {
     const h = makeHarness();
     try {
       const fetch = hubFetch(h.dir);
+      // Every DB-dependent guard returns the same JSON 503 shape
+      // (`service_unavailable`) so consumers don't branch on content-type to
+      // extract the message. The pattern was already canonical on
+      // /api/auth/* (hub#215, #226) and was extended to all guards in
+      // hub#227.
       const cases: Array<[string, RequestInit]> = [
+        ["/oauth/authorize?client_id=x", { method: "GET" }],
+        ["/oauth/authorize/approve", { method: "POST" }],
         ["/oauth/token", { method: "POST" }],
         ["/oauth/register", { method: "POST" }],
         ["/oauth/revoke", { method: "POST" }],
         ["/vaults", { method: "POST" }],
-        ["/admin/login", { method: "POST" }],
-        ["/admin/logout", { method: "POST" }],
-        ["/admin/config", { method: "GET" }],
-        ["/admin/config/example", { method: "POST" }],
+        // /login + /logout — canonical names since the auth-UX rename;
+        // /admin/login + /admin/logout 301-redirect to here (separate
+        // tests pin the redirects themselves).
+        ["/login", { method: "POST" }],
+        ["/logout", { method: "POST" }],
         ["/admin/host-admin-token", { method: "GET" }],
+        ["/admin/vault-admin-token/demo", { method: "GET" }],
+        ["/api/me", { method: "GET" }],
+        ["/api/auth/mint-token", { method: "POST" }],
+        ["/api/auth/revoke-token", { method: "POST" }],
+        ["/api/auth/tokens", { method: "GET" }],
+        ["/api/grants", { method: "GET" }],
+        ["/api/grants/client-x", { method: "DELETE" }],
+        ["/api/oauth/clients/client-x", { method: "GET" }],
+        ["/api/oauth/clients/client-x/approve", { method: "POST" }],
       ];
       for (const [path, init] of cases) {
         const res = await fetch(req(path, init));
         expect(res.status).toBe(503);
+        expect(res.headers.get("content-type")?.toLowerCase()).toContain("application/json");
+        const body = (await res.json()) as { error: string; error_description: string };
+        expect(body.error).toBe("service_unavailable");
+        expect(body.error_description).toBe("hub db not configured");
       }
     } finally {
       h.cleanup();
@@ -611,6 +939,11 @@ describe("hubFetch routing", () => {
     try {
       const db = openHubDb(hubDbPath(h.dir));
       try {
+        // Seed an admin so the pre-admin setup gate (hub#258) doesn't
+        // 503 the request before the OAuth method-allow check runs.
+        // OAuth routing semantics are what this test pins; the setup
+        // gate has its own coverage in src/__tests__/setup-gate.test.ts.
+        await createUser(db, "owner", "pw");
         const res = await hubFetch(h.dir, { getDb: () => db })(
           req("/oauth/token", { method: "GET" }),
         );
@@ -628,6 +961,7 @@ describe("hubFetch routing", () => {
     try {
       const db = openHubDb(hubDbPath(h.dir));
       try {
+        await createUser(db, "owner", "pw");
         const res = await hubFetch(h.dir, {
           getDb: () => db,
           issuer: "https://hub.example",
@@ -649,6 +983,191 @@ describe("hubFetch routing", () => {
     }
   });
+  // Platform health check (hub#258). Returns 200 JSON regardless of DB
+  // state — Render et al. poll this every few seconds and a transient DB
+  // open shouldn't cascade into a restart loop. The body advertises the
+  // running version so a deploy verifier can confirm the rolled-out
+  // image is the one it expected.
+  test("/health returns 200 JSON without invoking the db", async () => {
+    const h = makeHarness();
+    try {
+      const res = await hubFetch(h.dir, {
+        getDb: () => {
+          throw new Error("getDb must not be called by /health");
+        },
+      })(req("/health"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toContain("application/json");
+      expect(res.headers.get("cache-control")).toBe("no-store");
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("ok");
+      expect(body.service).toBe("parachute-hub");
+      expect(typeof body.version).toBe("string");
+    } finally {
+      h.cleanup();
+    }
+  });
+  // First-boot setup wizard (hub#259, expanding hub#258's static
+  // placeholder). When no admin exists, GET /admin/setup renders the
+  // wizard's account-step form. Once admin + vault both exist, it 301s
+  // to /login so a stale bookmark still lands somewhere useful. With
+  // admin but no vault, the wizard resumes at the vault step.
+  test("/admin/setup renders the wizard's account form when no admin exists", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, { getDb: () => db })(req("/admin/setup"));
+        expect(res.status).toBe(200);
+        expect(res.headers.get("content-type")).toContain("text/html");
+        const body = await res.text();
+        expect(body).toContain('action="/admin/setup/account"');
+        // Env-var seed path is still surfaced as the alt-path disclosure.
+        expect(body).toContain("PARACHUTE_INITIAL_ADMIN_USERNAME");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/admin/setup 301s to /login once admin + vault + expose mode all exist (hub#259, hub#268)", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        await createUser(db, "owner", "pw");
+        // Seed the vault entry + expose-mode answer so the wizard's
+        // state derives as "done" and the GET 301s. Without expose
+        // (hub#268 Item 2) the wizard would resume on the expose step.
+        const { writeManifest } = await import("../services-manifest.ts");
+        const { setSetting } = await import("../hub-settings.ts");
+        const { join } = await import("node:path");
+        writeManifest(
+          {
+            services: [
+              {
+                name: "parachute-vault",
+                version: "0.1.0",
+                port: 1940,
+                paths: ["/vault/default"],
+                health: "/health",
+              },
+            ],
+          },
+          join(h.dir, "services.json"),
+        );
+        setSetting(db, "setup_expose_mode", "localhost");
+        const res = await hubFetch(h.dir, {
+          getDb: () => db,
+          manifestPath: join(h.dir, "services.json"),
+        })(req("/admin/setup"));
+        expect(res.status).toBe(301);
+        expect(res.headers.get("location")).toBe("/login");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+  // Pre-admin lockout (hub#258). When no admin row exists, operator-
+  // facing surfaces (admin/api/login) 503 with a JSON body pointing at
+  // /admin/setup. Public surfaces (health, well-known, /, oauth, vault,
+  // /admin/setup itself) stay open so the container is reachable and
+  // OAuth third parties aren't held hostage by admin onboarding.
+  test("pre-admin lockout: /admin/vaults returns 503 setup_required", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, { getDb: () => db })(req("/admin/vaults"));
+        expect(res.status).toBe(503);
+        const body = (await res.json()) as Record<string, unknown>;
+        expect(body.error).toBe("setup_required");
+        expect(body.setup_url).toBe("/admin/setup");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("pre-admin lockout: /api/me returns 503 setup_required", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, { getDb: () => db })(req("/api/me"));
+        expect(res.status).toBe(503);
+        const body = (await res.json()) as Record<string, unknown>;
+        expect(body.error).toBe("setup_required");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("pre-admin lockout: /login is gated, /admin/setup + /health + well-known stay open, / funnels to /admin/setup", async () => {
+    const h = makeHarness();
+    try {
+      writeFileSync(join(h.dir, "hub.html"), "<html>discovery</html>");
+      writeManifest({ services: [] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const handler = hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath });
+        // /login gated
+        const loginRes = await handler(req("/login"));
+        expect(loginRes.status).toBe(503);
+        // /admin/setup open
+        const setupRes = await handler(req("/admin/setup"));
+        expect(setupRes.status).toBe(200);
+        // /health open
+        const healthRes = await handler(req("/health"));
+        expect(healthRes.status).toBe(200);
+        // / funnels to the wizard (hub#259 rc.6 fix for Bug 2 — the
+        // static portal pre-setup is useless; redirect to setup).
+        const rootRes = await handler(req("/"));
+        expect(rootRes.status).toBe(302);
+        expect(rootRes.headers.get("location")).toBe("/admin/setup");
+        // /.well-known/parachute.json open
+        const wkRes = await handler(req("/.well-known/parachute.json"));
+        expect(wkRes.status).toBe(200);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("pre-admin lockout falls away once an admin exists", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        // Before: /api/me 503s under the lockout.
+        const before = await hubFetch(h.dir, { getDb: () => db })(req("/api/me"));
+        expect(before.status).toBe(503);
+        // After seeding an admin: dispatch resumes normal handling.
+        await createUser(db, "owner", "pw");
+        const after = await hubFetch(h.dir, { getDb: () => db })(req("/api/me"));
+        // /api/me with no session returns `hasSession: false` 200, not 503.
+        expect(after.status).toBe(200);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
   test("live Bun.serve round-trip: / and /.well-known resolve", async () => {
     const h = makeHarness();
     try {
@@ -1024,15 +1543,15 @@ describe("hubFetch /vault/<name>/* dynamic proxy (#144)", () => {
     }
   });
-  test("single-segment /vault/<name> picks proxy when registered, SPA shell when not", async () => {
+  test("single-segment /vault/<name> picks proxy when registered, 404 when not", async () => {
     // Two cases share one fixture so the contrast is explicit:
     //   - `/vault/default` is registered → proxy answers (200, JSON tag).
-    //   - `/vault/nonexistent` has no match → falls through to the SPA
-    //     shell (200, text/html). The SPA's :name route renders client-side
-    //     and shows a 404 in-app, but at the wire it's the shell.
+    //   - `/vault/nonexistent` has no match → 404 directly (no SPA-shell
+    //     fallback under /vault since hub#231 moved the admin SPA to
+    //     /admin/*; the /vault/<name>/* slot is now exclusively the
+    //     per-vault content proxy).
     // This is the routing-order seam #173 introduced — proxy is consulted
-    // before the SPA fallback, and the fallback only triggers when no
-    // vault claims the path.
+    // before the 404; the SPA fallback that used to live here is gone.
     const h = makeHarness();
     const upstream = startUpstream("default-vault");
     try {
@@ -1065,10 +1584,8 @@ describe("hubFetch /vault/<name>/* dynamic proxy (#144)", () => {
       expect(body.tag).toBe("default-vault");
       expect(body.pathname).toBe("/vault/default");
-      const shelled = await fetcher(req("/vault/nonexistent"));
-      expect(shelled.status).toBe(200);
-      expect(shelled.headers.get("content-type")).toBe("text/html; charset=utf-8");
-      expect(await shelled.text()).toContain("<div id=root>");
+      const notFound = await fetcher(req("/vault/nonexistent"));
+      expect(notFound.status).toBe(404);
     } finally {
       upstream.stop();
       h.cleanup();