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

package/src/commands/expose-cloudflare.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { mkdirSync, openSync } from "node:fs";
 import { dirname } from "node:path";
 import { DEFAULT_TUNNEL_NAME, cloudflaredPathsFor, writeConfig } from "../cloudflare/config.ts";
@@ -26,12 +27,28 @@ import {
   findTunnelByName,
   routeDns,
 } from "../cloudflare/tunnel.ts";
-import { SERVICES_MANIFEST_PATH } from "../config.ts";
-import { type AliveFn, defaultAlive } from "../process-state.ts";
+import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
+import {
+  EXPOSE_STATE_PATH,
+  type ExposeState,
+  clearExposeState,
+  writeExposeState,
+} from "../expose-state.ts";
+import {
+  type EnsureHubOpts,
+  HUB_DEFAULT_PORT,
+  ensureHubRunning,
+  readHubPort,
+} from "../hub-control.ts";
+import { deriveHubOrigin } from "../hub-origin.ts";
+import { type AliveFn, defaultAlive, processState } from "../process-state.ts";
 import { readManifest } from "../services-manifest.ts";
 import { type Runner, defaultRunner } from "../tailscale/run.ts";
+import { persistVaultHubOrigin } from "../vault-hub-origin-env.ts";
 import type { VaultAuthStatus } from "../vault/auth-status.ts";
+import { WELL_KNOWN_DIR } from "../well-known.ts";
 import { printPublic2FAWarning } from "./expose-2fa-warning.ts";
+import { restart } from "./lifecycle.ts";
 
 const AUTH_DOC_URL =
   "https://github.com/ParachuteComputer/parachute-vault/blob/main/docs/auth-model.md";
@@ -86,14 +103,171 @@ const defaultKill: KillFn = (pid, signal) => {
   process.kill(pid, signal);
 };
 
+/**
+ * Find the PIDs of every running `cloudflared` connector serving THIS tunnel.
+ * "This tunnel" is identified by either the tunnel UUID or the config.yml path
+ * appearing on the process command line — both are unique to Parachute's
+ * connector for this tunnel, so we never touch an unrelated cloudflared the
+ * operator may be running for a different tunnel.
+ *
+ * The motivating bug (hub#487): each `parachute expose public --cloudflare`
+ * "reused the tunnel" but spawned a fresh connector (new pid) without killing
+ * the prior ones, and the state file only tracked the most-recent pid. Orphan
+ * connectors accumulated — multiple `cloudflared tunnel run` processes all
+ * serving stale `config.yml` snapshots, so edge routing became nondeterministic
+ * ("silent fails"). Sweeping by UUID/config-path catches the orphans that the
+ * single-pid state record misses (prior runs that crashed mid-rewrite, or a
+ * connector the operator started by hand for this tunnel).
+ *
+ * Injectable so tests assert the sweep without a live `pgrep`.
+ */
+export type ConnectorPidsFn = (tunnelUuid: string, configPath: string) => number[];
+
+export const defaultConnectorPids: ConnectorPidsFn = (tunnelUuid, configPath) => {
+  try {
+    // `pgrep -fl cloudflared` lists "<pid> <full command line>" for every
+    // process whose command line matches "cloudflared". We then filter to the
+    // ones that name THIS tunnel (uuid or config path) so the kill is surgical.
+    // macOS + Linux ship pgrep; Windows is out of scope (mirrors hub#287's lsof
+    // assumption). Any failure → [] (caller falls back to state-tracked pid).
+    const result = spawnSync("pgrep", ["-fl", "cloudflared"], {
+      encoding: "utf8",
+      timeout: 2000,
+    });
+    if (result.status !== 0 || typeof result.stdout !== "string") return [];
+    const selfPid = process.pid;
+    const pids: number[] = [];
+    for (const line of result.stdout.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) continue;
+      const match = trimmed.match(/^(\d+)\s+(.*)$/);
+      if (!match) continue;
+      const pid = Number.parseInt(match[1]!, 10);
+      const cmdline = match[2]!;
+      if (!Number.isInteger(pid) || pid <= 0 || pid === selfPid) continue;
+      // Surgical match: only connectors that name this tunnel's UUID or its
+      // config path. A bare `cloudflared` (e.g. `--version`, `tunnel list`)
+      // or a connector for a *different* tunnel won't match either token.
+      if (cmdline.includes(tunnelUuid) || cmdline.includes(configPath)) {
+        pids.push(pid);
+      }
+    }
+    return pids;
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Resolve a hostname to its A/AAAA addresses. Returns [] when the name doesn't
+ * resolve (NXDOMAIN, SERVFAIL, no records yet) — the signal the DNS
+ * self-diagnosis keys on. Injectable so tests drive each case (unresolved /
+ * Cloudflare / non-Cloudflare) deterministically.
+ */
+export type ResolveHostFn = (hostname: string) => Promise<string[]>;
+
+export const defaultResolveHost: ResolveHostFn = async (hostname) => {
+  try {
+    // Bun.dns ships with the runtime; `node:dns/promises` is equally fine but
+    // Bun.dns.lookup returns both families in one call. `all: true` gives every
+    // record so a partially-propagated name still surfaces an address.
+    const records = await Bun.dns.lookup(hostname, { family: 0 });
+    return records.map((r) => r.address).filter((a) => typeof a === "string" && a.length > 0);
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Cloudflare's published anycast IPv4 ranges (the proxy edge). A proxied
+ * (orange-cloud) record — which is what `cloudflared tunnel route dns` creates
+ * — resolves to one of these. If the hostname resolves to something *outside*
+ * these ranges, it's almost certainly shadowed: a Pages project, an A record,
+ * or a grey-cloud CNAME pointing elsewhere. We keep the list to the v4 ranges
+ * (the common case) and treat any IPv6 in Cloudflare's 2606:4700::/32 block as
+ * Cloudflare too. Source: https://www.cloudflare.com/ips/ (stable for years).
+ */
+const CLOUDFLARE_V4_RANGES: ReadonlyArray<readonly [string, number]> = [
+  ["173.245.48.0", 20],
+  ["103.21.244.0", 22],
+  ["103.22.200.0", 22],
+  ["103.31.4.0", 22],
+  ["141.101.64.0", 18],
+  ["108.162.192.0", 18],
+  ["190.93.240.0", 20],
+  ["188.114.96.0", 20],
+  ["197.234.240.0", 22],
+  ["198.41.128.0", 17],
+  ["162.158.0.0", 15],
+  ["104.16.0.0", 13],
+  ["104.24.0.0", 14],
+  ["172.64.0.0", 13],
+  ["131.0.72.0", 22],
+];
+
+function ipv4ToInt(ip: string): number | undefined {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return undefined;
+  let n = 0;
+  for (const part of parts) {
+    const octet = Number.parseInt(part, 10);
+    if (!Number.isInteger(octet) || octet < 0 || octet > 255) return undefined;
+    n = n * 256 + octet;
+  }
+  return n >>> 0;
+}
+
+/** True if any resolved address belongs to Cloudflare's edge. */
+export function looksLikeCloudflare(addresses: readonly string[]): boolean {
+  for (const addr of addresses) {
+    // IPv6: Cloudflare's edge lives in 2606:4700::/32.
+    if (addr.includes(":")) {
+      if (addr.toLowerCase().startsWith("2606:4700")) return true;
+      continue;
+    }
+    const ipInt = ipv4ToInt(addr);
+    if (ipInt === undefined) continue;
+    for (const [base, bits] of CLOUDFLARE_V4_RANGES) {
+      const baseInt = ipv4ToInt(base);
+      if (baseInt === undefined) continue;
+      const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0;
+      if ((ipInt & mask) === (baseInt & mask)) return true;
+    }
+  }
+  return false;
+}
+
 export interface ExposeCloudflareOpts {
   runner?: Runner;
   spawner?: CloudflaredSpawner;
   alive?: AliveFn;
   kill?: KillFn;
+  /**
+   * Find every running cloudflared connector PID serving this tunnel (by UUID
+   * or config-path match). Used to sweep orphan connectors before spawning a
+   * fresh one (hub#487). Tests inject a stub; production uses
+   * `defaultConnectorPids` (a filtered `pgrep -fl cloudflared`).
+   */
+  connectorPids?: ConnectorPidsFn;
+  /**
+   * Resolve a hostname to its addresses, for the post-route DNS self-diagnosis
+   * (hub#487). Returns the resolved IPs (empty when NXDOMAIN / not yet live).
+   * Best-effort and non-fatal — a failure to resolve never blocks the expose.
+   * Tests inject a stub; production uses `defaultResolveHost` (Bun DNS).
+   */
+  resolveHost?: ResolveHostFn;
   log?: (line: string) => void;
   manifestPath?: string;
   statePath?: string;
+  /**
+   * Path to `expose-state.json` — the shared cross-provider expose record the
+   * Tailscale path also writes (`expose.ts`). Distinct from `statePath`
+   * (cloudflared-state.json, the per-tunnel process record). The cloudflare
+   * up-path writes this so downstream consumers (`resolveAdminUrl` in init,
+   * `resolveHubOrigin` in lifecycle / auth) see the public URL instead of
+   * loopback; the off-path clears it. Defaults to `EXPOSE_STATE_PATH`.
+   */
+  exposeStatePath?: string;
   /**
    * Tunnel name targeted by this invocation. Defaults to `parachute` —
    * the canonical single-tunnel name. Override to run multiple tunnels on
@@ -112,6 +286,37 @@ export interface ExposeCloudflareOpts {
   logPath?: string;
   /** Override `~/.cloudflared` for tests and `$HOME`-free environments. */
   cloudflaredHome?: string;
+  /**
+   * Config root for hub PID / port / log files. Defaults to `~/.parachute`.
+   * Threaded into `ensureHubRunning` so cloudflared's ingress target stays
+   * in sync with where the hub actually bound.
+   */
+  configDir?: string;
+  /**
+   * Override the public hub origin (the `iss` claim baked into the OAuth
+   * issuer). Mirrors the Tailscale path — when set, this URL is what the
+   * hub advertises rather than the cloudflared hostname.
+   */
+  hubOrigin?: string;
+  /**
+   * Overrides for hub lifecycle — primarily for tests. Tests pass
+   * `skipHubLifecycle: true` (above) plus a seeded `hub.port` file so the
+   * cloudflare path can resolve a port without actually spawning a hub.
+   */
+  hubEnsureOpts?: Omit<EnsureHubOpts, "configDir" | "wellKnownDir" | "log">;
+  /**
+   * Directory holding hub.html (passed through to the hub server on first
+   * spawn). Defaults to the same `well-known/` resolution the Tailscale
+   * path uses.
+   */
+  wellKnownDir?: string;
+  /**
+   * Skip spawning the hub server. Tests flip this on and pre-seed
+   * `<configDir>/hub/run/hub.port` so `readHubPort` can resolve the
+   * cloudflared target without a live process. Production always leaves
+   * this off so the bringup self-heals a missing hub.
+   */
+  skipHub?: boolean;
   now?: () => Date;
   /**
    * Override `~/.parachute/vault` for the 2FA-enrollment probe. Tests
@@ -125,6 +330,14 @@ export interface ExposeCloudflareOpts {
    * `<vaultHome>/config.yaml` from disk. (#186)
    */
   vaultAuthStatus?: VaultAuthStatus;
+  /**
+   * Restart a hub-dependent service so it re-reads the new public hub origin.
+   * Mirrors the Tailscale path's `restartService` seam (`expose.ts`). Defaults
+   * to lifecycle `restart`; tests inject a fake to assert the call without
+   * spawning a real daemon. Only invoked for vault (the only `iss`-validating
+   * service) and only when it's already running.
+   */
+  restartService?: (short: string) => Promise<number>;
 }
 
 interface Resolved {
@@ -132,36 +345,75 @@ interface Resolved {
   spawner: CloudflaredSpawner;
   alive: AliveFn;
   kill: KillFn;
+  connectorPids: ConnectorPidsFn;
+  resolveHost: ResolveHostFn;
   log: (line: string) => void;
   manifestPath: string;
   statePath: string;
+  exposeStatePath: string;
   tunnelName: string;
   configPath: string;
   logPath: string;
   cloudflaredHome: string;
+  configDir: string;
+  hubOrigin: string | undefined;
+  hubEnsureOpts: Omit<EnsureHubOpts, "configDir" | "wellKnownDir" | "log">;
+  wellKnownDir: string;
+  skipHub: boolean;
   now: () => Date;
   vaultHome: string | undefined;
   vaultAuthStatus: VaultAuthStatus | undefined;
+  restartService: (short: string) => Promise<number>;
 }
 
 function resolve(opts: ExposeCloudflareOpts): Resolved {
   const tunnelName = opts.tunnelName ?? DEFAULT_TUNNEL_NAME;
-  const paths = cloudflaredPathsFor(tunnelName);
+  const configDir = opts.configDir ?? CONFIG_DIR;
+  // Derive per-tunnel config/log paths from the *resolved* configDir, not the
+  // real `CONFIG_DIR`. When a test threads a tmp `configDir` but omits explicit
+  // `configPath`/`logPath`, this keeps the derived files inside the tmp dir
+  // instead of writing fixtures into the operator's real ~/.parachute.
+  const paths = cloudflaredPathsFor(tunnelName, configDir);
   return {
     runner: opts.runner ?? defaultRunner,
     spawner: opts.spawner ?? defaultCloudflaredSpawner,
     alive: opts.alive ?? defaultAlive,
     kill: opts.kill ?? defaultKill,
+    // Defaulting policy mirrors lifecycle's startReadyMs (hub#487): the real
+    // implementations shell out (`pgrep`) / hit the network (DNS). When a test
+    // injects a fake `spawner` but no explicit seam, fall back to inert stubs
+    // (no orphans found; "resolves at Cloudflare" → no DNS warning) so suites
+    // stay deterministic and offline. Production (no spawner override) always
+    // gets the real `pgrep` sweep + DNS diagnosis.
+    connectorPids:
+      opts.connectorPids ?? (opts.spawner === undefined ? defaultConnectorPids : () => []),
+    resolveHost:
+      opts.resolveHost ??
+      (opts.spawner === undefined ? defaultResolveHost : async () => ["104.16.0.1"]),
     log: opts.log ?? ((line) => console.log(line)),
     manifestPath: opts.manifestPath ?? SERVICES_MANIFEST_PATH,
     statePath: opts.statePath ?? CLOUDFLARED_STATE_PATH,
+    exposeStatePath: opts.exposeStatePath ?? EXPOSE_STATE_PATH,
     tunnelName,
     configPath: opts.configPath ?? paths.configPath,
     logPath: opts.logPath ?? paths.logPath,
     cloudflaredHome: opts.cloudflaredHome ?? DEFAULT_CLOUDFLARED_HOME,
+    configDir,
+    hubOrigin: opts.hubOrigin,
+    hubEnsureOpts: opts.hubEnsureOpts ?? {},
+    wellKnownDir: opts.wellKnownDir ?? WELL_KNOWN_DIR,
+    skipHub: opts.skipHub ?? false,
     now: opts.now ?? (() => new Date()),
     vaultHome: opts.vaultHome,
     vaultAuthStatus: opts.vaultAuthStatus,
+    restartService:
+      opts.restartService ??
+      ((short: string) =>
+        restart(short, {
+          manifestPath: opts.manifestPath,
+          configDir,
+          log: opts.log ?? (() => {}),
+        })),
   };
 }
 
@@ -174,19 +426,65 @@ function printAuthGuidance(log: (line: string) => void, vaultUrl: string): void
   log("Pick the path that matches how you'll reach it:");
   log("");
   log("  Humans (claude.ai / ChatGPT connectors, browser):");
-  log("    parachute auth set-password         # set an owner password");
-  log("    parachute auth 2fa enroll           # (recommended) TOTP + backup codes");
+  log("    parachute auth set-password         # set a STRONG owner password");
+  log("    parachute auth 2fa enroll           # add a second factor (recommended)");
+  log("    #  (or set 2FA up in the browser at /account/2fa for a scannable QR)");
   log("    then point your connector at:");
   log(`    ${vaultUrl}`);
   log("");
-  log("  Scripts / machines:");
-  log("    parachute vault tokens create       # creates a pvt_… bearer token");
-  log("    Authorization: Bearer pvt_…         # attach to every request");
+  log("  Scripts / machines (hub-issued JWT — set the owner password first):");
+  log("    parachute auth mint-token --scope vault:<name>:read   # or :write");
+  log("    Authorization: Bearer <hub-jwt>     # attach the printed token to every request");
+  log("    (or: Admin → Vaults → Connect mints one and shows the header for you)");
   log("");
-  log("Neither is a prerequisite for the other. Full auth reference:");
+  log("The owner password gates both paths — browser sign-in and minting tokens.");
+  log("Full auth reference:");
   log(`  ${AUTH_DOC_URL}`);
 }
 
+/**
+ * Best-effort registrable-zone guess: the last two labels of the hostname
+ * (`vault.example.com` → `example.com`, `gitcoin.parachute.computer` →
+ * `parachute.computer`). This is a heuristic — multi-label public suffixes
+ * (`foo.co.uk`) would guess `co.uk` — but it's only used to phrase the
+ * `dig +short <zone> NS` remedy, where being off by a label is a harmless
+ * nudge. We don't ship a full public-suffix list for one warning string.
+ */
+function guessZone(hostname: string): string {
+  const labels = hostname.split(".").filter((l) => l.length > 0);
+  if (labels.length <= 2) return hostname;
+  return labels.slice(-2).join(".");
+}
+
+/**
+ * Non-fatal post-route DNS diagnosis. Resolves `hostname` and warns when the
+ * result looks wrong — see the call site for the two symptoms this addresses.
+ * Never throws (resolveHost swallows its own errors) and never changes the
+ * exit code; the worst case is no output.
+ */
+async function diagnoseDns(hostname: string, r: Resolved): Promise<void> {
+  const zone = guessZone(hostname);
+  const addresses = await r.resolveHost(hostname);
+  if (addresses.length === 0) {
+    r.log("");
+    r.log(`⚠ DNS isn't live yet for ${hostname}.`);
+    r.log(`  If ${zone} is a new Cloudflare zone, its nameservers may not be switched at your`);
+    r.log("  registrar yet. Check with:");
+    r.log(`    dig +short ${zone} NS          # should list *.ns.cloudflare.com`);
+    r.log("  Propagation can take minutes to hours. The tunnel itself is up — the URLs below");
+    r.log("  will start working once DNS resolves.");
+    return;
+  }
+  if (!looksLikeCloudflare(addresses)) {
+    r.log("");
+    r.log(`⚠ ${hostname} resolves (${addresses.join(", ")}) but not to Cloudflare's edge.`);
+    r.log(`  It may be shadowed by another DNS record or a Cloudflare Pages project on ${zone}.`);
+    r.log("  Ensure it's a proxied (orange-cloud) CNAME to the tunnel — check");
+    r.log(`  https://dash.cloudflare.com → DNS for ${zone}. A grey-cloud / A record / Pages`);
+    r.log("  binding on this hostname will 404 the tunnel at the edge.");
+  }
+}
+
 export async function exposeCloudflareUp(
   hostname: string,
   opts: ExposeCloudflareOpts = {},
@@ -239,6 +537,46 @@ export async function exposeCloudflareUp(
     return 1;
   }
 
+  // Resolve the public hub origin before spawning the hub server — it gets
+  // baked into the OAuth `iss` claim via the `--issuer` flag. For Cloudflare
+  // ingress the canonical origin is the user-supplied hostname (mirrors the
+  // Tailscale Funnel path which uses the tailnet FQDN). Falling back to the
+  // request origin would put `http://127.0.0.1:<port>` in tokens, which any
+  // client following RFC 8414 would reject.
+  const canonicalOrigin = `https://${hostname}`;
+  const hubOrigin =
+    deriveHubOrigin({ override: r.hubOrigin, exposeFqdn: hostname }) ?? canonicalOrigin;
+
+  // Ensure the hub is running and figure out the loopback port cloudflared
+  // should target. The hub does all internal routing (discovery, admin,
+  // OAuth, well-known, per-vault proxy, generic /<svc>/* dispatch) — same
+  // shape the Tailscale Funnel path uses (see `planEntries` in expose.ts).
+  // Pre-2026-05-27 the cloudflared config routed straight at vault's port,
+  // so a public URL like https://gitcoin.parachute.computer/ returned 404
+  // from vault itself instead of the hub's discovery page; admin / OAuth
+  // were unreachable. Aaron hit this on a fresh EC2 install.
+  let hubPort: number;
+  if (r.skipHub) {
+    const existing = readHubPort(r.configDir);
+    if (existing === undefined) {
+      throw new Error("skipHub set but no hub.port on disk — tests must seed one");
+    }
+    hubPort = existing;
+  } else {
+    const hub = await ensureHubRunning({
+      reservedPorts: manifest.services.map((s) => s.port),
+      ...r.hubEnsureOpts,
+      configDir: r.configDir,
+      wellKnownDir: r.wellKnownDir,
+      issuer: hubOrigin,
+      log: r.log,
+    });
+    hubPort = hub.port;
+    if (hub.started) r.log(`✓ hub started (pid ${hub.pid}, port ${hub.port}).`);
+    else r.log(`✓ hub already running (pid ${hub.pid}, port ${hub.port}).`);
+  }
+  if (hubPort === 0) hubPort = HUB_DEFAULT_PORT;
+
   let tunnel: Tunnel | undefined;
   try {
     tunnel = await findTunnelByName(r.runner, r.tunnelName);
@@ -276,24 +614,59 @@ export async function exposeCloudflareUp(
   }
   r.log("✓ DNS routed.");
 
+  // Post-route DNS self-diagnosis (hub#487). `cloudflared tunnel route dns`
+  // can succeed (the CNAME is written in Cloudflare's API) while the hostname
+  // is still NOT actually serving the tunnel — two shapes Aaron hit:
+  //   (a) a "pending" zone whose nameservers aren't switched at the registrar
+  //       yet, so the record exists in Cloudflare but nothing resolves; and
+  //   (b) a subdomain shadowed by a Cloudflare Pages project on the same zone,
+  //       so the edge 404s the tunnel.
+  // Both previously printed "✓ DNS routed" + the URLs as if fine. This check
+  // is best-effort and strictly NON-FATAL — it only adds a warning; it never
+  // changes the exit code or blocks the expose. Fast: one DNS lookup with a
+  // built-in timeout in `resolveHost`.
+  await diagnoseDns(hostname, r);
+
   const credsFile = credentialsPath(tunnel.id, r.cloudflaredHome);
   writeConfig(
     {
       tunnelUuid: tunnel.id,
       credentialsFile: credsFile,
       hostname,
-      servicePort: vaultEntry.port,
+      // Route into the hub, not vault directly. The hub dispatches
+      // discovery / admin / OAuth / per-vault proxy / generic /<svc>/*
+      // — same shape Tailscale Funnel uses (single mount → hub catchall).
+      // Pre-fix this was `vaultEntry.port`, which served vault's own 404
+      // page on every request that wasn't /vault/<name>/… — admin SPA and
+      // OAuth surfaces were unreachable from the public URL.
+      servicePort: hubPort,
     },
     r.configPath,
   );
   r.log(`✓ Wrote ${r.configPath}`);
 
+  // Orphan-connector sweep (hub#487). Before spawning a fresh connector, kill
+  // EVERY cloudflared connector currently serving this tunnel so exactly one
+  // process serves the config.yml we just wrote. Pre-fix, each re-expose
+  // spawned a new connector without killing the prior ones (state tracked only
+  // the most-recent pid), so orphans accumulated and edge routing became
+  // nondeterministic. We union two sources:
+  //   - the pid recorded in cloudflared-state.json (the prior `parachute`-
+  //     spawned connector for this tunnel name), and
+  //   - any pid found by scanning running processes for this tunnel's UUID or
+  //     config path (catches orphans the state file lost track of — crashed
+  //     mid-rewrite, or started by hand for this tunnel).
   const stateBefore = readCloudflaredState(r.statePath);
   const prior = findTunnelRecord(stateBefore, r.tunnelName);
-  if (prior && r.alive(prior.pid)) {
+  const toKill = new Set<number>();
+  if (prior && r.alive(prior.pid)) toKill.add(prior.pid);
+  for (const pid of r.connectorPids(tunnel.id, r.configPath)) {
+    if (r.alive(pid)) toKill.add(pid);
+  }
+  for (const deadPid of toKill) {
     try {
-      r.kill(prior.pid, "SIGTERM");
-      r.log(`Stopped prior cloudflared (pid ${prior.pid}).`);
+      r.kill(deadPid, "SIGTERM");
+      r.log(`Stopped prior cloudflared connector (pid ${deadPid}).`);
     } catch {
       // Process is already gone — safe to ignore; we replace the record below.
     }
@@ -314,6 +687,67 @@ export async function exposeCloudflareUp(
   };
   writeCloudflaredState(withTunnelRecord(stateBefore, record), r.statePath);
 
+  // Persist the shared cross-provider expose record. Without this, the
+  // Tailscale path was the only one writing expose-state.json — so after a
+  // Cloudflare bring-up `readExposeState()` returned undefined and downstream
+  // consumers fell back to loopback:
+  //   - init's `resolveAdminUrl` printed http://127.0.0.1:1939/admin/ instead
+  //     of the public URL.
+  //   - lifecycle's `resolveHubOrigin` (and the hub#460 vault `.env`
+  //     PARACHUTE_HUB_ORIGIN persistence) kept the loopback origin, so vault's
+  //     OAuth `iss` claim didn't match the public host — the "rejected on
+  //     reconnect" P0 on Cloudflare deploys.
+  // Mode is "subdomain": cloudflared routes the whole FQDN at the hub catchall
+  // (one ingress → hub), unlike the Tailscale path's "path" routing. The single
+  // proxy entry mirrors the hub-catchall shape the Tailscale Funnel path plans.
+  const exposeState: ExposeState = {
+    version: 1,
+    layer: "public",
+    mode: "subdomain",
+    canonicalFqdn: hostname,
+    port: hubPort,
+    funnel: false,
+    entries: [
+      {
+        kind: "proxy",
+        mount: "/",
+        target: `http://localhost:${hubPort}`,
+        service: "hub",
+      },
+    ],
+    hubOrigin,
+  };
+  writeExposeState(exposeState, r.exposeStatePath);
+
+  // Persist the public hub origin into vault's `.env` and restart vault — the
+  // durable half of the OAuth issuer-mismatch fix on Cloudflare deploys.
+  //
+  // The bug (vault 401s every hub token on a Cloudflare deploy): the Tailscale
+  // path gets this for free because it auto-restarts vault, and that restart
+  // flows the freshly-written expose-state `hubOrigin` into `vault/.env` via
+  // lifecycle's `persistVaultHubOrigin`. The Cloudflare path wrote expose-state
+  // but never touched vault's `.env` or restarted it, so 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 (whose `iss`
+  // is the public origin) failed the `iss` check → 401 → "You're not signed in
+  // to the hub." We mirror the Tailscale path here exactly.
+  //
+  // `persistVaultHubOrigin` writes the durable `.env` (skips loopback itself,
+  // so a `--hub-origin http://127.0.0.1` override never bakes a dead issuer in);
+  // the restart makes the running vault re-read it immediately rather than
+  // waiting for the next reboot.
+  persistVaultHubOrigin(r.configDir, hubOrigin, r.log);
+  if (processState("vault", r.configDir, r.alive).status === "running") {
+    r.log("");
+    r.log("Restarting vault to pick up new hub origin…");
+    const rcode = await r.restartService("vault");
+    if (rcode !== 0) {
+      r.log(
+        "⚠ vault restart failed. Run manually once the issue is resolved: parachute restart vault",
+      );
+    }
+  }
+
   const baseUrl = `https://${hostname}`;
   // A well-formed vault manifest always lists at least one mount path. If
   // it's empty, something went sideways in `parachute install vault` — warn
@@ -329,9 +763,11 @@ export async function exposeCloudflareUp(
 
   r.log("");
   r.log(`✓ Cloudflare tunnel up (pid ${pid}).`);
-  r.log(`  URL:    ${baseUrl}`);
-  r.log(`  Vault:  ${vaultUrl}`);
-  r.log(`  Logs:   ${r.logPath}`);
+  r.log(`  Open:    ${baseUrl}/`);
+  r.log(`  Admin:   ${baseUrl}/admin/`);
+  r.log(`  Vault:   ${vaultUrl}`);
+  r.log(`  OAuth:   ${hubOrigin}`);
+  r.log(`  Logs:    ${r.logPath}`);
   r.log("");
   r.log("Point a claude.ai / ChatGPT connector at:");
   r.log(`  ${vaultUrl}`);
@@ -376,12 +812,31 @@ export async function exposeCloudflareOff(opts: ExposeCloudflareOpts = {}): Prom
   } else {
     r.log(`cloudflared (pid ${record.pid}) wasn't running; clearing stale state.`);
   }
+  // Sweep any orphan connectors for this tunnel that the state record didn't
+  // track (hub#487) so `off` leaves exactly zero connectors serving it. Match
+  // by UUID/config-path; skip the record pid we already signalled above.
+  for (const orphanPid of r.connectorPids(record.tunnelUuid, record.configPath)) {
+    if (orphanPid === record.pid || !r.alive(orphanPid)) continue;
+    try {
+      r.kill(orphanPid, "SIGTERM");
+      r.log(`✓ Stopped orphan cloudflared connector (pid ${orphanPid}).`);
+    } catch {
+      // Already gone between probe and kill — fine.
+    }
+  }
   const stateAfter = withoutTunnelRecord(stateBefore, r.tunnelName);
   if (stateAfter) {
     writeCloudflaredState(stateAfter, r.statePath);
   } else {
     clearCloudflaredState(r.statePath);
   }
+  // Clear the shared expose-state.json when no Cloudflare tunnels remain, so
+  // downstream consumers stop resolving the now-dead public URL (mirrors the
+  // up-path write above + the Tailscale off-path's expose-state teardown). When
+  // other tunnels survive we leave it — a later off for the last one clears it.
+  if (!stateAfter) {
+    clearExposeState(r.exposeStatePath);
+  }
   r.log(`  ${record.hostname} is no longer reachable through this machine.`);
   r.log(
     `  Tunnel "${record.tunnelName}" (${record.tunnelUuid}) remains defined in Cloudflare; re-running`,

package/src/commands/expose-interactive.ts

@@ -13,6 +13,7 @@
 import { createInterface } from "node:readline/promises";
 import {
   DEFAULT_CLOUDFLARED_HOME,
+  cloudflaredInstallHint,
   isCloudflaredInstalled,
   isCloudflaredLoggedIn,
 } from "../cloudflare/detect.ts";
@@ -273,19 +274,17 @@ async function guideCloudflareSetup(
         return false;
       }
     } else {
+      // 2026-05-27 refresh: distro-package paths (`apt-get`, `dnf`) are
+      // unreliable across versions — Aaron hit `No match for argument:
+      // cloudflared` on Amazon Linux 2023 — and the
+      // pkg.cloudflare.com / developers.cloudflare.com paths the old hint
+      // pointed at now serve HTML/404. Defer to `cloudflaredInstallHint`,
+      // which writes the canonical GitHub-release static-binary path
+      // matching the host's architecture.
       r.log("");
       r.log("Cloudflare Tunnel uses the `cloudflared` binary, which isn't installed yet.");
-      r.log("Install one way:");
-      r.log("  Debian / Ubuntu:");
-      r.log(
-        "    curl -L https://pkg.cloudflare.com/install.sh | sudo bash && sudo apt-get install -y cloudflared",
-      );
-      r.log("  RHEL / Fedora:");
-      r.log("    sudo dnf install cloudflared");
-      r.log("  Tarball / other:");
-      r.log(
-        "    https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/",
-      );
+      r.log("");
+      for (const line of cloudflaredInstallHint(r.platform).split("\n")) r.log(line);
       r.log("");
       r.log("After install, re-run: parachute expose public");
       return false;