@openparachute/hub 0.5.10 → 0.5.12-rc.2

package/src/hub-server.ts

@@ -48,6 +48,7 @@
  *   /api/modules/:short/upgrade   (POST)       → bun add @<channel> + restart (async op)
  *   /api/modules/:short/uninstall (POST)       → stop child + bun remove + drop row (sync)
  *   /api/modules/operations/:id   (GET)        → poll async op status
+ *   /api/settings/hub-origin      (GET + PUT)  → canonical hub URL (host:admin)
  *   /api/auth/mint-token          (POST)       → CLI/automation token mint (bearer)
  *   /api/auth/revoke-token        (POST)       → revoke registry-row token by jti
  *   /api/auth/tokens              (GET)        → paginated registry list
@@ -125,6 +126,7 @@ import {
 import { handleApiModules, handleApiModulesChannel } from "./api-modules.ts";
 import { REVOCATION_LIST_MOUNT, handleRevocationList } from "./api-revocation-list.ts";
 import { handleApiRevokeToken } from "./api-revoke-token.ts";
+import { handleApiSettingsHubOrigin } from "./api-settings-hub-origin.ts";
 import { handleApiTokens } from "./api-tokens.ts";
 import {
   handleCreateUser,
@@ -138,6 +140,7 @@ import { ensureCsrfToken } from "./csrf.ts";
 import { readExposeState } from "./expose-state.ts";
 import { HUB_DEFAULT_PORT, HUB_SVC, clearHubPort, writeHubPort } from "./hub-control.ts";
 import { hubDbPath, openHubDb } from "./hub-db.ts";
+import { getHubOrigin } from "./hub-settings.ts";
 import { type RenderHubOpts, renderHub } from "./hub.ts";
 import { pemToJwk } from "./jwks.ts";
 import {
@@ -289,6 +292,27 @@ export function findVaultUpstream(
   return best;
 }
 
+/**
+ * True iff at least one vault module is registered in services.json. Drives
+ * the wizard-resume redirect on `/` and `/hub.html` (Issue 2 of the
+ * first-boot-path hardening bundle): an env-seeded admin with no vault
+ * still needs the wizard, so `/` should funnel them there rather than
+ * render the empty discovery portal.
+ *
+ * Reads services.json on every check (cheap — single ~KB parse) so a
+ * vault provisioned seconds ago un-gates the discovery page without a
+ * hub restart. Returns `false` on a malformed services.json — safer to
+ * surface the wizard than to 500 the operator's first page load.
+ */
+function hasVaultInstalled(manifestPath: string): boolean {
+  try {
+    const services = readManifest(manifestPath).services;
+    return services.some((s) => isVaultEntry(s));
+  } catch {
+    return false;
+  }
+}
+
 /**
  * The trust layer a request arrived through. Hub binds `127.0.0.1:1939`, so
  * every request reaches it via one of three trusted forwarders (or directly
@@ -866,6 +890,57 @@ function dbNotConfigured(): Response {
   );
 }
 
+/**
+ * Resolve the OAuth issuer URL for this request. Precedence, highest
+ * first (hub#298):
+ *
+ *   1. `hub_settings.hub_origin` — operator-set canonical URL from the
+ *      admin SPA. Wins when present.
+ *   2. `configuredIssuer` — `--issuer` flag or `PARACHUTE_HUB_ORIGIN`
+ *      env var captured at hub start. The deploy-time setting.
+ *   3. `new URL(req.url).origin` — the request's own origin. Local dev
+ *      + Render-assigned subdomains land here when nothing's been
+ *      configured.
+ *
+ * Per-request (not cached at hub start) so a PUT to
+ * `/api/settings/hub-origin` takes effect on the next request without a
+ * restart. The hub_settings read is a single small SQLite query — cheap
+ * relative to JWT signing on the same request path.
+ *
+ * `db` is optional because the wellknown / discovery surfaces are
+ * reachable on a hub with no DB configured (the dbNotConfigured 503
+ * gate sits behind these in the dispatcher). In that case we skip the
+ * settings layer and fall through to env/request precedence.
+ */
+export function resolveIssuer(
+  req: Request,
+  db: Database | undefined,
+  configuredIssuer: string | undefined,
+): string {
+  if (db !== undefined) {
+    const stored = getHubOrigin(db);
+    if (stored) return stored;
+  }
+  if (configuredIssuer) return configuredIssuer;
+  return new URL(req.url).origin;
+}
+
+/**
+ * Where did the resolved issuer come from? Drives the source-label
+ * surfaced in the admin SPA so operators can tell which precedence
+ * layer they're on without inspecting the DB or env.
+ */
+export type IssuerSource = "settings" | "env" | "request";
+
+export function resolveIssuerSource(
+  db: Database | undefined,
+  configuredIssuer: string | undefined,
+): IssuerSource {
+  if (db !== undefined && getHubOrigin(db)) return "settings";
+  if (configuredIssuer) return "env";
+  return "request";
+}
+
 export function hubFetch(
   wellKnownDir: string,
   deps?: HubFetchDeps,
@@ -889,7 +964,7 @@ export function hubFetch(
     });
 
   const oauthDeps = (req: Request) => {
-    const issuer = configuredIssuer ?? new URL(req.url).origin;
+    const issuer = resolveIssuer(req, getDb?.(), configuredIssuer);
     return {
       issuer,
       // Per-request resolution (closes #245): expose-state.json can change
@@ -1061,23 +1136,43 @@ export function hubFetch(
       return new Response("not found", { status: 404 });
     }
 
-    // Fresh-hub redirect: on a hub with no admin row yet, the discovery
-    // page (`/`, `/hub.html`) funnels straight to the wizard. The static
-    // portal isn't useful pre-setup — nothing's installed, the
-    // "Signed in" affordance has no session to surface — and the
-    // operator landing on `/` in a browser otherwise has to manually
-    // type `/admin/setup` to escape. 302 (not 301) so the redirect
-    // disappears the moment the wizard finishes.
+    // Fresh-hub redirect: when the wizard still has work to do, the
+    // discovery page (`/`, `/hub.html`) funnels straight to it. Two
+    // wizard-mode conditions trigger the redirect:
     //
-    // Sits before the JSON-shaped 503 gate below because `/` is an
-    // HTML surface — a JSON 503 there would render as raw text in the
-    // operator's browser tab. The 503 gate handles API + admin SPA +
-    // OAuth callers that branch on the structured body.
-    if (getDb && (pathname === "/" || pathname === "/hub.html") && userCount(getDb()) === 0) {
-      return new Response(null, {
-        status: 302,
-        headers: { location: "/admin/setup" },
-      });
+    //   1. No admin row exists (the original fresh-deploy case). The
+    //      static portal carries no usable signal — no installed
+    //      services to discover, no admin to sign in as.
+    //   2. Admin exists but no vault is installed (env-seed deploys
+    //      where the operator baked admin into env vars but hasn't
+    //      walked the wizard's vault step). Pre-fix, env-seeded
+    //      operators bounced past the wizard entirely and had to
+    //      hand-find /admin/modules + /admin/vaults; surface
+    //      "let me finish the wizard" instead.
+    //
+    // The wizard's GET handler already picks the right step
+    // (`deriveWizardState` resumes at vault step when admin exists +
+    // no vault), so we just need the redirect to fire.
+    //
+    // 302 (not 301) so the redirect disappears the moment the wizard
+    // finishes. Sits before the JSON-shaped 503 gate below because `/`
+    // is an HTML surface — a JSON 503 there would render as raw text
+    // in the operator's browser tab. The 503 gate handles API + admin
+    // SPA + OAuth callers that branch on the structured body.
+    if (getDb && (pathname === "/" || pathname === "/hub.html")) {
+      const db = getDb();
+      // Either condition triggers the wizard funnel:
+      //   - no admin row (the fresh-deploy case)
+      //   - admin row exists but no vault installed (env-seed case)
+      // Short-circuit the manifest read when `noAdmin` is true; the
+      // wizard's first step is admin creation regardless of vault state.
+      const needsWizard = userCount(db) === 0 || !hasVaultInstalled(manifestPath);
+      if (needsWizard) {
+        return new Response(null, {
+          status: 302,
+          headers: { location: "/admin/setup" },
+        });
+      }
     }
 
     // Pre-admin lockout. When the hub has booted with no admin row (the
@@ -1173,7 +1268,15 @@ export function hubFetch(
       // the request's own origin (fine for direct loopback hits).
       try {
         const manifest = readManifest(manifestPath);
-        const canonicalOrigin = configuredIssuer ?? new URL(req.url).origin;
+        // Same precedence as the OAuth issuer (hub#298): hub_settings →
+        // env → request origin. The well-known doc embeds this origin
+        // in service URLs + the issuer metadata link, so it must follow
+        // the same chain — otherwise a public-domain operator who set
+        // `hub_origin` would still see the Render-assigned URL on
+        // `/.well-known/parachute.json` while their JWTs carry the
+        // canonical URL, and discovery clients would split-brain on
+        // which one to trust.
+        const canonicalOrigin = resolveIssuer(req, getDb?.(), configuredIssuer);
         const readManifestFn = deps?.readModuleManifest ?? defaultReadModuleManifest;
         const [managementUrlByName, serviceUiMeta] = await Promise.all([
           loadManagementUrls(manifest.services, readManifestFn),
@@ -1398,6 +1501,21 @@ export function hubFetch(
       });
     }
 
+    // Canonical hub URL (hub#298). Admin SPA reads + writes the
+    // operator-set issuer override. The handler computes the resolved
+    // issuer + source here so it can surface them in the GET payload
+    // without re-walking the precedence chain inside the handler.
+    if (pathname === "/api/settings/hub-origin") {
+      if (!getDb) return dbNotConfigured();
+      const db = getDb();
+      return handleApiSettingsHubOrigin(req, {
+        db,
+        issuer: oauthDeps(req).issuer,
+        resolvedIssuer: resolveIssuer(req, db, configuredIssuer),
+        resolvedSource: resolveIssuerSource(db, configuredIssuer),
+      });
+    }
+
     // Module operation poll surface — pre-empts the /api/modules/:short/*
     // routes below so `/api/modules/operations/<uuid>` doesn't accidentally
     // match a parseModulesPath("/operations") and fall through.

package/src/hub-settings.ts

@@ -52,7 +52,21 @@ export type HubSettingKey =
   // channel); after the first seed the row is source of truth and the
   // env var is ignored — admin must use the SPA toggle (or
   // `PUT /api/modules/channel`) to change channel.
-  | "module_install_channel";
+  | "module_install_channel"
+  // hub#298: operator-settable canonical hub URL. The value (when set)
+  // is the OAuth issuer claim stamped into every JWT minted by hub.
+  // Precedence on each request: this row, then `PARACHUTE_HUB_ORIGIN`
+  // env, then `new URL(req.url).origin` as the local-dev fallback.
+  //
+  // Storing the canonical origin in hub_settings (rather than relying
+  // solely on the env var) lets a Render operator attach a custom
+  // domain after first boot + flip the issuer URL from the admin SPA
+  // without restarting the container. Tokens minted before the change
+  // carry the old `iss` claim; tokens minted after carry the new one.
+  // Operators must accept that flipping the canonical hub URL
+  // invalidates any tokens already in circulation (issuer mismatch on
+  // verification) — surfaced in the admin SPA's helper copy.
+  | "hub_origin";
 
 export type SetupExposeMode = "localhost" | "tailnet" | "public";
 
@@ -257,3 +271,41 @@ export function getModuleInstallChannel(
 export function setModuleInstallChannel(db: Database, channel: ModuleInstallChannel): void {
   setSetting(db, "module_install_channel", channel);
 }
+
+// --- domain helpers: canonical hub origin --------------------------------
+
+/**
+ * Read the operator-set canonical hub origin from hub_settings. Returns
+ * `null` when no row is present — callers fall through to env / request-
+ * origin precedence in that case (see `resolveIssuer` in hub-server).
+ *
+ * Unlike `module_install_channel` this helper does NOT seed from env on
+ * first read. The env var (`PARACHUTE_HUB_ORIGIN`) remains a separate
+ * precedence layer below this one — operators who set the env var still
+ * see "from env" attribution in the admin SPA. Auto-seeding would
+ * collapse that layer into the row + lose the source attribution.
+ */
+export function getHubOrigin(db: Database): string | null {
+  const value = getSetting(db, "hub_origin");
+  return value ?? null;
+}
+
+/**
+ * Write or clear the canonical hub origin. Passing `null` deletes the
+ * row, reverting to env / request-origin precedence on subsequent
+ * requests. The caller must have validated the URL shape — the
+ * function trusts the input and writes verbatim (mirrors
+ * `setModuleInstallChannel`'s "typed-callsite is the contract" stance).
+ *
+ * Empty-string is treated as null (the value would never be a useful
+ * issuer) to avoid storing a row that no codepath would honor — the
+ * resolveIssuer fallback chain would skip it as falsy and the source
+ * label would lie about where the value came from.
+ */
+export function setHubOrigin(db: Database, value: string | null): void {
+  if (value === null || value === "") {
+    deleteSetting(db, "hub_origin");
+    return;
+  }
+  setSetting(db, "hub_origin", value);
+}

package/src/oauth-ui.ts

@@ -359,10 +359,30 @@ export function renderApprovePending(props: ApprovePendingViewProps): string {
     approveForm,
   } = props;
   const redirectList = redirectUris.map((u) => `<li><code>${escapeHtml(u)}</code></li>`).join("");
+  // Substitute unnamed `vault:<verb>` rows with the wildcard display form
+  // (`vault:*:<verb>`) so the operator sees the shape that will appear in
+  // the token after consent narrows the scope to a specific vault. At
+  // approve time no vault has been picked yet — the SPA's
+  // `/admin/approve-client/<id>` view uses the same wildcard treatment
+  // (see `resolveScopeForDisplay` in `web/ui/src/routes/ApproveClient.tsx`).
+  const displayedScopes = requestedScopes.map((s) => substituteVaultDisplay(s, "*"));
   const scopeRows =
-    requestedScopes.length === 0
+    displayedScopes.length === 0
       ? `<li class="scope scope-empty">No scopes requested — the app gets a session token only.</li>`
-      : requestedScopes.map(renderScopeRow).join("\n");
+      : displayedScopes.map(renderScopeRow).join("\n");
+  // Wildcard explanation: surface the "the asterisk means the vault is
+  // picked later" hint below the scope list when at least one row carries
+  // `vault:*:<verb>`. Mirrors the SPA's inline note on
+  // `/admin/approve-client/<id>`. Omitted when no scope renders with `*`
+  // (all scopes are either non-vault or already-named).
+  const wildcardNote = displayedScopes.some((s) => /^vault:\*:(read|write)$/.test(s))
+    ? `
+        <p class="scope-wildcard-note">
+          <code>*</code> — a specific vault is selected during sign-in via the consent
+          picker (or the user's assigned vault for multi-user setups). The
+          <code>*</code> shows the unbound shape.
+        </p>`
+    : "";
   // Vault hint (closes #244): Notes' VaultPopover (notes#115) passes
   // `vault=<name>` on `/oauth/authorize` for per-vault grants. Surface it
   // alongside scopes so a multi-vault operator can tell which vault they're
@@ -414,7 +434,7 @@ export function renderApprovePending(props: ApprovePendingViewProps): string {
       </section>
       <section class="scopes">
         <h2 class="scopes-title">Permissions requested</h2>
-        <ul class="scope-list">${scopeRows}</ul>
+        <ul class="scope-list">${scopeRows}</ul>${wildcardNote}
       </section>
       ${formSection}
     </div>`;
@@ -507,6 +527,13 @@ function renderUnauthenticatedApproveCtas(hubOrigin: string, clientId: string):
  *     the admin consent screen when the picker hasn't been touched yet, and
  *     on the operator approval page where the vault is selected at the
  *     per-user sign-in step, not at approve time.
+ *   - `displayVault === "*"` → render with a literal asterisk placeholder
+ *     (`vault:*:verb`). Used on the server-rendered approve-pending page
+ *     and the SPA's `/admin/approve-client/<id>` view: at approve time the
+ *     vault isn't bound yet (no consent picker has run), so the asterisk
+ *     signals "wildcard — a specific vault is selected later in the flow."
+ *     Callers that render this form should also surface the inline
+ *     explanation below the scope list (see `renderApprovePending`).
  *   - `displayVault === "name"` → render as `vault:name:verb` literally.
  *
  * Non-vault scopes pass through untouched. Already-named `vault:<x>:<verb>`
@@ -1143,6 +1170,21 @@ const STYLES = `
     color: ${PALETTE.fgDim};
     font-style: italic;
   }
+  .scope-wildcard-note {
+    margin: 0.6rem 0 0;
+    font-size: 0.82rem;
+    color: ${PALETTE.fgDim};
+    font-style: italic;
+    line-height: 1.45;
+  }
+  .scope-wildcard-note code {
+    font-family: ${FONT_MONO};
+    font-style: normal;
+    background: ${PALETTE.bgSoft};
+    padding: 0.05rem 0.3rem;
+    border-radius: 4px;
+    color: ${PALETTE.fgMuted};
+  }
   .badge {
     display: inline-block;
     font-size: 0.7rem;

package/src/setup-wizard.ts

@@ -40,6 +40,12 @@
 import type { Database } from "bun:sqlite";
 import { type OperationsRegistry, runInstall, specFor } from "./api-modules-ops.ts";
 import { CURATED_MODULES, type CuratedModuleShort } from "./api-modules.ts";
+import {
+  BOOTSTRAP_TOKEN_PREFIX,
+  consumeBootstrapToken,
+  getBootstrapToken,
+  verifyBootstrapToken,
+} from "./bootstrap-token.ts";
 import {
   CSRF_FIELD_NAME,
   ensureCsrfToken,
@@ -254,12 +260,60 @@ export interface RenderAccountStepProps {
   errorMessage?: string;
   /** Pre-fill the username field after a validation failure. */
   username?: string;
+  /**
+   * Whether the bootstrap-token field should render and be required.
+   * True under `parachute serve` wizard mode (no admin, no env-seed) —
+   * `commands/serve.ts` mints + logs the token on boot and the form
+   * requires it to claim the admin row. False on the on-box CLI surface
+   * (the operator already has shell access; gating the form behind a
+   * token they'd also need to read from logs adds friction with no
+   * security gain).
+   *
+   * UX: when true, the token field is the FIRST field on the form so
+   * an operator who hasn't seen the log line stops here rather than
+   * filling username + password and bouncing off a 401.
+   */
+  requireBootstrapToken?: boolean;
+  /**
+   * Pre-fill the bootstrap-token field after a validation failure on a
+   * field OTHER than the token itself. We never echo a wrong token back
+   * — the form re-renders with an empty token field so the operator has
+   * to re-look-up the correct value.
+   */
+  bootstrapToken?: string;
 }
 
 export function renderAccountStep(props: RenderAccountStepProps): string {
-  const { csrfToken, errorMessage, username } = props;
+  const { csrfToken, errorMessage, username, requireBootstrapToken, bootstrapToken } = props;
   const error = errorMessage ? `<p class="error-banner">${escapeHtml(errorMessage)}</p>` : "";
   const usernameAttr = username ? ` value="${escapeAttr(username)}"` : "";
+  const tokenAttr = bootstrapToken ? ` value="${escapeAttr(bootstrapToken)}"` : "";
+  // Bootstrap-token field comes FIRST when required. An operator who
+  // missed the log line is stopped here rather than after filling
+  // username + password.
+  const bootstrapField = requireBootstrapToken
+    ? `
+        <label class="field">
+          <span class="field-label">Bootstrap token</span>
+          <input type="text" name="bootstrap_token" autocomplete="off"
+            autofocus required minlength="20" maxlength="200"
+            spellcheck="false" autocapitalize="off"
+            placeholder="${escapeAttr(BOOTSTRAP_TOKEN_PREFIX)}…"${tokenAttr} />
+          <span class="field-hint">Find this in your hub's startup logs.
+            Look for the <code>${escapeHtml(BOOTSTRAP_TOKEN_PREFIX)}</code> line.</span>
+        </label>`
+    : "";
+  // When the token is required we drop `autofocus` off the username field
+  // so it doesn't fight the token field's focus.
+  const usernameAutofocus = requireBootstrapToken ? "" : " autofocus";
+  const tokenCallout = requireBootstrapToken
+    ? `<aside class="bootstrap-callout">
+        <strong>One-time setup credential.</strong> This hub was deployed without
+        baked-in admin credentials, so it generated a one-time bootstrap token
+        on startup. Paste it below to claim the admin account. The token
+        expires once the admin is created (or when the hub restarts).
+      </aside>`
+    : "";
   const body = `
     <div class="card">
       <div class="card-header">
@@ -278,13 +332,15 @@ export function renderAccountStep(props: RenderAccountStepProps): string {
         <p>After this you'll name your first vault. The hub will install it
           and issue a token your Claude Code MCP client can use.</p>
       </section>
+      ${tokenCallout}
       ${error}
       <form method="POST" action="/admin/setup/account" class="auth-form">
         ${renderCsrfHiddenInput(csrfToken)}
+        ${bootstrapField}
         <label class="field">
           <span class="field-label">Username</span>
-          <input type="text" name="username" autocomplete="username"
-            autofocus required minlength="2" maxlength="64"
+          <input type="text" name="username" autocomplete="username"${usernameAutofocus}
+            required minlength="2" maxlength="64"
             pattern="[A-Za-z0-9_.-]+" title="letters, digits, _ . - (2–64 chars)"
             ${usernameAttr} />
           <span class="field-hint">letters, digits, <code>_</code>, <code>.</code>, <code>-</code></span>
@@ -307,7 +363,8 @@ export function renderAccountStep(props: RenderAccountStepProps): string {
         <p>Set <code>PARACHUTE_INITIAL_ADMIN_USERNAME</code> and
           <code>PARACHUTE_INITIAL_ADMIN_PASSWORD</code> on the container and
           restart. The hub will create the admin row on next boot and skip this
-          wizard.</p>
+          wizard (no bootstrap token needed — the env vars themselves are the
+          claim).</p>
       </details>
     </div>`;
   return baseDocument("Set up your Parachute hub — account", body);
@@ -1049,11 +1106,23 @@ export function handleSetupGet(req: Request, deps: SetupWizardDeps): Response {
     });
   }
 
-  // Step 1+2 (no admin yet).
-  return new Response(renderAccountStep({ csrfToken: csrf.token }), {
-    status: 200,
-    headers: extraHeaders,
-  });
+  // Step 1+2 (no admin yet). Render with the bootstrap-token field iff a
+  // token is currently active — `commands/serve.ts` only mints one on
+  // wizard-mode boot (no env-seed), so the field's presence is a 1:1
+  // signal of "the operator needs a token to claim this hub." On the
+  // on-box CLI surface and on env-seed-followed-by-deleted-admin paths,
+  // the token is absent and the form renders the historical shape.
+  const requireToken = getBootstrapToken() !== undefined;
+  return new Response(
+    renderAccountStep({
+      csrfToken: csrf.token,
+      requireBootstrapToken: requireToken,
+    }),
+    {
+      status: 200,
+      headers: extraHeaders,
+    },
+  );
 }
 
 /**
@@ -1076,17 +1145,65 @@ export async function handleSetupAccountPost(
     return badRequestPage("Invalid form submission", "Reload and try again.");
   }
   // Already-bootstrapped: bounce. The wizard's GET state will resolve to
-  // step 3 or step 4 on the next request.
+  // step 3 or step 4 on the next request. We return 410 Gone for the
+  // case where a bootstrap token was active this boot AND has already
+  // been consumed by a prior POST — distinguishes "you missed your
+  // window" from "this hub never had a wizard-mode boot" so a racing
+  // attacker sees a hard-stop rather than a soft redirect.
+  const csrfToken = typeof formCsrf === "string" ? formCsrf : "";
+  const requireToken = getBootstrapToken() !== undefined;
   if (userCount(deps.db) > 0) {
-    return redirect("/admin/setup");
+    if (!requireToken) {
+      return redirect("/admin/setup");
+    }
+    // Defense in depth: a token was active but an admin already exists.
+    // Treat as consumed.
+    return new Response(renderClaimAlreadyHappenedPage(), {
+      status: 410,
+      headers: { "content-type": "text/html; charset=utf-8" },
+    });
+  }
+  // Bootstrap-token gate. Only enforced when wizard mode is active —
+  // env-seed admins never reach this path (they're admin-exists by
+  // boot time), CLI mode never mints a token (the on-box operator
+  // already has shell auth). Wrong token → 401 + form re-render with
+  // an empty token field; right token → fall through.
+  if (requireToken) {
+    const suppliedToken = String(form.get("bootstrap_token") ?? "").trim();
+    if (!verifyBootstrapToken(suppliedToken)) {
+      const username = String(form.get("username") ?? "").trim();
+      return htmlResponse(
+        renderAccountStep({
+          csrfToken,
+          username,
+          requireBootstrapToken: true,
+          // Deliberately do NOT echo the wrong supplied token back —
+          // forces re-look-up rather than tab-completing a typo.
+          errorMessage:
+            "Wrong bootstrap token. Re-check your hub's startup logs for the " +
+            "`parachute-bootstrap-…` line and try again.",
+        }),
+        401,
+      );
+    }
   }
   const username = String(form.get("username") ?? "").trim();
   const password = String(form.get("password") ?? "");
   const confirm = String(form.get("password_confirm") ?? "");
-  const csrfToken = typeof formCsrf === "string" ? formCsrf : "";
   const fieldErr = validateAccountFields({ username, password, confirm });
   if (fieldErr) {
-    return htmlResponse(renderAccountStep({ csrfToken, username, errorMessage: fieldErr }), 400);
+    return htmlResponse(
+      renderAccountStep({
+        csrfToken,
+        username,
+        // Re-render with the token field present iff still required (it
+        // was valid this attempt — the field-error came from username/
+        // password). Empty value so the operator pastes again.
+        requireBootstrapToken: requireToken,
+        errorMessage: fieldErr,
+      }),
+      400,
+    );
   }
   try {
     // Wizard-admin chose their password through this very form; skip the
@@ -1095,6 +1212,14 @@ export async function handleSetupAccountPost(
     // (the wizard never asks the first admin to pin themselves to a
     // single vault; that's a non-admin user pattern).
     const user = await createUser(deps.db, username, password, { passwordChanged: true });
+    // Consume the bootstrap token AFTER the admin row is committed.
+    // Doing it before would let a `createUser` exception (UNIQUE-collision,
+    // disk full, anything) leave the token un-consumed but the admin row
+    // partially written — and the operator without a way to retry.
+    // Doing it after means a successful claim invalidates the token for
+    // any racer who saw it over the operator's shoulder during the
+    // window between log-print and form-submit.
+    if (requireToken) consumeBootstrapToken();
     const session = createSession(deps.db, { userId: user.id });
     const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000), {
       secure: isHttpsRequest(req),
@@ -1116,6 +1241,7 @@ export async function handleSetupAccountPost(
       renderAccountStep({
         csrfToken,
         username,
+        requireBootstrapToken: requireToken,
         errorMessage: "Failed to create account. The username may already be taken.",
       }),
       400,
@@ -1123,6 +1249,34 @@ export async function handleSetupAccountPost(
   }
 }
 
+/**
+ * Static error page surfaced when an `/admin/setup/account` POST arrives
+ * after the bootstrap token has already been consumed by a successful
+ * admin claim. Returned with HTTP 410 Gone (vs. the 302 redirect a
+ * stale-tab without a token gets) so a scripted attacker reading the
+ * status code sees an unmistakable "you missed the window" signal.
+ *
+ * No retry CTA — the wizard is past its account step; pointing the
+ * operator at /login is the right answer.
+ */
+function renderClaimAlreadyHappenedPage(): string {
+  const body = `
+    <div class="card">
+      ${header("account")}
+      <h1 class="error-title">Admin already claimed</h1>
+      <p class="subtitle">This hub's bootstrap token was already used to
+        create the admin account. The token is one-shot — it can't be
+        reused to claim a second admin or rotate the existing one.</p>
+      <p class="subtitle">If you're the legitimate operator, sign in at
+        <a href="/login"><code>/login</code></a>. If you've lost the
+        password, restart the hub (which mints a fresh token) and use
+        <code>parachute auth set-password</code> from a shell with
+        access to the hub's PARACHUTE_HOME.</p>
+      <p><a class="btn btn-primary" href="/login">Go to sign-in</a></p>
+    </div>`;
+  return baseDocument("Admin already claimed", body);
+}
+
 /**
  * POST `/admin/setup/vault`. Form-encoded.
  *
@@ -1954,6 +2108,17 @@ const STYLES = `
   }
   .error-title { color: ${PALETTE.danger}; }
 
+  .bootstrap-callout {
+    background: ${PALETTE.warnSoft};
+    border-left: 3px solid ${PALETTE.warn};
+    border-radius: 0 6px 6px 0;
+    padding: 0.7rem 0.9rem;
+    margin: 0 0 1rem;
+    font-size: 0.9rem;
+    color: ${PALETTE.fg};
+  }
+  .bootstrap-callout strong { color: ${PALETTE.fg}; }
+
   .op-log {
     background: ${PALETTE.bg};
     border: 1px solid ${PALETTE.borderLight};