@openparachute/hub 0.5.14-rc.2 → 0.5.14-rc.21

package/src/account-vault-token.ts

@@ -0,0 +1,282 @@
+/**
+ * `POST /account/vault-token/<name>` — friend-facing scoped vault token mint.
+ *
+ * A non-admin friend with a hub session is ALREADY authorized for their
+ * assigned vault(s): the OAuth issuer mints `vault:<assigned>:read|write` for
+ * them on the no-token connect path. This endpoint lets the same friend mint
+ * that same authority *in token form* — a long-lived bearer for a script or
+ * headless client that can't open a browser to do interactive OAuth. It is
+ * the same authority, just materialized; no escalation.
+ *
+ * Authorization — the security spine of this surface. The mint is capped to
+ * the caller's own authority by three gates, in order:
+ *
+ *   1. **Session.** A valid, unexpired hub session cookie is required (the
+ *      friend's). No session → 401. (Resolved via `findActiveSession`, the
+ *      same gate `/account/change-password` uses.)
+ *   2. **Assignment.** The requested `<name>` MUST be one of the session
+ *      user's `user_vaults` assignments. A vault the user is not assigned to
+ *      → 403. This is what blocks "mint for a vault I'm not assigned" and
+ *      cross-vault minting. Read directly from `user_vaults` via
+ *      `vaultVerbsForUserVault` (which returns `null` for an unassigned
+ *      vault), NOT from the verb-blind `assignedVaults` array.
+ *   3. **Scope cap.** The requested verb MUST be one the user's assignment
+ *      role permits, and may only ever be `read` or `write` — NEVER `admin`,
+ *      never a broader scope than the user holds. `vaultVerbsForUserVault`
+ *      returns the role's verb set (today always `["read", "write"]` since
+ *      every assignment is `role = 'write'`); a verb outside that set → 403.
+ *      `admin` is not in the form's vocabulary at all and is rejected at the
+ *      parse step as an invalid verb.
+ *
+ * The first admin (unrestricted, empty `assignedVaults`) has no `user_vaults`
+ * rows, so gate 2 returns `null` for every vault and the admin gets a 403
+ * here too — by design. Admins mint vault tokens through the admin SPA's
+ * tokens page (`/admin/vault-admin-token/<name>` → `/api/auth/mint-token`),
+ * not this friend surface. This endpoint is exclusively the friend path.
+ *
+ * CSRF: double-submit cookie, same `__csrf` field + `verifyCsrfToken` as
+ * `/account/change-password` and `/logout`. A cross-site POST without the
+ * matching cookie/form token → 400.
+ *
+ * Rate limit: `vaultTokenMintRateLimiter`, per-user (10 / 10 min). Fires
+ * after CSRF (so a junk cross-site POST doesn't burn the victim's bucket)
+ * and before the mint. A floor against a stolen-cookie mint flood, not the
+ * primary defense.
+ *
+ * Mint: `signAccessToken` (the same machinery the OAuth issuer + admin paths
+ * use — no hand-rolled JWT signing) with:
+ *   - `scopes: ["vault:<name>:<verb>"]`
+ *   - `audience: "vault.<name>"` (via `inferAudience`; vault validates this
+ *     against its URL-derived name — identical to the OAuth + admin mints)
+ *   - `iss`: the hub origin
+ *   - `sub`: the friend's user id
+ *   - `vaultScope: [<name>]` — pins the token to that one vault (defense in
+ *     depth, mirrors the admin vault-token + the rule-2/3 mints in
+ *     `api-mint-token.ts`)
+ *   - `ttlSeconds`: 90 days (`ACCOUNT_VAULT_TOKEN_TTL_SECONDS`, matching the
+ *     CLI/api-mint default)
+ * and a `tokens` registry row via `recordTokenMint` (`created_via='cli_mint'`,
+ * `userId` = the friend) so the token shows up in the revocation list and the
+ * operator's token registry.
+ *
+ * Response: a re-render of `/account/` (server-rendered, no-JS posture) with
+ * the token shown ONCE in a banner. The hub keeps no plaintext copy, so this
+ * is the only moment the token string is visible.
+ */
+import type { Database } from "bun:sqlite";
+import {
+  ACCOUNT_VAULT_TOKEN_TTL_SECONDS,
+  type MintedTokenView,
+  renderAccountHome,
+} from "./account-home-ui.ts";
+import { renderAdminError } from "./admin-login-ui.ts";
+import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
+import { inferAudience } from "./jwt-audience.ts";
+import { recordTokenMint, signAccessToken } from "./jwt-sign.ts";
+import { vaultTokenMintRateLimiter } from "./rate-limit.ts";
+import { findActiveSession } from "./sessions.ts";
+import { isTotpEnrolled } from "./two-factor-store.ts";
+import { type VaultVerb, getUserById, isFirstAdmin, vaultVerbsForUserVault } from "./users.ts";
+
+/** Matches the manifest vault-name validator + `/admin/vault-admin-token`. */
+const VAULT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+/** Verbs this surface will ever mint. `admin` is deliberately absent. */
+const ALLOWED_VERBS: readonly VaultVerb[] = ["read", "write"];
+/** client_id stamped on the minted JWT + registry row. */
+const ACCOUNT_VAULT_TOKEN_CLIENT_ID = "parachute-account";
+
+export interface AccountVaultTokenDeps {
+  db: Database;
+  /** Hub origin for this request — `iss` of the minted token. */
+  hubOrigin: string;
+  /** Test seam for the clock (rate limiter + mint). */
+  now?: () => Date;
+}
+
+function htmlResponse(body: string, status = 200, extra: Record<string, string> = {}): Response {
+  return new Response(body, {
+    status,
+    headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", ...extra },
+  });
+}
+
+/**
+ * Build the `mintableVerbs` map the account-home renderer needs: each of the
+ * user's assigned vaults → the verbs its role permits. Used both on the
+ * success re-render (so every tile keeps its mint affordance) and the error
+ * re-render. Mirrors the GET handler's construction.
+ */
+function buildMintableVerbs(
+  db: Database,
+  userId: string,
+  assignedVaults: readonly string[],
+): Record<string, VaultVerb[]> {
+  const map: Record<string, VaultVerb[]> = {};
+  for (const v of assignedVaults) {
+    const verbs = vaultVerbsForUserVault(db, userId, v);
+    if (verbs && verbs.length > 0) map[v] = verbs;
+  }
+  return map;
+}
+
+export async function handleAccountVaultTokenPost(
+  req: Request,
+  vaultName: string,
+  deps: AccountVaultTokenDeps,
+): Promise<Response> {
+  if (req.method !== "POST") {
+    return htmlResponse("method not allowed", 405);
+  }
+
+  // Gate 1 — session. No identity, no mint.
+  const session = findActiveSession(deps.db, req);
+  if (!session) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Not signed in",
+        message: "Please sign in before minting an access token.",
+      }),
+      401,
+    );
+  }
+  const user = getUserById(deps.db, session.userId);
+  if (!user) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Account not found",
+        message: "The signed-in account no longer exists. Please sign in again.",
+      }),
+      401,
+    );
+  }
+
+  // CSRF — verify before any state change / rate-limit bucket touch, same
+  // shape + 400 status as `/account/change-password`.
+  const form = await req.formData();
+  const formCsrf = form.get(CSRF_FIELD_NAME);
+  if (!verifyCsrfToken(req, typeof formCsrf === "string" ? formCsrf : null)) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Invalid form submission",
+        message: "The form's CSRF token did not match. Reload the page and try again.",
+      }),
+      400,
+    );
+  }
+
+  // Helper to re-render the account home (success banner or inline error).
+  // Re-resolves the CSRF token + 2FA state so the page stays fully usable.
+  const renderHome = (
+    status: number,
+    extras: { mintedToken?: MintedTokenView; mintError?: string },
+  ): Response => {
+    const csrf = ensureCsrfToken(req);
+    const setCookie: Record<string, string> = csrf.setCookie
+      ? { "set-cookie": csrf.setCookie }
+      : {};
+    const adminFlag = isFirstAdmin(deps.db, user.id);
+    return htmlResponse(
+      renderAccountHome({
+        username: user.username,
+        assignedVaults: user.assignedVaults,
+        passwordChanged: user.passwordChanged,
+        hubOrigin: deps.hubOrigin,
+        isFirstAdmin: adminFlag,
+        csrfToken: csrf.token,
+        twoFactorEnabled: isTotpEnrolled(deps.db, user.id),
+        mintableVerbs: buildMintableVerbs(deps.db, user.id, user.assignedVaults),
+        ...extras,
+      }),
+      status,
+      setCookie,
+    );
+  };
+
+  // Vault-name shape guard — reject anything that can't be a services.json
+  // key before any DB / authority work (router can hand us arbitrary path
+  // segments). Same posture as `/admin/vault-admin-token`.
+  if (!VAULT_NAME_RE.test(vaultName)) {
+    return renderHome(400, { mintError: `"${vaultName}" is not a valid vault name.` });
+  }
+
+  // Verb parse — must be exactly one of read/write. `admin` (or anything
+  // else) is not in this surface's vocabulary and is rejected here, well
+  // before authority is even consulted.
+  const verbRaw = form.get("verb");
+  const verb = typeof verbRaw === "string" ? verbRaw : "";
+  if (!ALLOWED_VERBS.includes(verb as VaultVerb)) {
+    return renderHome(400, {
+      mintError: "Pick an access level (read or write).",
+    });
+  }
+  const requestedVerb = verb as VaultVerb;
+
+  // Gate 2 + 3 — assignment + scope cap. `vaultVerbsForUserVault` returns:
+  //   - null  → the user has NO assignment for this vault (gate 2 fail): 403.
+  //   - []    → assignment exists but its role grants no mintable verb
+  //             (fail-closed for an unknown role): 403.
+  //   - [...] → the verbs the assignment role permits. The requested verb
+  //             must be in this set (gate 3): else 403.
+  // This is the cap to the user's actual authority — it blocks minting for
+  // an unassigned vault, a broader verb than the role grants, and (since the
+  // set never contains `admin`) any admin escalation.
+  const allowedForUser = vaultVerbsForUserVault(deps.db, user.id, vaultName);
+  if (allowedForUser === null) {
+    return renderHome(403, {
+      mintError: `You're not assigned to a vault named "${vaultName}", so you can't mint a token for it. Ask the hub operator if you think this is wrong.`,
+    });
+  }
+  if (!allowedForUser.includes(requestedVerb)) {
+    return renderHome(403, {
+      mintError: `Your access to "${vaultName}" doesn't allow minting a ${requestedVerb} token.`,
+    });
+  }
+
+  // Rate limit — after CSRF + authority shape, before the mint. Per-user.
+  const rlNow = (deps.now ?? (() => new Date()))();
+  const gate = vaultTokenMintRateLimiter.checkAndRecord(user.id, rlNow);
+  if (!gate.allowed) {
+    return renderHome(429, {
+      mintError: `Too many token-mint attempts. Try again in ${gate.retryAfterSeconds ?? 1} seconds.`,
+    });
+  }
+
+  // Mint — the same machinery the OAuth issuer + admin paths use. The scope
+  // is exactly the capped `vault:<name>:<verb>`; the audience binds the token
+  // to that one vault; `vaultScope` pins it as defense in depth.
+  const scope = `vault:${vaultName}:${requestedVerb}`;
+  const audience = inferAudience([scope]); // → `vault.<name>`
+  const minted = await signAccessToken(deps.db, {
+    sub: user.id,
+    scopes: [scope],
+    audience,
+    clientId: ACCOUNT_VAULT_TOKEN_CLIENT_ID,
+    issuer: deps.hubOrigin,
+    ttlSeconds: ACCOUNT_VAULT_TOKEN_TTL_SECONDS,
+    vaultScope: [vaultName],
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  });
+
+  recordTokenMint(deps.db, {
+    jti: minted.jti,
+    createdVia: "cli_mint",
+    subject: user.id,
+    // Anchor the registry row to the friend's user id so the operator's
+    // token registry + the revocation list attribute it correctly, and a
+    // future per-user revoke surface can find it.
+    userId: user.id,
+    clientId: ACCOUNT_VAULT_TOKEN_CLIENT_ID,
+    scopes: [scope],
+    expiresAt: minted.expiresAt,
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  });
+
+  return renderHome(200, {
+    mintedToken: {
+      vaultName,
+      verb: requestedVerb,
+      token: minted.token,
+      expiresInDays: Math.round(ACCOUNT_VAULT_TOKEN_TTL_SECONDS / (24 * 60 * 60)),
+    },
+  });
+}

package/src/admin-handlers.ts

@@ -11,9 +11,17 @@
  * (`parachute_hub_csrf` cookie + `__csrf` form field, constant-time compare).
  */
 import type { Database } from "bun:sqlite";
-import { renderAdminError, renderAdminLogin } from "./admin-login-ui.ts";
+import { renderAdminError, renderAdminLogin, renderTotpChallenge } from "./admin-login-ui.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
-import { checkAndRecord, clientIpFromRequest } from "./rate-limit.ts";
+import {
+  buildPendingLoginClearCookie,
+  buildPendingLoginCookie,
+  consumePendingLogin,
+  createPendingLogin,
+  getPendingLogin,
+  parsePendingLoginCookie,
+} from "./pending-login.ts";
+import { checkAndRecord, clientIpFromRequest, totpRateLimiter } from "./rate-limit.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
 import {
   SESSION_TTL_MS,
@@ -23,9 +31,11 @@ import {
   deleteSession,
   parseSessionCookie,
 } from "./sessions.ts";
+import { isTotpEnrolled, verifySecondFactor } from "./two-factor-store.ts";
 import {
   PASSWORD_MAX_LEN,
   type User,
+  getUserById,
   getUserByUsername,
   isFirstAdmin,
   verifyPassword,
@@ -214,8 +224,42 @@ export async function handleAdminLoginPost(
       401,
     );
   }
+
+  // 2FA gate (hub#473). If the user has TOTP enrolled, the password is only
+  // the *first* factor — do NOT mint a session yet. Stash a short-lived
+  // pending-login (server-side, keyed by an opaque cookie token) and render
+  // the "enter your code" page. The session is minted in
+  // `handleAdminLoginTotpPost` only after the second factor verifies.
+  // Users WITHOUT 2FA fall through to the existing password-only path
+  // unchanged — existing operators keep signing in exactly as before.
+  if (isTotpEnrolled(db, user.id)) {
+    const pendingToken = createPendingLogin(user.id, next);
+    // Reuse the same CSRF token (cookie unchanged) for the challenge form.
+    return htmlResponse(renderTotpChallenge({ next, csrfToken }), 200, {
+      "set-cookie": buildPendingLoginCookie(pendingToken, req),
+    });
+  }
+
+  return mintSessionAndRedirect(db, req, user, next);
+}
+
+/**
+ * Mint a session for an authenticated user and 302 to the resolved target.
+ * Shared by the password-only login path and the post-2FA path so both apply
+ * the identical force-change-password / friend-rewrite redirect logic.
+ *
+ * `extraCookies` lets the 2FA path also clear the pending-login cookie in the
+ * same response.
+ */
+function mintSessionAndRedirect(
+  db: Database,
+  req: Request,
+  user: User,
+  next: string,
+  extraCookies: string[] = [],
+): Response {
   const session = createSession(db, { userId: user.id });
-  const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000), {
+  const sessionCookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000), {
     secure: isHttpsRequest(req),
   });
   // Multi-user Phase 1 PR 3 — `password_changed === false` (admin-created
@@ -226,7 +270,118 @@ export async function handleAdminLoginPost(
   // `next` rides along on the change-password URL so the post-change
   // POST can land them at their intended destination.
   const target = loginRedirectTarget(db, user, next);
-  return redirect(target, { "set-cookie": cookie });
+  const headers = new Headers({ location: target });
+  headers.append("set-cookie", sessionCookie);
+  for (const c of extraCookies) headers.append("set-cookie", c);
+  return new Response(null, { status: 302, headers });
+}
+
+/**
+ * POST `/login/2fa` — the second-factor step (hub#473).
+ *
+ * Reached only after a correct password POST for a 2FA-enrolled user handed
+ * back a pending-login cookie. Order of checks:
+ *   1. CSRF (else 400 — same shape as `/login`).
+ *   2. Per-IP rate-limit (5 / 15 min) BEFORE the factor check, so backup-code
+ *      / TOTP grinding by a password-holder is bounded.
+ *   3. Pending-login cookie resolves to a live half-login (else 401 — the
+ *      pending login expired or was never created; restart the password step).
+ *   4. The user row still exists + still has 2FA enrolled (defensive).
+ *   5. Verify the submitted code as TOTP (±1 window) OR a backup code (single-
+ *      use, consumed on match). On success: consume the pending login, mint
+ *      the session, 302 to the resolved target + clear the pending cookie.
+ *      On failure: re-render the challenge with an error (the pending login
+ *      stays valid so the user can retry without re-entering the password).
+ */
+export async function handleAdminLoginTotpPost(
+  db: Database,
+  req: Request,
+  deps: AdminLoginDeps = {},
+): Promise<Response> {
+  const form = await req.formData();
+  const formCsrf = form.get(CSRF_FIELD_NAME);
+  const csrfToken = typeof formCsrf === "string" ? formCsrf : "";
+  if (!verifyCsrfToken(req, csrfToken || null)) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Invalid form submission",
+        message: "The form's CSRF token did not match. Reload the page and try again.",
+      }),
+      400,
+    );
+  }
+
+  const next = safeNext(String(form.get("next") ?? ""));
+  const code = String(form.get("code") ?? "");
+
+  // Rate-limit BEFORE resolving the pending login or verifying the factor.
+  const clientIp = clientIpFromRequest(req);
+  const now = deps.now ? deps.now() : new Date();
+  const gate = totpRateLimiter.checkAndRecord(clientIp, now);
+  if (!gate.allowed) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Too many attempts",
+        message: `Too many verification attempts from this IP. Try again in ${gate.retryAfterSeconds ?? 1} seconds.`,
+      }),
+      429,
+      { "retry-after": String(gate.retryAfterSeconds ?? 1) },
+    );
+  }
+
+  const pendingToken = parsePendingLoginCookie(req.headers.get("cookie"));
+  const pending = getPendingLogin(pendingToken, () => now);
+  if (!pending) {
+    // No live pending login — expired, missing, or tampered. Send the user
+    // back to the start; clear any stale pending cookie.
+    return htmlResponse(
+      renderAdminError({
+        title: "Session expired",
+        message: "Your sign-in attempt expired. Please sign in again.",
+      }),
+      401,
+      { "set-cookie": buildPendingLoginClearCookie(req) },
+    );
+  }
+
+  const user = getUserById(db, pending.userId);
+  if (!user || !isTotpEnrolled(db, user.id)) {
+    consumePendingLogin(pendingToken);
+    return htmlResponse(
+      renderAdminError({
+        title: "Sign-in unavailable",
+        message: "Please sign in again.",
+      }),
+      401,
+      { "set-cookie": buildPendingLoginClearCookie(req) },
+    );
+  }
+
+  if (!code) {
+    return htmlResponse(
+      renderTotpChallenge({ next, csrfToken, errorMessage: "Enter your authentication code." }),
+      400,
+    );
+  }
+
+  const result = await verifySecondFactor(db, user.id, code);
+  if (!result.ok) {
+    return htmlResponse(
+      renderTotpChallenge({
+        next,
+        csrfToken,
+        errorMessage: "That code is incorrect or expired. Try again.",
+      }),
+      401,
+    );
+  }
+
+  // Second factor good. Consume the pending login (single use), mint the
+  // session, and clear the pending cookie in the same response. Use the
+  // pending login's stored `next` if the form's was tampered to the default.
+  consumePendingLogin(pendingToken);
+  const target = pending.next && pending.next !== POST_LOGIN_DEFAULT ? pending.next : next;
+  return mintSessionAndRedirect(db, req, user, target, [buildPendingLoginClearCookie(req)]);
 }
 
 /**

package/src/admin-login-ui.ts

@@ -12,7 +12,7 @@
  *
  * Pure functions — DB, sessions live in `admin-handlers.ts`.
  */
-import { brandMarkSvg, WORDMARK_TEXT } from "./brand.ts";
+import { WORDMARK_TEXT, brandMarkSvg } from "./brand.ts";
 import { renderCsrfHiddenInput } from "./csrf.ts";
 import { escapeHtml } from "./oauth-ui.ts";
 
@@ -67,7 +67,7 @@ function header(): string {
         <div class="brand">
           <span class="brand-mark" aria-hidden="true">${brandMarkSvg(20, "admin-login")}</span>
           <span class="brand-name">${WORDMARK_TEXT}</span>
-          <span class="brand-tag">admin</span>
+          <span class="brand-tag">sign in</span>
         </div>`;
 }
 
@@ -87,8 +87,8 @@ export function renderAdminLogin(props: AdminLoginProps): string {
     <div class="card">
       <div class="card-header">
         ${header()}
-        <h1>Sign in</h1>
-        <p class="subtitle">to administer this hub</p>
+        <h1>Sign in to your Parachute account</h1>
+        <p class="subtitle">Hub operators and invited members sign in here.</p>
       </div>
       ${error}
       <form method="POST" action="/login" class="auth-form">
@@ -105,7 +105,51 @@ export function renderAdminLogin(props: AdminLoginProps): string {
         <button type="submit" class="btn btn-primary">Sign in</button>
       </form>
     </div>`;
-  return baseDocument("Sign in to Parachute Hub admin", body);
+  return baseDocument("Sign in — Parachute", body);
+}
+
+// --- /login/2fa (second-factor step) --------------------------------------
+
+export interface TotpChallengeProps {
+  /** Continuation path after a successful second factor — hidden field. */
+  next: string;
+  csrfToken: string;
+  errorMessage?: string;
+}
+
+/**
+ * Server-rendered "enter your code" page shown after a correct password when
+ * the user has 2FA enrolled (hub#473). Posts to `/login/2fa` along with the
+ * pending-login cookie minted by the password step. Accepts either a 6-digit
+ * TOTP code or a backup code in the same field — the handler tries TOTP first,
+ * then backup codes.
+ *
+ * No JS, stands alone like `/login`. `inputmode`/`autocomplete` hint mobile
+ * keyboards toward a numeric pad + the platform's one-time-code autofill.
+ */
+export function renderTotpChallenge(props: TotpChallengeProps): string {
+  const { next, csrfToken, errorMessage } = props;
+  const error = errorMessage ? `<p class="error-banner">${escapeHtml(errorMessage)}</p>` : "";
+  const body = `
+    <div class="card">
+      <div class="card-header">
+        ${header()}
+        <h1>Two-factor authentication</h1>
+        <p class="subtitle">Enter the 6-digit code from your authenticator app, or a backup code.</p>
+      </div>
+      ${error}
+      <form method="POST" action="/login/2fa" class="auth-form">
+        ${renderCsrfHiddenInput(csrfToken)}
+        <input type="hidden" name="next" value="${escapeAttr(next)}" />
+        <label class="field">
+          <span class="field-label">Authentication code</span>
+          <input type="text" name="code" inputmode="numeric" autocomplete="one-time-code"
+                 autofocus required placeholder="123456" />
+        </label>
+        <button type="submit" class="btn btn-primary">Verify</button>
+      </form>
+    </div>`;
+  return baseDocument("Two-factor authentication — Parachute", body);
 }
 
 // --- error page ------------------------------------------------------------

package/src/admin-vaults.ts

@@ -12,16 +12,24 @@
  *   Content-Type: application/json
  *   { "name": "<vault-name>" }
  *
- *   201 → { name, url, version, token?, paths? }
- *           // vault freshly created. `token` (single-emit `pvt_*`) and
- *           // filesystem `paths` are present when the create path took the
- *           // `parachute-vault create --json` branch — that's the only time
- *           // the just-emitted token is captured. The first-vault-on-host
- *           // bootstrap (`parachute install vault`) doesn't emit JSON yet,
- *           // so a fresh-box response carries name/url/version only.
+ *   201 → { name, url, version, token?, token_guidance?, paths? }
+ *           // vault freshly created. `token` is a hub-issued ACCESS token
+ *           // (a JWT scoped `vault:<name>:admin`) captured from the
+ *           // `parachute-vault create --json` branch — NOT a `pvt_*` vault
+ *           // token (those were dropped). Post-DROP `token` may be the
+ *           // empty string `""` when the bootstrap mint was unavailable
+ *           // (e.g. a loopback origin the hub can't mint against); in that
+ *           // case `token_guidance` carries the vault's human-readable
+ *           // reason, forwarded verbatim so the SPA can explain the gap.
+ *           // `paths` is the new vault's filesystem layout. The
+ *           // first-vault-on-host bootstrap (`parachute install vault`)
+ *           // doesn't emit JSON yet, so a fresh-box response carries
+ *           // name/url/version only.
  *   200 → { name, url, version }
  *           // idempotent re-POST: existing vault. Never includes `token` —
- *           // tokens are single-emit at create time, not retrievable later.
+ *           // the create-time access token isn't retrievable later. The
+ *           // caller branches on HTTP status (201 vs 200), not on `token`
+ *           // truthiness, so an empty-token 201 isn't confused with a 200.
  *   400 → { error: "invalid_request", error_description: ... }
  *   401/403 → bearer-auth failure
  *   500 → orchestration failure
@@ -50,7 +58,7 @@
 import type { Database } from "bun:sqlite";
 import { type AdminAuthError, adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
 import { SERVICES_MANIFEST_PATH } from "./config.ts";
-import { findService, readManifest, readManifestLenient } from "./services-manifest.ts";
+import { findService, type readManifest, readManifestLenient } from "./services-manifest.ts";
 import { type WellKnownVaultEntry, isVaultEntry, vaultInstanceNameFor } from "./well-known.ts";
 
 /** Scope required to call POST /vaults. */
@@ -74,7 +82,20 @@ export interface CreateVaultRequest {
 /** Output shape of `parachute-vault create --json` (vault PR #184). */
 export interface VaultCreateJson {
   name: string;
+  /**
+   * Hub-issued access token (a JWT scoped `vault:<name>:admin`) the vault
+   * minted at create time. Post the pvt_* DROP this is the empty string
+   * `""` when no hub origin was reachable to mint against (e.g. a loopback
+   * create) — the field is always present but may be empty.
+   */
   token: string;
+  /**
+   * Vault-supplied human-readable reason no token was minted, present only
+   * when `token` is empty (e.g. "no hub origin reachable to mint against").
+   * Optional — older vaults that always minted don't emit it. Forwarded
+   * verbatim to the caller so the SPA can explain the empty-token state.
+   */
+  token_guidance?: string;
   paths: {
     vault_dir: string;
     vault_db: string;
@@ -239,8 +260,9 @@ interface OrchestrateError {
  * Run the orchestration step. Picks `parachute install` (bootstrap) vs
  * `parachute-vault create --json` (subsequent) based on whether vault is
  * already registered in services.json. The create branch parses stdout for
- * the just-emitted `pvt_*` token + filesystem paths so the caller can talk
- * to the new vault — those creds are single-emit.
+ * the just-minted hub access token (a `vault:<name>:admin` JWT, possibly
+ * empty post-DROP), the optional `token_guidance`, and filesystem paths so
+ * the caller can talk to the new vault — the access token is single-emit.
  */
 async function orchestrate(
   manifestPath: string,
@@ -348,14 +370,25 @@ export async function handleCreateVault(req: Request, deps: CreateVaultDeps): Pr
   }
 
   const entry = buildEntry(name, created.path, created.version, deps.issuer);
-  // Token + filesystem paths are single-emit at create time. We surface them
-  // here so the caller can immediately bootstrap a connection to the new
-  // vault. Idempotent re-POSTs intentionally never include them.
+  // Access token (a `vault:<name>:admin` JWT, possibly empty post-DROP) +
+  // filesystem paths are single-emit at create time. We surface them here so
+  // the caller can immediately bootstrap a connection to the new vault.
+  // `token_guidance` (when the vault couldn't mint) is forwarded verbatim so
+  // the SPA can explain the empty-token state rather than rendering a blank.
+  // Idempotent re-POSTs intentionally never include any of these.
   const body: WellKnownVaultEntry & {
     token?: string;
+    token_guidance?: string;
     paths?: VaultCreateJson["paths"];
   } = result.createJson
-    ? { ...entry, token: result.createJson.token, paths: result.createJson.paths }
+    ? {
+        ...entry,
+        token: result.createJson.token,
+        ...(result.createJson.token_guidance
+          ? { token_guidance: result.createJson.token_guidance }
+          : {}),
+        paths: result.createJson.paths,
+      }
     : entry;
 
   return new Response(JSON.stringify(body), {