@openparachute/hub 0.5.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

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

@@ -5,7 +5,7 @@ import { join } from "node:path";
 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 { findServiceUpstream, 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";
@@ -1051,6 +1051,585 @@ describe("hubFetch /vault/<name>/* dynamic proxy (#144)", () => {
   });
 });
 
+describe("findServiceUpstream (#182)", () => {
+  // Generic longest-prefix match across non-vault services.json entries. Vault
+  // entries are filtered out — vault routing is the SPA-fallback-aware path
+  // through findVaultUpstream / proxyToVault.
+
+  test("matches a non-vault entry by exact path", () => {
+    const services: ServiceEntry[] = [
+      {
+        name: "scribe",
+        port: 1942,
+        paths: ["/scribe"],
+        health: "/scribe/health",
+        version: "0.1.0",
+      },
+    ];
+    const m = findServiceUpstream(services, "/scribe");
+    expect(m?.port).toBe(1942);
+    expect(m?.mount).toBe("/scribe");
+    expect(m?.entry.name).toBe("scribe");
+  });
+
+  test("matches a deeper subpath via prefix", () => {
+    const services: ServiceEntry[] = [
+      {
+        name: "agent",
+        port: 1943,
+        paths: ["/agent"],
+        health: "/agent/api/health",
+        version: "0.1.0",
+      },
+    ];
+    expect(findServiceUpstream(services, "/agent/api/health")?.port).toBe(1943);
+  });
+
+  test("ignores vault entries — those route via findVaultUpstream", () => {
+    const services: ServiceEntry[] = [
+      {
+        name: "parachute-vault",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: "0.4.0",
+      },
+    ];
+    expect(findServiceUpstream(services, "/vault/default/health")).toBeUndefined();
+  });
+
+  test("returns undefined when no service claims the path", () => {
+    const services: ServiceEntry[] = [
+      {
+        name: "scribe",
+        port: 1942,
+        paths: ["/scribe"],
+        health: "/scribe/health",
+        version: "0.1.0",
+      },
+    ];
+    expect(findServiceUpstream(services, "/unknown/foo")).toBeUndefined();
+  });
+
+  test("longest-prefix wins when multiple paths could match", () => {
+    // A service registering `/api` and another (older / catch-all) registering
+    // `/` would conflict on every request — longest mount wins so the more
+    // specific one takes precedence.
+    const services: ServiceEntry[] = [
+      { name: "wide", port: 1950, paths: ["/api"], health: "/api/health", version: "0.1.0" },
+      {
+        name: "deeper",
+        port: 1951,
+        paths: ["/api/v2"],
+        health: "/api/v2/health",
+        version: "0.1.0",
+      },
+    ];
+    expect(findServiceUpstream(services, "/api/v2/things")?.port).toBe(1951);
+    expect(findServiceUpstream(services, "/api/v1/things")?.port).toBe(1950);
+  });
+
+  test("does not match a sibling that shares a prefix without a slash boundary", () => {
+    // `/scribe-admin` must NOT match a service mounted at `/scribe`. The
+    // boundary check is `pathname === path || pathname.startsWith(path + '/')`.
+    const services: ServiceEntry[] = [
+      {
+        name: "scribe",
+        port: 1942,
+        paths: ["/scribe"],
+        health: "/scribe/health",
+        version: "0.1.0",
+      },
+    ];
+    expect(findServiceUpstream(services, "/scribe-admin")).toBeUndefined();
+    expect(findServiceUpstream(services, "/scribe-admin/foo")).toBeUndefined();
+  });
+});
+
+describe("hubFetch /<svc>/* generic proxy dispatch (#182)", () => {
+  // hub#182: services.json-driven dispatch for non-vault modules. Lets
+  // `parachute install <svc>` reach the on-box hub at hub:1939/<svc>/* with
+  // no per-service codepath. Vault keeps its own routing for the SPA seam.
+
+  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);
+        const body = req.body ? await req.text() : "";
+        return new Response(
+          JSON.stringify({
+            tag: replyTag,
+            method: req.method,
+            pathname: u.pathname,
+            search: u.search,
+            authorization: req.headers.get("authorization") ?? "",
+            contentType: req.headers.get("content-type") ?? "",
+            body,
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      },
+    });
+    return { port: server.port as number, stop: () => server.stop(true) };
+  }
+
+  test("routes /scribe/health to the matching upstream, path preserved", async () => {
+    const h = makeHarness();
+    const upstream = startUpstream("scribe");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "scribe",
+              port: upstream.port,
+              paths: ["/scribe"],
+              health: "/scribe/health",
+              version: "0.1.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/scribe/health"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string; pathname: string };
+      expect(body.tag).toBe("scribe");
+      // Path-preservation convention: backend sees the full mount-prefixed
+      // path, matching `serviceProxyTarget` in commands/expose.ts.
+      expect(body.pathname).toBe("/scribe/health");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("routes /notes/sw.js to the matching upstream", async () => {
+    // Notes is the canonical path-mount case — the PWA shell has to see the
+    // full `/notes/...` path so its service worker registers correctly (the
+    // motivator for the `--mount` strip in notes-serve.ts).
+    const h = makeHarness();
+    const upstream = startUpstream("notes");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "notes",
+              port: upstream.port,
+              paths: ["/notes"],
+              health: "/notes/health",
+              version: "0.1.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/notes/sw.js"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string; pathname: string };
+      expect(body.tag).toBe("notes");
+      expect(body.pathname).toBe("/notes/sw.js");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("routes a deep /agent/api/health to the matching upstream", async () => {
+    // Agent registers `/agent`; deeper paths route by prefix.
+    const h = makeHarness();
+    const upstream = startUpstream("agent");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "agent",
+              port: upstream.port,
+              paths: ["/agent"],
+              health: "/agent/api/health",
+              version: "0.1.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/agent/api/health?probe=1"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string; pathname: string; search: string };
+      expect(body.tag).toBe("agent");
+      expect(body.pathname).toBe("/agent/api/health");
+      expect(body.search).toBe("?probe=1");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("preserves method, multipart body, and Authorization on POSTs", async () => {
+    // Scribe-shaped upload: multipart/form-data with a bearer token. Multipart
+    // is what real scribe clients send; if the proxy strips the boundary or
+    // drops Authorization, scribe rejects the request before transcribing.
+    const h = makeHarness();
+    const upstream = startUpstream("scribe");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "scribe",
+              port: upstream.port,
+              paths: ["/scribe"],
+              health: "/scribe/health",
+              version: "0.1.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const form = new FormData();
+      form.append("model", "whisper-1");
+      form.append("file", new Blob([new Uint8Array([1, 2, 3, 4])]), "audio.wav");
+      const res = await fetcher(
+        req("/scribe/v1/audio/transcriptions", {
+          method: "POST",
+          headers: { authorization: "Bearer test-token" },
+          body: form,
+        }),
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as {
+        method: string;
+        authorization: string;
+        contentType: string;
+        body: string;
+      };
+      expect(body.method).toBe("POST");
+      expect(body.authorization).toBe("Bearer test-token");
+      // Bun's fetch sets the boundary; we just need to confirm the
+      // multipart content-type survived.
+      expect(body.contentType).toMatch(/^multipart\/form-data;\s*boundary=/);
+      // And the body bytes — the boundary marker the upstream echoes back
+      // should contain the form fields we sent.
+      expect(body.body).toContain('name="model"');
+      expect(body.body).toContain("whisper-1");
+      expect(body.body).toContain('name="file"');
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("stripPrefix=true forwards the bare path (mount removed)", async () => {
+    // The scribe-shaped case from real life: scribe's HTTP routes are
+    // `/health`, `/v1/...` — no `/scribe` prefix. When the entry sets
+    // stripPrefix:true the hub strips the mount before forwarding so the
+    // backend sees `/health` rather than `/scribe/health`. Without this,
+    // every proxied scribe request 404s at the backend.
+    const h = makeHarness();
+    const upstream = startUpstream("scribe");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "scribe",
+              port: upstream.port,
+              paths: ["/scribe"],
+              health: "/scribe/health",
+              version: "0.1.0",
+              stripPrefix: true,
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/scribe/v1/audio/transcriptions?model=whisper-1"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string; pathname: string; search: string };
+      expect(body.tag).toBe("scribe");
+      // Backend sees the bare path — `/scribe` is stripped.
+      expect(body.pathname).toBe("/v1/audio/transcriptions");
+      // Query string is always preserved verbatim regardless of stripPrefix.
+      expect(body.search).toBe("?model=whisper-1");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("stripPrefix=true: request to bare mount becomes `/`", async () => {
+    // Edge case: pathname === mount. Slicing yields the empty string; the
+    // proxy normalizes to `/` so the backend sees a valid path.
+    const h = makeHarness();
+    const upstream = startUpstream("scribe");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "scribe",
+              port: upstream.port,
+              paths: ["/scribe"],
+              health: "/health",
+              version: "0.1.0",
+              stripPrefix: true,
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/scribe"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { pathname: string };
+      expect(body.pathname).toBe("/");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("stripPrefix absent (default false) preserves the prefix — no behavior change for existing entries", async () => {
+    // Migration safety: a services.json entry written before stripPrefix
+    // existed (e.g. notes / agent rows already on disk) must continue to
+    // forward the full path. The /notes/sw.js test above already exercises
+    // this in the happy case; this test makes the absence-of-flag → keep-
+    // prefix contract explicit.
+    const h = makeHarness();
+    const upstream = startUpstream("notes");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "notes",
+              port: upstream.port,
+              paths: ["/notes"],
+              health: "/notes/health",
+              version: "0.1.0",
+              // stripPrefix intentionally omitted — must default to false.
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/notes/health"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { pathname: string };
+      expect(body.pathname).toBe("/notes/health");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("stripPrefix=false explicitly preserves the prefix", async () => {
+    // The opposite explicit-declaration of the previous test: an operator
+    // who writes `stripPrefix: false` in services.json gets the same
+    // keep-prefix behavior as omitting the field. Confirms validator round-
+    // tripping doesn't lose the explicit-false (separate from the absent
+    // case which is checked above).
+    const h = makeHarness();
+    const upstream = startUpstream("notes");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "notes",
+              port: upstream.port,
+              paths: ["/notes"],
+              health: "/notes/health",
+              version: "0.1.0",
+              stripPrefix: false,
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/notes/sw.js"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { pathname: string };
+      expect(body.pathname).toBe("/notes/sw.js");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("unknown /<svc>/* path returns 404", async () => {
+    const h = makeHarness();
+    const upstream = startUpstream("scribe");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "scribe",
+              port: upstream.port,
+              paths: ["/scribe"],
+              health: "/scribe/health",
+              version: "0.1.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/notinstalled/foo"));
+      expect(res.status).toBe(404);
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("returns 502 when the matching upstream is unreachable", async () => {
+    // Service is in services.json but the port has nothing listening — same
+    // shape as the vault-unreachable test, label is the entry's `name`.
+    const h = makeHarness();
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "scribe",
+              port: await pickClosedPort(),
+              paths: ["/scribe"],
+              health: "/scribe/health",
+              version: "0.1.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/scribe/health"));
+      expect(res.status).toBe(502);
+      const body = (await res.json()) as { error: string };
+      expect(body.error).toContain("scribe upstream unreachable");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("/oauth/authorize is hub-handled, never reaches service dispatch", async () => {
+    // Even if a (misbehaving) service registers `/oauth`, the hub's own
+    // /oauth/* handlers run first by virtue of dispatch ordering. We don't
+    // need an explicit denylist — ordering enforces it.
+    const h = makeHarness();
+    const upstream = startUpstream("malicious");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "malicious",
+              port: upstream.port,
+              paths: ["/oauth"],
+              health: "/oauth/health",
+              version: "0.0.1",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/oauth/authorize"));
+      // Hub's own /oauth/authorize handler responds (likely a redirect or
+      // error page rendering) — we just need to verify the upstream was NOT
+      // reached, i.e. `tag: "malicious"` is not in the body.
+      const text = await res.text();
+      expect(text).not.toContain('"tag":"malicious"');
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("/.well-known/parachute.json is hub-handled, never reaches service dispatch", async () => {
+    const h = makeHarness();
+    const upstream = startUpstream("malicious");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "malicious",
+              port: upstream.port,
+              paths: ["/.well-known"],
+              health: "/.well-known/health",
+              version: "0.0.1",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/.well-known/parachute.json"));
+      expect(res.status).toBe(200);
+      // Hub serves the well-known doc as JSON — its body has `vaults`,
+      // `services`, etc., not the upstream's `tag` echo.
+      const text = await res.text();
+      expect(text).not.toContain('"tag":"malicious"');
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("vault entries are NOT routed via the generic dispatch (regression for #144)", async () => {
+    // Reach hubFetch with a vault entry but a request shape that the vault
+    // block won't match (e.g. no leading `/vault/`). The generic dispatch
+    // must skip vault entries — confirming via findServiceUpstream-level
+    // unit test isn't enough, we want the integration to stay coherent.
+    const h = makeHarness();
+    const upstream = startUpstream("vault-default");
+    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 });
+      // /vault/default/health goes through the vault-specific block and
+      // proxies (still works — that's the regression check).
+      const vaultRes = await fetcher(req("/vault/default/health"));
+      expect(vaultRes.status).toBe(200);
+      // /vault/default by itself is the SPA single-segment seam — it does
+      // proxy via proxyToVault per the existing behavior.
+      // The point of this test is the generic dispatch CANNOT mistakenly
+      // match a vault entry. Verify by writing a request that's not under
+      // /vault/* and confirming no fallthrough to the vault upstream.
+      const elsewhere = await fetcher(req("/totally/not/a/vault"));
+      expect(elsewhere.status).toBe(404);
+    } 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") });

package/src/__tests__/module-manifest.test.ts

@@ -130,6 +130,19 @@ describe("validateModuleManifest", () => {
     const m = validateModuleManifest(VALID, "x");
     expect(m.managementUrl).toBeUndefined();
   });
+
+  test("stripPrefix accepts boolean true and false; rejects non-boolean", () => {
+    expect(validateModuleManifest({ ...VALID, stripPrefix: true }, "x").stripPrefix).toBe(true);
+    expect(validateModuleManifest({ ...VALID, stripPrefix: false }, "x").stripPrefix).toBe(false);
+    expect(() => validateModuleManifest({ ...VALID, stripPrefix: "yes" }, "x")).toThrow(
+      /stripPrefix/,
+    );
+  });
+
+  test("stripPrefix absent stays absent", () => {
+    const m = validateModuleManifest(VALID, "x");
+    expect(m.stripPrefix).toBeUndefined();
+  });
 });
 
 describe("readModuleManifest", () => {

package/src/__tests__/services-manifest.test.ts

@@ -196,6 +196,32 @@ describe("services-manifest", () => {
       cleanup();
     }
   });
+
+  test("round-trips optional stripPrefix (true and false)", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const stripping: ServiceEntry = { ...vault, stripPrefix: true };
+      upsertService(stripping, path);
+      expect(readManifest(path).services[0]).toEqual(stripping);
+
+      const explicitFalse: ServiceEntry = { ...vault, stripPrefix: false };
+      upsertService(explicitFalse, path);
+      expect(readManifest(path).services[0]).toEqual(explicitFalse);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("rejects non-boolean stripPrefix", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      expect(() =>
+        upsertService({ ...vault, stripPrefix: "yes" as unknown as boolean }, path),
+      ).toThrow(/stripPrefix/);
+    } finally {
+      cleanup();
+    }
+  });
 });
 
 describe("claw → agent migration", () => {

package/src/hub-server.ts

@@ -147,40 +147,39 @@ export function findVaultUpstream(
 }
 
 /**
- * Reverse-proxy a `/vault/<name>/*` request onto the vault backend's loopback
- * port. The path is preserved end-to-end (vault since paraclaw#18 expects
- * requests at `/vault/<name>/...` not stripped to `/...`), so the upstream URL
- * mirrors the incoming pathname exactly.
+ * Forward a request to a loopback service on `127.0.0.1:<port>`. By default
+ * the incoming pathname + query are preserved verbatim; pass `targetPath` to
+ * rewrite the path (e.g. when the caller has stripped a mount prefix because
+ * the backend serves bare routes). Query string is always preserved from the
+ * incoming URL.
  *
- * `manifestPath` is the services.json path from `HubFetchDeps`. Read on every
- * proxied request so a vault created seconds ago is reachable without a
- * re-expose — same dynamism as the well-known doc (#135).
+ * Note: this is **not** equivalent to the tailscale convention. `tailscale
+ * serve <mount>=<target>` strips the mount before forwarding, so
+ * `serviceProxyTarget` in `commands/expose.ts` works by making mount and
+ * target byte-equal. The hub's fetch-based proxy does no stripping unless the
+ * caller asks; per-service preferences vary (scribe wants bare paths, notes
+ * / agent / vault want the prefix), so the decision lives one layer up in
+ * `proxyToService` / `proxyToVault`.
  *
- * Returns `undefined` when no vault is currently mounted at this pathname so
- * the caller falls through to the catch-all 404. Returns a 502 response when
- * the upstream connection fails (vault crashed, port shifted) — the upstream
- * URL was valid; we just couldn't reach it.
+ * Returns 502 when the loopback fetch fails — port valid, target unreachable
+ * (service crashed, port shifted, mid-restart). `serviceLabel` is folded into
+ * the error message so 502 bodies say `vault upstream unreachable` /
+ * `scribe upstream unreachable` etc.
  *
  * Hop-by-hop notes: WebSocket upgrades and HTTP/2 trailers don't traverse
- * fetch-based proxies cleanly. Vault uses neither today; if a future service
- * needs them, switch to a Node http.IncomingMessage / http.request pair.
+ * fetch-based proxies cleanly. No on-box service uses either today; if one
+ * eventually needs them, switch to a Node http.IncomingMessage / http.request
+ * pair.
  */
-async function proxyToVault(req: Request, manifestPath: string): Promise<Response | undefined> {
-  let services: readonly ServiceEntry[];
-  try {
-    services = readManifest(manifestPath).services;
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return new Response(JSON.stringify({ error: `vault routing failed: ${msg}` }), {
-      status: 500,
-      headers: { "content-type": "application/json" },
-    });
-  }
+async function proxyRequest(
+  req: Request,
+  port: number,
+  serviceLabel: string,
+  targetPath?: string,
+): Promise<Response> {
   const url = new URL(req.url);
-  const match = findVaultUpstream(services, url.pathname);
-  if (!match) return undefined;
-
-  const upstream = `http://127.0.0.1:${match.port}${url.pathname}${url.search}`;
+  const path = targetPath ?? url.pathname;
+  const upstream = `http://127.0.0.1:${port}${path}${url.search}`;
   const headers = new Headers(req.headers);
   // Host comes from the requester (tailnet FQDN); the loopback target wants
   // its own. Bun's fetch fills it in when omitted.
@@ -199,13 +198,104 @@ async function proxyToVault(req: Request, manifestPath: string): Promise<Respons
     return await fetch(upstream, init);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    return new Response(JSON.stringify({ error: `vault upstream unreachable: ${msg}` }), {
+    return new Response(JSON.stringify({ error: `${serviceLabel} upstream unreachable: ${msg}` }), {
       status: 502,
       headers: { "content-type": "application/json" },
     });
   }
 }
 
+/**
+ * Reverse-proxy a `/vault/<name>/*` request onto the vault backend.
+ * `manifestPath` is the services.json path from `HubFetchDeps`. Read on every
+ * proxied request so a vault created seconds ago is reachable without a
+ * re-expose — same dynamism as the well-known doc (#135).
+ *
+ * Returns `undefined` when no vault claims this pathname so the caller can
+ * fall through to the SPA shell fallback for unknown vault names (the seam
+ * #173 introduced).
+ */
+async function proxyToVault(req: Request, manifestPath: string): Promise<Response | undefined> {
+  let services: readonly ServiceEntry[];
+  try {
+    services = readManifest(manifestPath).services;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return new Response(JSON.stringify({ error: `vault routing failed: ${msg}` }), {
+      status: 500,
+      headers: { "content-type": "application/json" },
+    });
+  }
+  const url = new URL(req.url);
+  const match = findVaultUpstream(services, url.pathname);
+  if (!match) return undefined;
+  return proxyRequest(req, match.port, "vault");
+}
+
+/**
+ * Resolve which (non-vault) ServiceEntry should handle a given request.
+ * Generic longest-prefix match across every service's `paths[]`. Vault
+ * entries are filtered out — they're routed by `findVaultUpstream` /
+ * `proxyToVault`, which encode the vault-specific SPA-fallback seam.
+ *
+ * Returns `undefined` when no service claims the pathname; the caller 404s.
+ */
+export function findServiceUpstream(
+  services: readonly ServiceEntry[],
+  pathname: string,
+): { port: number; mount: string; entry: ServiceEntry } | undefined {
+  let best: { port: number; mount: string; entry: ServiceEntry } | undefined;
+  for (const s of services) {
+    if (isVaultEntry(s)) continue;
+    for (const path of s.paths) {
+      if (pathname === path || pathname.startsWith(`${path}/`)) {
+        if (!best || path.length > best.mount.length) {
+          best = { port: s.port, mount: path, entry: s };
+        }
+      }
+    }
+  }
+  return best;
+}
+
+/**
+ * Reverse-proxy a request onto whichever non-vault service registers a
+ * matching `paths[]` prefix in services.json. Wired after every specific
+ * handler in `hubFetch` so the exclusion list (`/`, `/admin/*`, `/oauth/*`,
+ * `/.well-known/*`, `/hub/*`, `/vault/*`, `/api/*`) is enforced by ordering:
+ * those specific handlers run first and never reach this dispatch.
+ *
+ * Read services.json on every request so a `parachute install <svc>` made
+ * seconds ago is reachable without a hub restart — same dynamism as the
+ * well-known doc and `proxyToVault`.
+ *
+ * Honors `entry.stripPrefix`: when `true` the matched mount prefix is
+ * removed from the forwarded path so the backend sees a bare route
+ * (`/scribe/health` becomes `/health`). Default (`false` / absent) forwards
+ * the full path — matches what notes / agent / vault expect.
+ *
+ * Returns `undefined` when no service claims the pathname; caller 404s.
+ */
+async function proxyToService(req: Request, manifestPath: string): Promise<Response | undefined> {
+  let services: readonly ServiceEntry[];
+  try {
+    services = readManifest(manifestPath).services;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return new Response(JSON.stringify({ error: `service routing failed: ${msg}` }), {
+      status: 500,
+      headers: { "content-type": "application/json" },
+    });
+  }
+  const url = new URL(req.url);
+  const match = findServiceUpstream(services, url.pathname);
+  if (!match) return undefined;
+  const targetPath = match.entry.stripPrefix
+    ? url.pathname.slice(match.mount.length) || "/"
+    : undefined;
+  return proxyRequest(req, match.port, match.entry.name, targetPath);
+}
+
 export interface HubFetchDeps {
   /**
    * Lazily opens (or returns a cached handle to) the hub DB. Optional so
@@ -690,6 +780,13 @@ export function hubFetch(
       return serveSpa(spaDistDir, pathname, "/vault");
     }
 
+    // Generic services.json-driven dispatch for non-vault modules. Reaches
+    // here only after every hub-owned prefix above has had its turn — so
+    // `/`, `/admin/*`, `/oauth/*`, `/.well-known/*`, `/hub/*`, `/vault/*`,
+    // `/api/*` are excluded by ordering, not by an explicit denylist (#182).
+    const proxied = await proxyToService(req, manifestPath);
+    if (proxied) return proxied;
+
     return new Response("not found", { status: 404 });
   };
 }

package/src/module-manifest.ts

@@ -114,6 +114,15 @@ export interface ModuleManifest {
    * as `hasAuth` / `init` / `urlForEntry`.
    */
   readonly managementUrl?: string;
+  /**
+   * When `true`, the hub's `/<svc>/*` proxy strips the matched mount prefix
+   * before forwarding (so the backend sees `/health` rather than
+   * `/<name>/health`). Default `false` matches the prefix-aware convention
+   * notes / agent / vault already follow. Carried into services.json via
+   * `seedEntryFromManifest`. See `ServiceEntry.stripPrefix` for the full
+   * per-module rationale.
+   */
+  readonly stripPrefix?: boolean;
 }
 
 export class ModuleManifestError extends Error {
@@ -365,6 +374,13 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
   const dependencies = asDependencies(m.dependencies, where);
   const configSchema = asConfigSchema(m.configSchema, where);
   const managementUrl = asManagementUrl(m.managementUrl, where);
+  let stripPrefix: boolean | undefined;
+  if (m.stripPrefix !== undefined) {
+    if (typeof m.stripPrefix !== "boolean") {
+      throw new ModuleManifestError(`${where}: "stripPrefix" must be a boolean if present`);
+    }
+    stripPrefix = m.stripPrefix;
+  }
 
   const out: ModuleManifest = { name, manifestName, kind, port, paths, health };
   if (displayName !== undefined) (out as { displayName?: string }).displayName = displayName;
@@ -380,6 +396,9 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
   if (managementUrl !== undefined) {
     (out as { managementUrl?: string }).managementUrl = managementUrl;
   }
+  if (stripPrefix !== undefined) {
+    (out as { stripPrefix?: boolean }).stripPrefix = stripPrefix;
+  }
   return out;
 }
 

package/src/service-spec.ts

@@ -199,6 +199,7 @@ export function seedEntryFromManifest(manifest: ModuleManifest): ServiceEntry {
   };
   if (manifest.displayName !== undefined) entry.displayName = manifest.displayName;
   if (manifest.tagline !== undefined) entry.tagline = manifest.tagline;
+  if (manifest.stripPrefix !== undefined) entry.stripPrefix = manifest.stripPrefix;
   return entry;
 }
 
@@ -319,6 +320,13 @@ const SCRIBE_FALLBACK: FirstPartyFallback = {
     paths: ["/scribe"],
     health: "/scribe/health",
     startCmd: ["parachute-scribe", "serve"],
+    // Scribe's HTTP routes are bare (`/health`, `/v1/...`), unlike notes /
+    // agent which strip the mount themselves. Until scribe ships a `--mount`
+    // flag (tracked upstream in parachute-scribe), the hub strips the
+    // `/scribe` prefix before forwarding so a request to
+    // `hub:1939/scribe/v1/audio/transcriptions` reaches scribe as
+    // `/v1/audio/transcriptions`.
+    stripPrefix: true,
   },
   extras: {
     // No auth gate today. Scribe's launch PR adds optional SCRIBE_AUTH_TOKEN;

package/src/services-manifest.ts

@@ -45,6 +45,22 @@ export interface ServiceEntry {
    * can use clean relative paths in their `startCmd`.
    */
   installDir?: string;
+  /**
+   * When `true`, the hub's `/<svc>/*` proxy strips the matched mount prefix
+   * before forwarding so the backend sees a bare path (e.g. `/health` rather
+   * than `/scribe/health`). Default `false` keeps the prefix intact, which
+   * matches what notes / agent / vault expect today.
+   *
+   * Per-module rather than uniform because conventions differ:
+   *   - notes-serve.ts strips internally via `--mount`; expects the prefix.
+   *   - parachute-agent reads PARACHUTE_AGENT_WEB_MOUNT and strips itself.
+   *   - parachute-vault routes by `/vault/<name>/...` and expects the prefix.
+   *   - parachute-scribe serves bare paths (`/health`, `/v1/...`); the proxy
+   *     must strip. Eventually scribe should accept its own `--mount` flag
+   *     and join the always-prefixed convention; until then this opt-in
+   *     bridges the gap. Tracked in parachute-scribe (separate issue).
+   */
+  stripPrefix?: boolean;
 }
 
 export interface ServicesManifest {
@@ -105,11 +121,16 @@ function validateEntry(raw: unknown, where: string): ServiceEntry {
   if (installDir !== undefined && (typeof installDir !== "string" || installDir.length === 0)) {
     throw new ServicesManifestError(`${where}: "installDir" must be a non-empty string if present`);
   }
+  const stripPrefix = e.stripPrefix;
+  if (stripPrefix !== undefined && typeof stripPrefix !== "boolean") {
+    throw new ServicesManifestError(`${where}: "stripPrefix" must be a boolean if present`);
+  }
   const entry: ServiceEntry = { name, port, paths: paths as string[], health, version };
   if (displayName !== undefined) entry.displayName = displayName;
   if (tagline !== undefined) entry.tagline = tagline;
   if (publicExposure !== undefined) entry.publicExposure = publicExposure as PublicExposure;
   if (installDir !== undefined) entry.installDir = installDir;
+  if (stripPrefix !== undefined) entry.stripPrefix = stripPrefix;
   return entry;
 }