@openparachute/hub 0.5.14-rc.2 → 0.5.14-rc.21

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

@@ -14,12 +14,20 @@ import {
   exposeCloudflareOff,
   exposeCloudflareUp,
 } from "../commands/expose-cloudflare.ts";
+import { readEnvFileValues } from "../env-file.ts";
+import { readExposeState } from "../expose-state.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;
   statePath: string;
+  exposeStatePath: string;
   configPath: string;
   logPath: string;
   cloudflaredHome: string;
@@ -35,12 +43,18 @@ function makeEnv(opts: { includeVault?: boolean; loggedIn?: boolean } = {}): Tes
   const cloudflaredHome = join(dir, "cloudflared");
   const manifestPath = join(configDir, "services.json");
   const statePath = join(configDir, "cloudflared-state.json");
+  const exposeStatePath = join(configDir, "expose-state.json");
   const configPath = join(configDir, "cloudflared", "parachute", "config.yml");
   const logPath = join(configDir, "cloudflared", "parachute", "cloudflared.log");
 
   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"), "---");
   }
@@ -62,6 +76,7 @@ function makeEnv(opts: { includeVault?: boolean; loggedIn?: boolean } = {}): Tes
     configDir,
     manifestPath,
     statePath,
+    exposeStatePath,
     configPath,
     logPath,
     cloudflaredHome,
@@ -125,9 +140,12 @@ describe("exposeCloudflareUp", () => {
         log: (l) => logs.push(l),
         manifestPath: env.manifestPath,
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
         now: () => new Date("2026-04-22T12:00:00Z"),
       });
 
@@ -170,18 +188,207 @@ 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");
       expect(joined).toContain("parachute auth set-password");
-      expect(joined).toContain("parachute vault tokens create");
+      // Scripts/machines path points at the hub-JWT mint (vault#412 / hub#466
+      // DROPped `vault tokens create`), not the removed pvt_* command.
+      expect(joined).toContain("parachute auth mint-token --scope vault:");
+      expect(joined).toContain("Bearer <hub-jwt>");
+      expect(joined).not.toContain("vault tokens create");
+      expect(joined).not.toContain("pvt_");
       expect(joined).toContain("auth-model.md");
     } finally {
       env.cleanup();
     }
   });
 
+  test("persists expose-state.json with the canonicalFqdn + public hubOrigin (Fix 1)", async () => {
+    // The OAuth-iss bug: pre-fix the cloudflare path never wrote
+    // expose-state.json, so `readExposeState()` returned undefined and
+    // downstream consumers (init's resolveAdminUrl, lifecycle's
+    // resolveHubOrigin, the vault .env PARACHUTE_HUB_ORIGIN persistence)
+    // fell back to loopback — wrong OAuth `iss` on Cloudflare deploys.
+    const env = makeEnv();
+    try {
+      const uuid = "eeeeeeee-0000-0000-0000-000000000005";
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: "[]", stderr: "" },
+        {
+          code: 0,
+          stdout: `Tunnel credentials written to ${env.cloudflaredHome}/${uuid}.json.\nCreated tunnel parachute with id ${uuid}\n`,
+          stderr: "",
+        },
+        { code: 0, stdout: "", stderr: "" },
+      ]);
+      const { spawner } = fakeSpawner(42200);
+
+      // Pre-condition: no expose-state.json yet.
+      expect(readExposeState(env.exposeStatePath)).toBeUndefined();
+
+      const code = await exposeCloudflareUp("gitcoin.parachute.computer", {
+        runner,
+        spawner,
+        alive: () => false,
+        kill: () => {},
+        log: () => {},
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+      });
+
+      expect(code).toBe(0);
+      const exposeState = readExposeState(env.exposeStatePath);
+      expect(exposeState).toBeDefined();
+      expect(exposeState?.layer).toBe("public");
+      expect(exposeState?.mode).toBe("subdomain");
+      expect(exposeState?.canonicalFqdn).toBe("gitcoin.parachute.computer");
+      expect(exposeState?.funnel).toBe(false);
+      expect(exposeState?.port).toBe(TEST_HUB_PORT);
+      // The public origin OAuth clients will see — the load-bearing field.
+      expect(exposeState?.hubOrigin).toBe("https://gitcoin.parachute.computer");
+      // Single hub-catchall proxy entry (matches the Tailscale path's shape).
+      expect(exposeState?.entries).toEqual([
+        {
+          kind: "proxy",
+          mount: "/",
+          target: `http://localhost:${TEST_HUB_PORT}`,
+          service: "hub",
+        },
+      ]);
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("persists the public hub origin to vault/.env + restarts vault (Cloudflare 401 fix)", async () => {
+    // The Cloudflare 401 P0: the cloudflare path wrote expose-state.json but —
+    // unlike the Tailscale path, which auto-restarts vault and so flows the
+    // public origin into vault/.env via lifecycle's persistVaultHubOrigin —
+    // never touched vault's .env or restarted it. The launchd/systemd daemon
+    // kept booting vault with NO PARACHUTE_HUB_ORIGIN → vault fell back to
+    // loopback as its expected issuer → every hub-minted token (iss=public)
+    // failed the iss check → 401. This asserts the durable .env write + the
+    // running-vault restart that mirrors the Tailscale path.
+    const env = makeEnv();
+    try {
+      // Seed vault as "running" so the restart branch fires. PID lives at
+      // <configDir>/vault/run/vault.pid (see process-state.ts:pidPath).
+      const vaultRun = join(env.configDir, "vault", "run");
+      require("node:fs").mkdirSync(vaultRun, { recursive: true });
+      writeFileSync(join(vaultRun, "vault.pid"), "99001");
+
+      const uuid = "ffffffff-0000-0000-0000-000000000006";
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: "[]", stderr: "" },
+        {
+          code: 0,
+          stdout: `Tunnel credentials written to ${env.cloudflaredHome}/${uuid}.json.\nCreated tunnel parachute with id ${uuid}\n`,
+          stderr: "",
+        },
+        { code: 0, stdout: "", stderr: "" },
+      ]);
+      const { spawner } = fakeSpawner(42300);
+      const restarted: string[] = [];
+
+      const code = await exposeCloudflareUp("gitcoin-parachute.unforced.dev", {
+        runner,
+        spawner,
+        // `alive` reports the seeded vault pid as running so processState() ===
+        // "running" and the restart branch executes.
+        alive: (pid) => pid === 99001,
+        kill: () => {},
+        log: () => {},
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+        restartService: async (short) => {
+          restarted.push(short);
+          return 0;
+        },
+      });
+
+      expect(code).toBe(0);
+      // Durable half: the public origin is written to vault/.env (NOT loopback,
+      // NOT unset) so the daemon boot path validates iss against it.
+      expect(readEnvFileValues(join(env.configDir, "vault", ".env")).PARACHUTE_HUB_ORIGIN).toBe(
+        "https://gitcoin-parachute.unforced.dev",
+      );
+      // Live half: the running vault is restarted to re-read the new origin.
+      expect(restarted).toEqual(["vault"]);
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("persists vault/.env but does NOT restart when vault isn't running", async () => {
+    // No vault pidfile → processState() !== "running" → no restart, but the
+    // durable .env write still happens so the next daemon boot is correct.
+    const env = makeEnv();
+    try {
+      const uuid = "ffffffff-0000-0000-0000-000000000007";
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: "[]", stderr: "" },
+        {
+          code: 0,
+          stdout: `Tunnel credentials written to ${env.cloudflaredHome}/${uuid}.json.\nCreated tunnel parachute with id ${uuid}\n`,
+          stderr: "",
+        },
+        { code: 0, stdout: "", stderr: "" },
+      ]);
+      const { spawner } = fakeSpawner(42301);
+      const restarted: string[] = [];
+
+      const code = await exposeCloudflareUp("gitcoin-parachute.unforced.dev", {
+        runner,
+        spawner,
+        alive: () => false,
+        kill: () => {},
+        log: () => {},
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+        restartService: async (short) => {
+          restarted.push(short);
+          return 0;
+        },
+      });
+
+      expect(code).toBe(0);
+      expect(readEnvFileValues(join(env.configDir, "vault", ".env")).PARACHUTE_HUB_ORIGIN).toBe(
+        "https://gitcoin-parachute.unforced.dev",
+      );
+      expect(restarted).toEqual([]);
+    } finally {
+      env.cleanup();
+    }
+  });
+
   test("reuses existing tunnel when name already present", async () => {
     const env = makeEnv();
     try {
@@ -206,9 +413,12 @@ describe("exposeCloudflareUp", () => {
         log: (l) => logs.push(l),
         manifestPath: env.manifestPath,
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
       expect(code).toBe(0);
       // No `tunnel create` — only list + route.
@@ -233,9 +443,12 @@ describe("exposeCloudflareUp", () => {
         log: (l) => logs.push(l),
         manifestPath: env.manifestPath,
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -259,9 +472,12 @@ describe("exposeCloudflareUp", () => {
         log: (l) => logs.push(l),
         manifestPath: env.manifestPath,
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
         tunnelName: "bad name with spaces",
       });
 
@@ -288,9 +504,12 @@ describe("exposeCloudflareUp", () => {
         log: (l) => logs.push(l),
         manifestPath: env.manifestPath,
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -314,9 +533,12 @@ describe("exposeCloudflareUp", () => {
         log: (l) => logs.push(l),
         manifestPath: env.manifestPath,
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -339,9 +561,12 @@ describe("exposeCloudflareUp", () => {
         log: (l) => logs.push(l),
         manifestPath: env.manifestPath,
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -373,9 +598,12 @@ describe("exposeCloudflareUp", () => {
         log: (l) => logs.push(l),
         manifestPath: env.manifestPath,
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(1);
@@ -422,9 +650,12 @@ describe("exposeCloudflareUp", () => {
         log: () => {},
         manifestPath: env.manifestPath,
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         configPath: env.configPath,
         logPath: env.logPath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
       });
 
       expect(code).toBe(0);
@@ -436,6 +667,191 @@ describe("exposeCloudflareUp", () => {
     }
   });
 
+  test("hub#487: kills orphan connectors found by pgrep before spawning, not just the state pid", async () => {
+    // The orphan-accumulation bug: each re-expose spawned a fresh connector
+    // without killing prior ones, and state only tracked the most-recent pid.
+    // Orphans the state file lost track of (crashed mid-rewrite, started by
+    // hand) must still be swept — `connectorPids` finds them by UUID/config
+    // path. Here state knows pid 99999, but pgrep also surfaces 88888 + 77777
+    // serving the same tunnel; all three get SIGTERM before the new spawn.
+    const env = makeEnv();
+    try {
+      const uuid = "cccccccc-0000-0000-0000-000000000003";
+      const priorRecord: CloudflaredTunnelRecord = {
+        pid: 99999,
+        tunnelUuid: uuid,
+        tunnelName: "parachute",
+        hostname: "vault.example.com",
+        startedAt: "2026-04-21T00:00:00.000Z",
+        configPath: env.configPath,
+      };
+      writeCloudflaredState({ version: 2, tunnels: { parachute: priorRecord } }, env.statePath);
+
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+        { code: 0, stdout: "", stderr: "" }, // route dns
+      ]);
+      const { spawner, seen } = fakeSpawner(42010);
+      const killed: number[] = [];
+
+      const code = await exposeCloudflareUp("vault.example.com", {
+        runner,
+        spawner,
+        alive: () => true, // all candidate pids report alive
+        kill: (pid) => killed.push(pid),
+        // pgrep surfaces two orphans the state record didn't track.
+        connectorPids: () => [88888, 77777],
+        resolveHost: async () => ["104.16.0.1"], // Cloudflare — no DNS warning
+        log: () => {},
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+      });
+
+      expect(code).toBe(0);
+      // Every prior connector (state pid + both pgrep orphans) is stopped
+      // before the new one spawns.
+      expect(killed.sort()).toEqual([77777, 88888, 99999]);
+      // Exactly one fresh connector spawned, and it's the one recorded.
+      expect(seen).toHaveLength(1);
+      expect(findTunnelRecord(readCloudflaredState(env.statePath), "parachute")?.pid).toBe(42010);
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("hub#487: warns when DNS doesn't resolve yet (pending zone)", async () => {
+    // route dns succeeded but the hostname doesn't resolve — the "pending"
+    // zone shape (NS not switched at the registrar). Non-fatal: still exit 0,
+    // still print the URLs, but add the nameserver-switch nudge.
+    const env = makeEnv();
+    try {
+      const uuid = "dddddddd-0000-0000-0000-000000000004";
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+        { code: 0, stdout: "", stderr: "" },
+      ]);
+      const { spawner } = fakeSpawner(42020);
+      const logs: string[] = [];
+
+      const code = await exposeCloudflareUp("vault.newzone.com", {
+        runner,
+        spawner,
+        alive: () => false,
+        kill: () => {},
+        connectorPids: () => [],
+        resolveHost: async () => [], // NXDOMAIN / not live yet
+        log: (l) => logs.push(l),
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+      });
+
+      expect(code).toBe(0); // non-fatal — the expose still completes
+      const joined = logs.join("\n");
+      expect(joined).toContain("DNS isn't live yet for vault.newzone.com");
+      expect(joined).toContain("dig +short newzone.com NS");
+      expect(joined).toContain("ns.cloudflare.com");
+      // The success URLs still print.
+      expect(joined).toContain("https://vault.newzone.com/admin/");
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("hub#487: warns when hostname resolves but not to Cloudflare (shadowed)", async () => {
+    // route dns succeeded but the hostname resolves to a non-Cloudflare IP —
+    // a Pages project / grey-cloud A record shadowing the tunnel → edge 404.
+    const env = makeEnv();
+    try {
+      const uuid = "eeeeeeee-0000-0000-0000-000000000006";
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+        { code: 0, stdout: "", stderr: "" },
+      ]);
+      const { spawner } = fakeSpawner(42021);
+      const logs: string[] = [];
+
+      const code = await exposeCloudflareUp("docs.parachute.computer", {
+        runner,
+        spawner,
+        alive: () => false,
+        kill: () => {},
+        connectorPids: () => [],
+        resolveHost: async () => ["203.0.113.10"], // not a Cloudflare range
+        log: (l) => logs.push(l),
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+      });
+
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).toContain("not to Cloudflare's edge");
+      expect(joined).toContain("shadowed");
+      expect(joined).toContain("Pages project");
+    } finally {
+      env.cleanup();
+    }
+  });
+
+  test("hub#487: no DNS warning when hostname resolves at Cloudflare's edge", async () => {
+    const env = makeEnv();
+    try {
+      const uuid = "ffffffff-0000-0000-0000-000000000007";
+      const { runner } = queueRunner([
+        { code: 0, stdout: "cloudflared 2024.1.0\n", stderr: "" },
+        { code: 0, stdout: JSON.stringify([{ id: uuid, name: "parachute" }]), stderr: "" },
+        { code: 0, stdout: "", stderr: "" },
+      ]);
+      const { spawner } = fakeSpawner(42022);
+      const logs: string[] = [];
+
+      const code = await exposeCloudflareUp("vault.example.com", {
+        runner,
+        spawner,
+        alive: () => false,
+        kill: () => {},
+        connectorPids: () => [],
+        resolveHost: async () => ["104.18.32.7"], // 104.16.0.0/13 — Cloudflare
+        log: (l) => logs.push(l),
+        manifestPath: env.manifestPath,
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        configPath: env.configPath,
+        logPath: env.logPath,
+        cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
+      });
+
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).not.toContain("DNS isn't live yet");
+      expect(joined).not.toContain("not to Cloudflare's edge");
+    } finally {
+      env.cleanup();
+    }
+  });
+
   test("two tunnels with different --tunnel-name coexist in state", async () => {
     const env = makeEnv();
     try {
@@ -461,8 +877,14 @@ describe("exposeCloudflareUp", () => {
         log: () => {},
         manifestPath: env.manifestPath,
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         cloudflaredHome: env.cloudflaredHome,
-        // Use defaults for configPath/logPath so they're per-tunnel-derived.
+        configDir: env.configDir,
+        skipHub: true,
+        // Omit configPath/logPath so they're per-tunnel-derived — but the
+        // derivation now resolves against the tmp `configDir` above, so the
+        // generated config.yml lands under tmp, not the operator's real
+        // ~/.parachute/cloudflared/parachute/.
       });
       expect(code1).toBe(0);
 
@@ -486,7 +908,10 @@ describe("exposeCloudflareUp", () => {
         log: () => {},
         manifestPath: env.manifestPath,
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         cloudflaredHome: env.cloudflaredHome,
+        configDir: env.configDir,
+        skipHub: true,
         tunnelName: "second",
       });
       expect(code2).toBe(0);
@@ -541,9 +966,12 @@ describe("exposeCloudflareUp", () => {
           log: (l) => logs.push(l),
           manifestPath: env.manifestPath,
           statePath: env.statePath,
+          exposeStatePath: env.exposeStatePath,
           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: {
@@ -556,7 +984,9 @@ describe("exposeCloudflareUp", () => {
 
         expect(code).toBe(0);
         const joined = logs.join("\n");
-        expect(joined).toContain("2FA is not enrolled");
+        // hub#473: real hub-login 2FA — the warning now recommends the real
+        // `parachute auth 2fa enroll` path.
+        expect(joined).toContain("/login is now reachable on the public internet");
         expect(joined).toContain("https://vault.example.com/login");
         expect(joined).toContain("parachute auth 2fa enroll");
       } finally {
@@ -564,7 +994,7 @@ describe("exposeCloudflareUp", () => {
       }
     });
 
-    test("enrolled → warning suppressed (no '2FA is not enrolled' line)", async () => {
+    test("enrolled → warning suppressed (no public-/login warning line)", async () => {
       const env = makeEnv();
       try {
         const uuid = "dddddddd-0000-0000-0000-000000000004";
@@ -589,9 +1019,12 @@ describe("exposeCloudflareUp", () => {
           log: (l) => logs.push(l),
           manifestPath: env.manifestPath,
           statePath: env.statePath,
+          exposeStatePath: env.exposeStatePath,
           configPath: env.configPath,
           logPath: env.logPath,
           cloudflaredHome: env.cloudflaredHome,
+          configDir: env.configDir,
+          skipHub: true,
           vaultAuthStatus: {
             hasOwnerPassword: true,
             hasTotp: true,
@@ -602,11 +1035,76 @@ describe("exposeCloudflareUp", () => {
 
         expect(code).toBe(0);
         const joined = logs.join("\n");
-        expect(joined).not.toContain("2FA is not enrolled");
-        // The existing `printAuthGuidance` 2FA-recommend bullet is unrelated
-        // to the new contextual warning and stays in place — assert it on a
-        // shape that doesn't collide with the warning text.
-        expect(joined).toContain("(recommended) TOTP + backup codes");
+        expect(joined).not.toContain("/login is now reachable on the public internet");
+        // The contextual 2FA warning is suppressed (2FA already enrolled); the
+        // always-shown owner-password guidance from `printAuthGuidance` still
+        // appears, and it now (hub#473) also surfaces the real `2fa enroll`
+        // path in the humans section.
+        expect(joined).toContain("parachute auth set-password");
+        expect(joined).toContain("parachute auth 2fa enroll");
+      } finally {
+        env.cleanup();
+      }
+    });
+  });
+
+  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,
+          exposeStatePath: env.exposeStatePath,
+          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();
       }
@@ -621,6 +1119,7 @@ describe("exposeCloudflareOff", () => {
       const logs: string[] = [];
       const code = await exposeCloudflareOff({
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         log: (l) => logs.push(l),
       });
       expect(code).toBe(0);
@@ -630,7 +1129,7 @@ describe("exposeCloudflareOff", () => {
     }
   });
 
-  test("SIGTERMs the process and clears state", async () => {
+  test("SIGTERMs the process and clears state (incl. expose-state.json — Fix 1)", async () => {
     const env = makeEnv();
     try {
       writeCloudflaredState(
@@ -649,10 +1148,36 @@ describe("exposeCloudflareOff", () => {
         },
         env.statePath,
       );
+      // Seed the shared expose-state.json the up-path would have written, so we
+      // can assert teardown clears it (downstream consumers stop resolving the
+      // now-dead public URL).
+      writeFileSync(
+        env.exposeStatePath,
+        `${JSON.stringify({
+          version: 1,
+          layer: "public",
+          mode: "subdomain",
+          canonicalFqdn: "vault.example.com",
+          port: TEST_HUB_PORT,
+          funnel: false,
+          entries: [
+            {
+              kind: "proxy",
+              mount: "/",
+              target: `http://localhost:${TEST_HUB_PORT}`,
+              service: "hub",
+            },
+          ],
+          hubOrigin: "https://vault.example.com",
+        })}\n`,
+      );
+      expect(readExposeState(env.exposeStatePath)).toBeDefined();
+
       const killed: number[] = [];
       const logs: string[] = [];
       const code = await exposeCloudflareOff({
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         alive: () => true,
         kill: (pid) => killed.push(pid),
         log: (l) => logs.push(l),
@@ -660,6 +1185,9 @@ describe("exposeCloudflareOff", () => {
       expect(code).toBe(0);
       expect(killed).toEqual([55555]);
       expect(existsSync(env.statePath)).toBe(false);
+      // Fix 1: the shared expose-state.json is cleared on the last tunnel down.
+      expect(existsSync(env.exposeStatePath)).toBe(false);
+      expect(readExposeState(env.exposeStatePath)).toBeUndefined();
       // Reassures the user that the tunnel definition isn't lost.
       expect(logs.join("\n")).toContain("remains defined in Cloudflare");
     } finally {
@@ -689,6 +1217,7 @@ describe("exposeCloudflareOff", () => {
       const killed: number[] = [];
       const code = await exposeCloudflareOff({
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         alive: () => false,
         kill: (pid) => killed.push(pid),
         log: () => {},
@@ -701,6 +1230,46 @@ describe("exposeCloudflareOff", () => {
     }
   });
 
+  test("hub#487: off sweeps orphan connectors the state record didn't track", async () => {
+    const env = makeEnv();
+    try {
+      const uuid = "abababab-0000-0000-0000-000000000009";
+      writeCloudflaredState(
+        {
+          version: 2,
+          tunnels: {
+            parachute: {
+              pid: 55555,
+              tunnelUuid: uuid,
+              tunnelName: "parachute",
+              hostname: "vault.example.com",
+              startedAt: "2026-04-22T12:00:00.000Z",
+              configPath: env.configPath,
+            },
+          },
+        },
+        env.statePath,
+      );
+      const killed: number[] = [];
+      const code = await exposeCloudflareOff({
+        statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
+        alive: () => true,
+        kill: (pid) => killed.push(pid),
+        // pgrep finds the tracked pid (skipped — already signalled) plus an
+        // untracked orphan 66666 serving the same tunnel.
+        connectorPids: () => [55555, 66666],
+        log: () => {},
+      });
+      expect(code).toBe(0);
+      // Tracked pid stopped once, orphan also stopped — no double-kill of 55555.
+      expect(killed.sort()).toEqual([55555, 66666]);
+      expect(existsSync(env.statePath)).toBe(false);
+    } finally {
+      env.cleanup();
+    }
+  });
+
   test("targets the named tunnel and leaves siblings intact", async () => {
     const env = makeEnv();
     try {
@@ -728,6 +1297,7 @@ describe("exposeCloudflareOff", () => {
       const killed: number[] = [];
       const code = await exposeCloudflareOff({
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         alive: () => true,
         kill: (pid) => killed.push(pid),
         log: () => {},
@@ -762,6 +1332,7 @@ describe("exposeCloudflareOff", () => {
       const logs: string[] = [];
       const code = await exposeCloudflareOff({
         statePath: env.statePath,
+        exposeStatePath: env.exposeStatePath,
         alive: () => true,
         kill: () => {},
         log: (l) => logs.push(l),