@openparachute/hub 0.5.14-rc.4 → 0.5.14-rc.6

package/package.json

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

package/src/__tests__/api-ready.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "bun:test";
+import { handleApiReady } from "../api-ready.ts";
+import type { ModuleState, Supervisor } from "../supervisor.ts";
+
+function stubSupervisor(states: ModuleState[]): Supervisor {
+  return {
+    list: () => states,
+    get: (short: string) => states.find((s) => s.short === short),
+    start: async () => {
+      throw new Error("not implemented");
+    },
+    stop: async () => undefined,
+    restart: async () => undefined,
+  } as unknown as Supervisor;
+}
+
+function req(): Request {
+  return new Request("http://127.0.0.1/api/ready", {
+    headers: { accept: "application/json" },
+  });
+}
+
+function moduleState(partial: Partial<ModuleState> & { short: string }): ModuleState {
+  return {
+    status: "running",
+    restartsInWindow: 0,
+    ...partial,
+  };
+}
+
+describe("handleApiReady — no supervisor (CLI mode)", () => {
+  test("returns ready=true + empty arrays when supervisor absent", async () => {
+    const res = handleApiReady(req());
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      ready: boolean;
+      ready_modules: string[];
+      transient_modules: string[];
+      persistent_modules: string[];
+    };
+    expect(body.ready).toBe(true);
+    expect(body.ready_modules).toEqual([]);
+    expect(body.transient_modules).toEqual([]);
+    expect(body.persistent_modules).toEqual([]);
+  });
+});
+
+describe("handleApiReady — supervisor mode", () => {
+  test("all modules running past boot window → ready=true", async () => {
+    const now = 1_700_000_000_000;
+    const startedAt = new Date(now - 60_000).toISOString();
+    const sup = stubSupervisor([
+      moduleState({ short: "vault", status: "running", startedAt }),
+      moduleState({ short: "scribe", status: "running", startedAt }),
+    ]);
+    const res = handleApiReady(req(), { supervisor: sup, now: () => now });
+    const body = (await res.json()) as {
+      ready: boolean;
+      ready_modules: string[];
+      transient_modules: string[];
+      persistent_modules: string[];
+    };
+    expect(body.ready).toBe(true);
+    expect(body.ready_modules.sort()).toEqual(["scribe", "vault"]);
+    expect(body.transient_modules).toEqual([]);
+    expect(body.persistent_modules).toEqual([]);
+  });
+
+  test("module inside boot window → transient, ready=false", async () => {
+    const now = 1_700_000_000_000;
+    const sup = stubSupervisor([
+      moduleState({
+        short: "vault",
+        status: "running",
+        startedAt: new Date(now - 10_000).toISOString(),
+      }),
+    ]);
+    const res = handleApiReady(req(), { supervisor: sup, now: () => now });
+    const body = (await res.json()) as {
+      ready: boolean;
+      ready_modules: string[];
+      transient_modules: string[];
+    };
+    expect(body.ready).toBe(false);
+    expect(body.transient_modules).toEqual(["vault"]);
+    expect(body.ready_modules).toEqual([]);
+  });
+
+  test("starting + restarting + crashed all classified correctly", async () => {
+    const now = 1_700_000_000_000;
+    const sup = stubSupervisor([
+      moduleState({ short: "vault", status: "starting" }),
+      moduleState({ short: "scribe", status: "restarting" }),
+      moduleState({ short: "notes", status: "crashed" }),
+      moduleState({ short: "channel", status: "stopped" }),
+      moduleState({
+        short: "runner",
+        status: "running",
+        startedAt: new Date(now - 60_000).toISOString(),
+      }),
+    ]);
+    const res = handleApiReady(req(), { supervisor: sup, now: () => now });
+    const body = (await res.json()) as {
+      ready: boolean;
+      ready_modules: string[];
+      transient_modules: string[];
+      persistent_modules: string[];
+    };
+    expect(body.ready).toBe(false);
+    expect(body.ready_modules).toEqual(["runner"]);
+    expect(body.transient_modules.sort()).toEqual(["scribe", "vault"]);
+    expect(body.persistent_modules.sort()).toEqual(["channel", "notes"]);
+  });
+
+  test("only crashed/stopped + nothing transient → ready=false (still failing)", async () => {
+    const sup = stubSupervisor([moduleState({ short: "vault", status: "crashed" })]);
+    const res = handleApiReady(req(), { supervisor: sup });
+    const body = (await res.json()) as { ready: boolean };
+    expect(body.ready).toBe(false);
+  });
+});
+
+describe("handleApiReady — method check", () => {
+  test("rejects non-GET", () => {
+    const r = new Request("http://127.0.0.1/api/ready", { method: "POST" });
+    const res = handleApiReady(r);
+    expect(res.status).toBe(405);
+  });
+
+  test("accepts HEAD", () => {
+    const r = new Request("http://127.0.0.1/api/ready", { method: "HEAD" });
+    const res = handleApiReady(r);
+    expect(res.status).toBe(200);
+  });
+});

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

@@ -59,10 +59,65 @@ describe("cloudflare detect", () => {
     }
   });
 
-  test("install hint names brew on darwin and a URL elsewhere", () => {
-    expect(cloudflaredInstallHint("darwin")).toContain("brew install cloudflared");
-    expect(cloudflaredInstallHint("linux")).toContain(
-      "developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads",
-    );
+  describe("cloudflaredInstallHint", () => {
+    test("darwin: names brew + points at GitHub releases as fallback", () => {
+      const hint = cloudflaredInstallHint("darwin", "arm64");
+      expect(hint).toContain("brew install cloudflared");
+      expect(hint).toContain("https://github.com/cloudflare/cloudflared/releases/latest");
+    });
+
+    test("linux x64: writes the curl line with the amd64 artifact suffix", () => {
+      // Refresh of stale URLs (2026-05-27). Aaron hit this on a fresh
+      // Amazon Linux 2023 install — `sudo dnf install cloudflared`
+      // returned 'No match for argument: cloudflared', and the hub's
+      // hint pointed at developers.cloudflare.com paths that 404. The
+      // GitHub release is the reliable cross-distro path.
+      const hint = cloudflaredInstallHint("linux", "x64");
+      expect(hint).toContain("curl -L -o /usr/local/bin/cloudflared");
+      expect(hint).toContain(
+        "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64",
+      );
+      expect(hint).toContain("sudo chmod +x /usr/local/bin/cloudflared");
+    });
+
+    test("linux arm64: writes the arm64 artifact suffix", () => {
+      const hint = cloudflaredInstallHint("linux", "arm64");
+      expect(hint).toContain("cloudflared-linux-arm64");
+    });
+
+    test("linux arm (32-bit): writes the arm artifact suffix", () => {
+      const hint = cloudflaredInstallHint("linux", "arm");
+      expect(hint).toContain("cloudflared-linux-arm");
+    });
+
+    test("linux exotic arch: falls back to a generic GitHub releases pointer", () => {
+      // riscv64 / ppc64 / mips64 — no cloudflared artifact published, so
+      // we don't fabricate a 404-bound download URL; we point the user at
+      // the releases page and surface what their arch is so they can pick.
+      const hint = cloudflaredInstallHint("linux", "riscv64");
+      expect(hint).toContain("https://github.com/cloudflare/cloudflared/releases/latest");
+      expect(hint).toContain("riscv64");
+      expect(hint).not.toContain("curl -L -o /usr/local/bin/cloudflared");
+    });
+
+    test("no stale developers.cloudflare.com or pkg.cloudflare.com paths anywhere", () => {
+      // Aaron caught both URL shapes returning HTML/404 on 2026-05-27 —
+      // they had been the hub's installer instructions for months.
+      // Hard-assert they're gone so they don't regress.
+      for (const platform of ["darwin", "linux"] as const) {
+        for (const arch of ["x64", "arm64"] as const) {
+          const hint = cloudflaredInstallHint(platform, arch);
+          expect(hint).not.toContain("developers.cloudflare.com");
+          expect(hint).not.toContain("pkg.cloudflare.com");
+        }
+      }
+    });
+
+    test("non-Linux, non-darwin platform: GitHub releases pointer with no curl line", () => {
+      const hint = cloudflaredInstallHint("win32", "x64");
+      expect(hint).toContain("https://github.com/cloudflare/cloudflared/releases/latest");
+      expect(hint).not.toContain("brew install");
+      expect(hint).not.toContain("curl -L -o");
+    });
   });
 });

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

@@ -14,8 +14,13 @@ import {
   exposeCloudflareOff,
   exposeCloudflareUp,
 } from "../commands/expose-cloudflare.ts";
+import { writeHubPort } from "../hub-control.ts";
 import type { CommandResult, Runner } from "../tailscale/run.ts";
 
+// Default seeded hub port used by tests with `skipHub: true`. The cloudflared
+// path reads `<configDir>/hub/run/hub.port` instead of spawning a real hub.
+const TEST_HUB_PORT = 1939;
+
 interface TestEnv {
   configDir: string;
   manifestPath: string;
@@ -41,6 +46,11 @@ function makeEnv(opts: { includeVault?: boolean; loggedIn?: boolean } = {}): Tes
   require("node:fs").mkdirSync(configDir, { recursive: true });
   require("node:fs").mkdirSync(cloudflaredHome, { recursive: true });
 
+  // Seed the hub port so `skipHub: true` invocations can resolve a port
+  // without spawning the actual hub process. Matches the seam pattern used
+  // by expose.test.ts (which threads `hubEnsureOpts` for the same purpose).
+  writeHubPort(TEST_HUB_PORT, configDir);
+
   if (loggedIn) {
     writeFileSync(join(cloudflaredHome, "cert.pem"), "---");
   }
@@ -128,6 +138,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
         now: () => new Date("2026-04-22T12:00:00Z"),
       });
 
@@ -170,7 +182,12 @@ describe("exposeCloudflareUp", () => {
       const yaml = readFileSync(env.configPath, "utf8");
       expect(yaml).toContain(`tunnel: ${uuid}`);
       expect(yaml).toContain("- hostname: vault.example.com");
-      expect(yaml).toContain("service: http://localhost:1940");
+      // Routes through the hub (not directly at vault). The hub dispatches
+      // discovery / admin / OAuth / per-vault proxy / generic /<svc>/* —
+      // same shape Tailscale Funnel uses. Pre-2026-05-27 this was
+      // http://localhost:1940 (vault's port), which served vault's own 404
+      // page on every request that wasn't /vault/<name>/...
+      expect(yaml).toContain(`service: http://localhost:${TEST_HUB_PORT}`);
 
       // Security copy surfaces both paths plus a pointer to the auth doc.
       const joined = logs.join("\n");
@@ -209,6 +226,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
       expect(code).toBe(0);
       // No `tunnel create` — only list + route.
@@ -236,6 +255,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -262,6 +283,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
         tunnelName: "bad name with spaces",
       });
 
@@ -291,6 +314,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -317,6 +342,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -342,6 +369,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -376,6 +405,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -425,6 +456,8 @@ describe("exposeCloudflareUp", () => {
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(0);
@@ -462,6 +495,8 @@ describe("exposeCloudflareUp", () => {
         manifestPath: env.manifestPath,
         statePath: env.statePath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
         // Use defaults for configPath/logPath so they're per-tunnel-derived.
       });
       expect(code1).toBe(0);
@@ -487,6 +522,8 @@ describe("exposeCloudflareUp", () => {
         manifestPath: env.manifestPath,
         statePath: env.statePath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
         tunnelName: "second",
       });
       expect(code2).toBe(0);
@@ -544,6 +581,8 @@ describe("exposeCloudflareUp", () => {
           configPath: env.configPath,
           logPath: env.logPath,
           cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
           // No password, no 2FA — fully wide open. The warning should still
           // fire; password-recovery copy already lives in `printAuthGuidance`.
           vaultAuthStatus: {
@@ -592,6 +631,8 @@ describe("exposeCloudflareUp", () => {
           configPath: env.configPath,
           logPath: env.logPath,
           cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
           vaultAuthStatus: {
             hasOwnerPassword: true,
             hasTotp: true,
@@ -612,6 +653,68 @@ describe("exposeCloudflareUp", () => {
       }
     });
   });
+
+  describe("routes through hub, not vault", () => {
+    test("config.yml targets the hub port; success log mentions Admin + OAuth URLs", async () => {
+      // Regression guard for the 2026-05-27 cut. Aaron ran `parachute expose
+      // public` on a fresh EC2 box, configured Cloudflare with a custom
+      // domain, and hit it — and got vault's 404 page rather than the hub's
+      // discovery / admin. The pre-fix cloudflared config routed straight at
+      // vault's port; the fix routes at the hub, mirroring the Tailscale
+      // Funnel shape (single mount → hub catchall; hub dispatches per-request).
+      const env = makeEnv();
+      try {
+        // Re-seed hub port to a non-default value so the assertion is
+        // unambiguous about *which* port got into the yaml.
+        writeHubPort(1949, env.configDir);
+
+        const uuid = "ffff0000-0000-0000-0000-00000000beef";
+        const { runner } = queueRunner([
+          { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+          { code: 0, stdout: "[]", stderr: "" },
+          {
+            code: 0,
+            stdout: `Created tunnel parachute with id ${uuid}\n`,
+            stderr: "",
+          },
+          { code: 0, stdout: "", stderr: "" },
+        ]);
+        const { spawner } = fakeSpawner(60001);
+        const logs: string[] = [];
+
+        const code = await exposeCloudflareUp("gitcoin.parachute.computer", {
+          runner,
+          spawner,
+          alive: () => false,
+          kill: () => {},
+          log: (l) => logs.push(l),
+          manifestPath: env.manifestPath,
+          statePath: env.statePath,
+          configPath: env.configPath,
+          logPath: env.logPath,
+          cloudflaredHome: env.cloudflaredHome,
+          configDir: env.configDir,
+          skipHub: true,
+        });
+
+        expect(code).toBe(0);
+        const yaml = readFileSync(env.configPath, "utf8");
+        // Routes through the hub on its loopback port.
+        expect(yaml).toContain("service: http://localhost:1949");
+        // Does NOT route directly at vault's port (1940 per makeEnv default).
+        expect(yaml).not.toContain("service: http://localhost:1940");
+
+        const joined = logs.join("\n");
+        // Discoverable surfaces: open / admin / vault / OAuth all surfaced.
+        expect(joined).toContain("https://gitcoin.parachute.computer/");
+        expect(joined).toContain("Admin:   https://gitcoin.parachute.computer/admin/");
+        expect(joined).toContain("Vault:   https://gitcoin.parachute.computer/vault/default");
+        expect(joined).toContain("OAuth:   https://gitcoin.parachute.computer");
+      } finally {
+        env.cleanup();
+      }
+    });
+  });
 });
 
 describe("exposeCloudflareOff", () => {

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

@@ -469,10 +469,16 @@ describe("exposePublicInteractive — neither ready", () => {
       expect(interactiveCalled).toBe(false);
       expect(cloudflareCalled).toBe(false);
       const joined = logs.join("\n");
-      expect(joined).toMatch(/apt-get|dnf/);
-      expect(joined).toContain(
-        "developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads",
-      );
+      // Post 2026-05-27 cloudflared-URL refresh: the install hint moved
+      // off apt-get / dnf / developers.cloudflare.com (all unreliable —
+      // Aaron hit `No match for argument: cloudflared` on AL2023 and
+      // 404s from the docs URL on the same box) onto the static binary
+      // from GitHub releases.
+      expect(joined).toContain("github.com/cloudflare/cloudflared/releases/latest");
+      expect(joined).toContain("curl -L -o /usr/local/bin/cloudflared");
+      expect(joined).not.toContain("developers.cloudflare.com");
+      expect(joined).not.toContain("pkg.cloudflare.com");
+      expect(joined).not.toContain("sudo dnf install cloudflared");
     } finally {
       env.cleanup();
     }

package/src/__tests__/expose-public-auto.test.ts

@@ -126,7 +126,11 @@ describe("exposePublicAutoPick — neither ready", () => {
     expect(code).toBe(1);
     const joined = logs.join("\n");
     expect(joined).toContain("tailscale.com/download");
-    expect(joined).toContain("developers.cloudflare.com");
+    // Post 2026-05-27 cloudflared-URL refresh: the install hint now points
+    // at GitHub releases (developers.cloudflare.com / pkg.cloudflare.com
+    // both returned HTML/404 on Aaron's fresh AL2023 EC2 box).
+    expect(joined).toContain("github.com/cloudflare/cloudflared/releases/latest");
+    expect(joined).not.toContain("developers.cloudflare.com");
     expect(joined).toContain("--skip-provider-check");
   });