@openparachute/hub 0.5.2 → 0.5.7

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 { findServiceUpstream, findVaultUpstream, hubFetch } from "../hub-server.ts";
+import { findServiceUpstream, findVaultUpstream, hubFetch, layerOf } from "../hub-server.ts";
 import { pidPath } from "../process-state.ts";
 import { type ServiceEntry, writeManifest } from "../services-manifest.ts";
 import { rotateSigningKey } from "../signing-keys.ts";
@@ -746,6 +746,31 @@ describe("findVaultUpstream (#144)", () => {
     expect(m?.mount).toBe("/vault/inner");
     expect(m?.port).toBe(1941);
   });
+
+  // #197: a services.json entry written with a trailing slash on the mount
+  // path (e.g. `paths: ["/vault/default/"]`) used to only match the exact
+  // pathname `/vault/default/` and silently drop every sub-path because
+  // `pathname.startsWith("/vault/default//")` is always false. Normalize
+  // trailing slashes before comparison so sub-paths route correctly.
+  test("trailing-slash mount path matches sub-paths (#197)", () => {
+    const trailing: ServiceEntry = {
+      name: "parachute-vault",
+      port: 1940,
+      paths: ["/vault/default/"],
+      health: "/vault/default/health",
+      version: "0.4.0",
+    };
+    const exact = findVaultUpstream([trailing], "/vault/default");
+    expect(exact?.port).toBe(1940);
+    // mount is reported normalized (trailing slash stripped) so callers
+    // computing `pathname.slice(match.mount.length)` get the same answer
+    // regardless of how the entry was written on disk.
+    expect(exact?.mount).toBe("/vault/default");
+
+    const sub = findVaultUpstream([trailing], "/vault/default/notes/abc");
+    expect(sub?.port).toBe(1940);
+    expect(sub?.mount).toBe("/vault/default");
+  });
 });
 
 describe("hubFetch /vault/<name>/* dynamic proxy (#144)", () => {
@@ -1144,6 +1169,62 @@ describe("findServiceUpstream (#182)", () => {
     expect(findServiceUpstream(services, "/scribe-admin")).toBeUndefined();
     expect(findServiceUpstream(services, "/scribe-admin/foo")).toBeUndefined();
   });
+
+  // #197: a services.json entry written with a trailing slash on the mount
+  // path (e.g. `paths: ["/notes/"]`) used to only match the exact pathname
+  // `/notes/` and silently drop every sub-path because
+  // `pathname.startsWith("/notes//")` is always false. Notes blank-screen
+  // on Aaron's box (2026-05-08) was the operator-visible symptom: the SPA
+  // shell loaded but every `/notes/assets/*.js` 404'd. Normalize trailing
+  // slashes before comparison.
+  test("trailing-slash mount path matches sub-paths (#197)", () => {
+    const services: ServiceEntry[] = [
+      {
+        name: "parachute-notes",
+        port: 1942,
+        paths: ["/notes/"],
+        health: "/notes/health",
+        version: "0.1.0",
+      },
+    ];
+    const exact = findServiceUpstream(services, "/notes");
+    expect(exact?.port).toBe(1942);
+    // mount is reported normalized (trailing slash stripped) so callers
+    // computing `pathname.slice(match.mount.length)` (the stripPrefix path)
+    // get the same answer regardless of how the entry was written on disk.
+    expect(exact?.mount).toBe("/notes");
+
+    const asset = findServiceUpstream(services, "/notes/assets/index-XXX.js");
+    expect(asset?.port).toBe(1942);
+    expect(asset?.mount).toBe("/notes");
+    expect(asset?.entry.name).toBe("parachute-notes");
+  });
+
+  test('mount path "/" survives normalization without collapsing to empty string (#197)', () => {
+    // Edge case: `"/".replace(/\/+$/, "")` yields the empty string; the
+    // `|| "/"` branch keeps it stable so an exact-`/` request still matches.
+    // Pre-fix this branch wasn't reachable (legacy `paths: ["/"]` entries
+    // are already remapped to `/<shortname>` in-memory by services-manifest;
+    // the test pins the lookup-level behavior so a future regression in the
+    // remap layer doesn't silently 404 every catchall request).
+    //
+    // Sub-path matching for `/`-mounted entries is intentionally not asserted
+    // here — that would change the existing "exact match only" behavior
+    // captured in `pathname === path || pathname.startsWith(path + '/')`,
+    // which never matched `/anything` when `path === "/"` (since `"//"` is
+    // not a real URL prefix).
+    const services: ServiceEntry[] = [
+      {
+        name: "catchall",
+        port: 1950,
+        paths: ["/"],
+        health: "/health",
+        version: "0.1.0",
+      },
+    ];
+    expect(findServiceUpstream(services, "/")?.port).toBe(1950);
+    expect(findServiceUpstream(services, "/")?.mount).toBe("/");
+  });
 });
 
 describe("hubFetch /<svc>/* generic proxy dispatch (#182)", () => {
@@ -1628,6 +1709,572 @@ describe("hubFetch /<svc>/* generic proxy dispatch (#182)", () => {
       h.cleanup();
     }
   });
+
+  test("trailing-slash entry routes sub-paths end-to-end (#197)", async () => {
+    // Operator-symptom regression: notes blank-screen on Aaron's box
+    // (2026-05-08). services.json had `paths: ["/notes/"]` (trailing slash),
+    // which used to make the matcher return undefined for every sub-path
+    // because `pathname.startsWith("/notes//")` is always false. Hub
+    // returned 404 for `/notes/assets/*.js` even though the SPA shell
+    // loaded fine, breaking the page silently.
+    const h = makeHarness();
+    const upstream = startUpstream("notes");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-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/assets/index-XXX.js"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string; pathname: string };
+      expect(body.tag).toBe("notes");
+      // Path is forwarded verbatim — no stripPrefix on the notes entry, so
+      // backend sees the full mount-prefixed path.
+      expect(body.pathname).toBe("/notes/assets/index-XXX.js");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("FIRST_PARTY_FALLBACKS supplies stripPrefix when entry omits it (#196)", async () => {
+    // Operator-symptom regression: scribe `/scribe/health` 404 on Aaron's
+    // box (2026-05-08). Scribe v0.4.0 doesn't write `stripPrefix: true` to
+    // its services.json entry; the declaration only lives in hub's
+    // SCRIBE_FALLBACK manifest. Pre-#187 this didn't matter because the
+    // per-service `tailscale serve` plan baked the path into the target
+    // URL; post-#187 routing went through hub which wasn't consulting the
+    // fallback registry. Result: hub forwarded `/scribe/health` verbatim
+    // to scribe at :1943, scribe served bare paths and 404'd. Fix: hub-
+    // side fallback merge in `stripPrefixFor`.
+    //
+    // Use a `parachute-scribe` manifestName so `shortNameForManifest`
+    // resolves to "scribe" → SCRIBE_FALLBACK (which declares
+    // `stripPrefix: true`). The entry itself omits stripPrefix to mirror
+    // what scribe v0.4.0 actually writes today.
+    const h = makeHarness();
+    const upstream = startUpstream("scribe");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-scribe",
+              port: upstream.port,
+              paths: ["/scribe"],
+              health: "/scribe/health",
+              version: "0.4.0",
+              // stripPrefix intentionally omitted — must be derived from
+              // FIRST_PARTY_FALLBACKS.scribe.manifest.stripPrefix.
+            },
+          ],
+        },
+        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");
+      // The mount prefix is stripped — backend sees the bare `/health`
+      // route that scribe v0.4.0 actually serves.
+      expect(body.pathname).toBe("/health");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("explicit stripPrefix:false on entry overrides FIRST_PARTY_FALLBACKS (#196)", async () => {
+    // Explicit-on-entry must win, even when the fallback would default to
+    // stripping. Documents the precedence ordering: explicit > fallback >
+    // false. Without this, an operator who deliberately writes
+    // `"stripPrefix": false` couldn't opt out of the fallback's strip.
+    const h = makeHarness();
+    const upstream = startUpstream("scribe");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-scribe",
+              port: upstream.port,
+              paths: ["/scribe"],
+              health: "/scribe/health",
+              version: "0.4.0",
+              stripPrefix: false,
+            },
+          ],
+        },
+        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 { pathname: string };
+      // Explicit false wins — full path forwarded.
+      expect(body.pathname).toBe("/scribe/health");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("third-party service without fallback does not strip (#196)", async () => {
+    // Default behavior contract: a service whose manifestName isn't in
+    // FIRST_PARTY_FALLBACKS and whose entry omits stripPrefix gets the
+    // pre-#196 keep-prefix behavior. No accidental strip on third-party
+    // installs.
+    const h = makeHarness();
+    const upstream = startUpstream("third-party");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "third-party-service",
+              port: upstream.port,
+              paths: ["/third"],
+              health: "/third/health",
+              version: "0.1.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/third/health"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { pathname: string };
+      expect(body.pathname).toBe("/third/health");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+});
+
+describe("layerOf — classify trust layer from proxy headers", () => {
+  // Hub binds 127.0.0.1:1939; only trusted forwarders (cloudflared,
+  // tailscaled-serve, tailscaled-funnel) reach the listener. Spoofing isn't
+  // a concern. layerOf inspects the headers each forwarder injects.
+
+  test("no proxy headers → loopback (direct localhost call)", () => {
+    expect(layerOf(req("/"))).toBe("loopback");
+  });
+
+  test("Tailscale-User-Login → tailnet (authed via tailscale serve)", () => {
+    // Set verbatim per Tailscale docs / serve.go addTailscaleIdentityHeaders.
+    const r = req("/", { headers: { "Tailscale-User-Login": "alice@example.com" } });
+    expect(layerOf(r)).toBe("tailnet");
+  });
+
+  test("Tailscale-Funnel-Request: ?1 → public (Tailscale Funnel)", () => {
+    // Tailscale Funnel sets this header on every funneled connection per
+    // serve.go; mutually exclusive with Tailscale-User-Login.
+    const r = req("/", { headers: { "Tailscale-Funnel-Request": "?1" } });
+    expect(layerOf(r)).toBe("public");
+  });
+
+  test("CF-Ray → public (Cloudflare tunnel)", () => {
+    const r = req("/", { headers: { "CF-Ray": "abc123-DEN" } });
+    expect(layerOf(r)).toBe("public");
+  });
+
+  test("CF-Connecting-IP → public (Cloudflare tunnel — alt header shape)", () => {
+    const r = req("/", { headers: { "CF-Connecting-IP": "203.0.113.42" } });
+    expect(layerOf(r)).toBe("public");
+  });
+
+  test("Cloudflare wins over tailscale headers (cloudflared-then-serve hop, defensive)", () => {
+    // If a node ran both forwarders chained, the outer-most public layer
+    // wins. Defensive — not a recommended deployment shape.
+    const r = req("/", {
+      headers: { "CF-Ray": "abc", "Tailscale-User-Login": "alice@example.com" },
+    });
+    expect(layerOf(r)).toBe("public");
+  });
+
+  test("Tailscale-Funnel-Request wins over Tailscale-User-Login (defensive)", () => {
+    // serve.go can't actually set both — funnel returns early. Defensive.
+    const r = req("/", {
+      headers: {
+        "Tailscale-Funnel-Request": "?1",
+        "Tailscale-User-Login": "alice@example.com",
+      },
+    });
+    expect(layerOf(r)).toBe("public");
+  });
+});
+
+describe("hubFetch publicExposure layer-gate (proxyToService)", () => {
+  // The hub's only layer-gate. effectivePublicExposure(entry) === "loopback"
+  // → 404 on tailnet/public; pass through on loopback. "allowed" /
+  // "auth-required" reach all layers (service does its own auth gate).
+
+  function startUpstream(replyTag: string): { port: number; stop: () => void } {
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () =>
+        new Response(JSON.stringify({ tag: replyTag }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+    });
+    return { port: server.port as number, stop: () => server.stop(true) };
+  }
+
+  test("publicExposure: loopback + tailnet header → 404 (gate hides the route)", async () => {
+    const h = makeHarness();
+    const upstream = startUpstream("loopback-only");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "loopback-only",
+              port: upstream.port,
+              paths: ["/loopback-only"],
+              health: "/loopback-only/health",
+              version: "0.1.0",
+              publicExposure: "loopback",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const r = req("/loopback-only/anything", {
+        headers: { "Tailscale-User-Login": "alice@example.com" },
+      });
+      const res = await fetcher(r);
+      expect(res.status).toBe(404);
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("publicExposure: loopback + public header → 404 (gate hides the route)", async () => {
+    const h = makeHarness();
+    const upstream = startUpstream("loopback-only");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "loopback-only",
+              port: upstream.port,
+              paths: ["/loopback-only"],
+              health: "/loopback-only/health",
+              version: "0.1.0",
+              publicExposure: "loopback",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const r = req("/loopback-only/anything", { headers: { "CF-Ray": "abc123" } });
+      const res = await fetcher(r);
+      expect(res.status).toBe(404);
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("publicExposure: loopback + no headers → reaches upstream (loopback layer)", async () => {
+    const h = makeHarness();
+    const upstream = startUpstream("loopback-only");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "loopback-only",
+              port: upstream.port,
+              paths: ["/loopback-only"],
+              health: "/loopback-only/health",
+              version: "0.1.0",
+              publicExposure: "loopback",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/loopback-only/health"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string };
+      expect(body.tag).toBe("loopback-only");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("publicExposure: allowed + tailnet header → reaches upstream (no gate)", async () => {
+    const h = makeHarness();
+    const upstream = startUpstream("allowed");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "allowed",
+              port: upstream.port,
+              paths: ["/allowed"],
+              health: "/allowed/health",
+              version: "0.1.0",
+              publicExposure: "allowed",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const r = req("/allowed/health", {
+        headers: { "Tailscale-User-Login": "alice@example.com" },
+      });
+      const res = await fetcher(r);
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string };
+      expect(body.tag).toBe("allowed");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("publicExposure: auth-required + public header → reaches upstream (service self-gates)", async () => {
+    // The service does its own auth check; the hub passes through.
+    const h = makeHarness();
+    const upstream = startUpstream("auth-required");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "auth-required",
+              port: upstream.port,
+              paths: ["/auth-required"],
+              health: "/auth-required/health",
+              version: "0.1.0",
+              publicExposure: "auth-required",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const r = req("/auth-required/health", { headers: { "CF-Ray": "abc123" } });
+      const res = await fetcher(r);
+      expect(res.status).toBe(200);
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("scribe (kind=api, hasAuth=false default) → loopback gate fires from public layer", async () => {
+    // Spec-derived default for scribe is "auth-required" (NOT loopback —
+    // see effectivePublicExposure in service-spec.ts). So the hub passes
+    // through; this test confirms the spec-default isn't accidentally
+    // loopback-gating well-known services.
+    const h = makeHarness();
+    const upstream = startUpstream("scribe");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-scribe",
+              port: upstream.port,
+              paths: ["/scribe"],
+              health: "/scribe/health",
+              version: "0.1.0",
+              // publicExposure absent — exercises spec-derived default
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const r = req("/scribe/health", { headers: { "CF-Ray": "abc123" } });
+      const res = await fetcher(r);
+      // auth-required → pass through; service does its own gate.
+      expect(res.status).toBe(200);
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("unknown third-party service (no SERVICE_SPECS row, no publicExposure) → defaults to allowed, reaches public layer", async () => {
+    // Third-party modules installed via `module.json` aren't in
+    // FIRST_PARTY_FALLBACKS, so effectivePublicExposure has no spec to
+    // derive from. The contract documented on effectivePublicExposure is
+    // "default to 'allowed'", which means the gate must NOT fire from the
+    // public layer for an unknown service that didn't opt into a stricter
+    // exposure. Regression-guards anyone tightening the default to
+    // "loopback" without realizing it would silently 404 every
+    // third-party module on tailnet/public.
+    const h = makeHarness();
+    const upstream = startUpstream("unknown-thirdparty");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-unknown-thirdparty",
+              port: upstream.port,
+              paths: ["/parachute-unknown-thirdparty"],
+              health: "/parachute-unknown-thirdparty/health",
+              version: "0.1.0",
+              // publicExposure absent — exercises the unknown-spec default path
+              // kind absent — no SERVICE_SPECS / FIRST_PARTY_FALLBACKS row matches
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const r = req("/parachute-unknown-thirdparty/health", {
+        headers: { "CF-Ray": "abc123" },
+      });
+      const res = await fetcher(r);
+      // Default "allowed" → no gate. Forwarded to upstream.
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string };
+      expect(body.tag).toBe("unknown-thirdparty");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+});
+
+describe("hubFetch publicExposure layer-gate (proxyToVault)", () => {
+  // Same gate, applied to /vault/<name>/* dispatch. A vault entry that
+  // declares publicExposure: "loopback" is hidden from non-loopback callers.
+
+  function startVaultUpstream(replyTag: string): { port: number; stop: () => void } {
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () =>
+        new Response(JSON.stringify({ tag: replyTag }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+    });
+    return { port: server.port as number, stop: () => server.stop(true) };
+  }
+
+  test("vault publicExposure: loopback + tailnet header → 404", async () => {
+    const h = makeHarness();
+    const upstream = startVaultUpstream("vault-private");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault-private",
+              port: upstream.port,
+              paths: ["/vault/private"],
+              health: "/vault/private/health",
+              version: "0.4.0",
+              publicExposure: "loopback",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const r = req("/vault/private/health", {
+        headers: { "Tailscale-User-Login": "alice@example.com" },
+      });
+      const res = await fetcher(r);
+      expect(res.status).toBe(404);
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("vault publicExposure: loopback + no headers → reaches vault backend", async () => {
+    const h = makeHarness();
+    const upstream = startVaultUpstream("vault-private");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault-private",
+              port: upstream.port,
+              paths: ["/vault/private"],
+              health: "/vault/private/health",
+              version: "0.4.0",
+              publicExposure: "loopback",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/vault/private/health"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string };
+      expect(body.tag).toBe("vault-private");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("vault publicExposure: allowed + tailnet header → reaches backend", async () => {
+    const h = makeHarness();
+    const upstream = startVaultUpstream("vault-public");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: upstream.port,
+              paths: ["/vault/default"],
+              health: "/vault/default/health",
+              version: "0.4.0",
+              publicExposure: "allowed",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const r = req("/vault/default/health", {
+        headers: { "Tailscale-User-Login": "alice@example.com" },
+      });
+      const res = await fetcher(r);
+      expect(res.status).toBe(200);
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
 });
 
 /** Find a port that no one is listening on by binding briefly and releasing. */