@openparachute/hub 0.6.4-rc.8 → 0.6.4

package/package.json

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

package/src/__tests__/expose-cloudflare.test.ts

@@ -1464,6 +1464,109 @@ describe("exposeCloudflareOff", () => {
     }
   });
 
+  test("clears stale PARACHUTE_HUB_ORIGIN from vault/.env on last-tunnel down (#503)", async () => {
+    const env = makeEnv();
+    try {
+      // Seed the stale public origin the up-path persisted into vault/.env.
+      // After teardown the hub is loopback-only, so leaving this would pin a
+      // public expected issuer and 401 every request on the next vault restart.
+      const vaultEnvPath = join(env.configDir, "vault", ".env");
+      require("node:fs").mkdirSync(join(env.configDir, "vault"), { recursive: true });
+      writeFileSync(vaultEnvPath, "PARACHUTE_HUB_ORIGIN=https://vault.example.com\n");
+
+      writeCloudflaredState(
+        {
+          version: 2,
+          tunnels: {
+            parachute: {
+              pid: 55557,
+              tunnelUuid: "ffffffff-0000-0000-0000-000000000006",
+              tunnelName: "parachute",
+              hostname: "vault.example.com",
+              startedAt: "2026-04-22T12:00:00.000Z",
+              configPath: env.configPath,
+            },
+          },
+        },
+        env.statePath,
+      );
+
+      const logs: string[] = [];
+      const code = await exposeCloudflareOff({
+        configDir: env.configDir,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        alive: () => false,
+        kill: () => {},
+        log: (l) => logs.push(l),
+      });
+
+      expect(code).toBe(0);
+      // The stale public origin is gone — vault reverts to its loopback default.
+      expect(readEnvFileValues(vaultEnvPath).PARACHUTE_HUB_ORIGIN).toBeUndefined();
+      // Operator is told what to restart so a running vault picks up the change.
+      expect(logs.join("\n")).toContain("cleared PARACHUTE_HUB_ORIGIN");
+      expect(logs.join("\n")).toContain("parachute restart vault");
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("leaves vault/.env untouched while other tunnels survive (#503)", async () => {
+    const env = makeEnv();
+    try {
+      const vaultEnvPath = join(env.configDir, "vault", ".env");
+      require("node:fs").mkdirSync(join(env.configDir, "vault"), { recursive: true });
+      writeFileSync(vaultEnvPath, "PARACHUTE_HUB_ORIGIN=https://vault.example.com\n");
+
+      // Two tunnels; tear down only one by name → the box stays exposed, so the
+      // persisted public origin must remain (clearing it would break the live
+      // tunnel's iss check). Symmetric with the expose-state.json retention.
+      writeCloudflaredState(
+        {
+          version: 2,
+          tunnels: {
+            alpha: {
+              pid: 55558,
+              tunnelUuid: "11111111-0000-0000-0000-000000000007",
+              tunnelName: "alpha",
+              hostname: "alpha.example.com",
+              startedAt: "2026-04-22T12:00:00.000Z",
+              configPath: env.configPath,
+            },
+            beta: {
+              pid: 55559,
+              tunnelUuid: "22222222-0000-0000-0000-000000000008",
+              tunnelName: "beta",
+              hostname: "beta.example.com",
+              startedAt: "2026-04-22T12:00:00.000Z",
+              configPath: env.configPath,
+            },
+          },
+        },
+        env.statePath,
+      );
+
+      const code = await exposeCloudflareOff({
+        configDir: env.configDir,
+        tunnelName: "alpha",
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        alive: () => false,
+        kill: () => {},
+        log: () => {},
+      });
+
+      expect(code).toBe(0);
+      // Beta tunnel survives → public origin stays.
+      expect(readEnvFileValues(vaultEnvPath).PARACHUTE_HUB_ORIGIN).toBe(
+        "https://vault.example.com",
+      );
+    } finally {
+      env.cleanup();
+    }
+  });
+
   test("clears stale state when the process is already gone", async () => {
     const env = makeEnv();
     try {

package/src/__tests__/expose-supervisor-version.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from "bun:test";
+import { ensureHubUnitForExpose, resolveExposeSupervisor } from "../commands/expose-supervisor.ts";
+import type { EnsureHubVersionMatchesResult } from "../hub-unit.ts";
+
+/**
+ * #590: `ensureHubUnitForExpose` must run the version-check-and-restart at the
+ * expose adoption point, so an expose never wires a tunnel to a stale zombie
+ * that merely answers /health on the canonical port. These tests drive the
+ * version-check seam directly (no real launchctl / live hub).
+ */
+describe("ensureHubUnitForExpose — version-check at the expose adoption point (#590)", () => {
+  function sup(
+    ensureHubUnitOutcome: "already-up" | "started" | "no-unit",
+    versionResult: EnsureHubVersionMatchesResult,
+    versionSpy?: (port: number) => void,
+  ) {
+    return resolveExposeSupervisor({
+      ensureHubUnit: async ({ port }) => ({
+        outcome: ensureHubUnitOutcome,
+        port: port ?? 1939,
+        messages: ensureHubUnitOutcome === "no-unit" ? ["no hub unit installed"] : [],
+      }),
+      ensureHubVersion: async ({ port }) => {
+        versionSpy?.(port);
+        return versionResult;
+      },
+    });
+  }
+
+  test("hub up + version matches → ok, version check ran with the probed port", async () => {
+    const logs: string[] = [];
+    let checkedPort: number | undefined;
+    const s = sup(
+      "already-up",
+      {
+        outcome: "match",
+        runningVersion: "0.6.4-rc.9",
+        installedVersion: "0.6.4-rc.9",
+        messages: [],
+      },
+      (p) => {
+        checkedPort = p;
+      },
+    );
+    const res = await ensureHubUnitForExpose(s, 1939, (l) => logs.push(l));
+    expect(res.ok).toBe(true);
+    expect(checkedPort).toBe(1939);
+  });
+
+  test("hub up but a stale zombie → restarted → ok (tunnel binds to NEW code)", async () => {
+    const logs: string[] = [];
+    const s = sup("already-up", {
+      outcome: "restarted",
+      runningVersion: "0.6.4-rc.9",
+      installedVersion: "0.6.4-rc.9",
+      messages: ["✓ hub unit restarted; now running 0.6.4-rc.9."],
+    });
+    const res = await ensureHubUnitForExpose(s, 1939, (l) => logs.push(l));
+    expect(res.ok).toBe(true);
+    expect(logs.join("\n")).toContain("now running 0.6.4-rc.9");
+  });
+
+  test("hub up but mismatch + NOT unit-managed → expose FAILS (don't tunnel to a zombie)", async () => {
+    const logs: string[] = [];
+    const s = sup("already-up", {
+      outcome: "not-unit-managed",
+      runningVersion: "0.5.14-rc.4",
+      installedVersion: "0.6.4-rc.9",
+      messages: ["⚠ the running hub is 0.5.14-rc.4 but 0.6.4-rc.9 is installed."],
+    });
+    const res = await ensureHubUnitForExpose(s, 1939, (l) => logs.push(l));
+    expect(res.ok).toBe(false);
+    expect(logs.join("\n")).toContain("0.5.14-rc.4");
+  });
+
+  test("still-mismatched after restart → expose CONTINUES (warn, don't block)", async () => {
+    const logs: string[] = [];
+    const s = sup("already-up", {
+      outcome: "still-mismatched",
+      runningVersion: "0.6.4-rc.8",
+      installedVersion: "0.6.4-rc.9",
+      messages: ["⚠ restarted the hub unit, but it is still not reporting 0.6.4-rc.9."],
+    });
+    const res = await ensureHubUnitForExpose(s, 1939, (l) => logs.push(l));
+    expect(res.ok).toBe(true);
+    expect(logs.join("\n")).toContain("still not reporting");
+  });
+
+  test("hub NOT up (no unit) → fails BEFORE the version check (no false adoption)", async () => {
+    const logs: string[] = [];
+    let versionRan = false;
+    const s = sup(
+      "no-unit",
+      { outcome: "match", installedVersion: "0.6.4-rc.9", messages: [] },
+      () => {
+        versionRan = true;
+      },
+    );
+    const res = await ensureHubUnitForExpose(s, 1939, (l) => logs.push(l));
+    expect(res.ok).toBe(false);
+    // The version check only runs once the hub is confirmed up.
+    expect(versionRan).toBe(false);
+  });
+});

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

@@ -1630,6 +1630,139 @@ describe("hubFetch /vault/<name>/* dynamic proxy (#144)", () => {
     }
   });
 
+  // #525: bare `/vault/<name>` POST (no `/mcp` suffix) half-connects MCP
+  // clients. The fix 308-redirects the bare-path POST to `<mount>/mcp` BEFORE
+  // proxying, so a compliant client re-POSTs to the right endpoint and clients
+  // that don't follow redirects at least get an actionable Location + JSON body
+  // (vs the old opaque vault 405).
+  test("POST to bare /vault/<name> 308-redirects to /vault/<name>/mcp with an actionable body (#525)", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [vaultEntry("aaron")] }, h.manifestPath);
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(
+        req("/vault/aaron", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ jsonrpc: "2.0", method: "initialize", id: 1 }),
+        }),
+      );
+      expect(res.status).toBe(308);
+      expect(res.headers.get("location")).toBe("/vault/aaron/mcp");
+      // 308 is permanently cacheable by default — no-store prevents a cached
+      // redirect outliving a remount.
+      expect(res.headers.get("cache-control")).toBe("no-store");
+      const body = (await res.json()) as { error: string; mcp_url: string; message: string };
+      expect(body.error).toBe("missing_mcp_suffix");
+      expect(body.mcp_url).toBe("/vault/aaron/mcp");
+      expect(body.message).toContain("/vault/aaron/mcp");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("bare-path 308 honors a trailing-slash mount: POST /vault/default → /vault/default/mcp (#525)", async () => {
+    // Mounts in services.json sometimes carry a trailing slash (#197). The
+    // redirect target must be built from the *normalized* mount so it stays
+    // `/vault/default/mcp`, never `/vault/default//mcp`.
+    const h = makeHarness();
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault-default",
+              port: 1940,
+              paths: ["/vault/default/"],
+              health: "/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/vault/default", { method: "POST" }));
+      expect(res.status).toBe(308);
+      expect(res.headers.get("location")).toBe("/vault/default/mcp");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("GET to bare /vault/<name> is NOT redirected — proxies through untouched (#525)", async () => {
+    // Only POST (the MCP transport verb) is caught. A browser GET to the bare
+    // path keeps its existing proxy behavior so we don't break any bare-path
+    // GET surface.
+    const h = makeHarness();
+    const upstream = startUpstream("bare-get");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault-aaron",
+              port: upstream.port,
+              paths: ["/vault/aaron"],
+              health: "/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/vault/aaron", { method: "GET" }));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string; method: string; pathname: string };
+      expect(body.tag).toBe("bare-get");
+      expect(body.method).toBe("GET");
+      expect(body.pathname).toBe("/vault/aaron");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  test("POST to the canonical /vault/<name>/mcp sub-path is NOT redirected — proxies through (#525)", async () => {
+    // The real MCP endpoint must keep working: a POST that already carries the
+    // `/mcp` suffix is a sub-path (not the exact bare mount) and proxies
+    // straight to the vault backend.
+    const h = makeHarness();
+    const upstream = startUpstream("mcp-post");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault-aaron",
+              port: upstream.port,
+              paths: ["/vault/aaron"],
+              health: "/health",
+              version: "0.4.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(
+        req("/vault/aaron/mcp", {
+          method: "POST",
+          body: JSON.stringify({ jsonrpc: "2.0", method: "tools/list", id: 2 }),
+        }),
+      );
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string; method: string; pathname: string };
+      expect(body.tag).toBe("mcp-post");
+      expect(body.method).toBe("POST");
+      expect(body.pathname).toBe("/vault/aaron/mcp");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
   test("synthesizes X-Forwarded-Proto when edge didn't set it (direct HTTPS to hub)", async () => {
     // Non-Render shape: hub bound directly to https (e.g. local TLS or a
     // proxy that doesn't set X-Forwarded-Proto). isHttpsRequest sees the

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

@@ -4,6 +4,7 @@ import {
   NO_MANAGER_MESSAGE,
   NO_UNIT_MESSAGE,
   ensureHubUnit,
+  ensureHubVersionMatches,
   installAndStartHubUnit,
   queryHubUnitState,
   restartHubUnit,
@@ -38,6 +39,12 @@ function fakeDeps(
   over: Partial<HubUnitDeps> & {
     runResults?: ServiceCommandResult[];
     healthSeq?: boolean[];
+    /**
+     * #590: scripted version-aware /health probe results. Each element is
+     * `null` (hub not answering) or `{ ok, version }`. Drives
+     * `probeHealthVersion` across the version-check + post-restart re-probe.
+     */
+    healthVersionSeq?: ({ ok: boolean; version?: string } | null)[];
     listeningSeq?: boolean[];
     installedUnit?: boolean;
   } = {},
@@ -46,6 +53,7 @@ function fakeDeps(
   const files = new Map<string, string>();
   let runIdx = 0;
   let healthIdx = 0;
+  let healthVersionIdx = 0;
   let listeningIdx = 0;
   const ok: ServiceCommandResult = { code: 0, stdout: "", stderr: "" };
 
@@ -96,6 +104,13 @@ function fakeDeps(
         if (!seq) return false;
         return seq[Math.min(healthIdx++, seq.length - 1)] ?? false;
       }),
+    probeHealthVersion:
+      over.probeHealthVersion ??
+      (async () => {
+        const seq = over.healthVersionSeq;
+        if (!seq) return null;
+        return seq[Math.min(healthVersionIdx++, seq.length - 1)] ?? null;
+      }),
     portListening:
       over.portListening ??
       (async () => {
@@ -576,3 +591,169 @@ describe("queryHubUnitState — §6.4 hub-row manager query", () => {
     expect(r.detail).toContain("spawn EPERM");
   });
 });
+
+describe("ensureHubVersionMatches — version-check-and-restart at adoption (#590)", () => {
+  const INSTALLED = "0.6.4-rc.9";
+
+  test("versions match → no-op, NO restart, NO manager call", async () => {
+    const f = fakeDeps({
+      platform: "darwin",
+      getuid: () => 501,
+      installedUnit: true,
+      healthVersionSeq: [{ ok: true, version: INSTALLED }],
+    });
+    const res = await ensureHubVersionMatches({
+      installedVersion: INSTALLED,
+      port: 1939,
+      deps: f.deps,
+      readyPollMs: 0,
+    });
+    expect(res.outcome).toBe("match");
+    expect(res.runningVersion).toBe(INSTALLED);
+    // No launchctl/systemctl call at all — the version agreed.
+    expect(f.calls).toEqual([]);
+  });
+
+  test("mismatch + unit-managed → restarts ONCE + re-probe shows new version → restarted", async () => {
+    const f = fakeDeps({
+      platform: "darwin",
+      getuid: () => 501,
+      installedUnit: true,
+      // first probe: stale zombie; after the restart the re-probe sees the new code.
+      healthVersionSeq: [
+        { ok: true, version: "0.5.14-rc.4" },
+        { ok: true, version: INSTALLED },
+      ],
+    });
+    const res = await ensureHubVersionMatches({
+      installedVersion: INSTALLED,
+      port: 1939,
+      deps: f.deps,
+      readyPollMs: 0,
+    });
+    expect(res.outcome).toBe("restarted");
+    // Exactly ONE restart (launchctl kickstart -k) was issued.
+    const restarts = f.calls.filter((c) => c.includes("kickstart"));
+    expect(restarts).toHaveLength(1);
+    expect(restarts[0]).toEqual(["launchctl", "kickstart", "-k", "gui/501/computer.parachute.hub"]);
+  });
+
+  test("/health has NO version field (very old hub) → treated as mismatch → restart", async () => {
+    const f = fakeDeps({
+      platform: "linux",
+      getuid: () => 1000,
+      installedUnit: true,
+      healthVersionSeq: [{ ok: true /* no version */ }, { ok: true, version: INSTALLED }],
+    });
+    const res = await ensureHubVersionMatches({
+      installedVersion: INSTALLED,
+      port: 1939,
+      deps: f.deps,
+      readyPollMs: 0,
+    });
+    expect(res.outcome).toBe("restarted");
+    expect(f.calls).toContainEqual(["systemctl", "--user", "restart", "parachute-hub.service"]);
+  });
+
+  test("mismatch but NOT unit-managed (no unit installed) → not-unit-managed, NO kill, actionable message", async () => {
+    const f = fakeDeps({
+      platform: "darwin",
+      getuid: () => 501,
+      installedUnit: false, // a detached legacy pid / dev `bun run serve`
+      healthVersionSeq: [{ ok: true, version: "0.5.14-rc.4" }],
+    });
+    const res = await ensureHubVersionMatches({
+      installedVersion: INSTALLED,
+      port: 1939,
+      deps: f.deps,
+      readyPollMs: 0,
+    });
+    expect(res.outcome).toBe("not-unit-managed");
+    // Did NOT issue any manager command — we never blindly kill a hub we don't own.
+    expect(f.calls).toEqual([]);
+    const joined = res.messages.join("\n");
+    expect(joined).toContain("NOT managed by a Parachute service unit");
+    expect(joined).toContain("0.5.14-rc.4");
+    expect(joined).toContain(INSTALLED);
+  });
+
+  test("mismatch but no service manager at all → not-unit-managed (don't kill)", async () => {
+    const f = fakeDeps({
+      platform: "linux",
+      installedUnit: true,
+      which: () => null, // no systemctl → no manager
+      healthVersionSeq: [{ ok: true, version: "0.5.14-rc.4" }],
+    });
+    const res = await ensureHubVersionMatches({
+      installedVersion: INSTALLED,
+      port: 1939,
+      deps: f.deps,
+      readyPollMs: 0,
+    });
+    expect(res.outcome).toBe("not-unit-managed");
+    expect(f.calls).toEqual([]);
+  });
+
+  test("restart-loop guard: still mismatched after the single restart → still-mismatched, restarts ONCE", async () => {
+    const f = fakeDeps({
+      platform: "darwin",
+      getuid: () => 501,
+      installedUnit: true,
+      // bun-linked branch checkout: the restart comes back STILL on the old
+      // version (package.json trails). Every probe returns the stale version.
+      healthVersionSeq: [{ ok: true, version: "0.5.14-rc.4" }],
+    });
+    const res = await ensureHubVersionMatches({
+      installedVersion: INSTALLED,
+      port: 1939,
+      deps: f.deps,
+      readyTimeoutMs: 0, // immediate deadline → one re-probe then settle
+      readyPollMs: 0,
+    });
+    expect(res.outcome).toBe("still-mismatched");
+    // Restarted AT MOST once — no loop.
+    const restarts = f.calls.filter((c) => c.includes("kickstart"));
+    expect(restarts).toHaveLength(1);
+    expect(res.messages.join("\n")).toContain("still not reporting");
+  });
+
+  test("hub not answering /health at all → not-running (no-op, no restart)", async () => {
+    const f = fakeDeps({
+      platform: "darwin",
+      getuid: () => 501,
+      installedUnit: true,
+      healthVersionSeq: [null], // connection refused / timeout
+    });
+    const res = await ensureHubVersionMatches({
+      installedVersion: INSTALLED,
+      port: 1939,
+      deps: f.deps,
+      readyPollMs: 0,
+    });
+    expect(res.outcome).toBe("not-running");
+    expect(f.calls).toEqual([]);
+  });
+
+  test("mismatch + unit-managed but the restart command fails → restart-failed", async () => {
+    const f = fakeDeps({
+      platform: "linux",
+      getuid: () => 1000,
+      installedUnit: true,
+      healthVersionSeq: [{ ok: true, version: "0.5.14-rc.4" }],
+      run: (cmd) => {
+        if (cmd.includes("restart")) {
+          return { code: 1, stdout: "", stderr: "Unit parachute-hub.service not found." };
+        }
+        return { code: 0, stdout: "", stderr: "" };
+      },
+    });
+    const res = await ensureHubVersionMatches({
+      installedVersion: INSTALLED,
+      port: 1939,
+      deps: f.deps,
+      readyPollMs: 0,
+    });
+    expect(res.outcome).toBe("restart-failed");
+    expect(res.messages.join("\n")).toContain("Unit parachute-hub.service not found.");
+  });
+});