@openparachute/hub 0.5.14-rc.16 → 0.5.14-rc.17

package/package.json

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

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

@@ -14,6 +14,7 @@ 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";
@@ -273,6 +274,121 @@ describe("exposeCloudflareUp", () => {
     }
   });
 
+  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 {

package/src/__tests__/lifecycle.test.ts

@@ -362,6 +362,51 @@ describe("parachute start", () => {
     }
   });
 
+  test("self-heals a stale-loopback vault/.env from a cloudflare expose-state on restart", async () => {
+    // Existing-broken-deploy shape: a Cloudflare deploy whose vault/.env had a
+    // loopback PARACHUTE_HUB_ORIGIN baked in (or was unset and a prior run
+    // wrote loopback). expose-state.json carries the real public origin. A
+    // plain `parachute start vault` must rewrite vault/.env to the public
+    // origin so the daemon stops 401ing hub tokens — the self-heal half of the
+    // Cloudflare 401 fix.
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      writeFileSync(
+        join(h.configDir, "expose-state.json"),
+        JSON.stringify({
+          version: 1,
+          layer: "public",
+          mode: "subdomain",
+          canonicalFqdn: "gitcoin-parachute.unforced.dev",
+          port: 1939,
+          funnel: false,
+          entries: [{ kind: "proxy", mount: "/", target: "http://localhost:1939", service: "hub" }],
+          hubOrigin: "https://gitcoin-parachute.unforced.dev",
+        }),
+      );
+      // Pre-seed vault/.env with a stale loopback value (the broken state).
+      mkdirSync(join(h.configDir, "vault"), { recursive: true });
+      writeFileSync(
+        join(h.configDir, "vault", ".env"),
+        "PARACHUTE_HUB_ORIGIN=http://127.0.0.1:1939\n",
+      );
+      const spawner = makeSpawner([4242]);
+      const code = await start("vault", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        spawner,
+        log: () => {},
+      });
+      expect(code).toBe(0);
+      expect(readEnvFileValues(join(h.configDir, "vault", ".env")).PARACHUTE_HUB_ORIGIN).toBe(
+        "https://gitcoin-parachute.unforced.dev",
+      );
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("does NOT persist a loopback origin into vault/.env (would shadow a later exposure)", async () => {
     const h = makeHarness();
     try {

package/src/__tests__/vault-hub-origin-env.test.ts

@@ -10,10 +10,14 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { readEnvFileValues } from "../env-file.ts";
+import type { ExposeState } from "../expose-state.ts";
+import { writeExposeState } from "../expose-state.ts";
 import {
   clearVaultHubOrigin,
   isLoopbackOrigin,
   persistVaultHubOrigin,
+  publicOriginFromExposeState,
+  selfHealVaultHubOrigin,
 } from "../vault-hub-origin-env.ts";
 
 let dir: string;
@@ -124,3 +128,136 @@ function mkVaultDir(): string {
   mkdirSync(join(dir, "vault"), { recursive: true });
   return vaultEnv();
 }
+
+function exposeStatePath(): string {
+  return join(dir, "expose-state.json");
+}
+
+/** Cloudflare-shaped expose state (subdomain mode, single hub-catchall entry). */
+function cloudflareState(overrides: Partial<ExposeState> = {}): ExposeState {
+  return {
+    version: 1,
+    layer: "public",
+    mode: "subdomain",
+    canonicalFqdn: "gitcoin-parachute.unforced.dev",
+    port: 1939,
+    funnel: false,
+    entries: [{ kind: "proxy", mount: "/", target: "http://localhost:1939", service: "hub" }],
+    hubOrigin: "https://gitcoin-parachute.unforced.dev",
+    ...overrides,
+  };
+}
+
+/** Tailnet-shaped expose state (path mode). */
+function tailnetState(overrides: Partial<ExposeState> = {}): ExposeState {
+  return {
+    version: 1,
+    layer: "tailnet",
+    mode: "path",
+    canonicalFqdn: "parachute-aaron.tailc75afc.ts.net",
+    port: 1939,
+    funnel: false,
+    entries: [{ kind: "proxy", mount: "/", target: "http://localhost:1939", service: "hub" }],
+    hubOrigin: "https://parachute-aaron.tailc75afc.ts.net",
+    ...overrides,
+  };
+}
+
+describe("publicOriginFromExposeState", () => {
+  test("undefined when no expose-state file exists", () => {
+    expect(publicOriginFromExposeState(exposeStatePath())).toBeUndefined();
+  });
+
+  test("returns the cloudflare hubOrigin", () => {
+    writeExposeState(cloudflareState(), exposeStatePath());
+    expect(publicOriginFromExposeState(exposeStatePath())).toBe(
+      "https://gitcoin-parachute.unforced.dev",
+    );
+  });
+
+  test("returns the tailnet hubOrigin", () => {
+    writeExposeState(tailnetState(), exposeStatePath());
+    expect(publicOriginFromExposeState(exposeStatePath())).toBe(
+      "https://parachute-aaron.tailc75afc.ts.net",
+    );
+  });
+
+  test("synthesizes https://<canonicalFqdn> when hubOrigin is absent (pre-Phase-0 state)", () => {
+    // hubOrigin is optional on older state files; canonicalFqdn is mandatory.
+    const { hubOrigin, ...rest } = cloudflareState();
+    void hubOrigin;
+    writeExposeState(rest as ExposeState, exposeStatePath());
+    expect(publicOriginFromExposeState(exposeStatePath())).toBe(
+      "https://gitcoin-parachute.unforced.dev",
+    );
+  });
+});
+
+describe("selfHealVaultHubOrigin (Cloudflare 401 self-heal)", () => {
+  test("writes the cloudflare public origin when vault/.env is UNSET", () => {
+    // The exact broken-deploy shape: expose-state carries a public cloudflare
+    // hubOrigin but vault/.env has no PARACHUTE_HUB_ORIGIN, so the daemon falls
+    // back to loopback and 401s every hub token. Restart self-corrects it.
+    writeExposeState(cloudflareState(), exposeStatePath());
+    const wrote = selfHealVaultHubOrigin(dir, () => {}, exposeStatePath());
+    expect(wrote).toBe(true);
+    expect(readEnvFileValues(vaultEnv()).PARACHUTE_HUB_ORIGIN).toBe(
+      "https://gitcoin-parachute.unforced.dev",
+    );
+  });
+
+  test("overwrites a LOOPBACK value already persisted in vault/.env", () => {
+    writeExposeState(cloudflareState(), exposeStatePath());
+    writeFileSync(mkVaultDir(), "PARACHUTE_HUB_ORIGIN=http://127.0.0.1:1939\n");
+    const wrote = selfHealVaultHubOrigin(dir, () => {}, exposeStatePath());
+    expect(wrote).toBe(true);
+    expect(readEnvFileValues(vaultEnv()).PARACHUTE_HUB_ORIGIN).toBe(
+      "https://gitcoin-parachute.unforced.dev",
+    );
+  });
+
+  test("tailnet shape still self-heals (no regression)", () => {
+    writeExposeState(tailnetState(), exposeStatePath());
+    const wrote = selfHealVaultHubOrigin(dir, () => {}, exposeStatePath());
+    expect(wrote).toBe(true);
+    expect(readEnvFileValues(vaultEnv()).PARACHUTE_HUB_ORIGIN).toBe(
+      "https://parachute-aaron.tailc75afc.ts.net",
+    );
+  });
+
+  test("does NOT persist when there's no exposure (genuine loopback / local dev)", () => {
+    // No expose-state file → no public origin → vault keeps its loopback
+    // default. Persisting loopback would shadow a later exposure.
+    const wrote = selfHealVaultHubOrigin(dir, () => {}, exposeStatePath());
+    expect(wrote).toBe(false);
+    expect(existsSync(vaultEnv())).toBe(false);
+  });
+
+  test("leaves a DIFFERENT non-loopback value alone (deliberate --hub-origin override)", () => {
+    writeExposeState(cloudflareState(), exposeStatePath());
+    writeFileSync(mkVaultDir(), "PARACHUTE_HUB_ORIGIN=https://custom.example.com\n");
+    const wrote = selfHealVaultHubOrigin(dir, () => {}, exposeStatePath());
+    expect(wrote).toBe(false);
+    // Untouched — self-heal only fixes unset/loopback, never clobbers a public
+    // value an operator may have set on purpose.
+    expect(readEnvFileValues(vaultEnv()).PARACHUTE_HUB_ORIGIN).toBe("https://custom.example.com");
+  });
+
+  test("no-op (no double-write) when the persisted value already equals the public origin", () => {
+    writeExposeState(cloudflareState(), exposeStatePath());
+    writeFileSync(mkVaultDir(), "PARACHUTE_HUB_ORIGIN=https://gitcoin-parachute.unforced.dev\n");
+    const wrote = selfHealVaultHubOrigin(dir, () => {}, exposeStatePath());
+    expect(wrote).toBe(false);
+  });
+
+  test("expose-state with a loopback hubOrigin is treated as no public exposure", () => {
+    // A loopback hubOrigin (local-dev hub) must never be persisted — it would
+    // recreate the iss mismatch on the daemon boot path.
+    writeExposeState(cloudflareState({ hubOrigin: "http://127.0.0.1:1939" }), exposeStatePath());
+    // canonicalFqdn is still public here, but hubOrigin wins — we honor the
+    // explicit value the writer chose.
+    const wrote = selfHealVaultHubOrigin(dir, () => {}, exposeStatePath());
+    expect(wrote).toBe(false);
+    expect(existsSync(vaultEnv())).toBe(false);
+  });
+});

package/src/commands/expose-cloudflare.ts

@@ -41,12 +41,14 @@ import {
   readHubPort,
 } from "../hub-control.ts";
 import { deriveHubOrigin } from "../hub-origin.ts";
-import { type AliveFn, defaultAlive } from "../process-state.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";
@@ -328,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 {
@@ -353,6 +363,7 @@ interface Resolved {
   now: () => Date;
   vaultHome: string | undefined;
   vaultAuthStatus: VaultAuthStatus | undefined;
+  restartService: (short: string) => Promise<number>;
 }
 
 function resolve(opts: ExposeCloudflareOpts): Resolved {
@@ -395,6 +406,14 @@ function resolve(opts: ExposeCloudflareOpts): Resolved {
     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 ?? (() => {}),
+        })),
   };
 }
 
@@ -700,6 +719,35 @@ export async function exposeCloudflareUp(
   };
   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

package/src/commands/lifecycle.ts

@@ -34,7 +34,7 @@ import {
   shortNameForManifest,
 } from "../service-spec.ts";
 import { type ServiceEntry, readManifest } from "../services-manifest.ts";
-import { persistVaultHubOrigin } from "../vault-hub-origin-env.ts";
+import { persistVaultHubOrigin, selfHealVaultHubOrigin } from "../vault-hub-origin-env.ts";
 
 /**
  * Tiny seam over `Bun.spawn` for lifecycle tests. The real spawner opens the
@@ -657,30 +657,44 @@ export async function start(svc: string | undefined, opts: LifecycleOpts = {}):
           `  It may still be coming up — check \`parachute status\` and \`parachute logs ${short}\`.`,
         );
         if (r.hubOrigin) r.log(`  ${HUB_ORIGIN_ENV}=${r.hubOrigin}`);
-        if (short === "vault" && r.hubOrigin) {
-          persistVaultHubOrigin(r.configDir, r.hubOrigin, r.log);
-        }
+        if (short === "vault") persistVaultHubOriginForStart(r);
         continue;
       }
     }
 
     r.log(`✓ ${short} started (pid ${pid}); logs: ${logFile}`);
     if (r.hubOrigin) r.log(`  ${HUB_ORIGIN_ENV}=${r.hubOrigin}`);
-    // Persist the resolved public origin to vault's `.env` so the launchd /
-    // systemd daemon (which boots vault out-of-band on reboot / crash-restart
-    // and never sees this spawn env) validates hub-minted JWTs' `iss` against
-    // the public origin. The spawn-env injection above is ephemeral; this is
-    // the durable half of the OAuth issuer-mismatch fix. Vault is the only
-    // hub-origin-dependent service with an OS-supervised autostart daemon
-    // today — scribe/notes don't validate `iss`. See
-    // `vault-hub-origin-env.ts:persistVaultHubOrigin`.
-    if (short === "vault" && r.hubOrigin) {
-      persistVaultHubOrigin(r.configDir, r.hubOrigin, r.log);
-    }
+    if (short === "vault") persistVaultHubOriginForStart(r);
   }
   return failures === 0 ? 0 : 1;
 }
 
+/**
+ * Durable-persist vault's `PARACHUTE_HUB_ORIGIN` on a vault `start`. Two cases,
+ * in order:
+ *
+ *  1. The resolved spawn origin (`r.hubOrigin`) is a real public origin — write
+ *     it. This is the long-standing happy path: an exposure is live, the
+ *     launchd / systemd daemon (which boots vault out-of-band and never sees
+ *     this spawn env) needs it in `.env` to validate hub-minted JWTs' `iss`.
+ *     `persistVaultHubOrigin` skips loopback / unchanged values itself.
+ *
+ *  2. Self-heal: even when `r.hubOrigin` resolved to loopback or undefined
+ *     (e.g. the hub.port file outran the expose-state read, or this is a bare
+ *     `restart vault` on a deploy whose `.env` was never written), consult
+ *     `expose-state.json` directly. If it advertises a public origin and
+ *     vault's persisted value is unset / loopback, write the public origin.
+ *     This is what lets an EXISTING broken Cloudflare deploy self-correct on
+ *     the next `parachute restart vault`, not only fresh exposes.
+ *
+ * Case 1 covers the override / freshly-resolved path; case 2 catches the gap
+ * the Cloudflare 401 P0 fell through. See `vault-hub-origin-env.ts`.
+ */
+function persistVaultHubOriginForStart(r: Resolved): void {
+  if (r.hubOrigin) persistVaultHubOrigin(r.configDir, r.hubOrigin, r.log);
+  selfHealVaultHubOrigin(r.configDir, r.log, join(r.configDir, "expose-state.json"));
+}
+
 export async function stop(svc: string | undefined, opts: LifecycleOpts = {}): Promise<number> {
   const r = resolve(opts);
   if (svc === HUB_SVC) return stopHubSvc(r);

package/src/vault-hub-origin-env.ts

@@ -28,6 +28,7 @@
  */
 import { join } from "node:path";
 import { parseEnvFile, removeEnvLine, upsertEnvLine, writeEnvFile } from "./env-file.ts";
+import { EXPOSE_STATE_PATH, readExposeState } from "./expose-state.ts";
 import { HUB_ORIGIN_ENV } from "./hub-origin.ts";
 
 /**
@@ -98,3 +99,65 @@ export function clearVaultHubOrigin(configDir: string, log: (line: string) => vo
   log(`  cleared ${HUB_ORIGIN_ENV} from ${path} (exposure torn down)`);
   return true;
 }
+
+/**
+ * The public origin a live exposure advertises, or undefined when no exposure
+ * is active. Both the Tailscale and Cloudflare expose paths populate
+ * `expose-state.json` with a `hubOrigin` (the URL stamped into OAuth tokens'
+ * `iss` claim); older state files predating Phase 0 may carry only
+ * `canonicalFqdn`, so we synthesize `https://<fqdn>` as a fallback. Loopback /
+ * empty values resolve to undefined — there's no public origin to persist.
+ */
+export function publicOriginFromExposeState(
+  exposeStatePath: string = EXPOSE_STATE_PATH,
+): string | undefined {
+  let state: ReturnType<typeof readExposeState>;
+  try {
+    state = readExposeState(exposeStatePath);
+  } catch {
+    // A malformed expose-state must never block a vault start — treat it as
+    // "no exposure" and let the loopback default stand.
+    return undefined;
+  }
+  if (!state) return undefined;
+  const origin = state.hubOrigin ?? (state.canonicalFqdn ? `https://${state.canonicalFqdn}` : "");
+  if (!origin || isLoopbackOrigin(origin)) return undefined;
+  return origin.replace(/\/+$/, "");
+}
+
+/**
+ * Self-heal vault's persisted `PARACHUTE_HUB_ORIGIN` from `expose-state.json`.
+ *
+ * The bug this closes (the Cloudflare 401 P0): on a Cloudflare-tunnel deploy the
+ * expose path writes a public `hubOrigin` into `expose-state.json`, but — unlike
+ * the Tailscale path, which auto-restarts vault and so flows the public origin
+ * into `vault/.env` via `persistVaultHubOrigin` — it never wrote vault's `.env`.
+ * So the launchd / systemd daemon kept booting vault with NO `PARACHUTE_HUB_ORIGIN`,
+ * vault fell back to loopback as its expected issuer, and every hub-minted token
+ * (whose `iss` is the public origin) failed the `iss` check → 401 on every vault
+ * request → "You're not signed in to the hub."
+ *
+ * Called on `parachute start|restart vault`: when expose-state advertises a
+ * public origin AND vault's persisted value is unset or loopback, write the
+ * public origin. Existing broken deploys self-correct on the next restart, not
+ * just fresh ones. We deliberately do NOT overwrite a *different* non-loopback
+ * value already in `.env` — that could be a deliberate `--hub-origin` override;
+ * `persistVaultHubOrigin` (the explicit, resolved-origin path) owns that case.
+ *
+ * Returns true iff `.env` was written this call.
+ */
+export function selfHealVaultHubOrigin(
+  configDir: string,
+  log: (line: string) => void,
+  exposeStatePath: string = EXPOSE_STATE_PATH,
+): boolean {
+  const publicOrigin = publicOriginFromExposeState(exposeStatePath);
+  if (!publicOrigin) return false;
+  const current = parseEnvFile(vaultEnvPath(configDir)).values[HUB_ORIGIN_ENV];
+  // Only heal the broken shapes: unset (daemon falls back to loopback) or an
+  // already-persisted loopback (a value that itself causes the iss mismatch).
+  // A current public value — including one equal to publicOrigin — is left to
+  // persistVaultHubOrigin's idempotent path so we don't double-log.
+  if (current !== undefined && !isLoopbackOrigin(current)) return false;
+  return persistVaultHubOrigin(configDir, publicOrigin, log);
+}