@openparachute/hub 0.7.3-rc.9 → 0.7.3

package/src/cli.ts

@@ -8,6 +8,7 @@
 
 import { MissingDependencyError } from "@openparachute/depcheck";
 import pkg from "../package.json" with { type: "json" };
+import { validateHubOrigin } from "./api-settings-hub-origin.ts";
 import { CloudflaredStateError } from "./cloudflare/state.ts";
 // Command-implementation modules are loaded LAZILY inside their switch arms (see
 // `loadCommand` + each `case`), so a module that throws at eval-time is isolated
@@ -360,7 +361,32 @@ async function main(argv: string[]): Promise<number> {
         console.log(initHelp());
         return 0;
       }
-      const exposeExtract = extractNamedFlag(rest, "--expose");
+      const originExtract = extractHubOrigin(rest);
+      if (originExtract.error) {
+        console.error(`parachute init: ${originExtract.error}`);
+        return 1;
+      }
+      // Validate --hub-origin to the SAME shape `hub set-origin` enforces — the
+      // value is persisted to hub_settings.hub_origin and stamps the OAuth `iss`
+      // claim on every minted token, so a malformed path/scheme/credential must
+      // never reach the DB. Strip a trailing slash first (browser copy-paste
+      // ergonomics), then validate; pass the normalized form downstream.
+      let validatedHubOrigin: string | undefined;
+      if (originExtract.hubOrigin !== undefined) {
+        const result = validateHubOrigin(originExtract.hubOrigin.replace(/\/+$/, ""));
+        if (!result.ok) {
+          console.error(`parachute init: invalid --hub-origin: ${result.description}`);
+          return 1;
+        }
+        if (result.normalized === null) {
+          console.error(
+            "parachute init: invalid --hub-origin: an empty value is not a valid public origin.",
+          );
+          return 1;
+        }
+        validatedHubOrigin = result.normalized;
+      }
+      const exposeExtract = extractNamedFlag(originExtract.rest, "--expose");
       if (exposeExtract.error) {
         console.error(`parachute init: ${exposeExtract.error}`);
         return 1;
@@ -392,6 +418,7 @@ async function main(argv: string[]): Promise<number> {
         console.error(
           "usage: parachute init [--no-browser] [--no-expose-prompt]\n" +
             "                     [--expose none|tailnet|cloudflare]\n" +
+            "                     [--hub-origin <url>]\n" +
             "                     [--cli-wizard | --browser-wizard]",
         );
         return 1;
@@ -403,6 +430,7 @@ async function main(argv: string[]): Promise<number> {
       const initOpts: Parameters<typeof init>[0] = {};
       if (noBrowser) initOpts.noBrowser = true;
       if (noExposePrompt) initOpts.noExposePrompt = true;
+      if (validatedHubOrigin) initOpts.hubOrigin = validatedHubOrigin;
       if (exposeExtract.value) {
         initOpts.exposeChoice = exposeExtract.value as "none" | "tailnet" | "cloudflare";
       }
@@ -931,6 +959,12 @@ async function main(argv: string[]): Promise<number> {
       return await mod.auth(rest);
     }
 
+    case "hub": {
+      const mod = await loadCommand("hub", () => import("./commands/hub.ts"));
+      if (!mod) return 1;
+      return await mod.hub(rest);
+    }
+
     case "vault": {
       const mod = await loadCommand("vault", () => import("./commands/vault.ts"));
       if (!mod) return 1;

package/src/commands/hub.ts

@@ -0,0 +1,409 @@
+/**
+ * `parachute hub <subcommand>` — hub-local configuration verbs that write
+ * `~/.parachute/hub.db`.
+ *
+ * Subcommands:
+ *   - `set-origin <url>` — persist the operator's canonical public hub origin
+ *     into `hub_settings.hub_origin`. That row is tier-1 in `resolveIssuer`
+ *     (hub-server.ts) — the OAuth `iss` claim hub stamps into every JWT — and,
+ *     since the onboarding-streamline 2026-06-25 boot-issuer fix, also seeds the
+ *     `PARACHUTE_HUB_ORIGINS` set hub injects into supervised modules
+ *     (vault/scribe) so they accept tokens minted under the public origin.
+ *
+ * The headline use case is the zero-SSH Caddy-direct DigitalOcean path: a bare
+ * droplet runs Caddy (Let's Encrypt TLS terminator + reverse proxy to the
+ * loopback hub), and the hub never does TLS. The hub binds loopback and reads
+ * its public origin from the DB. Before this verb the only way to set
+ * `hub_origin` was the admin SPA's `PUT /api/settings/hub-origin` — which needs
+ * a browser session you don't have on a freshly-provisioned headless box. The
+ * CLI verb closes that gap so a cloud-init script (or an operator over the DO
+ * console) can record the public origin without SSHing into the admin UI.
+ *
+ * Validation reuses `validateHubOrigin` (api-settings-hub-origin.ts) so the CLI
+ * and the SPA enforce the EXACT same shape: http(s) scheme, a hostname, no
+ * trailing slash / path / query / fragment / credentials. A loopback value is
+ * allowed (a dev/test box may legitimately set one) but warned about, since a
+ * loopback `hub_origin` would advertise a non-public issuer.
+ */
+
+import type { Database } from "bun:sqlite";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { validateHubOrigin } from "../api-settings-hub-origin.ts";
+import { restart } from "../commands/lifecycle.ts";
+import { CONFIG_DIR } from "../config.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { setHubOrigin } from "../hub-settings.ts";
+import { type CommandResult, type Runner, defaultRunner } from "../tailscale/run.ts";
+import { isLoopbackOrigin } from "../vault-hub-origin-env.ts";
+
+/** Default path to the Parachute-managed Caddyfile (install/digitalocean.sh). */
+const DEFAULT_CADDYFILE_PATH = "/etc/caddy/Caddyfile";
+
+/**
+ * Stable prefix of the marker comment the install script writes as line 1 of a
+ * Parachute-managed Caddyfile (`# Managed by Parachute install …`). We match a
+ * prefix, not the whole line, so a future heredoc tweak to the trailing text
+ * doesn't break detection.
+ */
+const CADDY_MARKER_PREFIX = "# Managed by Parachute install";
+
+export interface HubCommandDeps {
+  configDir?: string;
+  log?: (line: string) => void;
+  /**
+   * Test seam: open the hub DB. Production opens `hub.db` under the resolved
+   * `configDir` (running migrations). Tests pass an in-memory / temp DB so the
+   * write is exercised without touching the operator's live `~/.parachute`.
+   */
+  openDb?: (configDir: string) => Database;
+  /**
+   * Path to the Parachute-managed Caddyfile. Defaults to the install script's
+   * hardcoded `/etc/caddy/Caddyfile`. Tests point it at a temp fixture.
+   */
+  caddyfilePath?: string;
+  /** fs read seam (default `node:fs`). Returns undefined when the file is absent. */
+  readFile?: (path: string) => string | undefined;
+  /** fs write seam (default `node:fs`). */
+  writeFile?: (path: string, content: string) => void;
+  /** fs existence seam (default `node:fs`). */
+  exists?: (path: string) => boolean;
+  /**
+   * Runner for `systemctl reload caddy` + the module restart fan-out. Canonical
+   * {@link Runner} seam (the same one `expose.ts` injects). Tests mock it so
+   * nothing real reloads.
+   */
+  run?: Runner;
+  /** Effective uid (default `process.getuid`). Non-root → skip the write/reload. */
+  getuid?: () => number | undefined;
+  /**
+   * Restart supervised modules so `PARACHUTE_HUB_ORIGINS` re-injects with the
+   * fresh origin. Defaults to `restart(undefined, …)` (restarts the hub unit,
+   * re-booting all modules). Tests mock it so the live supervisor isn't driven.
+   */
+  restartModules?: (configDir: string) => Promise<number>;
+}
+
+/** Outcome of an attempted in-place Caddyfile hostname rewrite. */
+type CaddyRewriteResult =
+  | { kind: "rewritten"; content: string; host: string }
+  | { kind: "unchanged" } // host already matches — idempotent, no reload needed
+  | { kind: "not-managed" } // no file, or no `# Managed by Parachute install` marker
+  | { kind: "customized" }; // marker present but the site-address line shape is unrecognized
+
+/**
+ * Rewrite ONLY the site-address (hostname) line of a Parachute-managed Caddyfile
+ * to `host`, leaving the `reverse_proxy` body + the security-load-bearing
+ * `header_up -…` trust-signal strips byte-intact.
+ *
+ * The managed shape (install/digitalocean.sh write_caddyfile) is:
+ *
+ *   # Managed by Parachute install (install/digitalocean.sh). Re-run to refresh.
+ *   <hostname> {
+ *       reverse_proxy 127.0.0.1:<port> {
+ *           header_up -Cf-Ray
+ *           …
+ *       }
+ *   }
+ *
+ * Strategy: confirm the first non-empty line carries the marker prefix; then
+ * find the first top-level site-opener line (`<token> {`) that is NOT the
+ * `reverse_proxy …` line and replace its host token with `host`, preserving
+ * indentation + the trailing ` {`. If the marker is present but no such line
+ * matches (operator hand-edited), return `customized` and let the caller fall
+ * back to manual steps rather than guess.
+ */
+export function rewriteCaddyfileHost(content: string, host: string): CaddyRewriteResult {
+  const lines = content.split("\n");
+  const firstNonEmpty = lines.find((l) => l.trim().length > 0);
+  if (firstNonEmpty === undefined || !firstNonEmpty.trim().startsWith(CADDY_MARKER_PREFIX)) {
+    return { kind: "not-managed" };
+  }
+  // The site-address opener is the first `<token> {`-terminated line that is NOT
+  // the `reverse_proxy …` line. A bare host token: no whitespace, no scheme.
+  const siteOpener = /^(\s*)(\S+)(\s*\{\s*)$/;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined) continue;
+    const trimmed = line.trim();
+    if (trimmed.startsWith("#") || trimmed.length === 0) continue;
+    if (trimmed.startsWith("reverse_proxy")) continue;
+    const m = line.match(siteOpener);
+    if (!m) continue;
+    const [, indent, token, brace] = m;
+    if (indent === undefined || token === undefined || brace === undefined) continue;
+    if (token === host) return { kind: "unchanged" };
+    lines[i] = `${indent}${host}${brace}`;
+    return { kind: "rewritten", content: lines.join("\n"), host };
+  }
+  return { kind: "customized" };
+}
+
+/**
+ * `parachute hub set-origin <url>`. Validates + canonicalizes the URL, persists
+ * it to `hub_settings.hub_origin`, then — on a Parachute-managed Caddy-direct
+ * box — rewrites the Caddyfile hostname, reloads Caddy, and restarts the
+ * supervised modules so they re-pick the origin. Every post-DB step is
+ * best-effort: on any miss (no managed Caddyfile, `--no-caddy`, non-root, a
+ * failed reload/restart) the origin still persisted and the manual steps are
+ * printed. Returns 0 on success (incl. soft Caddy/restart misses), 1 only on a
+ * validation / DB-write failure.
+ */
+export async function hubSetOrigin(
+  args: readonly string[],
+  deps: HubCommandDeps = {},
+): Promise<number> {
+  const configDir = deps.configDir ?? CONFIG_DIR;
+  const log = deps.log ?? ((line) => console.log(line));
+  const err = (line: string) => console.error(line);
+  const openDb = deps.openDb ?? ((dir: string) => openHubDb(hubDbPath(dir)));
+  const caddyfilePath = deps.caddyfilePath ?? DEFAULT_CADDYFILE_PATH;
+  const exists = deps.exists ?? ((path: string) => existsSync(path));
+  const readFile = deps.readFile ?? ((path: string) => readFileSync(path, "utf8"));
+  const writeFile =
+    deps.writeFile ?? ((path: string, content: string) => writeFileSync(path, content));
+  const run = deps.run ?? defaultRunner;
+  const getuid =
+    deps.getuid ?? (() => (typeof process.getuid === "function" ? process.getuid() : undefined));
+  const restartModules =
+    deps.restartModules ??
+    ((dir: string) => restart(undefined, { configDir: dir, supervisor: {} }));
+
+  const noCaddy = args.includes("--no-caddy");
+  const noRestart = args.includes("--no-restart");
+  const positional = args.filter((a) => !a.startsWith("-"));
+  const raw = positional[0];
+  if (raw === undefined) {
+    err("usage: parachute hub set-origin <url>");
+    err("example: parachute hub set-origin https://box.sslip.io");
+    return 1;
+  }
+  if (positional.length > 1) {
+    err(`parachute hub set-origin: unexpected argument "${positional[1]}"`);
+    err("usage: parachute hub set-origin <url>");
+    return 1;
+  }
+
+  // Strip a trailing slash up front so the convenient `https://host/` form is
+  // accepted (the operator copy-pastes a browser URL). `validateHubOrigin`
+  // itself REJECTS a trailing slash (it's the SPA's PUT body validator, where a
+  // strict shape is wanted) — we canonicalize here, then validate the rest of
+  // the shape (scheme / hostname / no-path / no-credentials) through the shared
+  // validator so the CLI and SPA agree on everything else.
+  const trimmed = raw.replace(/\/+$/, "");
+  const result = validateHubOrigin(trimmed);
+  if (!result.ok) {
+    err(`parachute hub set-origin: ${result.description}`);
+    return 1;
+  }
+  // `validateHubOrigin` maps empty / null to `normalized: null` (clear the row).
+  // `set-origin` with an explicit non-empty arg should never land there — a
+  // present positional that normalizes to null means the operator passed an
+  // empty string, which is not a valid public origin for this verb.
+  if (result.normalized === null) {
+    err("parachute hub set-origin: a non-empty origin URL is required");
+    err("usage: parachute hub set-origin <url>");
+    return 1;
+  }
+  const origin = result.normalized;
+
+  // Loopback is allowed (a dev/test box may set one deliberately) but warned —
+  // a loopback hub_origin advertises a non-public issuer, so remote devices
+  // and supervised resource servers reached over a public URL would reject it.
+  if (isLoopbackOrigin(origin)) {
+    log(`⚠ ${origin} is a loopback origin — it won't be reachable from other devices.`);
+    log("  Set the box's PUBLIC URL (e.g. https://<droplet-ip>.sslip.io) for a real deploy.");
+  }
+
+  const db = openDb(configDir);
+  try {
+    setHubOrigin(db, origin);
+  } finally {
+    db.close();
+  }
+
+  log(`✓ Canonical hub origin set to ${origin}.`);
+  log("  Stored in hub_settings — the OAuth issuer (`iss`) hub stamps on every token,");
+  log("  and the origin set injected into supervised modules so they accept it.");
+
+  // The DB write is the load-bearing contract; everything below is best-effort
+  // automation of the manual restart/rewrite steps. Any miss falls back to
+  // printing the manual instructions and still returns 0.
+  //
+  // The Caddy site address is a BARE host (Caddy auto-TLS on HTTPS-default),
+  // taken from the ALREADY-VALIDATED URL — `new URL(origin).host` (no scheme),
+  // never a raw arg, so there's nothing to inject (the rewrite is a file edit,
+  // the reload/restart are argv-form Bun.spawn, no shell).
+  const host = new URL(origin).host;
+
+  if (noCaddy) {
+    log("");
+    log("(--no-caddy) Skipping the Caddyfile rewrite + reload.");
+  } else if (!exists(caddyfilePath)) {
+    // Tailscale / Cloudflare / manual-proxy box — no managed Caddyfile to touch.
+    log("");
+    log(
+      `No Parachute-managed Caddyfile at ${caddyfilePath} — origin set; restart modules to apply.`,
+    );
+  } else {
+    let content: string | undefined;
+    try {
+      content = readFile(caddyfilePath);
+    } catch {
+      content = undefined;
+    }
+    const rewrite =
+      content === undefined
+        ? ({ kind: "not-managed" } as const)
+        : rewriteCaddyfileHost(content, host);
+    if (rewrite.kind === "not-managed") {
+      log("");
+      log(
+        `No Parachute-managed Caddyfile at ${caddyfilePath} — origin set; restart modules to apply.`,
+      );
+    } else if (rewrite.kind === "customized") {
+      log("");
+      log(`The Caddyfile at ${caddyfilePath} looks customized — not rewriting its host line.`);
+      log(`  Update the site address to "${host}" by hand, then: sudo systemctl reload caddy`);
+    } else if (rewrite.kind === "unchanged") {
+      // Host already matches — nothing to write or reload.
+      log("");
+      log(`Caddyfile already points at ${host} — no change needed.`);
+    } else if (getuid() !== undefined && getuid() !== 0) {
+      // Writing /etc/caddy/Caddyfile + `systemctl reload` need root; the hub
+      // never shells `sudo` itself. Persist + print the manual steps.
+      log("");
+      log(`Not running as root — can't rewrite ${caddyfilePath} or reload Caddy.`);
+      log(
+        `  As root: set the Caddyfile site address to "${host}", then: sudo systemctl reload caddy`,
+      );
+    } else {
+      // Root + managed file + host changed → rewrite, then (only if the write
+      // landed) reload.
+      let wrote = false;
+      try {
+        writeFile(caddyfilePath, rewrite.content);
+        wrote = true;
+      } catch (e) {
+        log("");
+        log(`Could not write ${caddyfilePath}: ${e instanceof Error ? e.message : String(e)}`);
+        log(`  Update its site address to "${host}" by hand, then: sudo systemctl reload caddy`);
+      }
+      if (wrote) {
+        // `runCaddyReload` → defaultRunner pre-flights `systemctl` and THROWS
+        // (friendly missing-dep error) on a non-systemd box, before its own
+        // try/catch. Wrap it so a throw degrades to the manual-reload hint
+        // instead of escaping past the module restart below — the origin is
+        // already persisted, so the restart must still run.
+        let reload: CommandResult;
+        try {
+          reload = await runCaddyReload(run);
+        } catch (e) {
+          reload = { code: 1, stdout: "", stderr: e instanceof Error ? e.message : String(e) };
+        }
+        if (reload.code === 0) {
+          log("");
+          log(`✓ Rewrote ${caddyfilePath} → ${host}, reloaded Caddy.`);
+        } else {
+          log("");
+          log(`✓ Rewrote ${caddyfilePath} → ${host}, but Caddy reload reported an error:`);
+          if (reload.stderr.trim().length > 0) log(`  ${reload.stderr.trim()}`);
+          log("  Reload it manually: sudo systemctl reload caddy");
+        }
+      }
+    }
+  }
+
+  // Restart supervised modules so they re-pick the origin via PARACHUTE_HUB_ORIGINS
+  // (injected at child-spawn time). One hub-unit restart re-boots all modules —
+  // strictly better than the old "restart vault / restart scribe" two-step.
+  if (noRestart) {
+    log("");
+    log("(--no-restart) Skipping the module restart. Apply with: parachute restart");
+  } else {
+    let restarted = false;
+    try {
+      restarted = (await restartModules(configDir)) === 0;
+    } catch {
+      restarted = false;
+    }
+    if (restarted) {
+      log("✓ Restarted modules (vault, scribe) so they accept the new origin.");
+    } else {
+      log("");
+      log("Restart already-running modules so they pick up the new origin:");
+      log("  parachute restart");
+    }
+  }
+
+  return 0;
+}
+
+/**
+ * `systemctl reload caddy` through the injected Runner. Kept tiny so the call
+ * site reads as one step; the Runner default (`defaultRunner`) env-inherits +
+ * pre-flights the binary, and tests mock it.
+ */
+async function runCaddyReload(run: Runner): Promise<CommandResult> {
+  return run(["systemctl", "reload", "caddy"]);
+}
+
+/**
+ * `parachute hub <subcommand>` dispatcher. Mirrors `auth`'s shape (a thin
+ * router over subcommand handlers, each catching its own errors).
+ */
+export async function hub(args: readonly string[], deps: HubCommandDeps = {}): Promise<number> {
+  const sub = args[0];
+  if (sub === undefined || sub === "--help" || sub === "-h" || sub === "help") {
+    console.log(hubHelp());
+    return 0;
+  }
+  if (sub === "set-origin") {
+    try {
+      return await hubSetOrigin(args.slice(1), deps);
+    } catch (err) {
+      console.error(
+        `parachute hub set-origin: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return 1;
+    }
+  }
+  console.error(`parachute hub: unknown subcommand "${sub}"`);
+  console.error("");
+  console.error(hubHelp());
+  return 1;
+}
+
+export function hubHelp(): string {
+  return `parachute hub — hub-local configuration
+
+Usage:
+  parachute hub set-origin <url> [--no-caddy] [--no-restart]
+
+Subcommands:
+  set-origin <url>    Persist the canonical public origin (OAuth issuer) to the
+                      hub DB. This is the URL the hub stamps as the \`iss\` claim
+                      on every token AND the origin it tells supervised modules
+                      (vault, scribe) to accept. Use it on a reverse-proxy /
+                      Caddy-direct box where the hub binds loopback but is reached
+                      over a public HTTPS URL — no admin browser session needed.
+
+                      The URL must be http(s), with a hostname and no trailing
+                      slash / path / query.
+
+                      On a Parachute-managed Caddy-direct box (a
+                      /etc/caddy/Caddyfile written by the install script), this
+                      ALSO rewrites the Caddyfile's hostname line to the new
+                      origin (the reverse_proxy body + trust-signal header strips
+                      are left intact), reloads Caddy, and restarts the modules so
+                      the new origin propagates — a one-command domain change. If
+                      no managed Caddyfile is present, the rewrite is skipped and
+                      the manual steps are printed. Pass --no-caddy to skip the
+                      Caddyfile rewrite + reload, or --no-restart to skip the
+                      module restart.
+
+Examples:
+  parachute hub set-origin https://box.sslip.io
+  parachute hub set-origin https://parachute.example.com
+  parachute hub set-origin https://parachute.example.com --no-caddy
+`;
+}

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,
@@ -184,6 +185,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 +413,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
@@ -629,10 +670,32 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   const installVaultModuleImpl = opts.installVaultModuleImpl ?? defaultInstallVaultModule;
   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 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

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") {