@openparachute/hub 0.6.3 → 0.6.4-rc.10

package/src/commands/init.ts

@@ -35,12 +35,18 @@
 import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import pkg from "../../package.json" with { type: "json" };
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { type ExposeState, readExposeState } from "../expose-state.ts";
 import { type EnsureHubOpts, HUB_DEFAULT_PORT, HUB_SVC, readHubPort } from "../hub-control.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { deriveHubOrigin } from "../hub-origin.ts";
-import { ensureHubUnit, installAndStartHubUnit } from "../hub-unit.ts";
+import {
+  type EnsureHubVersionMatchesResult,
+  ensureHubUnit,
+  ensureHubVersionMatches,
+  installAndStartHubUnit,
+} from "../hub-unit.ts";
 import { issueOperatorToken, readOperatorTokenFile } from "../operator-token.ts";
 import { type AliveFn, defaultAlive, processState } from "../process-state.ts";
 import { findService, readManifestLenient } from "../services-manifest.ts";
@@ -81,6 +87,18 @@ export interface InitOpts {
    * Design §3.3 (init row), §4.1/§4.2, appendix (c).
    */
   ensureHub?: (opts: EnsureHubOpts) => Promise<{ pid: number; port: number; started: boolean }>;
+  /**
+   * Test seam: version-check-and-restart at the hub adoption point (#590).
+   * After init confirms a hub is answering on the canonical port, it compares
+   * the RUNNING hub's `/health` version against this installed package version;
+   * on mismatch it restarts the managed unit (once) so a freshly-installed hub
+   * never adopts a stale zombie. Production wires `ensureHubVersionMatches`;
+   * tests stub it to assert the call without touching launchctl / the live hub.
+   */
+  ensureHubVersion?: (ctx: {
+    port: number;
+    log: (line: string) => void;
+  }) => Promise<EnsureHubVersionMatchesResult>;
   /**
    * Test seam: guarantee an operator token exists once the hub is up (design
    * §3.1 / §3.3). Production reads `operator.token`; if absent AND a hub user
@@ -162,6 +180,17 @@ export interface InitOpts {
    * already known so there's no question to ask).
    */
   noWizardPrompt?: boolean;
+  /**
+   * Test seam: probe the running hub for its first-claim bootstrap token
+   * (hub#576). Production hits `GET http://127.0.0.1:<port>/admin/setup` with
+   * `accept: application/json` and reads `bootstrapToken` (the hub returns it
+   * only to loopback callers). Returns the token string when the hub is in
+   * wizard mode (no admin yet), or `undefined` when there's no token to surface
+   * (admin already exists, or the probe failed). Init uses it to print the
+   * token next to the admin URL when the hub is publicly exposed, so a browser
+   * operator can claim the box without digging through the hub logs.
+   */
+  fetchBootstrapTokenImpl?: (loopbackUrl: string) => Promise<string | undefined>;
 }
 
 /**
@@ -461,6 +490,41 @@ async function defaultRunCliWizard(opts: {
   return await runCliWizard(opts);
 }
 
+/**
+ * Default impl for the bootstrap-token probe (hub#576). GETs the loopback hub's
+ * `/admin/setup` with `accept: application/json` and returns the `bootstrapToken`
+ * the hub hands to loopback callers. Returns `undefined` on any failure (hub
+ * not answering, no token because an admin already exists, malformed body) —
+ * surfacing the token is a convenience, never a hard dependency of init.
+ */
+async function defaultFetchBootstrapToken(loopbackUrl: string): Promise<string | undefined> {
+  // Debug breadcrumb (gated on PARACHUTE_DEBUG so it never clutters the normal
+  // operator output). When the token doesn't print in the field, this tells a
+  // troubleshooter WHY — hub didn't answer, returned non-200, or the body
+  // carried no token (already-claimed / no-gate) — instead of a silent nothing.
+  const debug = (msg: string): void => {
+    if (process.env.PARACHUTE_DEBUG) console.error(`[init][bootstrap-token] ${msg}`);
+  };
+  try {
+    const res = await fetch(`${loopbackUrl.replace(/\/+$/, "")}/admin/setup`, {
+      headers: { accept: "application/json" },
+    });
+    if (!res.ok) {
+      debug(`probe returned ${res.status}; not printing a token`);
+      return undefined;
+    }
+    const body = (await res.json()) as { bootstrapToken?: unknown };
+    if (typeof body.bootstrapToken === "string" && body.bootstrapToken.length > 0) {
+      return body.bootstrapToken;
+    }
+    debug("probe ok but no bootstrapToken in body (already-claimed or no gate active)");
+    return undefined;
+  } catch (err) {
+    debug(`probe failed: ${err instanceof Error ? err.message : String(err)}`);
+    return undefined;
+  }
+}
+
 /**
  * Prompt for the wizard-choice question (hub#168 Cut 4). Returns the
  * picked option, or `undefined` if the operator quit. Default is
@@ -536,6 +600,18 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   // spawn). The `ensureHub` seam is preserved for tests (and the return shape is
   // unchanged); only the production default flipped.
   const ensureHub = opts.ensureHub ?? defaultEnsureHubViaUnit;
+  // #590: after the hub is confirmed up, compare its RUNNING version to the
+  // installed package version and restart the managed unit on mismatch, so a
+  // freshly-installed hub never adopts a stale zombie that merely answers
+  // /health. Injectable for tests.
+  const ensureHubVersion =
+    opts.ensureHubVersion ??
+    ((ctx) =>
+      ensureHubVersionMatches({
+        installedVersion: pkg.version,
+        port: ctx.port,
+        log: ctx.log,
+      }));
   const guaranteeOperatorToken = opts.guaranteeOperatorToken ?? defaultGuaranteeOperatorToken;
   const readExposeStateFn = opts.readExposeStateFn ?? (() => readExposeState());
   const isTty = opts.isTty ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -547,6 +623,7 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   const exposeCloudflareImpl = opts.exposeCloudflareImpl ?? defaultExposeCloudflare;
   const installVaultModuleImpl = opts.installVaultModuleImpl ?? defaultInstallVaultModule;
   const runCliWizardImpl = opts.runCliWizardImpl ?? defaultRunCliWizard;
+  const fetchBootstrapTokenImpl = opts.fetchBootstrapTokenImpl ?? defaultFetchBootstrapToken;
 
   log("Parachute init — getting your hub set up.");
   log("");
@@ -593,6 +670,38 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   // overridden, so the fallback is almost always correct.
   if (hubPort === undefined) hubPort = HUB_DEFAULT_PORT;
 
+  // Step 1.25 (#590): the hub answered /health, but is it the version we just
+  // installed? A zombie LaunchAgent survives `rm -rf ~/.parachute`, so a brand-
+  // new install can adopt month-old code that merely keeps the port. Compare the
+  // RUNNING version to the installed package version; on mismatch, restart the
+  // managed unit (once) so the tunnel/wizard/vault-install downstream bind to the
+  // NEW code. A non-unit-managed hub (legacy detached pid / dev `bun run serve`)
+  // is NOT killed — we surface the mismatch + an actionable message and bail so
+  // the operator decides. A still-mismatched-after-restart (bun-linked branch)
+  // warns + continues rather than looping.
+  try {
+    const versionResult = await ensureHubVersion({ port: hubPort, log });
+    for (const m of versionResult.messages) log(m);
+    if (versionResult.outcome === "not-unit-managed") {
+      // We can't safely take over a hub we don't own. Stop here so init doesn't
+      // wire a fresh tunnel + credentials to a stale runtime (the #590 field bug).
+      log("");
+      log("Resolve the version mismatch above, then re-run `parachute init`.");
+      return 1;
+    }
+    if (versionResult.outcome === "restart-failed") {
+      log("");
+      log("The hub service manager rejected the restart command.");
+      log("Try checking the logs:");
+      log("  parachute logs hub");
+      return 1;
+    }
+    // `match` / `not-running` / `restarted` / `still-mismatched` → continue.
+  } catch (err) {
+    // A version-check failure must never block init — degrade to a note.
+    log(`note: hub version check skipped (${err instanceof Error ? err.message : String(err)})`);
+  }
+
   // Step 1.5: guarantee an operator token exists (design §3.1 / §3.3). Under
   // the unified model every per-module verb is an authenticated module-ops
   // call, so the steady-state operator needs an `operator.token` on disk — the
@@ -619,7 +728,12 @@ export async function init(opts: InitOpts = {}): Promise<number> {
       exposeTailnetImpl,
       exposeCloudflareImpl,
     });
-    if (code !== 0) return code;
+    // hub#565: exposure is an ENHANCEMENT, not a prerequisite. A failed
+    // expose chain must NOT abort init — warn + print the exact retry
+    // command, then fall through to vault install + the admin-URL/wizard
+    // handoff on the loopback URL. Init's contract is hub up → vault module
+    // installed → admin URL → wizard, ALWAYS.
+    if (code !== 0) warnExposeFailedContinue(opts.exposeChoice, log);
     // Refresh state — the chain may have brought up an FQDN.
     exposeState = readExposeStateFn();
   } else if (opts.noExposePrompt) {
@@ -642,7 +756,9 @@ export async function init(opts: InitOpts = {}): Promise<number> {
         exposeTailnetImpl,
         exposeCloudflareImpl,
       });
-      if (code !== 0) return code;
+      // hub#565: warn + continue on a failed expose chain rather than
+      // aborting init (same contract as the non-interactive branch above).
+      if (code !== 0) warnExposeFailedContinue(picked, log);
       exposeState = readExposeStateFn();
     }
   }
@@ -704,6 +820,19 @@ export async function init(opts: InitOpts = {}): Promise<number> {
     return 1;
   }
 
+  // hub#576: when the hub is publicly exposed AND still in wizard mode (no
+  // admin yet), the admin URL above is a public FQDN — whoever opens it first
+  // claims the box. Surface the first-claim bootstrap token in the operator's
+  // OWN terminal so the wizard's account step demands proof of box access. We
+  // only probe + print on the public-FQDN path: a loopback-only install needs
+  // no token (reaching 127.0.0.1 already proves access), and the CLI-wizard
+  // path picks the token up transparently over loopback (above). The probe is
+  // best-effort — a failure (or an already-claimed hub) just prints nothing.
+  let bootstrapToken: string | undefined;
+  if (exposeState?.canonicalFqdn) {
+    bootstrapToken = await fetchBootstrapTokenImpl(`http://127.0.0.1:${hubPort}`);
+  }
+
   log("");
   if (hasVault) {
     log("Looks good — your hub is up and a vault is configured.");
@@ -713,6 +842,24 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   log("");
   log(`  ${adminUrl}`);
   log("");
+  if (bootstrapToken) {
+    log("Because this hub is reachable on the public internet, the wizard asks for a");
+    log("one-time bootstrap token before it lets anyone create the admin account —");
+    log("so whoever opens the URL first can't claim your hub. Paste this when asked:");
+    log("");
+    log(`  ${bootstrapToken}`);
+    log("");
+    log("(Valid until the admin is created or the hub restarts. Re-run `parachute init`");
+    log(" to mint a fresh one.)");
+    log("");
+  }
+  // hub#565: when we're on the loopback URL (no public exposure active),
+  // remind the operator they can expose later. Skipped once an FQDN is up.
+  if (!exposeState?.canonicalFqdn) {
+    log("(Reachable on this machine. To expose it publicly later, run");
+    log(" `parachute expose public --cloudflare` or `parachute expose public --tailnet`.)");
+    log("");
+  }
 
   // Step 4.5: offer the operator the CLI wizard vs. the browser wizard
   // (hub#168 Cut 4). Aaron's 2026-05-28 directive: "we should be able to
@@ -742,7 +889,13 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   if (choice === "cli") {
     log("");
     log("Launching the CLI wizard. (You can also visit the URL above in a browser any time.)");
-    return await runCliWizardImpl({ hubUrl: adminUrl.replace(/\/admin\/?$/, ""), log });
+    // hub#576: drive the CLI wizard against the LOOPBACK hub, not the public
+    // FQDN in `adminUrl`. The wizard runs on this box, so loopback is both
+    // correct and what lets the hub hand it the bootstrap token transparently
+    // (the loopback-gated GET /admin/setup probe) — the operator never has to
+    // copy the token out of the startup logs.
+    const cliWizardUrl = `http://127.0.0.1:${hubPort}`;
+    return await runCliWizardImpl({ hubUrl: cliWizardUrl, log });
   }
 
   // Step 5: offer to open the browser. Skip in non-TTY shells (CI),
@@ -784,6 +937,32 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   return 0;
 }
 
+/** The exact retry command for a given exposure choice (hub#565 / #566). */
+export function exposeRetryCommand(choice: ExposeChoice): string {
+  if (choice === "tailnet") return "parachute expose public --tailnet";
+  // `none` never reaches here in practice — `runExposureChoice("none")` always
+  // returns 0, so `warnExposeFailedContinue` (the only caller) is never invoked
+  // for it. It falls through to the `--cloudflare` branch below; harmless, and
+  // spelled out so the fallthrough isn't read as a bug.
+  // Cloudflare (and the unreachable `none`): default the bare command to
+  // `--cloudflare` so the operator who picked Cloudflare lands in the right
+  // provider on retry (bare `parachute expose public` defaults to Tailscale
+  // Funnel — hub#566).
+  return "parachute expose public --cloudflare";
+}
+
+/**
+ * hub#565: warn that the exposure chain failed but init is continuing anyway,
+ * and print the exact retry command. Exposure is an enhancement, not a
+ * prerequisite — init still installs the vault module and hands off to the
+ * wizard on the loopback URL.
+ */
+function warnExposeFailedContinue(choice: ExposeChoice, log: (line: string) => void): void {
+  log("");
+  log("⚠ Couldn't finish setting up public access — continuing without it.");
+  log(`  To expose publicly later, run: ${exposeRetryCommand(choice)}`);
+}
+
 /**
  * Dispatch the chosen exposure path. Returns the exit code of the
  * downstream chain. `none` is a no-op (success).