npm - @openparachute/hub - Versions diffs - 0.3.0-rc.1 → 0.5.1 - Mend

@openparachute/hub 0.3.0-rc.1 → 0.5.1

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 (91) hide show

package/README.md +19 -17
package/package.json +15 -4
package/src/__tests__/admin-auth.test.ts +197 -0
package/src/__tests__/admin-config.test.ts +281 -0
package/src/__tests__/admin-grants.test.ts +271 -0
package/src/__tests__/admin-handlers.test.ts +530 -0
package/src/__tests__/admin-host-admin-token.test.ts +115 -0
package/src/__tests__/admin-vault-admin-token.test.ts +190 -0
package/src/__tests__/admin-vaults.test.ts +615 -0
package/src/__tests__/auth-codes.test.ts +253 -0
package/src/__tests__/auth.test.ts +1063 -17
package/src/__tests__/cli.test.ts +50 -0
package/src/__tests__/clients.test.ts +264 -0
package/src/__tests__/cloudflare-state.test.ts +167 -7
package/src/__tests__/csrf.test.ts +117 -0
package/src/__tests__/expose-cloudflare.test.ts +232 -37
package/src/__tests__/expose-off-auto.test.ts +15 -9
package/src/__tests__/expose-public-auto.test.ts +153 -0
package/src/__tests__/expose.test.ts +216 -24
package/src/__tests__/grants.test.ts +164 -0
package/src/__tests__/hub-db.test.ts +153 -0
package/src/__tests__/hub-server.test.ts +984 -26
package/src/__tests__/hub.test.ts +56 -49
package/src/__tests__/install.test.ts +327 -3
package/src/__tests__/jwks.test.ts +37 -0
package/src/__tests__/jwt-sign.test.ts +361 -0
package/src/__tests__/lifecycle.test.ts +616 -5
package/src/__tests__/module-manifest.test.ts +183 -0
package/src/__tests__/oauth-handlers.test.ts +3112 -0
package/src/__tests__/oauth-ui.test.ts +253 -0
package/src/__tests__/operator-token.test.ts +140 -0
package/src/__tests__/providers-detect.test.ts +158 -0
package/src/__tests__/scope-explanations.test.ts +108 -0
package/src/__tests__/scope-registry.test.ts +220 -0
package/src/__tests__/services-manifest.test.ts +137 -1
package/src/__tests__/sessions.test.ts +116 -0
package/src/__tests__/setup.test.ts +361 -0
package/src/__tests__/signing-keys.test.ts +153 -0
package/src/__tests__/upgrade.test.ts +541 -0
package/src/__tests__/users.test.ts +154 -0
package/src/__tests__/well-known.test.ts +127 -10
package/src/admin-auth.ts +126 -0
package/src/admin-config-ui.ts +534 -0
package/src/admin-config.ts +226 -0
package/src/admin-grants.ts +160 -0
package/src/admin-handlers.ts +365 -0
package/src/admin-host-admin-token.ts +83 -0
package/src/admin-vault-admin-token.ts +98 -0
package/src/admin-vaults.ts +359 -0
package/src/auth-codes.ts +189 -0
package/src/cli.ts +202 -25
package/src/clients.ts +210 -0
package/src/cloudflare/config.ts +25 -6
package/src/cloudflare/state.ts +108 -28
package/src/commands/auth.ts +851 -19
package/src/commands/expose-cloudflare.ts +85 -45
package/src/commands/expose-interactive.ts +20 -44
package/src/commands/expose-off-auto.ts +27 -11
package/src/commands/expose-public-auto.ts +179 -0
package/src/commands/expose.ts +63 -32
package/src/commands/install.ts +337 -48
package/src/commands/lifecycle.ts +269 -38
package/src/commands/setup.ts +366 -0
package/src/commands/status.ts +4 -1
package/src/commands/upgrade.ts +429 -0
package/src/csrf.ts +101 -0
package/src/grants.ts +142 -0
package/src/help.ts +133 -19
package/src/hub-control.ts +12 -0
package/src/hub-db.ts +164 -0
package/src/hub-server.ts +643 -22
package/src/hub.ts +97 -390
package/src/jwks.ts +41 -0
package/src/jwt-audience.ts +40 -0
package/src/jwt-sign.ts +275 -0
package/src/module-manifest.ts +435 -0
package/src/oauth-handlers.ts +1175 -0
package/src/oauth-ui.ts +582 -0
package/src/operator-token.ts +129 -0
package/src/providers/detect.ts +97 -0
package/src/scope-explanations.ts +137 -0
package/src/scope-registry.ts +158 -0
package/src/service-spec.ts +270 -97
package/src/services-manifest.ts +57 -1
package/src/sessions.ts +115 -0
package/src/signing-keys.ts +120 -0
package/src/users.ts +144 -0
package/src/well-known.ts +62 -26
package/web/ui/dist/assets/index-BKzPDdB0.js +60 -0
package/web/ui/dist/assets/index-Dyk6g7vT.css +1 -0
package/web/ui/dist/index.html +14 -0

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

@@ -1,29 +1,54 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { hubFetch } from "../hub-server.ts";
+import { fileURLToPath } from "node:url";
+import { HUB_SVC, hubPortPath } from "../hub-control.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { findVaultUpstream, hubFetch } from "../hub-server.ts";
+import { pidPath } from "../process-state.ts";
+import { type ServiceEntry, writeManifest } from "../services-manifest.ts";
+import { rotateSigningKey } from "../signing-keys.ts";
 interface Harness {
   dir: string;
+  manifestPath: string;
   cleanup: () => void;
 }
 function makeHarness(): Harness {
   const dir = mkdtempSync(join(tmpdir(), "pcli-hub-server-"));
-  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+  return {
+    dir,
+    manifestPath: join(dir, "services.json"),
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  };
 }
 function req(path: string, init?: RequestInit): Request {
   return new Request(`http://127.0.0.1/${path.replace(/^\//, "")}`, init);
 }
+function mkdirIfMissing(dir: string): void {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+function vaultEntry(name: string): ServiceEntry {
+  return {
+    name: `parachute-vault-${name}`,
+    port: 1940,
+    paths: [`/vault/${name}`],
+    health: "/health",
+    version: "0.4.0",
+  };
+}
 describe("hubFetch routing", () => {
   test("/ serves hub.html with text/html content-type", async () => {
     const h = makeHarness();
     try {
       writeFileSync(join(h.dir, "hub.html"), "<html><body>hi</body></html>");
-      const res = hubFetch(h.dir)(req("/"));
+      const res = await hubFetch(h.dir)(req("/"));
       expect(res.status).toBe(200);
       expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
       expect(await res.text()).toContain("<html>");
@@ -36,7 +61,7 @@ describe("hubFetch routing", () => {
     const h = makeHarness();
     try {
       writeFileSync(join(h.dir, "hub.html"), "<html>x</html>");
-      const res = hubFetch(h.dir)(req("/hub.html"));
+      const res = await hubFetch(h.dir)(req("/hub.html"));
       expect(res.status).toBe(200);
       expect(await res.text()).toBe("<html>x</html>");
     } finally {
@@ -44,14 +69,18 @@ describe("hubFetch routing", () => {
     }
   });
-  test("/.well-known/parachute.json serves JSON with application/json", async () => {
+  test("/.well-known/parachute.json builds the doc dynamically from services.json", async () => {
     const h = makeHarness();
     try {
-      writeFileSync(join(h.dir, "parachute.json"), '{"vaults":[]}\n');
-      const res = hubFetch(h.dir)(req("/.well-known/parachute.json"));
+      writeManifest({ services: [vaultEntry("default")] }, h.manifestPath);
+      const res = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/.well-known/parachute.json"),
+      );
       expect(res.status).toBe(200);
       expect(res.headers.get("content-type")).toBe("application/json");
-      expect(await res.text()).toBe('{"vaults":[]}\n');
+      const body = (await res.json()) as { vaults: Array<{ name: string; url: string }> };
+      expect(body.vaults).toHaveLength(1);
+      expect(body.vaults[0]?.name).toBe("default");
     } finally {
       h.cleanup();
     }
@@ -65,8 +94,10 @@ describe("hubFetch routing", () => {
   test("/.well-known/parachute.json includes wildcard CORS headers on GET", async () => {
     const h = makeHarness();
     try {
-      writeFileSync(join(h.dir, "parachute.json"), '{"vaults":[]}\n');
-      const res = hubFetch(h.dir)(req("/.well-known/parachute.json"));
+      writeManifest({ services: [] }, h.manifestPath);
+      const res = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/.well-known/parachute.json"),
+      );
       expect(res.status).toBe(200);
       expect(res.headers.get("access-control-allow-origin")).toBe("*");
       expect(res.headers.get("access-control-allow-methods")).toBe("GET, OPTIONS");
@@ -78,8 +109,10 @@ describe("hubFetch routing", () => {
   test("OPTIONS preflight on /.well-known/parachute.json returns 204 + CORS", async () => {
     const h = makeHarness();
     try {
-      // Note: no parachute.json on disk — preflight must not depend on it.
-      const res = hubFetch(h.dir)(req("/.well-known/parachute.json", { method: "OPTIONS" }));
+      // Note: no services.json on disk — preflight must not depend on it.
+      const res = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/.well-known/parachute.json", { method: "OPTIONS" }),
+      );
       expect(res.status).toBe(204);
       expect(res.headers.get("access-control-allow-origin")).toBe("*");
       expect(res.headers.get("access-control-allow-methods")).toBe("GET, OPTIONS");
@@ -88,14 +121,165 @@ describe("hubFetch routing", () => {
     }
   });
-  test("missing parachute.json still returns CORS headers on the 404", async () => {
-    // If the response 404s without CORS, the browser treats it as a network
-    // error and the consumer can't even tell the server is reachable.
+  // The dispatch from team-lead specifically: a fresh hub install has no
+  // expose run yet, but `parachute vault create` writes services.json. The
+  // well-known doc must reflect that vault on the *next* GET — no expose,
+  // no parachute.json on disk.
+  test("/.well-known/parachute.json works on a fresh hub (services.json only, no expose run)", async () => {
     const h = makeHarness();
     try {
-      const res = hubFetch(h.dir)(req("/.well-known/parachute.json"));
-      expect(res.status).toBe(404);
+      writeManifest({ services: [vaultEntry("default")] }, h.manifestPath);
+      const res = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/.well-known/parachute.json"),
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as {
+        vaults: Array<{ name: string }>;
+        services: Array<{ name: string }>;
+      };
+      expect(body.vaults.map((v) => v.name)).toEqual(["default"]);
+      expect(body.services.map((s) => s.name)).toEqual(["parachute-vault-default"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+  // hub#158: each vault entry's module.json:managementUrl rides through to
+  // the well-known doc. The SPA reads it to decide whether to render a
+  // "Manage" link on the row.
+  test("/.well-known/parachute.json surfaces managementUrl from the vault module manifest", async () => {
+    const h = makeHarness();
+    try {
+      const entryWithInstallDir: ServiceEntry = { ...vaultEntry("default"), installDir: "/fake" };
+      writeManifest({ services: [entryWithInstallDir] }, h.manifestPath);
+      const res = await hubFetch(h.dir, {
+        manifestPath: h.manifestPath,
+        // Stand in for module-manifest.readModuleManifest — production reads
+        // <installDir>/.parachute/module.json off disk.
+        readModuleManifest: async () => ({
+          name: "vault",
+          manifestName: "parachute-vault",
+          kind: "api",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/health",
+          managementUrl: "/admin",
+        }),
+      })(req("/.well-known/parachute.json"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as {
+        vaults: Array<{ name: string; managementUrl?: string }>;
+      };
+      expect(body.vaults).toHaveLength(1);
+      expect(body.vaults[0]?.managementUrl).toBe("/admin");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/.well-known/parachute.json omits managementUrl when manifest has none", async () => {
+    const h = makeHarness();
+    try {
+      const entryWithInstallDir: ServiceEntry = { ...vaultEntry("default"), installDir: "/fake" };
+      writeManifest({ services: [entryWithInstallDir] }, h.manifestPath);
+      const res = await hubFetch(h.dir, {
+        manifestPath: h.manifestPath,
+        readModuleManifest: async () => null,
+      })(req("/.well-known/parachute.json"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { vaults: Array<{ managementUrl?: string }> };
+      expect(body.vaults[0]).not.toHaveProperty("managementUrl");
+    } 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
+  // the new vault without any other action.
+  test("services.json change is reflected on the next GET (no restart, no expose)", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("default")] }, h.manifestPath);
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const before = (await (await fetcher(req("/.well-known/parachute.json"))).json()) as {
+        vaults: Array<{ name: string }>;
+      };
+      expect(before.vaults.map((v) => v.name)).toEqual(["default"]);
+      writeManifest({ services: [vaultEntry("default"), vaultEntry("techne")] }, h.manifestPath);
+      const after = (await (await fetcher(req("/.well-known/parachute.json"))).json()) as {
+        vaults: Array<{ name: string }>;
+      };
+      expect(after.vaults.map((v) => v.name)).toEqual(["default", "techne"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("missing services.json yields an empty doc with CORS, not a 404", async () => {
+    // No expose, no `parachute vault create` yet — readManifest returns
+    // {services: []}, so the doc is well-formed-but-empty rather than a
+    // network-error-looking 404.
+    const h = makeHarness();
+    try {
+      const res = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/.well-known/parachute.json"),
+      );
+      expect(res.status).toBe(200);
       expect(res.headers.get("access-control-allow-origin")).toBe("*");
+      expect(await res.json()).toEqual({ vaults: [], services: [] });
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("canonicalOrigin uses configured issuer when present", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("default")] }, h.manifestPath);
+      const res = await hubFetch(h.dir, {
+        manifestPath: h.manifestPath,
+        issuer: "https://hub.example",
+      })(req("/.well-known/parachute.json"));
+      const body = (await res.json()) as { vaults: Array<{ url: string }> };
+      expect(body.vaults[0]?.url).toBe("https://hub.example/vault/default");
+    } finally {
+      h.cleanup();
+    }
+  });
+  // Same fallback shape as the OAuth handlers: when the hub isn't started
+  // with `--issuer` (local dev, direct loopback hit), use the request's own
+  // origin so the doc is still self-consistent.
+  test("canonicalOrigin falls back to the request origin when no issuer is configured", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("default")] }, h.manifestPath);
+      const res = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        new Request("http://127.0.0.1:1939/.well-known/parachute.json"),
+      );
+      const body = (await res.json()) as { vaults: Array<{ url: string }> };
+      expect(body.vaults[0]?.url).toBe("http://127.0.0.1:1939/vault/default");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("malformed services.json returns 500 + CORS, not a crash", async () => {
+    const h = makeHarness();
+    try {
+      writeFileSync(h.manifestPath, "{ not json");
+      const res = await hubFetch(h.dir, { manifestPath: h.manifestPath })(
+        req("/.well-known/parachute.json"),
+      );
+      expect(res.status).toBe(500);
+      expect(res.headers.get("access-control-allow-origin")).toBe("*");
+      const body = (await res.json()) as { error: string };
+      expect(body.error).toContain("well-known build failed");
     } finally {
       h.cleanup();
     }
@@ -105,7 +289,7 @@ describe("hubFetch routing", () => {
     const h = makeHarness();
     try {
       writeFileSync(join(h.dir, "hub.html"), "<html/>");
-      const res = hubFetch(h.dir)(req("/nope"));
+      const res = await hubFetch(h.dir)(req("/nope"));
       expect(res.status).toBe(404);
     } finally {
       h.cleanup();
@@ -116,18 +300,350 @@ describe("hubFetch routing", () => {
     const h = makeHarness();
     try {
       // dir exists but no files in it
-      const res = hubFetch(h.dir)(req("/"));
+      const res = await hubFetch(h.dir)(req("/"));
       expect(res.status).toBe(404);
     } finally {
       h.cleanup();
     }
   });
-  test("missing parachute.json returns 404 rather than crashing", async () => {
+  test("/.well-known/jwks.json returns the JWKS from the live db", async () => {
     const h = makeHarness();
     try {
-      const res = hubFetch(h.dir)(req("/.well-known/parachute.json"));
-      expect(res.status).toBe(404);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const k = rotateSigningKey(db);
+        const res = await hubFetch(h.dir, { getDb: () => db })(req("/.well-known/jwks.json"));
+        expect(res.status).toBe(200);
+        expect(res.headers.get("content-type")).toBe("application/json");
+        expect(res.headers.get("access-control-allow-origin")).toBe("*");
+        const body = (await res.json()) as { keys: Array<{ kid: string; alg: string; n: string }> };
+        expect(body.keys.length).toBe(1);
+        expect(body.keys[0]?.kid).toBe(k.kid);
+        expect(body.keys[0]?.alg).toBe("RS256");
+        expect(body.keys[0]?.n.length).toBeGreaterThan(0);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("OPTIONS preflight on /.well-known/jwks.json returns 204 + CORS without touching the db", async () => {
+    const h = makeHarness();
+    try {
+      // Pass a getDb that throws — preflight must not invoke it.
+      const res = await hubFetch(h.dir, {
+        getDb: () => {
+          throw new Error("getDb should not be called for OPTIONS");
+        },
+      })(req("/.well-known/jwks.json", { method: "OPTIONS" }));
+      expect(res.status).toBe(204);
+      expect(res.headers.get("access-control-allow-origin")).toBe("*");
+      expect(res.headers.get("access-control-allow-methods")).toBe("GET, OPTIONS");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/.well-known/jwks.json returns 503 + CORS when db is not configured", async () => {
+    const h = makeHarness();
+    try {
+      const res = await hubFetch(h.dir)(req("/.well-known/jwks.json"));
+      expect(res.status).toBe(503);
+      expect(res.headers.get("content-type")).toBe("application/json");
+      expect(res.headers.get("access-control-allow-origin")).toBe("*");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/.well-known/jwks.json on an empty db returns {keys: []}", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, { getDb: () => db })(req("/.well-known/jwks.json"));
+        expect(res.status).toBe(200);
+        expect(await res.json()).toEqual({ keys: [] });
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/.well-known/oauth-authorization-server returns RFC 8414 metadata + CORS", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, {
+          getDb: () => db,
+          issuer: "https://hub.example",
+        })(req("/.well-known/oauth-authorization-server"));
+        expect(res.status).toBe(200);
+        expect(res.headers.get("access-control-allow-origin")).toBe("*");
+        const body = (await res.json()) as Record<string, unknown>;
+        expect(body.issuer).toBe("https://hub.example");
+        expect(body.authorization_endpoint).toBe("https://hub.example/oauth/authorize");
+        expect(body.code_challenge_methods_supported).toEqual(["S256"]);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+  // 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.
+  test("/vault serves index.html when the SPA bundle exists", async () => {
+    const h = makeHarness();
+    try {
+      const dist = join(h.dir, "dist");
+      mkdirIfMissing(dist);
+      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"),
+      );
+      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>");
+    } finally {
+      h.cleanup();
+    }
+  });
+  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.
+    const h = makeHarness();
+    try {
+      const dist = join(h.dir, "dist");
+      mkdirIfMissing(dist);
+      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"),
+      );
+      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>");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/vault/assets/*.js is served with the matching content-type", async () => {
+    const h = makeHarness();
+    try {
+      const dist = join(h.dir, "dist");
+      const assets = join(dist, "assets");
+      mkdirIfMissing(dist);
+      mkdirIfMissing(assets);
+      writeFileSync(join(dist, "index.html"), "<!doctype html>");
+      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"),
+      );
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toBe("application/javascript; charset=utf-8");
+      expect(await res.text()).toContain("console.log");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/vault/* 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"));
+      expect(res.status).toBe(503);
+      expect(await res.text()).toContain("bun run build");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/vault 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" }));
+      expect(res.status).toBe(405);
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/hub/permissions serves the SPA shell (back-compat mount)", 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>");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/hub/* returns 503 with build hint when dist is missing", 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");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/hub 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("/hub/permissions", { method: "POST" }),
+      );
+      expect(res.status).toBe(405);
+    } 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.
+    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");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/hub/vaults/new redirects to /vault/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");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/hub/vaults/* preserves the query string in the redirect", 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");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/oauth/authorize without configured db returns 503", async () => {
+    const h = makeHarness();
+    try {
+      const res = await hubFetch(h.dir)(req("/oauth/authorize?client_id=x"));
+      expect(res.status).toBe(503);
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("every DB-dependent route returns 503 when getDb is absent (closes #139)", async () => {
+    const h = makeHarness();
+    try {
+      const fetch = hubFetch(h.dir);
+      const cases: Array<[string, RequestInit]> = [
+        ["/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" }],
+        ["/admin/host-admin-token", { method: "GET" }],
+      ];
+      for (const [path, init] of cases) {
+        const res = await fetch(req(path, init));
+        expect(res.status).toBe(503);
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/oauth/token rejects non-POST with 405", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, { getDb: () => db })(
+          req("/oauth/token", { method: "GET" }),
+        );
+        expect(res.status).toBe(405);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("/oauth/register accepts POST with JSON body", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, {
+          getDb: () => db,
+          issuer: "https://hub.example",
+        })(
+          req("/oauth/register", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ redirect_uris: ["https://app.example/cb"] }),
+          }),
+        );
+        expect(res.status).toBe(201);
+        const body = (await res.json()) as Record<string, unknown>;
+        expect(typeof body.client_id).toBe("string");
+      } finally {
+        db.close();
+      }
     } finally {
       h.cleanup();
     }
@@ -137,8 +653,12 @@ describe("hubFetch routing", () => {
     const h = makeHarness();
     try {
       writeFileSync(join(h.dir, "hub.html"), "<html>live</html>");
-      writeFileSync(join(h.dir, "parachute.json"), '{"services":[]}');
-      const server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: hubFetch(h.dir) });
+      writeManifest({ services: [] }, h.manifestPath);
+      const server = Bun.serve({
+        port: 0,
+        hostname: "127.0.0.1",
+        fetch: hubFetch(h.dir, { manifestPath: h.manifestPath }),
+      });
       try {
         const base = `http://127.0.0.1:${server.port}`;
         const r1 = await fetch(`${base}/`);
@@ -146,7 +666,7 @@ describe("hubFetch routing", () => {
         expect(await r1.text()).toBe("<html>live</html>");
         const r2 = await fetch(`${base}/.well-known/parachute.json`);
         expect(r2.headers.get("content-type")).toBe("application/json");
-        expect(await r2.json()).toEqual({ services: [] });
+        expect(await r2.json()).toEqual({ vaults: [], services: [] });
       } finally {
         server.stop(true);
       }
@@ -155,3 +675,441 @@ describe("hubFetch routing", () => {
     }
   });
 });
+describe("findVaultUpstream (#144)", () => {
+  test("matches a single-path vault on its exact mount", () => {
+    const services: ServiceEntry[] = [vaultEntry("default")];
+    const m = findVaultUpstream(services, "/vault/default");
+    expect(m?.mount).toBe("/vault/default");
+    expect(m?.port).toBe(1940);
+  });
+  test("matches a vault on any descendant pathname", () => {
+    const services: ServiceEntry[] = [vaultEntry("default")];
+    expect(findVaultUpstream(services, "/vault/default/health")?.mount).toBe("/vault/default");
+    expect(findVaultUpstream(services, "/vault/default/notes/abc")?.mount).toBe("/vault/default");
+  });
+  test("returns undefined when no vault claims the path", () => {
+    const services: ServiceEntry[] = [vaultEntry("default")];
+    expect(findVaultUpstream(services, "/vault/missing")).toBeUndefined();
+    expect(findVaultUpstream(services, "/vault/missing/health")).toBeUndefined();
+    expect(findVaultUpstream(services, "/notes/foo")).toBeUndefined();
+  });
+  test("non-vault services are ignored even when their path begins with /vault/", () => {
+    const odd: ServiceEntry = {
+      name: "parachute-vaultkeeper", // not a vault — see isVaultEntry
+      port: 9999,
+      paths: ["/vault/keeper"],
+      health: "/health",
+      version: "0.0.1",
+    };
+    expect(findVaultUpstream([odd], "/vault/keeper")).toBeUndefined();
+  });
+  test("multi-path single ServiceEntry — both paths route to the same backend", () => {
+    // Post-#179/vault#208: one parachute-vault backend hosts every instance,
+    // expressed as a single ServiceEntry with multiple paths. The lookup must
+    // pick the matching path for each request.
+    const multi: ServiceEntry = {
+      name: "parachute-vault",
+      port: 1940,
+      paths: ["/vault/default", "/vault/techne"],
+      health: "/vault/default/health",
+      version: "0.4.0",
+    };
+    expect(findVaultUpstream([multi], "/vault/default/notes")?.mount).toBe("/vault/default");
+    expect(findVaultUpstream([multi], "/vault/techne/notes")?.mount).toBe("/vault/techne");
+    expect(findVaultUpstream([multi], "/vault/other")).toBeUndefined();
+  });
+  test("longest mount wins on overlapping prefixes", () => {
+    // Pathological but representable: a vault claims `/vault` AND another
+    // claims `/vault/inner`. Request for `/vault/inner/x` should pick the
+    // more specific mount.
+    const a: ServiceEntry = {
+      name: "parachute-vault",
+      port: 1940,
+      paths: ["/vault"],
+      health: "/health",
+      version: "0.4.0",
+    };
+    const b: ServiceEntry = {
+      name: "parachute-vault-inner",
+      port: 1941,
+      paths: ["/vault/inner"],
+      health: "/health",
+      version: "0.4.0",
+    };
+    const m = findVaultUpstream([a, b], "/vault/inner/x");
+    expect(m?.mount).toBe("/vault/inner");
+    expect(m?.port).toBe(1941);
+  });
+});
+describe("hubFetch /vault/<name>/* dynamic proxy (#144)", () => {
+  // The bug: tailscale serve config is built once at expose-time, so a vault
+  // created later was unreachable on the tailnet (404 from the `/` fallback)
+  // until the user re-ran `parachute expose`. The fix puts a single `/vault/`
+  // tailscale mount → hub, and hub picks the specific vault per request.
+  // These tests verify the hub-side picker works with a real upstream.
+  function startUpstream(replyTag: string): { port: number; stop: () => void } {
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: async (req) => {
+        const u = new URL(req.url);
+        // Echo enough metadata for tests to verify path + method + body
+        // arrive intact end-to-end.
+        const body = req.body ? await req.text() : "";
+        return new Response(
+          JSON.stringify({
+            tag: replyTag,
+            method: req.method,
+            pathname: u.pathname,
+            search: u.search,
+            body,
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      },
+    });
+    // server.port is `number | undefined` in Bun's types, but `Bun.serve()`
+    // returns synchronously with the bound port — non-null assertion is safe.
+    return { port: server.port as number, stop: () => server.stop(true) };
+  }
+  test("proxies a /vault/<name>/* request to the matching upstream", async () => {
+    const h = makeHarness();
+    const upstream = startUpstream("default-vault");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/vault/default/health?ok=1"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string; pathname: string; search: string };
+      expect(body.tag).toBe("default-vault");
+      // Path is preserved end-to-end — vault since paraclaw#18 expects requests
+      // at `/vault/<name>/...` rather than stripped.
+      expect(body.pathname).toBe("/vault/default/health");
+      expect(body.search).toBe("?ok=1");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+  test("a freshly-added vault is routable on the very next request, no restart", async () => {
+    // The whole reason hub#144 exists: `parachute vault create techne` writes
+    // services.json but the user shouldn't need to re-expose to reach the new
+    // vault. Read-on-each-request makes this work.
+    const h = makeHarness();
+    const u1 = startUpstream("default-vault");
+    const u2 = startUpstream("techne-vault");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: u1.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      // Before: /vault/techne 404s — no entry yet.
+      const before = await fetcher(req("/vault/techne/health"));
+      expect(before.status).toBe(404);
+      // Simulate `parachute vault create techne` — multi-path single
+      // ServiceEntry shape is what vault writes today.
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: u2.port,
+              paths: ["/vault/default", "/vault/techne"],
+              health: "/vault/default/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      // After: same hubFetch instance, no restart, /vault/techne is reachable.
+      const after = await fetcher(req("/vault/techne/health"));
+      expect(after.status).toBe(200);
+      const body = (await after.json()) as { tag: string; pathname: string };
+      expect(body.tag).toBe("techne-vault");
+      expect(body.pathname).toBe("/vault/techne/health");
+    } finally {
+      u1.stop();
+      u2.stop();
+      h.cleanup();
+    }
+  });
+  test("a removed vault returns 404 from the hub on the next request", async () => {
+    const h = makeHarness();
+    const upstream = startUpstream("default-vault");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      expect((await fetcher(req("/vault/default/health"))).status).toBe(200);
+      // Vault detached — services.json no longer mentions it.
+      writeManifest({ services: [] }, h.manifestPath);
+      const after = await fetcher(req("/vault/default/health"));
+      expect(after.status).toBe(404);
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+  test("preserves method + body for POSTs", async () => {
+    const h = makeHarness();
+    const upstream = startUpstream("default-vault");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(
+        req("/vault/default/notes", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ content: "hello" }),
+        }),
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { method: string; body: string };
+      expect(body.method).toBe("POST");
+      expect(JSON.parse(body.body)).toEqual({ content: "hello" });
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+  test("returns 502 when the matching vault upstream is unreachable", async () => {
+    // Vault is in services.json but the port has nothing listening — vault
+    // crashed, port shifted, or the user is mid-restart. We owe the caller a
+    // useful error instead of a hang or a silent 404.
+    const h = makeHarness();
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              // Bind a port + immediately release it so the proxy gets ECONNREFUSED.
+              port: await pickClosedPort(),
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/vault/default/health"));
+      expect(res.status).toBe(502);
+      const body = (await res.json()) as { error: string };
+      expect(body.error).toContain("vault upstream unreachable");
+    } finally {
+      h.cleanup();
+    }
+  });
+  test("non-vault path inside /vault/ namespace falls through to 404", async () => {
+    // `/vault/keeper` belongs to no installed service — no longest-prefix
+    // match, no proxy attempt, hub answers with the generic 404.
+    const h = makeHarness();
+    const upstream = startUpstream("default-vault");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/vault/keeper/health"));
+      expect(res.status).toBe(404);
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+  test("single-segment /vault/<name> picks proxy when registered, SPA shell 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.
+    // 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.
+    const h = makeHarness();
+    const upstream = startUpstream("default-vault");
+    try {
+      const dist = join(h.dir, "dist");
+      mkdirIfMissing(dist);
+      writeFileSync(join(dist, "index.html"), "<!doctype html><div id=root></div>");
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, {
+        spaDistDir: dist,
+        manifestPath: h.manifestPath,
+      });
+      const proxied = await fetcher(req("/vault/default"));
+      expect(proxied.status).toBe(200);
+      expect(proxied.headers.get("content-type")).toContain("application/json");
+      const body = (await proxied.json()) as { tag: string; pathname: string };
+      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>");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+});
+/** Find a port that no one is listening on by binding briefly and releasing. */
+async function pickClosedPort(): Promise<number> {
+  const s = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: () => new Response("x") });
+  const port = s.port as number;
+  s.stop(true);
+  return port;
+}
+const HUB_SERVER_PATH = fileURLToPath(new URL("../hub-server.ts", import.meta.url));
+async function pollUntil(check: () => boolean, timeoutMs = 3000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (check()) return true;
+    await new Promise((r) => setTimeout(r, 25));
+  }
+  return false;
+}
+describe("hub-server.ts startup PID/port registration (#148)", () => {
+  test("manual `bun src/hub-server.ts` writes hub.pid and hub.port; SIGTERM clears them", async () => {
+    const port = await pickClosedPort();
+    const configDir = mkdtempSync(join(tmpdir(), "pcli-hub-startup-"));
+    const wellKnownDir = join(configDir, "well-known");
+    const dbPath = join(configDir, "hub.db");
+    const proc = Bun.spawn(
+      [
+        process.execPath,
+        HUB_SERVER_PATH,
+        "--port",
+        String(port),
+        "--well-known-dir",
+        wellKnownDir,
+        "--db",
+        dbPath,
+      ],
+      {
+        stdout: "pipe",
+        stderr: "pipe",
+        env: { ...process.env, PARACHUTE_HOME: configDir },
+      },
+    );
+    const pidFile = pidPath(HUB_SVC, configDir);
+    const portFile = hubPortPath(configDir);
+    try {
+      const ready = await pollUntil(() => existsSync(pidFile) && existsSync(portFile));
+      expect(ready).toBe(true);
+      expect(Number.parseInt(readFileSync(pidFile, "utf8").trim(), 10)).toBe(proc.pid);
+      expect(Number.parseInt(readFileSync(portFile, "utf8").trim(), 10)).toBe(port);
+      proc.kill("SIGTERM");
+      await proc.exited;
+      // After SIGTERM the cleanup handler should have rm'd both files —
+      // proves manual starts also play nice with `parachute expose` teardown.
+      expect(existsSync(pidFile)).toBe(false);
+      expect(existsSync(portFile)).toBe(false);
+    } finally {
+      if (!proc.killed) proc.kill("SIGKILL");
+      rmSync(configDir, { recursive: true, force: true });
+    }
+  }, 10_000);
+});