@openparachute/hub 0.7.3-rc.9 → 0.7.4-rc.1

package/src/commands/init.ts

@@ -41,6 +41,7 @@ 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 { setHubOrigin } from "../hub-settings.ts";
 import {
   type EnsureHubVersionMatchesResult,
   ensureHubUnit,
@@ -153,14 +154,31 @@ export interface InitOpts {
    * stub to record the call without shelling out to `cloudflared`.
    */
   exposeCloudflareImpl?: () => Promise<number>;
+  /**
+   * Install channel for the vault module (hub#694 bug 2). `"rc"` makes init's
+   * vault install resolve `@openparachute/vault@rc` instead of `@latest`, so an
+   * rc-channel box (hub installed from `@rc`) doesn't DOWNGRADE vault below the
+   * hub on `parachute init`. Default `"latest"` (npm default; back-compat for
+   * every existing operator). Precedence in the CLI: `--channel <v>` flag >
+   * `PARACHUTE_CHANNEL` / `PARACHUTE_INSTALL_CHANNEL` env > `"latest"`. Threaded
+   * verbatim into `install()`'s existing `channel` plumbing
+   * (`resolveInstallChannel`).
+   */
+  channel?: "latest" | "rc";
   /**
    * Test seam: shim for the vault-module install step (hub#168 Cut 1).
    * Production calls `install("vault", { noCreate: true, noStart: true, …})`
    * to put `@openparachute/vault` on PATH without creating a first-vault
    * instance — the wizard's vault step decides Create/Import/Skip. Tests
-   * pass a stub to record the call without shelling out.
+   * pass a stub to record the call without shelling out. The `channel` arg
+   * (hub#694) forwards into `install()`'s `channel` option so an rc box installs
+   * vault from `@rc`.
    */
-  installVaultModuleImpl?: (configDir: string, manifestPath: string) => Promise<number>;
+  installVaultModuleImpl?: (
+    configDir: string,
+    manifestPath: string,
+    channel?: "latest" | "rc",
+  ) => Promise<number>;
   /**
    * Override the wizard-choice prompt (hub#168 Cut 4). When set, the
    * "Continue setup in the browser or CLI?" question is answered without
@@ -184,6 +202,27 @@ export interface InitOpts {
    * already known so there's no question to ask).
    */
   noWizardPrompt?: boolean;
+  /**
+   * Canonical public hub origin (the OAuth issuer / `iss` claim). Persisted to
+   * `hub_settings.hub_origin` BEFORE the hub unit starts + modules spawn, so
+   * supervised vault/scribe come up with the public origin already in their
+   * `PARACHUTE_HUB_ORIGINS` set in ONE pass — no restart needed. The headline
+   * use case is the zero-SSH Caddy-direct path: a cloud-init script passes
+   * `--hub-origin https://<droplet-ip>.sslip.io` so a reverse-proxied box
+   * records its public origin without an admin browser session. Validated +
+   * canonicalized by the CLI before it reaches here; persisted via the
+   * `setHubOriginImpl` seam. Loopback / non-http(s) values never reach this far
+   * (the CLI rejects them via `validateHubOrigin`). Absent → no-op (the laptop /
+   * loopback path is unchanged).
+   */
+  hubOrigin?: string;
+  /**
+   * Test seam: persist the canonical hub origin to `hub_settings.hub_origin`.
+   * Production opens `hub.db` (running migrations) and calls `setHubOrigin`.
+   * Tests pass a stub to assert the write happens BEFORE `ensureHub` without
+   * touching the operator's live DB. Receives the resolved configDir + origin.
+   */
+  setHubOriginImpl?: (configDir: string, origin: string) => void;
   /**
    * 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
@@ -391,6 +430,25 @@ async function defaultEnsureHubViaUnit(opts: EnsureHubOpts): Promise<{
   throw new Error(result.messages.join("\n") || `hub unit bringup failed (${result.outcome}).`);
 }
 
+/**
+ * Default impl for the `--hub-origin` persistence step. Opens `hub.db` (running
+ * migrations on a fresh box) and writes `hub_settings.hub_origin`. Runs BEFORE
+ * the hub unit starts so the boot-time issuer resolution + child-spawn env
+ * (`PARACHUTE_HUB_ORIGINS`) pick up the public origin in one pass. The DB is an
+ * on-disk SQLite file shared with the (not-yet-started) serve process, so a
+ * write here is visible to the unit when it boots. The CLI has already
+ * validated + canonicalized the URL via `validateHubOrigin`, so this trusts the
+ * input (mirrors `setHubOrigin`'s typed-callsite contract).
+ */
+function defaultSetHubOrigin(configDir: string, origin: string): void {
+  const db = openHubDb(hubDbPath(configDir));
+  try {
+    setHubOrigin(db, origin);
+  } finally {
+    db.close();
+  }
+}
+
 /**
  * Resolve the issuer to mint the operator token under. At init time the hub is
  * reachable on loopback (just installed); prefer the live expose-state origin
@@ -468,8 +526,18 @@ async function defaultGuaranteeOperatorToken(ctx: {
  * shim that re-emits each line under an `[install vault] ` prefix so the
  * init log stays grep-able. Idempotent — `install` short-circuits the
  * bun-add when vault is already linked / installed.
+ *
+ * The `channel` arg (hub#694) forwards into `install()`'s `channel` option so
+ * an rc-channel box installs `@openparachute/vault@rc` instead of `@latest` —
+ * otherwise init silently DOWNGRADES vault below the rc-tracking hub. Undefined
+ * → install's own resolution (`--tag` > `channel` > `PARACHUTE_INSTALL_CHANNEL`
+ * env > `"latest"`) applies, preserving today's behavior.
  */
-async function defaultInstallVaultModule(configDir: string, manifestPath: string): Promise<number> {
+async function defaultInstallVaultModule(
+  configDir: string,
+  manifestPath: string,
+  channel?: "latest" | "rc",
+): Promise<number> {
   const installOpts: InstallOpts = {
     configDir,
     manifestPath,
@@ -477,6 +545,7 @@ async function defaultInstallVaultModule(configDir: string, manifestPath: string
     noStart: true,
     log: (line) => console.log(`[install vault] ${line}`),
   };
+  if (channel) installOpts.channel = channel;
   return await defaultInstall("vault", installOpts);
 }
 
@@ -596,6 +665,32 @@ async function promptExposeChoice(
   return defaultChoice;
 }
 
+/**
+ * Resolve the install channel for init's vault module step (hub#694 bug 2).
+ *
+ * Precedence (highest → lowest):
+ *   1. explicit `--channel rc|latest` (parsed in cli.ts → `opts.channel`)
+ *   2. `PARACHUTE_CHANNEL` env (the DigitalOcean cloud-init script's var)
+ *   3. `PARACHUTE_INSTALL_CHANNEL` env (the install layer's own platform cascade)
+ *   4. `undefined` → `install()` falls back to its own "latest" default
+ *
+ * Returns `"latest"` / `"rc"` when one is resolved, or `undefined` to defer to
+ * `install()`'s resolution. A non-`rc`/`latest` env value is ignored (returns
+ * undefined) so a typo degrades to "latest" rather than crashing init — the
+ * same forgiving posture `resolveInstallChannel` takes for the install command.
+ */
+export function resolveInitChannel(
+  explicit: "latest" | "rc" | undefined,
+  env: NodeJS.ProcessEnv,
+): "latest" | "rc" | undefined {
+  if (explicit === "rc" || explicit === "latest") return explicit;
+  for (const key of ["PARACHUTE_CHANNEL", "PARACHUTE_INSTALL_CHANNEL"]) {
+    const v = env[key];
+    if (v === "rc" || v === "latest") return v;
+  }
+  return undefined;
+}
+
 export async function init(opts: InitOpts = {}): Promise<number> {
   const configDir = opts.configDir ?? CONFIG_DIR;
   const manifestPath = opts.manifestPath ?? SERVICES_MANIFEST_PATH;
@@ -627,12 +722,86 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   const exposeTailnetImpl = opts.exposeTailnetImpl ?? defaultExposeTailnet;
   const exposeCloudflareImpl = opts.exposeCloudflareImpl ?? defaultExposeCloudflare;
   const installVaultModuleImpl = opts.installVaultModuleImpl ?? defaultInstallVaultModule;
+  // hub#694 bug 2: resolve the channel for the vault module install. Precedence:
+  // explicit `--channel <v>` (opts.channel) > `PARACHUTE_CHANNEL` /
+  // `PARACHUTE_INSTALL_CHANNEL` env > undefined (install's own "latest"
+  // fallback). The env fallback is what makes the DigitalOcean cloud-init
+  // script's `PARACHUTE_CHANNEL=rc` cascade into init's vault install with zero
+  // extra flags — init never received a `--channel` from that script, but it
+  // reads the env the script already exports. A garbage env value falls through
+  // to undefined → install resolves "latest" (matching resolveInstallChannel's
+  // own garbage-handling), so an operator typo can't break init.
+  const installChannel: "latest" | "rc" | undefined = resolveInitChannel(opts.channel, env);
   const runCliWizardImpl = opts.runCliWizardImpl ?? defaultRunCliWizard;
   const fetchBootstrapTokenImpl = opts.fetchBootstrapTokenImpl ?? defaultFetchBootstrapToken;
+  const setHubOriginImpl = opts.setHubOriginImpl ?? defaultSetHubOrigin;
 
   log("Parachute init — getting your hub set up.");
   log("");
 
+  // Step 0: persist `--hub-origin` BEFORE the hub unit starts (below). The
+  // boot-time issuer resolution + child-spawn env (`PARACHUTE_HUB_ORIGINS`)
+  // both read `hub_settings.hub_origin`, so writing it now means vault/scribe
+  // come up with the public origin already in their accepted-`iss` set in ONE
+  // pass — no restart needed (the Caddy-direct zero-SSH path). A failure here
+  // is non-fatal: warn + continue (the operator can re-run `parachute hub
+  // set-origin` later), since init's contract is hub up → wizard regardless.
+  if (opts.hubOrigin) {
+    try {
+      setHubOriginImpl(configDir, opts.hubOrigin);
+      log(`✓ Canonical hub origin set to ${opts.hubOrigin} (OAuth issuer).`);
+      log("");
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      log(
+        `⚠ Couldn't persist the hub origin (${detail}); set it later with \`parachute hub set-origin <url>\`.`,
+      );
+      log("");
+    }
+  }
+
+  // Step 0.5 (hub#694 bug 1 — the spawn race): install + seed the vault module
+  // into services.json BEFORE the hub unit starts (Step 1 below). The hub unit's
+  // `serve` runs the in-process Supervisor, which scans services.json EXACTLY
+  // ONCE at boot (`bootSupervisedModules`) and never rescans. If we seed vault
+  // AFTER the unit boots (the old Step 2.5 ordering), that single scan reads a
+  // services.json with no vault row → vault is registered-but-never-spawned, so
+  // `/vault/*` 502s until a manual `parachute restart` re-triggers a per-module
+  // start. On a slow box (1GB droplet) the scan reliably wins that race. Seeding
+  // first means the boot scan finds vault and spawns it on the first pass — no
+  // restart needed.
+  //
+  // `install("vault", { noCreate: true, noStart: true, … })` only does the
+  // on-disk work — `bun add -g` (idempotent; short-circuits when vault is
+  // bun-linked / already installed) + an `upsertService` seed write. It does NOT
+  // need a running hub: the start path, the stale-unit sweep, and the
+  // supervised-hub guidance probe are all gated off under `noCreate`/`noStart`,
+  // so running it before the unit exists is safe. The wizard's vault step still
+  // owns Create / Import / Skip (noCreate defers first-vault creation); the
+  // supervisor (not install.ts) owns spawning (noStart).
+  //
+  // Idempotent: if a vault row already exists (re-run, or a prior install), this
+  // short-circuits past the bun-add and the row is left intact. We don't block
+  // init on a non-zero exit — the wizard can retry from /admin/setup.
+  const findVaultEntry = (): boolean => {
+    try {
+      return findService("parachute-vault", manifestPath) !== undefined;
+    } catch {
+      return false;
+    }
+  };
+  const vaultAlreadyInstalled = findVaultEntry();
+  if (!vaultAlreadyInstalled) {
+    log("Installing the vault module so the wizard can offer create / import / skip…");
+    const installCode = await installVaultModuleImpl(configDir, manifestPath, installChannel);
+    if (installCode !== 0) {
+      log(
+        `⚠ vault module install returned ${installCode}; the wizard can retry from /admin/setup.`,
+      );
+    }
+    log("");
+  }
+
   // Step 1: hub running?
   // NB: under the Phase 3a unit-managed hub there is no pidfile, so
   // `processState(HUB_SVC)` reports not-running on EVERY init re-run even when
@@ -768,41 +937,14 @@ export async function init(opts: InitOpts = {}): Promise<number> {
     }
   }
 
-  // Step 2.5: always install the vault module (hub#168 Cut 1). Aaron's
-  // 2026-05-28 directive: "it should always install the vault module"
-  // even though "creating a vault should be optional." We split the
-  // module install (always) from the first-vault create (deferred to
-  // the wizard) by passing `noCreate: true` to install — bun add -g
-  // runs, services.json gets seeded, but `parachute-vault init` (which
-  // would auto-create a `default` vault) is skipped. The wizard's
-  // vault step then either Creates / Imports / Skips.
-  //
-  // Idempotent: install short-circuits the bun-add when vault is
-  // already linked (`bun link`) or already globally installed. If the
-  // operator already has a vault row, this is a no-op past the
-  // already-installed log line. We don't block init on this step;
-  // a non-zero exit code is logged but treated as a warning, since the
-  // wizard can re-attempt the install itself from /admin/setup.
-  const findVaultEntry = (): boolean => {
-    try {
-      return findService("parachute-vault", manifestPath) !== undefined;
-    } catch {
-      return false;
-    }
-  };
-  const vaultAlreadyInstalled = findVaultEntry();
-  if (!vaultAlreadyInstalled) {
-    log("");
-    log("Installing the vault module so the wizard can offer create / import / skip…");
-    const installCode = await installVaultModuleImpl(configDir, manifestPath);
-    if (installCode !== 0) {
-      log(
-        `⚠ vault module install returned ${installCode}; the wizard can retry from /admin/setup.`,
-      );
-    }
-  }
+  // (The vault module install + seed now runs at Step 0.5, BEFORE the hub unit
+  // starts — see hub#694 bug 1. It used to live here, after exposure; moving it
+  // ahead of Step 1's hub bringup is what lets the supervisor's one-time boot
+  // scan find + spawn vault instead of registering it after the scan already
+  // ran. The "always install the vault module" directive — Aaron 2026-05-28,
+  // hub#168 Cut 1 — and the noCreate/noStart split are unchanged.)
 
-  // Step 3: vault configured? (After the module install above, this may
+  // Step 3: vault configured? (After the Step 0.5 module install above, this may
   // have flipped from false to true on a fresh box. The wizard reads
   // services.json on every request, so the "configured" answer here is
   // best-effort — it only shapes the next-step log message below.)

package/src/commands/serve.ts

@@ -37,13 +37,14 @@ import { readExposeState } from "../expose-state.ts";
 import { createDbHolder, defaultStatInode, startDbPathLivenessTimer } from "../hub-db-liveness.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { hubFetch } from "../hub-server.ts";
+import { getHubOrigin } from "../hub-settings.ts";
 import { writeHubFile } from "../hub.ts";
-import { createWsBridgeHandlers } from "../ws-bridge.ts";
 import { enrichedPath } from "../spawn-path.ts";
 import { Supervisor } from "../supervisor.ts";
 import { createUser, userCount } from "../users.ts";
 import { sanitizePublicOrigin } from "../vault-hub-origin-env.ts";
 import { WELL_KNOWN_DIR } from "../well-known.ts";
+import { createWsBridgeHandlers } from "../ws-bridge.ts";
 import { bootSupervisedModules } from "./serve-boot.ts";
 
 /**
@@ -217,12 +218,30 @@ function parsePort(raw: string | undefined): number | undefined {
  * remaining gap (rebuild the live spawn-env on `supervisor.restart` so the
  * first exposure propagates to already-running children without a manual
  * restart) is the deferred #532 follow-up; not implemented in this PR.
+ *
+ * DB ORIGIN, highest precedence (onboarding-streamline 2026-06-25, Caddy-direct
+ * zero-SSH path): the operator-set `hub_settings.hub_origin` is the tier-1 layer
+ * in the per-request `resolveIssuer` (hub-server.ts). The boot path MUST honor
+ * it too — otherwise a Caddy-fronted box whose ONLY canonical-origin source is
+ * the DB row (no `PARACHUTE_HUB_ORIGIN` env, no expose-state, no platform var)
+ * boots `serve` with no issuer, injects only loopback aliases into supervised
+ * children's `PARACHUTE_HUB_ORIGINS`, and vault/scribe then reject every token
+ * the hub mints under the public origin (which per-request `resolveIssuer` DOES
+ * stamp from the DB). Threading the DB origin in as the top input keeps the
+ * boot-time seed in lockstep with `resolveIssuer`'s tier-1. `serve()` reads the
+ * row off the opened hub DB and passes it as `dbHubOrigin`; tests pass it
+ * directly. It is sanitized like any other public-origin input (a stray
+ * loopback / non-http(s) DB value never pins the issuer).
  */
 export function resolveStartupIssuer(
-  opts: { issuer?: string },
+  opts: { issuer?: string; dbHubOrigin?: string },
   env: NodeJS.ProcessEnv,
   readExpose: () => string | undefined = defaultReadExposeHubOrigin,
 ): string | undefined {
+  // DB row first — mirrors `resolveIssuer`'s tier-1 (hub_settings.hub_origin).
+  // Sanitized so a stray loopback / non-http(s) value never pins the issuer.
+  const dbOrigin = sanitizePublicOrigin(opts.dbHubOrigin);
+  if (dbOrigin) return dbOrigin;
   const flyOrigin = flyDefaultOriginFromEnv(env);
   const explicit = (
     opts.issuer ??
@@ -435,7 +454,6 @@ export async function serve(opts: ServeOpts = {}): Promise<{
 
   const envPort = parsePort(env.PORT);
   const port = opts.port ?? envPort ?? DEFAULT_PORT;
-  const issuer = resolveStartupIssuer(opts, env);
   // Containers default to 0.0.0.0 so the platform's HTTP forwarder can
   // reach us; the `--hostname` flag / PARACHUTE_BIND_HOST is the escape
   // hatch for setups that want loopback-only inside a sidecar.
@@ -461,6 +479,24 @@ export async function serve(opts: ServeOpts = {}): Promise<{
   const dbPath = hubDbPath();
   // Self-heal-or-die DB holder (#594) + proactive ghost-fd watchdog (#610/#619).
   const { dbHolder, livenessTimer } = armServeDbWatchdog(dbPath, { log });
+  // Resolve the boot-time issuer AFTER the DB is open so the operator-set
+  // `hub_settings.hub_origin` (tier-1 in `resolveIssuer`) seeds the value the
+  // hub mints with AND the `PARACHUTE_HUB_ORIGINS` set injected into supervised
+  // children. This is what makes a Caddy-fronted, zero-SSH box (whose only
+  // canonical-origin source is the DB row) inject the public origin into
+  // vault/scribe so they accept hub-minted tokens. Pass it as `dbHubOrigin`;
+  // a malformed read can't crash startup — `getHubOrigin` is a plain SELECT
+  // and `resolveStartupIssuer` sanitizes the value.
+  let dbHubOrigin: string | undefined;
+  try {
+    dbHubOrigin = getHubOrigin(dbHolder.get()) ?? undefined;
+  } catch {
+    dbHubOrigin = undefined;
+  }
+  const issuer = resolveStartupIssuer(
+    { ...opts, ...(dbHubOrigin !== undefined ? { dbHubOrigin } : {}) },
+    env,
+  );
   const adminBootstrap = await seedInitialAdminIfNeeded(dbHolder.get(), env, log);
 
   if (adminBootstrap === "needs-setup") {

package/src/help.ts

@@ -28,6 +28,8 @@ Usage:
   parachute migrate --to-supervised move a legacy detached install to the managed hub
   parachute migrate [--dry-run]     archive legacy files at ecosystem root
   parachute auth <cmd>              identity (set password, manage 2FA)
+  parachute hub set-origin <url>    set the canonical public hub origin (OAuth issuer)
+                                    — for reverse-proxy / Caddy-direct boxes
   parachute vault <args...>         vault-specific ops (tokens, 2fa, config, init,
                                     etc.) — forwards to parachute-vault.
                                     For lifecycle, use \`parachute start|stop|restart|logs vault\`.
@@ -130,6 +132,8 @@ export function initHelp(): string {
 Usage:
   parachute init [--no-browser] [--no-expose-prompt]
                  [--expose none|tailnet|cloudflare]
+                 [--channel rc|latest]
+                 [--hub-origin <url>]
                  [--cli-wizard | --browser-wizard]
 
 What it does:
@@ -165,6 +169,15 @@ Flags:
                               none       — stay loopback-only
                               tailnet    — set up Tailscale serve (private to your tailnet)
                               cloudflare — set up Cloudflare Tunnel (your own domain)
+  --channel <rc|latest>     npm dist-tag for the vault module install (default: latest).
+                            Use \`rc\` on an rc-channel box so init doesn't downgrade
+                            vault below the hub. Also honors PARACHUTE_CHANNEL /
+                            PARACHUTE_INSTALL_CHANNEL env when the flag is absent.
+  --hub-origin <url>        set the canonical public origin (OAuth issuer) BEFORE
+                            the hub + modules start, so vault/scribe come up
+                            accepting it in one pass. For reverse-proxy /
+                            Caddy-direct boxes that bind loopback but are reached
+                            over a public HTTPS URL (e.g. https://<ip>.sslip.io).
   --cli-wizard              skip the "browser or CLI?" prompt and walk the wizard
                             in this terminal (hub#168 Cut 4)
   --browser-wizard          skip the prompt and open the browser wizard directly
@@ -177,6 +190,7 @@ Examples:
   parachute init --expose tailnet             # CI/scripted: chain straight into Tailscale
   parachute init --no-browser                 # don't shell out to open / xdg-open
   parachute init --cli-wizard                 # walk the wizard in this terminal (hub#168)
+  parachute init --channel rc                  # rc box: install the vault module from @rc
 `;
 }
 

package/src/hub-server.ts

@@ -578,6 +578,16 @@ export type RequestLayer = "loopback" | "tailnet" | "public";
  * the cloak fires. When `peerAddr` is unknown (null/undefined — no Server
  * threaded, e.g. a unit test calling `layerOf(req)` directly), we fail CLOSED
  * to `public` rather than open to `loopback`.
+ *
+ * Caddy/nginx-direct (hub#704): a SAME-BOX reverse proxy dials loopback (peer
+ * is 127.0.0.1) but, unlike cloudflared/tailscale, sets NO cf/tailscale header
+ * — so a header-only-or-peer-only classifier would call every public request
+ * through it "loopback" (most-trusted). The discriminator is the standard
+ * reverse-proxy forwarding headers (X-Forwarded-For / X-Forwarded-Host /
+ * Forwarded): a loopback peer that carries one is a proxied PUBLIC request →
+ * `public`; a header-less loopback peer (direct on-box caller — CLI, probes,
+ * the init bootstrap-token loopback probe) stays `loopback`. See the inline
+ * comment in the function for the full rationale + spoof analysis.
  */
 export function layerOf(req: Request, peerAddr?: string | null): RequestLayer {
   const h = req.headers;
@@ -590,6 +600,42 @@ export function layerOf(req: Request, peerAddr?: string | null): RequestLayer {
   // value to compare against, hence the presence-check above.
   if (h.get("tailscale-funnel-request") === "?1") return "public";
   if (h.get("tailscale-user-login") !== null) return "tailnet";
+  // Caddy/nginx-direct deploy (hub#704): a same-box reverse proxy terminates
+  // TLS and `reverse_proxy 127.0.0.1:1939` — so it dials loopback (peer is
+  // 127.0.0.1) and, unlike cloudflared/tailscale, stamps NO cf/tailscale
+  // header. Without this branch every PUBLIC request through such a proxy
+  // would classify "loopback" (the MOST-trusted layer): the GET /admin/setup
+  // bootstrap-token JSON probe would hand the token to any public visitor, and
+  // the publicExposure:"loopback" 404-cloak would stop hiding loopback-only
+  // services/vaults from the network.
+  //
+  // The discriminator is the standard reverse-proxy forwarding headers. A
+  // same-box proxy carrying a PUBLIC request sets X-Forwarded-For /
+  // X-Forwarded-Host / Forwarded; a direct on-box caller (the CLI, health
+  // probes, the init bootstrap-token loopback probe `curl 127.0.0.1/admin/setup`,
+  // the hub's own loopback self-requests) sets none of them — the hub never
+  // injects X-Forwarded-* on the INBOUND request it classifies (it only stamps
+  // X-Forwarded-Host/Proto on OUTBOUND proxy requests to modules). So a
+  // loopback peer that ALSO carries a forwarding header is a proxied public
+  // request → "public"; a header-less loopback peer stays "loopback".
+  //
+  // No spoof vector: a NON-loopback peer is already "public" regardless of
+  // headers (the branch below), so adding these headers can only DOWNGRADE a
+  // loopback caller (the on-box operator hurting only their own request) —
+  // never upgrade a network peer to "loopback".
+  //
+  // Presence check (`!== null`), NOT a trim: an empty/whitespace forwarding
+  // header still means "a proxy is in front" → err to public. Downgrading on
+  // ambiguity is the safe direction for a trust classifier; a future ".trim()
+  // tidy-up" that let an empty XFF fall back to loopback would re-open the leak.
+  if (
+    isLoopbackPeer(peerAddr) &&
+    (h.get("x-forwarded-for") !== null ||
+      h.get("x-forwarded-host") !== null ||
+      h.get("forwarded") !== null)
+  ) {
+    return "public";
+  }
   // No proxy headers — classify by peer address, failing closed when unknown.
   return isLoopbackPeer(peerAddr) ? "loopback" : "public";
 }

package/src/setup-wizard.ts

@@ -60,6 +60,7 @@ import {
   SETUP_EXPOSE_MODES,
   type SetupExposeMode,
   deleteSetting,
+  getHubOrigin,
   getSetting,
   isSetupExposeMode,
   openFirstClientAutoApproveWindow,
@@ -89,6 +90,7 @@ import {
 } from "./sessions.ts";
 import type { Supervisor } from "./supervisor.ts";
 import { createUser, userCount } from "./users.ts";
+import { sanitizePublicOrigin } from "./vault-hub-origin-env.ts";
 import { DEFAULT_VAULT_NAME, validateVaultName } from "./vault-name.ts";
 
 // --- shared chrome --------------------------------------------------------
@@ -352,6 +354,24 @@ export function deriveWizardState(deps: {
       setSetting(deps.db, "setup_expose_mode", seeded);
     }
   }
+  // hub Caddy-direct case: a reverse-proxy box (`parachute init --hub-origin
+  // https://<host>`, or `parachute hub set-origin`) persists a real public
+  // origin to `hub_settings.hub_origin` (also honored from PARACHUTE_HUB_ORIGIN).
+  // That origin already answers "how is this hub reached?" — Caddy/Let's-Encrypt
+  // fronts the loopback hub, no `parachute expose` and no Render/Fly env var.
+  // Auto-seed `setup_expose_mode = "public"` so the wizard skips the expose step
+  // exactly as the Render/Fly + live-tailscale branches do. `sanitizePublicOrigin`
+  // (the SAME guard `resolveIssuer`/`exposeIssuerOrigin` use) requires an absolute
+  // http(s) URL and REJECTS loopback/0.0.0.0 — so a laptop/loopback/unset origin
+  // returns undefined and the expose step still renders (the operator chooses).
+  if (getSetting(deps.db, "setup_expose_mode") === undefined) {
+    const configured =
+      sanitizePublicOrigin(getHubOrigin(deps.db) ?? undefined) ??
+      sanitizePublicOrigin(deps.env?.PARACHUTE_HUB_ORIGIN ?? process.env.PARACHUTE_HUB_ORIGIN);
+    if (configured !== undefined) {
+      setSetting(deps.db, "setup_expose_mode", "public");
+    }
+  }
   const hasExposeMode = getSetting(deps.db, "setup_expose_mode") !== undefined;
   let step: WizardStep;
   // Note: `"account"` is a visual-only step in the progress header —