@openparachute/hub 0.6.4-rc.7 → 0.6.4-rc.9

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

@@ -4051,6 +4051,116 @@ describe("setup-wizard JSON surface (hub#168 Cuts 2/3)", () => {
     }
   });
 
+  test("JSON probe hands the bootstrap token VALUE to a loopback caller (hub#576)", async () => {
+    const { generateBootstrapToken, _resetBootstrapTokenForTests } = await import(
+      "../bootstrap-token.ts"
+    );
+    _resetBootstrapTokenForTests();
+    const token = generateBootstrapToken();
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const res = handleSetupGet(req("/admin/setup", { headers: { accept: "application/json" } }), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+        requestIsLoopback: true,
+      });
+      const body = (await res.json()) as {
+        requireBootstrapToken: boolean;
+        bootstrapToken?: string;
+      };
+      expect(body.requireBootstrapToken).toBe(true);
+      expect(body.bootstrapToken).toBe(token);
+    } finally {
+      _resetBootstrapTokenForTests();
+      db.close();
+    }
+  });
+
+  test("JSON probe withholds the token VALUE from a non-loopback caller (hub#576)", async () => {
+    const { generateBootstrapToken, _resetBootstrapTokenForTests } = await import(
+      "../bootstrap-token.ts"
+    );
+    _resetBootstrapTokenForTests();
+    generateBootstrapToken();
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const res = handleSetupGet(req("/admin/setup", { headers: { accept: "application/json" } }), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+        requestIsLoopback: false,
+      });
+      const body = (await res.json()) as {
+        requireBootstrapToken: boolean;
+        bootstrapToken?: string;
+      };
+      // The boolean still tells a public browser a token is required...
+      expect(body.requireBootstrapToken).toBe(true);
+      // ...but the VALUE never leaks to it.
+      expect(body.bootstrapToken).toBeUndefined();
+    } finally {
+      _resetBootstrapTokenForTests();
+      db.close();
+    }
+  });
+
+  test("JSON probe fails CLOSED when loopback is unknown (hub#576)", async () => {
+    const { generateBootstrapToken, _resetBootstrapTokenForTests } = await import(
+      "../bootstrap-token.ts"
+    );
+    _resetBootstrapTokenForTests();
+    generateBootstrapToken();
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      // `requestIsLoopback` omitted entirely — must be treated as non-loopback.
+      const res = handleSetupGet(req("/admin/setup", { headers: { accept: "application/json" } }), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const body = (await res.json()) as { bootstrapToken?: string };
+      expect(body.bootstrapToken).toBeUndefined();
+    } finally {
+      _resetBootstrapTokenForTests();
+      db.close();
+    }
+  });
+
+  test("JSON probe omits the token when no admin gate is active (hub#576)", async () => {
+    const { _resetBootstrapTokenForTests } = await import("../bootstrap-token.ts");
+    _resetBootstrapTokenForTests(); // no token minted → not in wizard mode
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const res = handleSetupGet(req("/admin/setup", { headers: { accept: "application/json" } }), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "http://127.0.0.1:1939",
+        registry: getDefaultOperationsRegistry(),
+        requestIsLoopback: true,
+      });
+      const body = (await res.json()) as {
+        requireBootstrapToken: boolean;
+        bootstrapToken?: string;
+      };
+      expect(body.requireBootstrapToken).toBe(false);
+      expect(body.bootstrapToken).toBeUndefined();
+    } finally {
+      db.close();
+    }
+  });
+
   test("vault step skip mode short-circuits + persists setup_vault_skipped", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {

package/src/__tests__/well-known.test.ts

@@ -123,6 +123,31 @@ describe("buildWellKnown", () => {
     ]);
   });
 
+  test("SEED placeholder vault entry is NOT fabricated into a vault row (hub#577)", () => {
+    // `parachute init` installs the vault MODULE without creating an instance,
+    // seeding a services.json entry at version "0.0.0-linked" with the
+    // canonical /vault/default mount. That must NOT surface as a phantom
+    // `default` vault in the management page.
+    const seed: ServiceEntry = { ...vault, version: "0.0.0-linked" };
+    const doc = buildWellKnown({
+      services: [seed],
+      canonicalOrigin: "https://x.example",
+    });
+    // No phantom vault row...
+    expect(doc.vaults).toEqual([]);
+    // ...but the services entry stays so the SPA knows the module IS installed
+    // (offers "New vault", not "Install module").
+    expect(doc.services.map((s) => s.name)).toEqual(["parachute-vault"]);
+  });
+
+  test("a REAL (non-seed) vault entry still lands in vaults[] (hub#577 regression guard)", () => {
+    const doc = buildWellKnown({
+      services: [{ ...vault, version: "0.5.1", paths: ["/vault/techne"] }],
+      canonicalOrigin: "https://x.example",
+    });
+    expect(doc.vaults.map((v) => v.name)).toEqual(["techne"]);
+  });
+
   test("multiple installs of the same kind both land in the array (#92)", () => {
     const work: ServiceEntry = { ...notes, paths: ["/notes-work"], port: 5174 };
     const doc = buildWellKnown({

package/src/__tests__/wizard.test.ts

@@ -32,6 +32,12 @@ interface FakeHubState {
   importParams?: { remoteUrl: string; pat?: string; mode: string };
   exposeMode?: string;
   posted: Array<{ path: string; body: unknown }>;
+  /** hub#576: when set, the fake GET /admin/setup reports requireBootstrapToken=true. */
+  requireBootstrapToken?: boolean;
+  /** hub#576: when set, the fake GET also returns it (loopback-probe behavior). */
+  bootstrapToken?: string;
+  /** hub#576: when true, the account POST 401s unless the right token is supplied. */
+  enforceBootstrapToken?: boolean;
 }
 
 function makeFakeHub(initialState?: Partial<FakeHubState>): {
@@ -86,8 +92,10 @@ function makeFakeHub(initialState?: Partial<FakeHubState>): {
         hasAdmin: state.hasAdmin,
         hasVault: state.hasVault,
         hasExposeMode: state.hasExposeMode,
-        requireBootstrapToken: false,
+        requireBootstrapToken: state.requireBootstrapToken ?? false,
         csrfToken: csrf,
+        // hub#576: a loopback probe carries the actual token value.
+        ...(state.bootstrapToken ? { bootstrapToken: state.bootstrapToken } : {}),
       });
       return new Response(respBody, {
         status: 200,
@@ -101,6 +109,17 @@ function makeFakeHub(initialState?: Partial<FakeHubState>): {
     // POST /admin/setup/account
     if (path === "/admin/setup/account" && method === "POST") {
       state.posted.push({ path, body: bodyJson });
+      // hub#576: reject when the gate is enforced and the supplied token is
+      // wrong / missing — proves the CLI wizard actually sends it.
+      if (state.enforceBootstrapToken) {
+        const supplied = (bodyJson as { bootstrap_token?: string })?.bootstrap_token;
+        if (supplied !== state.bootstrapToken) {
+          return new Response(JSON.stringify({ error: "bad bootstrap token" }), {
+            status: 401,
+            headers: { "content-type": "application/json; charset=utf-8" },
+          });
+        }
+      }
       state.hasAdmin = true;
       return new Response(JSON.stringify({ step: "vault", message: "admin created" }), {
         status: 200,
@@ -270,6 +289,58 @@ describe("runCliWizard", () => {
     expect(state.exposeMode).toBe("localhost");
   });
 
+  test("loopback-probe bootstrap token is sent transparently (no prompt) — hub#576", async () => {
+    const { state, fetchImpl } = makeFakeHub({
+      requireBootstrapToken: true,
+      bootstrapToken: "parachute-bootstrap-LOOPBACK",
+      enforceBootstrapToken: true,
+    });
+    let prompted = false;
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      // No --bootstrap-token flag, no env: the value must come from the probe.
+      prompt: async () => {
+        prompted = true;
+        return "";
+      },
+      accountUsername: "admin",
+      accountPassword: "longpassword",
+      vaultMode: "skip",
+      exposeMode: "localhost",
+    });
+    expect(code).toBe(0);
+    // The account POST carried the probe-supplied token...
+    const accountBody = state.posted[0]?.body as Record<string, string>;
+    expect(accountBody.bootstrap_token).toBe("parachute-bootstrap-LOOPBACK");
+    // ...and the operator was never asked for it.
+    expect(prompted).toBe(false);
+  });
+
+  test("explicit --bootstrap-token flag still wins over the probe value — hub#576", async () => {
+    const { state, fetchImpl } = makeFakeHub({
+      requireBootstrapToken: true,
+      bootstrapToken: "parachute-bootstrap-PROBE",
+      enforceBootstrapToken: false,
+    });
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      bootstrapToken: "parachute-bootstrap-EXPLICIT",
+      accountUsername: "admin",
+      accountPassword: "longpassword",
+      vaultMode: "skip",
+      exposeMode: "localhost",
+    });
+    expect(code).toBe(0);
+    const accountBody = state.posted[0]?.body as Record<string, string>;
+    expect(accountBody.bootstrap_token).toBe("parachute-bootstrap-EXPLICIT");
+  });
+
   test("vault import mode threads remote_url + pat + import_mode", async () => {
     const { state, fetchImpl } = makeFakeHub();
     const code = await runCliWizard({

package/src/account-home-ui.ts

@@ -327,8 +327,31 @@ function renderOnboardingChecklist(opts: OnboardingChecklistOpts): string {
   const safeEndpoint = escapeHtml(endpoint);
   const safeAddCmd = escapeHtml(addCmd);
 
-  // Condensed state — they've connected, so the checklist shrinks to a single
-  // reassuring line. The vault card below remains the place to actually work.
+  // The endpoint + both connect methods. Shared between the full checklist
+  // (step 2) and the condensed "Connect another AI" expander (hub#583) so a
+  // genuinely-connected user can still wire up a SECOND client without losing
+  // the instructions.
+  const connectMethods = `
+            <div class="copy-row">
+              <code data-testid="onboarding-mcp-endpoint">${safeEndpoint}</code>
+              <button type="button" class="btn btn-copy" data-copy="${safeEndpoint}"
+                      data-testid="copy-onboarding-endpoint">Copy</button>
+            </div>
+            <p class="onboarding-method"><strong>Claude.ai (web):</strong> open
+               Settings → Connectors → Add custom connector, and paste the address above.</p>
+            <p class="onboarding-method"><strong>Claude Code (terminal):</strong> run this command:</p>
+            <div class="copy-row">
+              <code data-testid="onboarding-mcp-add-command">${safeAddCmd}</code>
+              <button type="button" class="btn btn-copy" data-copy="${safeAddCmd}"
+                      data-testid="copy-onboarding-add-command">Copy</button>
+            </div>`;
+
+  // Condensed state — they've connected, so the checklist shrinks to a quiet
+  // reassuring line. But keep a "Connect another AI" expander (hub#583): the
+  // condensed line used to DELETE the endpoint + methods outright, leaving a
+  // connected user no way to wire up a second client. A <details> expander
+  // (server-rendered, no-JS-required — the copy buttons stay progressive
+  // enhancement) re-reveals the full inline instructions on demand.
   if (connected) {
     return `
     <section class="section onboarding onboarding-done" data-testid="onboarding-checklist"
@@ -336,6 +359,14 @@ function renderOnboardingChecklist(opts: OnboardingChecklistOpts): string {
       <p class="onboarding-done-line" data-testid="onboarding-done-line">
         <span class="onboarding-check" aria-hidden="true">✓</span>
         You're connected — here's your vault.</p>
+      <details class="onboarding-connect-another" data-testid="onboarding-connect-another">
+        <summary data-testid="onboarding-connect-another-summary">Connect another AI →</summary>
+        <div class="onboarding-step-body">
+          <p class="onboarding-step-sub">Point another AI client at your vault using this
+             address — you'll sign in and approve the first time:</p>
+          ${connectMethods}
+        </div>
+      </details>
     </section>`;
   }
 
@@ -360,19 +391,7 @@ function renderOnboardingChecklist(opts: OnboardingChecklistOpts): string {
             <p class="onboarding-step-title">Connect your AI</p>
             <p class="onboarding-step-sub">Point Claude (or another AI) at your vault using this
                address — no token to copy, you'll sign in and approve the first time:</p>
-            <div class="copy-row">
-              <code data-testid="onboarding-mcp-endpoint">${safeEndpoint}</code>
-              <button type="button" class="btn btn-copy" data-copy="${safeEndpoint}"
-                      data-testid="copy-onboarding-endpoint">Copy</button>
-            </div>
-            <p class="onboarding-method"><strong>Claude.ai (web):</strong> open
-               Settings → Connectors → Add custom connector, and paste the address above.</p>
-            <p class="onboarding-method"><strong>Claude Code (terminal):</strong> run this command:</p>
-            <div class="copy-row">
-              <code data-testid="onboarding-mcp-add-command">${safeAddCmd}</code>
-              <button type="button" class="btn btn-copy" data-copy="${safeAddCmd}"
-                      data-testid="copy-onboarding-add-command">Copy</button>
-            </div>
+            ${connectMethods}
           </div>
         </li>
 
@@ -955,6 +974,18 @@ const STYLES = `
     align-items: center;
     justify-content: center;
   }
+  .onboarding-connect-another { margin: 0.7rem 0 0; }
+  .onboarding-connect-another > summary {
+    cursor: pointer;
+    font-size: 0.85rem;
+    font-weight: 500;
+    color: ${PALETTE.accent};
+    list-style: none;
+    user-select: none;
+  }
+  .onboarding-connect-another > summary::-webkit-details-marker { display: none; }
+  .onboarding-connect-another[open] > summary { margin-bottom: 0.4rem; }
+  .onboarding-connect-another .copy-row { margin: 0.35rem 0; }
 
   .account-security {
     margin: 0.9rem 0 0;

package/src/account-vault-token.ts

@@ -69,7 +69,7 @@ import {
 } from "./account-home-ui.ts";
 import { renderAdminError } from "./admin-login-ui.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
-import { userHasVaultGrant } from "./grants.ts";
+import { userHasExternalAiGrant } from "./grants.ts";
 import { inferAudience } from "./jwt-audience.ts";
 import { recordTokenMint, signAccessToken } from "./jwt-sign.ts";
 import { vaultTokenMintRateLimiter } from "./rate-limit.ts";
@@ -190,7 +190,14 @@ export async function handleAccountVaultTokenPost(
         csrfToken: csrf.token,
         twoFactorEnabled: isTotpEnrolled(deps.db, user.id),
         mintableVerbs: buildMintableVerbs(deps.db, user.id, user.assignedVaults),
-        connectedVault: user.assignedVaults.some((v) => userHasVaultGrant(deps.db, user.id, v)),
+        // hub#583: "connected" means an EXTERNAL AI/MCP client (Claude, Cursor,
+        // …) was wired to a vault — NOT a first-party browser sign-in. Notes /
+        // the admin SPA are OAuth clients too and write vault-scoped grants, so
+        // the old `userHasVaultGrant` lit "✓ You're connected" the moment the
+        // user opened Notes. `userHasExternalAiGrant` filters those out.
+        connectedVault: user.assignedVaults.some((v) =>
+          userHasExternalAiGrant(deps.db, user.id, v),
+        ),
         ...extras,
       }),
       status,

package/src/api-account.ts

@@ -54,7 +54,7 @@ import { fetchVaultUsage, formatUsageStat } from "./account-usage.ts";
 import { POST_LOGIN_DEFAULT } from "./admin-handlers.ts";
 import { renderAdminError } from "./admin-login-ui.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
-import { userHasVaultGrant } from "./grants.ts";
+import { userHasExternalAiGrant } from "./grants.ts";
 import { changePasswordRateLimiter } from "./rate-limit.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
 import { findActiveSession } from "./sessions.ts";
@@ -601,11 +601,18 @@ export async function handleAccountHomeGet(req: Request, deps: AccountHomeDeps):
     );
   }
 
-  // "Has this user connected an AI to any of their vaults yet?" — drives the
-  // onboarding checklist's "Connect your AI" step (done/condensed when true).
-  // A grant row only lands after the user clicks through an OAuth consent for a
-  // client wired to one of their vaults.
-  const connectedVault = user.assignedVaults.some((v) => userHasVaultGrant(deps.db, user.id, v));
+  // hub#583: "connected" means an EXTERNAL AI/MCP client (Claude, Cursor, …)
+  // was wired to a vault — NOT a first-party browser sign-in. This is the
+  // PRIMARY browser GET /account/ route — the exact page the field report
+  // describes — so it must use the same filtered check as the vault-token
+  // re-render (account-vault-token.ts:196): the old `userHasVaultGrant` lit
+  // "✓ You're connected" the moment the user opened Notes (a first-party OAuth
+  // client that writes a vault-scoped grant). `userHasExternalAiGrant` excludes
+  // first-party browser surfaces so the checklist only condenses on a real AI
+  // connection.
+  const connectedVault = user.assignedVaults.some((v) =>
+    userHasExternalAiGrant(deps.db, user.id, v),
+  );
 
   return htmlResponse(
     renderAccountHome({

package/src/commands/expose-cloudflare.ts

@@ -53,6 +53,7 @@ import { HUB_UNIT_DEFAULT_PORT } from "../hub-unit.ts";
 import { type AliveFn, defaultAlive } from "../process-state.ts";
 import { readManifestLenient } from "../services-manifest.ts";
 import { type Runner, defaultRunner } from "../tailscale/run.ts";
+import { clearVaultHubOrigin } from "../vault-hub-origin-env.ts";
 import type { VaultAuthStatus } from "../vault/auth-status.ts";
 import { printPublic2FAWarning } from "./expose-2fa-warning.ts";
 import {
@@ -1137,8 +1138,35 @@ export async function exposeCloudflareOff(opts: ExposeCloudflareOpts = {}): Prom
   // downstream consumers stop resolving the now-dead public URL (mirrors the
   // up-path write above + the Tailscale off-path's expose-state teardown). When
   // other tunnels survive we leave it — a later off for the last one clears it.
+  //
+  // TODO(multi-tunnel) #588: with TWO CF tunnels up, tearing down the
+  // last-written-up one (whose hostname is what's in vault's `.env`) while the
+  // other survives leaves `.env` carrying the dead tunnel's origin while the
+  // surviving tunnel serves a different one → stale-iss on the next vault
+  // restart. Retention is still the only SAFE choice here: a single
+  // `PARACHUTE_HUB_ORIGIN` field can't represent "which surviving tunnel wins,"
+  // and clearing it would break the survivor's iss check. Properly fixing it
+  // needs re-resolving the effective origin from the survivor (or multi-origin
+  // issuer acceptance vault-side) — larger than the #503 single-tunnel fix, and
+  // multi-CF-tunnel-on-one-box is rare. See #588.
   if (!state) {
     clearExposeState(r.exposeStatePath);
+    // Drop the persisted PARACHUTE_HUB_ORIGIN from vault's `.env` (#503). With
+    // the last Cloudflare tunnel gone, the hub is loopback-only and mints
+    // loopback-`iss` tokens; a stale public origin left in `vault/.env` would
+    // pin a public expected issuer and 401 every request on the next vault
+    // daemon restart ("not signed in to the hub" — the inverse of the bug
+    // selfHealVaultHubOrigin closed). This mirrors exactly what the Tailscale
+    // off-path does (`exposeOff` in expose.ts) — the Cloudflare path had been
+    // the asymmetric gap. expose-state's own `hubOrigin` is cleared above via
+    // clearExposeState, so hub's per-request `resolveIssuer`/`exposeIssuerOrigin`
+    // (which read expose-state) also stop minting the public iss after teardown.
+    // No restart needed for the gap this closes — the next vault restart picks
+    // up the cleared `.env` — but tell the operator so an already-running vault
+    // doesn't keep validating against the now-dead public origin.
+    if (clearVaultHubOrigin(r.configDir, r.log)) {
+      r.log("  Restart vault to apply the loopback issuer now: `parachute restart vault`.");
+    }
   }
   return failed ? 1 : 0;
 }

package/src/commands/init.ts

@@ -162,6 +162,17 @@ export interface InitOpts {
    * already known so there's no question to ask).
    */
   noWizardPrompt?: boolean;
+  /**
+   * Test seam: probe the running hub for its first-claim bootstrap token
+   * (hub#576). Production hits `GET http://127.0.0.1:<port>/admin/setup` with
+   * `accept: application/json` and reads `bootstrapToken` (the hub returns it
+   * only to loopback callers). Returns the token string when the hub is in
+   * wizard mode (no admin yet), or `undefined` when there's no token to surface
+   * (admin already exists, or the probe failed). Init uses it to print the
+   * token next to the admin URL when the hub is publicly exposed, so a browser
+   * operator can claim the box without digging through the hub logs.
+   */
+  fetchBootstrapTokenImpl?: (loopbackUrl: string) => Promise<string | undefined>;
 }
 
 /**
@@ -461,6 +472,41 @@ async function defaultRunCliWizard(opts: {
   return await runCliWizard(opts);
 }
 
+/**
+ * Default impl for the bootstrap-token probe (hub#576). GETs the loopback hub's
+ * `/admin/setup` with `accept: application/json` and returns the `bootstrapToken`
+ * the hub hands to loopback callers. Returns `undefined` on any failure (hub
+ * not answering, no token because an admin already exists, malformed body) —
+ * surfacing the token is a convenience, never a hard dependency of init.
+ */
+async function defaultFetchBootstrapToken(loopbackUrl: string): Promise<string | undefined> {
+  // Debug breadcrumb (gated on PARACHUTE_DEBUG so it never clutters the normal
+  // operator output). When the token doesn't print in the field, this tells a
+  // troubleshooter WHY — hub didn't answer, returned non-200, or the body
+  // carried no token (already-claimed / no-gate) — instead of a silent nothing.
+  const debug = (msg: string): void => {
+    if (process.env.PARACHUTE_DEBUG) console.error(`[init][bootstrap-token] ${msg}`);
+  };
+  try {
+    const res = await fetch(`${loopbackUrl.replace(/\/+$/, "")}/admin/setup`, {
+      headers: { accept: "application/json" },
+    });
+    if (!res.ok) {
+      debug(`probe returned ${res.status}; not printing a token`);
+      return undefined;
+    }
+    const body = (await res.json()) as { bootstrapToken?: unknown };
+    if (typeof body.bootstrapToken === "string" && body.bootstrapToken.length > 0) {
+      return body.bootstrapToken;
+    }
+    debug("probe ok but no bootstrapToken in body (already-claimed or no gate active)");
+    return undefined;
+  } catch (err) {
+    debug(`probe failed: ${err instanceof Error ? err.message : String(err)}`);
+    return undefined;
+  }
+}
+
 /**
  * Prompt for the wizard-choice question (hub#168 Cut 4). Returns the
  * picked option, or `undefined` if the operator quit. Default is
@@ -547,6 +593,7 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   const exposeCloudflareImpl = opts.exposeCloudflareImpl ?? defaultExposeCloudflare;
   const installVaultModuleImpl = opts.installVaultModuleImpl ?? defaultInstallVaultModule;
   const runCliWizardImpl = opts.runCliWizardImpl ?? defaultRunCliWizard;
+  const fetchBootstrapTokenImpl = opts.fetchBootstrapTokenImpl ?? defaultFetchBootstrapToken;
 
   log("Parachute init — getting your hub set up.");
   log("");
@@ -711,6 +758,19 @@ export async function init(opts: InitOpts = {}): Promise<number> {
     return 1;
   }
 
+  // hub#576: when the hub is publicly exposed AND still in wizard mode (no
+  // admin yet), the admin URL above is a public FQDN — whoever opens it first
+  // claims the box. Surface the first-claim bootstrap token in the operator's
+  // OWN terminal so the wizard's account step demands proof of box access. We
+  // only probe + print on the public-FQDN path: a loopback-only install needs
+  // no token (reaching 127.0.0.1 already proves access), and the CLI-wizard
+  // path picks the token up transparently over loopback (above). The probe is
+  // best-effort — a failure (or an already-claimed hub) just prints nothing.
+  let bootstrapToken: string | undefined;
+  if (exposeState?.canonicalFqdn) {
+    bootstrapToken = await fetchBootstrapTokenImpl(`http://127.0.0.1:${hubPort}`);
+  }
+
   log("");
   if (hasVault) {
     log("Looks good — your hub is up and a vault is configured.");
@@ -720,6 +780,17 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   log("");
   log(`  ${adminUrl}`);
   log("");
+  if (bootstrapToken) {
+    log("Because this hub is reachable on the public internet, the wizard asks for a");
+    log("one-time bootstrap token before it lets anyone create the admin account —");
+    log("so whoever opens the URL first can't claim your hub. Paste this when asked:");
+    log("");
+    log(`  ${bootstrapToken}`);
+    log("");
+    log("(Valid until the admin is created or the hub restarts. Re-run `parachute init`");
+    log(" to mint a fresh one.)");
+    log("");
+  }
   // hub#565: when we're on the loopback URL (no public exposure active),
   // remind the operator they can expose later. Skipped once an FQDN is up.
   if (!exposeState?.canonicalFqdn) {
@@ -756,7 +827,13 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   if (choice === "cli") {
     log("");
     log("Launching the CLI wizard. (You can also visit the URL above in a browser any time.)");
-    return await runCliWizardImpl({ hubUrl: adminUrl.replace(/\/admin\/?$/, ""), log });
+    // hub#576: drive the CLI wizard against the LOOPBACK hub, not the public
+    // FQDN in `adminUrl`. The wizard runs on this box, so loopback is both
+    // correct and what lets the hub hand it the bootstrap token transparently
+    // (the loopback-gated GET /admin/setup probe) — the operator never has to
+    // copy the token out of the startup logs.
+    const cliWizardUrl = `http://127.0.0.1:${hubPort}`;
+    return await runCliWizardImpl({ hubUrl: cliWizardUrl, log });
   }
 
   // Step 5: offer to open the browser. Skip in non-TTY shells (CI),

package/src/commands/wizard.ts

@@ -255,6 +255,14 @@ interface WizardStateSnapshot {
   hasVault: boolean;
   hasExposeMode: boolean;
   requireBootstrapToken: boolean;
+  /**
+   * The actual bootstrap token, present ONLY when the wizard-state probe ran
+   * over loopback (the on-box operator's own shell — hub#576). The hub returns
+   * it so the CLI wizard can satisfy the first-claim gate transparently without
+   * the operator copy-pasting it from the startup logs. Absent on any
+   * public/tailnet probe.
+   */
+  bootstrapToken?: string;
   csrfToken: string;
   /** Optional URL to redirect to (when state is fully done — 301 to /login). */
   redirectTo?: string;
@@ -294,7 +302,7 @@ async function fetchWizardState(
     );
   }
   const body = res.json as Partial<WizardStateSnapshot> & { csrfToken?: string };
-  return {
+  const snapshot: WizardStateSnapshot = {
     step: body.step ?? "welcome",
     hasAdmin: Boolean(body.hasAdmin),
     hasVault: Boolean(body.hasVault),
@@ -302,6 +310,12 @@ async function fetchWizardState(
     requireBootstrapToken: Boolean(body.requireBootstrapToken),
     csrfToken: typeof body.csrfToken === "string" ? body.csrfToken : (jar.csrf ?? ""),
   };
+  // hub#576: the loopback probe carries the actual token. Thread it through so
+  // the account step can submit it without prompting the operator.
+  if (typeof body.bootstrapToken === "string" && body.bootstrapToken.length > 0) {
+    snapshot.bootstrapToken = body.bootstrapToken;
+  }
+  return snapshot;
 }
 
 /**
@@ -422,7 +436,27 @@ async function walkAccountStep(
     log(`  ✗ ${pwErr}`);
     return 1;
   }
-  let bootstrap = opts.bootstrapToken ?? process.env.PARACHUTE_BOOTSTRAP_TOKEN;
+  // Token resolution order (hub#576):
+  //   1. Explicit `--bootstrap-token` flag / `opts.bootstrapToken` (init passes
+  //      this when it fetched the token from the loopback probe).
+  //   2. `PARACHUTE_BOOTSTRAP_TOKEN` env.
+  //   3. The token carried on the loopback wizard-state probe itself — the
+  //      common on-box `parachute init` path: the hub handed us the value
+  //      because we reached it over loopback, so we satisfy the gate
+  //      transparently with no operator action.
+  //   4. Prompt — the fallback when none of the above apply (e.g. a remote
+  //      `parachute init --cli-wizard` against a public hub, where the probe
+  //      didn't carry the token). The operator reads it from the startup logs.
+  // Treat an empty / whitespace value at any level as "absent" so a falsy
+  // `PARACHUTE_BOOTSTRAP_TOKEN=` (exported-but-empty) doesn't suppress the
+  // loopback-probe token and silently submit a blank token.
+  const firstNonEmpty = (...vals: Array<string | undefined>): string | undefined =>
+    vals.find((v) => typeof v === "string" && v.trim().length > 0);
+  let bootstrap = firstNonEmpty(
+    opts.bootstrapToken,
+    process.env.PARACHUTE_BOOTSTRAP_TOKEN,
+    state.bootstrapToken,
+  );
   if (state.requireBootstrapToken && !bootstrap) {
     log("");
     log("  This hub is in container/serve mode and minted a one-time");