@openparachute/hub 0.7.3-rc.9 → 0.7.3

package/src/__tests__/hub-server.test.ts

@@ -3,6 +3,10 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  _resetBootstrapTokenForTests,
+  generateBootstrapToken,
+} from "../bootstrap-token.ts";
 import { buildCsrfCookie, generateCsrfToken } from "../csrf.ts";
 import { HUB_SVC, hubPortPath } from "../hub-control.ts";
 import { createDbHolder } from "../hub-db-liveness.ts";
@@ -3676,6 +3680,74 @@ describe("layerOf — classify trust layer from proxy headers + peer (item E / #
     });
     expect(layerOf(r)).toBe("public");
   });
+
+  // Caddy/nginx-direct deploy (hub#704). A same-box reverse proxy dials
+  // loopback (peer 127.0.0.1) and stamps NO cf/tailscale header — but it DOES
+  // set a standard reverse-proxy forwarding header. That header is the
+  // discriminator: a loopback peer carrying one is a proxied PUBLIC request and
+  // must NOT be "loopback" (which would leak the bootstrap token + drop the
+  // loopback-exposure cloak for every public visitor on a Caddy-direct box).
+  test("loopback peer + X-Forwarded-For → public (Caddy-direct, NOT loopback) [#704]", () => {
+    const r = req("/", { headers: { "X-Forwarded-For": "203.0.113.7" } });
+    expect(layerOf(r, "127.0.0.1")).toBe("public");
+  });
+
+  test("loopback peer + X-Forwarded-Host → public (Caddy-direct) [#704]", () => {
+    const r = req("/", { headers: { "X-Forwarded-Host": "hub.example.com" } });
+    expect(layerOf(r, "127.0.0.1")).toBe("public");
+  });
+
+  test("loopback peer + Forwarded (RFC 7239) → public (Caddy-direct) [#704]", () => {
+    const r = req("/", { headers: { Forwarded: "for=203.0.113.7;host=hub.example.com" } });
+    expect(layerOf(r, "127.0.0.1")).toBe("public");
+  });
+
+  test("IPv6-mapped loopback peer + X-Forwarded-For → public (Caddy-direct) [#704]", () => {
+    const r = req("/", { headers: { "X-Forwarded-For": "203.0.113.7" } });
+    expect(layerOf(r, "::ffff:127.0.0.1")).toBe("public");
+  });
+
+  // Security edge: an EMPTY / whitespace-only forwarding header (a misconfigured
+  // or stripped-but-present proxy header) must still err toward "public", never
+  // back to "loopback". `layerOf` uses a presence check (`!== null`), not a
+  // trim — keep it that way: the safe direction for a trust classifier is to
+  // DOWNGRADE on ambiguity. A future "tidy up with .trim()" refactor that
+  // flipped an empty XFF back to loopback would re-open the Caddy-direct leak.
+  test("loopback peer + empty X-Forwarded-For → public (errs safe, not loopback) [#704]", () => {
+    expect(layerOf(req("/", { headers: { "X-Forwarded-For": "" } }), "127.0.0.1")).toBe("public");
+    expect(layerOf(req("/", { headers: { "X-Forwarded-For": "   " } }), "127.0.0.1")).toBe("public");
+  });
+
+  // The genuine on-box caller (CLI, health probe, init bootstrap-token loopback
+  // probe `curl 127.0.0.1/admin/setup`, hub self-requests) sets NO forwarding
+  // header and MUST stay loopback. This is the not-broken half of the fix.
+  test("loopback peer + NO forwarding header → loopback (genuine on-box caller) [#704]", () => {
+    expect(layerOf(req("/"), "127.0.0.1")).toBe("loopback");
+    expect(layerOf(req("/"), "::1")).toBe("loopback");
+  });
+
+  // No spoof vector: forwarding headers can only DOWNGRADE a loopback caller.
+  // A NON-loopback peer is already "public" regardless of headers, so adding
+  // X-Forwarded-* never upgrades a network peer to a more-trusted layer.
+  test("non-loopback peer + X-Forwarded-For → public (no upgrade; spoof-proof) [#704]", () => {
+    const r = req("/", { headers: { "X-Forwarded-For": "127.0.0.1" } });
+    expect(layerOf(r, "203.0.113.7")).toBe("public");
+  });
+
+  // CF/TS header checks run FIRST — a Caddy-style forwarding header alongside a
+  // cf/tailscale header doesn't change those (still public/tailnet). Order
+  // preserved.
+  test("CF-Ray + X-Forwarded-For from loopback peer → public (CF check wins, order preserved)", () => {
+    const r = req("/", { headers: { "CF-Ray": "abc123-DEN", "X-Forwarded-For": "203.0.113.7" } });
+    expect(layerOf(r, "127.0.0.1")).toBe("public");
+  });
+
+  test("Tailscale-User-Login + X-Forwarded-For from loopback peer → tailnet (TS check wins)", () => {
+    const r = req("/", {
+      headers: { "Tailscale-User-Login": "alice@example.com", "X-Forwarded-For": "100.64.0.1" },
+    });
+    expect(layerOf(r, "127.0.0.1")).toBe("tailnet");
+  });
 });
 
 describe("hubFetch publicExposure layer-gate (proxyToService)", () => {
@@ -3823,6 +3895,74 @@ describe("hubFetch publicExposure layer-gate (proxyToService)", () => {
     }
   });
 
+  // hub#704 — Caddy/nginx-direct. A same-box reverse proxy dials loopback
+  // (peer 127.0.0.1) and stamps NO cf/tailscale header, but DOES set
+  // X-Forwarded-For. That request is a PUBLIC visitor proxied to the box and
+  // must hit the loopback-exposure cloak (404) — otherwise a Caddy-direct box
+  // leaks every loopback-only service/vault to the network.
+  test("publicExposure: loopback + X-Forwarded-For + loopback peer → 404 (Caddy-direct cloak fires) [#704]", async () => {
+    const h = makeHarness();
+    const upstream = startUpstream("loopback-only");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "loopback-only",
+              port: upstream.port,
+              paths: ["/loopback-only"],
+              health: "/loopback-only/health",
+              version: "0.1.0",
+              publicExposure: "loopback",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      // Caddy: peer is 127.0.0.1 (reverse_proxy 127.0.0.1:1939) but the request
+      // carries X-Forwarded-For for the real public client.
+      const r = req("/loopback-only/health", { headers: { "X-Forwarded-For": "203.0.113.7" } });
+      const res = await fetcher(r, fakeServer("127.0.0.1"));
+      expect(res.status).toBe(404);
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
+  // The not-broken half: a header-less loopback peer (genuine on-box caller)
+  // still reaches the loopback-only service through the cloak.
+  test("publicExposure: loopback + NO forwarding header + loopback peer → reaches upstream [#704]", async () => {
+    const h = makeHarness();
+    const upstream = startUpstream("loopback-only");
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "loopback-only",
+              port: upstream.port,
+              paths: ["/loopback-only"],
+              health: "/loopback-only/health",
+              version: "0.1.0",
+              publicExposure: "loopback",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const fetcher = hubFetch(h.dir, { manifestPath: h.manifestPath });
+      const res = await fetcher(req("/loopback-only/health"), fakeServer("127.0.0.1"));
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { tag: string };
+      expect(body.tag).toBe("loopback-only");
+    } finally {
+      upstream.stop();
+      h.cleanup();
+    }
+  });
+
   test("publicExposure: allowed + tailnet header → reaches upstream (no gate)", async () => {
     const h = makeHarness();
     const upstream = startUpstream("allowed");
@@ -5850,3 +5990,103 @@ describe("resolveClientIp (H2)", () => {
     expect(resolveClientIp(r, null)).toBeNull();
   });
 });
+
+describe("GET /admin/setup bootstrap-token probe — loopback-gated (hub#576 + Caddy-direct #704)", () => {
+  // The hub#576 token probe: a LOOPBACK caller (the on-box operator's own
+  // shell / `parachute init`) reading GET /admin/setup with Accept:
+  // application/json gets the actual bootstrap token in the JSON envelope; a
+  // public/tailnet caller does not. The hub derives requestIsLoopback from
+  // `layerOf(req, peerAddr) === "loopback"` (hub-server.ts ~2296), so the
+  // Caddy-direct fix (#704) flows straight through: a same-box reverse proxy
+  // carrying X-Forwarded-For now classifies "public" and the token is withheld
+  // even though the peer is 127.0.0.1.
+
+  // Fake Bun Server handle (mirrors the cloak suite) so the fetch fn resolves
+  // the peer address. The on-box operator connects from 127.0.0.1; Caddy
+  // reverse_proxy also dials 127.0.0.1 but stamps X-Forwarded-For.
+  const fakeServer = (address: string) => ({ requestIP: () => ({ address }) });
+
+  test("loopback peer + NO forwarding header → bootstrapToken present (on-box operator) [#576]", async () => {
+    const h = makeHarness();
+    _resetBootstrapTokenForTests();
+    const token = generateBootstrapToken();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        // No admin row → wizard mode → GET /admin/setup JSON probe is live.
+        const res = await hubFetch(h.dir, { getDb: () => db })(
+          req("/admin/setup", { headers: { accept: "application/json" } }),
+          fakeServer("127.0.0.1"),
+        );
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as {
+          requireBootstrapToken?: boolean;
+          bootstrapToken?: string;
+        };
+        expect(body.requireBootstrapToken).toBe(true);
+        expect(body.bootstrapToken).toBe(token);
+      } finally {
+        db.close();
+      }
+    } finally {
+      _resetBootstrapTokenForTests();
+      h.cleanup();
+    }
+  });
+
+  test("loopback peer + X-Forwarded-For → bootstrapToken WITHHELD (Caddy-direct public visitor) [#704]", async () => {
+    const h = makeHarness();
+    _resetBootstrapTokenForTests();
+    generateBootstrapToken();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        // Caddy: peer 127.0.0.1, but the request carries the public client's
+        // X-Forwarded-For. Pre-fix this leaked the token to any public visitor.
+        const res = await hubFetch(h.dir, { getDb: () => db })(
+          req("/admin/setup", {
+            headers: { accept: "application/json", "x-forwarded-for": "203.0.113.7" },
+          }),
+          fakeServer("127.0.0.1"),
+        );
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as {
+          requireBootstrapToken?: boolean;
+          bootstrapToken?: string;
+        };
+        // The gate still SAYS a token is required (so the form renders the
+        // field) — it just doesn't hand the value to the public caller.
+        expect(body.requireBootstrapToken).toBe(true);
+        expect(body.bootstrapToken).toBeUndefined();
+      } finally {
+        db.close();
+      }
+    } finally {
+      _resetBootstrapTokenForTests();
+      h.cleanup();
+    }
+  });
+
+  test("non-loopback peer → bootstrapToken WITHHELD (direct public/tailnet)", async () => {
+    const h = makeHarness();
+    _resetBootstrapTokenForTests();
+    generateBootstrapToken();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, { getDb: () => db })(
+          req("/admin/setup", { headers: { accept: "application/json" } }),
+          fakeServer("203.0.113.9"),
+        );
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as { bootstrapToken?: string };
+        expect(body.bootstrapToken).toBeUndefined();
+      } finally {
+        db.close();
+      }
+    } finally {
+      _resetBootstrapTokenForTests();
+      h.cleanup();
+    }
+  });
+});

package/src/__tests__/init.test.ts

@@ -960,6 +960,154 @@ describe("hasNoDisplay heuristic (Fix 2 — headless browser-open guard)", () =>
   });
 });
 
+describe("init --hub-origin (Caddy-direct zero-SSH boot, onboarding-streamline 2026-06-25)", () => {
+  test("persists the origin BEFORE ensureHub so modules spawn with it in one pass", async () => {
+    const h = makeHarness();
+    try {
+      const order: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        hubOrigin: "https://box.sslip.io",
+        // The load-bearing ordering assertion: the origin write MUST happen
+        // before the hub unit starts (which boots + spawns vault/scribe), so
+        // the boot-time issuer + child env pick it up without a restart.
+        setHubOriginImpl: (_dir, origin) => {
+          order.push(`set-origin:${origin}`);
+        },
+        ensureHub: async () => {
+          order.push("ensureHub");
+          writeHubPort(1939, h.configDir);
+          return { pid: 5555, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(0);
+      expect(order).toEqual(["set-origin:https://box.sslip.io", "ensureHub"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("default impl writes hub_settings.hub_origin to the real DB", async () => {
+    const h = makeHarness();
+    try {
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        hubOrigin: "https://box.sslip.io",
+        // No setHubOriginImpl override → exercise the production default
+        // (openHubDb + setHubOrigin) against the harness's temp configDir.
+        ensureHub: async () => {
+          writeHubPort(1939, h.configDir);
+          return { pid: 5555, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(0);
+      const { hubDbPath, openHubDb } = await import("../hub-db.ts");
+      const { getHubOrigin } = await import("../hub-settings.ts");
+      const db = openHubDb(hubDbPath(h.configDir));
+      try {
+        expect(getHubOrigin(db)).toBe("https://box.sslip.io");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("no --hub-origin → no persistence call (laptop/loopback path unchanged)", async () => {
+    const h = makeHarness();
+    try {
+      let setCalls = 0;
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: () => {},
+        alive: () => false,
+        setHubOriginImpl: () => {
+          setCalls++;
+        },
+        ensureHub: async () => {
+          writeHubPort(1939, h.configDir);
+          return { pid: 5555, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(0);
+      expect(setCalls).toBe(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a persistence failure is non-fatal — init still reaches the wizard", async () => {
+    const h = makeHarness();
+    try {
+      const logs: string[] = [];
+      const code = await init({
+        configDir: h.configDir,
+        ensureHubVersion: async () => ({
+          outcome: "match" as const,
+          installedVersion: "test",
+          messages: [],
+        }),
+        manifestPath: h.manifestPath,
+        log: (l) => logs.push(l),
+        alive: () => false,
+        hubOrigin: "https://box.sslip.io",
+        setHubOriginImpl: () => {
+          throw new Error("disk full");
+        },
+        ensureHub: async () => {
+          writeHubPort(1939, h.configDir);
+          return { pid: 5555, port: 1939, started: true };
+        },
+        readExposeStateFn: () => undefined,
+        isTty: false,
+        platform: "linux",
+        installVaultModuleImpl: noopVaultInstall,
+      });
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).toContain("Couldn't persist the hub origin");
+      expect(joined).toContain("http://127.0.0.1:1939/admin/");
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
 describe("init exposure chain", () => {
   test("TTY + no exposure + no flags → prompt is shown", async () => {
     const h = makeHarness();

package/src/__tests__/serve.test.ts

@@ -21,7 +21,9 @@ describe("hubServeOptions — the production listener wires the WS bridge", () =
   // upgrades (the channel in-page terminal) 500'd through the hub
   // ("set the websocket object in Bun.serve({})"). The listener MUST declare a
   // websocket handler or `server.upgrade()` throws.
-  const fakeFetch = (() => new Response("ok")) as unknown as Parameters<typeof hubServeOptions>[0]["fetch"];
+  const fakeFetch = (() => new Response("ok")) as unknown as Parameters<
+    typeof hubServeOptions
+  >[0]["fetch"];
 
   test("declares a websocket handler set (open/message/close)", () => {
     const o = hubServeOptions({ port: 0, hostname: "127.0.0.1", fetch: fakeFetch });
@@ -404,6 +406,70 @@ describe("resolveStartupIssuer — precedence chain (hub#365)", () => {
   test("FLY_APP_NAME empty string → no fallback", () => {
     expect(resolveStartupIssuer({}, { FLY_APP_NAME: "" }, noExpose)).toBeUndefined();
   });
+
+  // onboarding-streamline 2026-06-25 — the Caddy-direct zero-SSH boot-issuer
+  // fix. The operator-set `hub_settings.hub_origin` (tier-1 in resolveIssuer)
+  // MUST also drive the boot-time issuer, else a box whose ONLY canonical-
+  // origin source is the DB row boots without an issuer and injects only
+  // loopback into supervised children's PARACHUTE_HUB_ORIGINS.
+  describe("dbHubOrigin tier (DB hub_settings.hub_origin)", () => {
+    test("dbHubOrigin wins over env/platform/expose (mirrors resolveIssuer tier-1)", () => {
+      const got = resolveStartupIssuer(
+        { dbHubOrigin: "https://box.sslip.io" },
+        {
+          PARACHUTE_HUB_ORIGIN: "https://env.example",
+          RENDER_EXTERNAL_URL: "https://render.example.onrender.com",
+        },
+        () => "https://exposed.example",
+      );
+      expect(got).toBe("https://box.sslip.io");
+    });
+
+    test("dbHubOrigin even wins over explicit opts.issuer (DB is the operator's deliberate canonical)", () => {
+      const got = resolveStartupIssuer(
+        { issuer: "https://flag.example", dbHubOrigin: "https://box.sslip.io" },
+        {},
+        noExpose,
+      );
+      expect(got).toBe("https://box.sslip.io");
+    });
+
+    test("dbHubOrigin trailing slash is stripped", () => {
+      expect(resolveStartupIssuer({ dbHubOrigin: "https://box.sslip.io/" }, {}, noExpose)).toBe(
+        "https://box.sslip.io",
+      );
+    });
+
+    test("a loopback dbHubOrigin is rejected (sanitized) → falls through to next tier", () => {
+      // A stray loopback value in the DB must NOT pin the issuer to a non-
+      // public origin; fall through to env so the box keeps a usable issuer.
+      const got = resolveStartupIssuer(
+        { dbHubOrigin: "http://127.0.0.1:1939" },
+        { PARACHUTE_HUB_ORIGIN: "https://env.example" },
+        noExpose,
+      );
+      expect(got).toBe("https://env.example");
+    });
+
+    test("a non-http(s) dbHubOrigin is rejected → falls through", () => {
+      const got = resolveStartupIssuer(
+        { dbHubOrigin: "ftp://box.example" },
+        {},
+        () => "https://exposed.example",
+      );
+      expect(got).toBe("https://exposed.example");
+    });
+
+    test("undefined dbHubOrigin is a no-op (unchanged precedence)", () => {
+      expect(
+        resolveStartupIssuer(
+          { dbHubOrigin: undefined },
+          { PARACHUTE_HUB_ORIGIN: "https://e.x" },
+          noExpose,
+        ),
+      ).toBe("https://e.x");
+    });
+  });
 });
 
 describe("resolveStartupIssuer — expose-state fallback (#531)", () => {

package/src/__tests__/setup-wizard.test.ts

@@ -26,7 +26,7 @@ import { CSRF_COOKIE_NAME, CSRF_FIELD_NAME } from "../csrf.ts";
 import { type ExposeState, readExposeState, writeExposeState } from "../expose-state.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { hubFetch } from "../hub-server.ts";
-import { getSetting, setSetting } from "../hub-settings.ts";
+import { getSetting, setHubOrigin, setSetting } from "../hub-settings.ts";
 import { validateAccessToken } from "../jwt-sign.ts";
 import {
   OPERATOR_TOKEN_SCOPE_SET_CLAIM,
@@ -537,6 +537,126 @@ describe("deriveWizardState", () => {
       db.close();
     }
   });
+
+  // --- Caddy-direct: a configured public origin already answers "how reached?"
+  // Seed a real vault row so the only step left to decide is expose.
+  const seedAdminAndVault = async (db: ReturnType<typeof openHubDb>) => {
+    await createUser(db, "owner", "pw");
+    writeManifest(
+      {
+        services: [
+          {
+            name: "parachute-vault",
+            version: "0.1.0",
+            port: 1940,
+            paths: ["/vault/default"],
+            health: "/health",
+          },
+        ],
+      },
+      h.manifestPath,
+    );
+  };
+
+  test("auto-skips expose when a public hub_origin is configured (Caddy-direct / init --hub-origin)", async () => {
+    // Caddy-direct box: `parachute init --hub-origin https://host` persisted a
+    // real public origin to hub_settings.hub_origin BEFORE the wizard opened.
+    // No Render/Fly env var, no live tailscale exposure. That origin already
+    // answers "how will this hub be reached?" — the wizard must skip the expose
+    // step (account → vault → done) rather than re-asking.
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await seedAdminAndVault(db);
+      setHubOrigin(db, "https://box.example.com");
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        env: {},
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      expect(s.step).toBe("done");
+      expect(s.hasExposeMode).toBe(true);
+      // Seeded "public" (not localhost/tailnet) — a Caddy-fronted box is public.
+      expect(getSetting(db, "setup_expose_mode")).toBe("public");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("auto-skips expose when PARACHUTE_HUB_ORIGIN env is a public origin (env-var Caddy box)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await seedAdminAndVault(db);
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        env: { PARACHUTE_HUB_ORIGIN: "https://box.example.com" },
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      expect(s.step).toBe("done");
+      expect(s.hasExposeMode).toBe(true);
+      expect(getSetting(db, "setup_expose_mode")).toBe("public");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("does NOT skip expose when hub_origin is loopback (laptop / dev box still asks)", async () => {
+    // A loopback hub_origin must NOT count as "reached publicly" —
+    // sanitizePublicOrigin rejects 127.0.0.1/localhost/::1/0.0.0.0, so the
+    // expose step still renders and the operator chooses.
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await seedAdminAndVault(db);
+      setHubOrigin(db, "http://127.0.0.1:1939");
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        env: {},
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      expect(s.step).toBe("expose");
+      expect(s.hasExposeMode).toBe(false);
+      expect(getSetting(db, "setup_expose_mode")).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  test("does NOT skip expose when no origin is configured (unset → still asks)", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await seedAdminAndVault(db);
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        env: {},
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      expect(s.step).toBe("expose");
+      expect(s.hasExposeMode).toBe(false);
+      expect(getSetting(db, "setup_expose_mode")).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+
+  test("does NOT skip expose when PARACHUTE_HUB_ORIGIN env is loopback", async () => {
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await seedAdminAndVault(db);
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        env: { PARACHUTE_HUB_ORIGIN: "http://localhost:1939" },
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      expect(s.step).toBe("expose");
+      expect(s.hasExposeMode).toBe(false);
+    } finally {
+      db.close();
+    }
+  });
 });
 
 // --- GET /admin/setup ----------------------------------------------------