@openparachute/hub 0.6.3 → 0.6.4-rc.1

package/src/account-vault-admin-token.ts

@@ -0,0 +1,242 @@
+/**
+ * `POST /account/vault-admin-token/<name>` — friend-facing vault ADMIN deep-link.
+ *
+ * The non-admin sibling of `GET /admin/vault-admin-token/<name>`
+ * (`admin-vault-admin-token.ts`). Both mint a `vault:<name>:admin` JWT and
+ * hand it to the vault's own admin SPA via a `#token=<jwt>` URL fragment — the
+ * SPA reads `location.hash` on bootstrap, then strips it. The admin sibling is
+ * gated `isFirstAdmin` and returns JSON for the hub SPA's fetch; THIS surface
+ * is gated on ASSIGNMENT (an individual user holds `admin` on a vault they're
+ * assigned to) and is a server-rendered POST → 303 redirect, matching the
+ * no-JS posture of the rest of `/account/*`.
+ *
+ * Why this exists: an assigned user is ALREADY authorized for `vault:<name>:admin`
+ * (`vaultVerbsForUserVault` returns `["read","write","admin"]` for their vault,
+ * 2026-05-30; vault gates mirror/backup config + token rotation on that scope).
+ * The authority existed; the only missing piece was a friend-reachable HTTP
+ * unlock + a button. With this, an individual user can open their vault's admin
+ * SPA — token mint/revoke, **and the Git-backup / mirror config** — without
+ * host-admin. The deep-link lands on the vault admin home (`managementUrl`,
+ * `/admin/` by default), whose "Git backup →" link reaches `VaultMirror`.
+ *
+ * Authorization — the same three-gate spine as `/account/vault-token/<name>`
+ * (`account-vault-token.ts`), here pinned to the single `admin` verb:
+ *
+ *   1. **Session.** A valid hub session cookie (the user's). No session → 401.
+ *   2. **Assignment.** `<name>` MUST be one of the user's `user_vaults`
+ *      assignments AND that assignment's role must grant `admin`. Read via
+ *      `vaultVerbsForUserVault` (`null` for an unassigned vault → 403; a role
+ *      that doesn't grant `admin` → 403). The first admin (empty
+ *      `assignedVaults`, no `user_vaults` rows) gets `null` here too — by
+ *      design, the same as `/account/vault-token`: admins use the SPA's
+ *      `/admin/vault-admin-token` path, not this friend surface.
+ *
+ * CSRF: double-submit cookie, same `__csrf` field + `verifyCsrfToken` as
+ * `/account/vault-token`, `/account/change-password`, and `/logout`. A
+ * cross-site POST without the matching cookie/form token → 400.
+ *
+ * Force-change-password gate (item F / hub#469): if `!user.passwordChanged`,
+ * 303 → `/account/change-password` BEFORE minting — identical to the gate
+ * `/account/vault-token` applies post-#550. An admin-created/reset user lands
+ * with a temp password and `password_changed: false`; without this gate they
+ * could mint a `vault:<name>:admin` deep-link token (10-min TTL, but still) and
+ * keep using the temp password instead of rotating it. Placed AFTER the
+ * authority gates (so an unassigned/garbage request still gets its 403/400) and
+ * BEFORE the mint. This does NOT reintroduce the bypass #469 closed.
+ *
+ * Mint: `signAccessToken` (the same machinery the OAuth issuer + admin paths
+ * use) with `scopes: ["vault:<name>:admin"]`, `audience: "vault.<name>"`,
+ * `iss`: the hub origin, `sub`: the user id, `vaultScope: [<name>]`, and the
+ * SAME short 10-min TTL as the admin sibling (`VAULT_ADMIN_TOKEN_TTL_SECONDS`):
+ * this is a deep-link bootstrap token, not a long-lived headless credential
+ * (that's `/account/vault-token`). A `tokens` registry row records it
+ * (`created_via='cli_mint'`, `userId` = the user) so it's revocable.
+ *
+ * Response: 303 → `<vault-url><managementUrl>#token=<jwt>`. 303 (See Other) so
+ * the browser re-issues the navigation as GET. The token rides the URL
+ * fragment, which is never sent to the server — same contract the hub SPA's
+ * `VaultsList` "Manage" button uses (vault PR #219).
+ */
+import type { Database } from "bun:sqlite";
+import { renderAdminError } from "./admin-login-ui.ts";
+import { VAULT_ADMIN_TOKEN_TTL_SECONDS } from "./admin-vault-admin-token.ts";
+import { CSRF_FIELD_NAME, verifyCsrfToken } from "./csrf.ts";
+import { recordTokenMint, signAccessToken } from "./jwt-sign.ts";
+import { findActiveSession } from "./sessions.ts";
+import { getUserById, vaultVerbsForUserVault } from "./users.ts";
+import { VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
+
+/** Lowercase-only vault-name charset — single source of truth in vault-name.ts. */
+const VAULT_NAME_RE = VAULT_NAME_CHARSET_RE;
+/** client_id stamped on the minted JWT + registry row. Matches the admin sibling. */
+const ACCOUNT_VAULT_ADMIN_CLIENT_ID = "parachute-hub-spa";
+
+export interface AccountVaultAdminTokenDeps {
+  db: Database;
+  /** Hub origin for this request — `iss` of the minted token + base of the redirect URL. */
+  hubOrigin: string;
+  /**
+   * The vault's declared `managementUrl` (from its `.parachute/module.json`),
+   * resolved by the route handler at request time. Either an absolute URL or a
+   * path relative to the vault's mounted URL. Defaults to `/admin/` (vault's
+   * canonical value) when the handler can't resolve one — that's where the
+   * admin sibling's deep-link lands too.
+   */
+  managementUrl?: string;
+  /** Test seam for the clock (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 },
+  });
+}
+
+/**
+ * Resolve a vault's `managementUrl` against the vault's hub-mounted URL.
+ * Absolute URL → returned verbatim; path → joined onto the vault URL after
+ * trimming a trailing slash. Mirrors `resolveManagementUrl` in the SPA's
+ * `web/ui/src/lib/api.ts` so hub-server and SPA deep-links agree.
+ */
+function resolveManagementUrl(vaultUrl: string, managementUrl: string): string {
+  if (/^https?:\/\//i.test(managementUrl)) return managementUrl;
+  const base = vaultUrl.replace(/\/+$/, "");
+  const tail = managementUrl.startsWith("/") ? managementUrl : `/${managementUrl}`;
+  return `${base}${tail}`;
+}
+
+export async function handleAccountVaultAdminTokenPost(
+  req: Request,
+  vaultName: string,
+  deps: AccountVaultAdminTokenDeps,
+): 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 opening your vault's admin tools.",
+      }),
+      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, same shape + 400 as the other
+  // `/account/*` POSTs.
+  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,
+    );
+  }
+
+  // Vault-name shape guard — reject anything that can't be a services.json key
+  // before any DB / authority work. Same posture as the other vault-token mints.
+  if (!VAULT_NAME_RE.test(vaultName)) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Invalid vault name",
+        message: `"${vaultName}" is not a valid vault name.`,
+      }),
+      400,
+    );
+  }
+
+  // Gate 2 — assignment + admin-verb cap. `vaultVerbsForUserVault` returns:
+  //   - null  → no assignment for this vault → 403.
+  //   - [...] → the verbs the assignment role permits; must include `admin`.
+  // Assigned users hold read/write/admin on their vault (2026-05-30); the first
+  // admin has no `user_vaults` rows so gets `null` here and a 403 — by design,
+  // admins use the SPA path. This is the cap to the user's actual authority.
+  const allowed = vaultVerbsForUserVault(deps.db, user.id, vaultName);
+  if (allowed === null || !allowed.includes("admin")) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Not your vault to manage",
+        message: `You don't have admin access to a vault named "${vaultName}". Ask the hub operator if you think this is wrong.`,
+      }),
+      403,
+    );
+  }
+
+  // Force-change-password gate (item F / hub#469). An admin-created/reset user
+  // with `password_changed: false` is sent to the change-password rail BEFORE
+  // minting — same gate `/account/vault-token` applies, so a temp-password
+  // handoff can't be parlayed into a vault-admin deep-link. Placed AFTER the
+  // authority gates (an unassigned/garbage request still gets its 403/400) and
+  // BEFORE the mint. 303 so the browser re-issues as GET. Does NOT reintroduce
+  // the bypass #469 closed.
+  if (!user.passwordChanged) {
+    return new Response(null, {
+      status: 303,
+      headers: { location: "/account/change-password", "cache-control": "no-store" },
+    });
+  }
+
+  // Mint the vault-admin deep-link token. Short TTL (10 min, matching the admin
+  // sibling) — it's a bootstrap token the vault SPA trades for its session, not
+  // a long-lived headless credential (that's `/account/vault-token`).
+  const scope = `vault:${vaultName}:admin`;
+  const audience = `vault.${vaultName}`;
+  const minted = await signAccessToken(deps.db, {
+    sub: user.id,
+    scopes: [scope],
+    audience,
+    clientId: ACCOUNT_VAULT_ADMIN_CLIENT_ID,
+    issuer: deps.hubOrigin,
+    ttlSeconds: VAULT_ADMIN_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 user's id so the operator's token registry
+    // + the revocation list attribute it correctly.
+    userId: user.id,
+    clientId: ACCOUNT_VAULT_ADMIN_CLIENT_ID,
+    scopes: [scope],
+    expiresAt: minted.expiresAt,
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  });
+
+  // Build the redirect target: <vault-url><managementUrl>#token=<jwt>. The
+  // vault URL is the hub-mounted path (`<hubOrigin>/vault/<name>`); the
+  // managementUrl (default `/admin/`) is the vault admin SPA entry point. The
+  // JWT rides the URL fragment — never sent to the server — exactly as the hub
+  // SPA's "Manage" button does (vault PR #219).
+  const trimmedOrigin = deps.hubOrigin.replace(/\/+$/, "");
+  const vaultUrl = `${trimmedOrigin}/vault/${vaultName}`;
+  const target = resolveManagementUrl(vaultUrl, deps.managementUrl ?? "/admin/");
+  const sep = target.includes("#") ? "&" : "#";
+  const location = `${target}${sep}token=${minted.token}`;
+
+  return new Response(null, {
+    status: 303,
+    headers: { location, "cache-control": "no-store" },
+  });
+}

package/src/account-vault-token.ts

@@ -75,9 +75,15 @@ 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";
+import { VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
 
-/** Matches the manifest vault-name validator + `/admin/vault-admin-token`. */
-const VAULT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Lowercase-only vault-name charset (item I) — single source of truth in
+ * vault-name.ts, matching what vault's init enforces. Was `[a-zA-Z0-9_-]`; the
+ * uppercase superset let a mint name drift from vault's lowercase URL-derived
+ * name, so the minted token's `vault.<Name>` audience wouldn't validate.
+ */
+const VAULT_NAME_RE = VAULT_NAME_CHARSET_RE;
 /** Verbs this surface will ever mint. `admin` is deliberately absent. */
 const ALLOWED_VERBS: readonly VaultVerb[] = ["read", "write", "admin"];
 /** client_id stamped on the minted JWT + registry row. */
@@ -233,6 +239,25 @@ export async function handleAccountVaultTokenPost(
     });
   }
 
+  // Force-change-password gate (item F / hub#469, NARROW). A user the admin
+  // created/reset lands with `password_changed: false` and an admin-known temp
+  // password. Without this gate an authorized friend could mint a LONG-LIVED
+  // vault token here and then keep using (or never rotate) the temp password —
+  // the token outlives any later rotation, defeating the "temp password is a
+  // one-time handoff" model. So an authorized-but-unrotated friend is sent to
+  // the change-password rail BEFORE minting anything. Placed AFTER the
+  // authority gates (so an unassigned/garbage request still gets its 403/400,
+  // preserving those semantics) and BEFORE the rate-limit + mint. 303 (See
+  // Other) so the browser re-issues as GET. Narrow #469 fix — gates
+  // token-minting specifically; the broad per-request /account/* wall is
+  // deferred to Aaron's design call.
+  if (!user.passwordChanged) {
+    return new Response(null, {
+      status: 303,
+      headers: { location: "/account/change-password", "cache-control": "no-store" },
+    });
+  }
+
   // Rate limit — after CSRF + authority shape, before the mint. Per-user.
   const rlNow = (deps.now ?? (() => new Date()))();
   const gate = vaultTokenMintRateLimiter.checkAndRecord(user.id, rlNow);

package/src/admin-login-ui.ts

@@ -152,6 +152,100 @@ export function renderTotpChallenge(props: TotpChallengeProps): string {
   return baseDocument("Two-factor authentication — Parachute", body);
 }
 
+// --- invite redemption ( /account/setup/<token> ) --------------------------
+
+export interface InviteSetupProps {
+  /** The raw token from the URL — POSTs back to the same path. */
+  token: string;
+  csrfToken: string;
+  /**
+   * When the invite pins a vault name the redeemer can't choose one — we show
+   * it read-only. When null the redeemer names their own vault (a text field).
+   */
+  pinnedVaultName: string | null;
+  /** Whether redemption provisions a vault at all (shows the vault row iff true). */
+  provisionVault: boolean;
+  username?: string;
+  vaultName?: string;
+  errorMessage?: string;
+}
+
+/**
+ * Server-rendered "claim your invite" form for `/account/setup/<token>`.
+ * Stands alone without the SPA (same posture as `/login` + the setup wizard):
+ * a brand-new invitee hits this with no session and no JS. Posts back to the
+ * same `/account/setup/<token>` path. Reuses the shared login chrome.
+ */
+export function renderInviteSetup(props: InviteSetupProps): string {
+  const { token, csrfToken, pinnedVaultName, provisionVault, username, vaultName, errorMessage } =
+    props;
+  const error = errorMessage ? `<p class="error-banner">${escapeHtml(errorMessage)}</p>` : "";
+  const usernameAttr = username ? ` value="${escapeAttr(username)}"` : "";
+
+  // Vault row: shown only when the invite provisions a vault. Pinned → a
+  // read-only display of the name the admin chose (redeemer can't squat names).
+  // Unpinned → a text field the redeemer fills.
+  let vaultRow = "";
+  if (provisionVault) {
+    if (pinnedVaultName !== null) {
+      vaultRow = `
+        <label class="field">
+          <span class="field-label">Your vault</span>
+          <input type="text" value="${escapeAttr(pinnedVaultName)}" readonly disabled />
+          <span class="field-hint">Your hub operator named this vault for you.</span>
+        </label>`;
+    } else {
+      const vaultAttr = vaultName ? ` value="${escapeAttr(vaultName)}"` : "";
+      vaultRow = `
+        <label class="field">
+          <span class="field-label">Name your vault</span>
+          <input type="text" name="vault_name" autocomplete="off"
+            required minlength="2" maxlength="32"
+            pattern="[a-z0-9_-]+" title="lowercase letters, digits, _ - (2–32 chars)"
+            spellcheck="false" autocapitalize="off"${vaultAttr} />
+          <span class="field-hint">lowercase letters, digits, <code>_</code>, <code>-</code> (2–32 chars)</span>
+        </label>`;
+    }
+  }
+
+  const body = `
+    <div class="card">
+      <div class="card-header">
+        ${header()}
+        <h1>Claim your invite</h1>
+        <p class="subtitle">Pick a username and password to create your Parachute account${
+          provisionVault ? " and your own vault" : ""
+        }.</p>
+      </div>
+      ${error}
+      <form method="POST" action="/account/setup/${escapeAttr(token)}" class="auth-form">
+        ${renderCsrfHiddenInput(csrfToken)}
+        <label class="field">
+          <span class="field-label">Username</span>
+          <input type="text" name="username" autocomplete="username" autofocus
+            required minlength="2" maxlength="32"
+            pattern="[a-z0-9_-]+" title="lowercase letters, digits, _ - (2–32 chars)"
+            spellcheck="false" autocapitalize="off"${usernameAttr} />
+          <span class="field-hint">lowercase letters, digits, <code>_</code>, <code>-</code></span>
+        </label>
+        <label class="field">
+          <span class="field-label">Password</span>
+          <input type="password" name="password" autocomplete="new-password"
+            required minlength="12" />
+          <span class="field-hint">at least 12 characters</span>
+        </label>
+        <label class="field">
+          <span class="field-label">Confirm password</span>
+          <input type="password" name="password_confirm" autocomplete="new-password"
+            required minlength="12" />
+        </label>
+        ${vaultRow}
+        <button type="submit" class="btn btn-primary">Create my account</button>
+      </form>
+    </div>`;
+  return baseDocument("Claim your invite — Parachute", body);
+}
+
 // --- error page ------------------------------------------------------------
 
 export function renderAdminError(props: { title: string; message: string }): string {

package/src/admin-vault-admin-token.ts

@@ -28,13 +28,19 @@ import type { Database } from "bun:sqlite";
 import { signAccessToken } from "./jwt-sign.ts";
 import { findSession, parseSessionCookie } from "./sessions.ts";
 import { isFirstAdmin } from "./users.ts";
+import { VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
 
 /** Short TTL — matches host-admin-token. SPA re-fetches on near-expiry. */
 export const VAULT_ADMIN_TOKEN_TTL_SECONDS = 10 * 60;
 const VAULT_ADMIN_CLIENT_ID = "parachute-hub-spa";
 
-/** Same shape as the manifest name validator — keeps URL-injection out. */
-const VAULT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Lowercase-only vault-name charset (item I) — single source of truth in
+ * vault-name.ts, matching vault's init. Keeps URL-injection out AND closes the
+ * case-drift class (an uppercased name minting `vault.<Name>` audience that
+ * vault's lowercase URL-derived name would never validate).
+ */
+const VAULT_NAME_RE = VAULT_NAME_CHARSET_RE;
 
 export interface MintVaultAdminTokenDeps {
   db: Database;

package/src/admin-vaults.ts

@@ -59,6 +59,8 @@ import type { Database } from "bun:sqlite";
 import { type AdminAuthError, adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
 import { SERVICES_MANIFEST_PATH } from "./config.ts";
 import { findService, type readManifest, readManifestLenient } from "./services-manifest.ts";
+import { enrichedPath } from "./spawn-path.ts";
+import { VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
 import { type WellKnownVaultEntry, isVaultEntry, vaultInstanceNameFor } from "./well-known.ts";
 
 /** Scope required to call POST /vaults. */
@@ -72,7 +74,12 @@ export const HOST_ADMIN_SCOPE = "parachute:host:admin";
  * the hub rejects them at the API edge before a vault under those names
  * can register and capture the proxy path.
  */
-const VAULT_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+// Lowercase-only (item I) — single source of truth in vault-name.ts. Vault's
+// init enforces `[a-z0-9_-]`; a hub-side `[a-zA-Z0-9_-]` superset let an
+// uppercased name through that vault would then lowercase or reject, drifting
+// the hub's idea of the vault from vault's. The hub-only reservations (`new`,
+// `assets`) shadow SPA routes and stay on top of vault's `list`.
+const VAULT_NAME_PATTERN = VAULT_NAME_CHARSET_RE;
 const RESERVED_VAULT_NAMES = new Set(["list", "new", "assets"]);
 
 export interface CreateVaultRequest {
@@ -164,7 +171,7 @@ async function parseBody(req: Request): Promise<ParseResult | ParseError> {
     return {
       ok: false,
       status: 400,
-      message: "vault name must contain only letters, numbers, hyphens, and underscores",
+      message: "vault name must contain only lowercase letters, numbers, hyphens, and underscores",
     };
   }
   if (RESERVED_VAULT_NAMES.has(name)) {
@@ -230,9 +237,13 @@ function buildEntry(
 async function defaultRunCommand(cmd: readonly string[]): Promise<RunResult> {
   // Inherit env so the child sees PATH, HOME, BUN_INSTALL, etc. Bun.spawn
   // defaults to empty env — see api-modules-ops.ts:defaultRun for the rationale.
+  // PATH enrichment (hub launchd-PATH regression): a launchd-managed hub bakes
+  // a minimal PATH, so this shell-out (vault ops) inherits that thin PATH too;
+  // enrich it with operator-tool dirs (`$HOME/.local/bin`, brew bin). See
+  // `spawn-path.ts`.
   const proc = Bun.spawn([...cmd], {
     stdio: ["ignore", "pipe", "pipe"],
-    env: process.env,
+    env: { ...process.env, PATH: enrichedPath() },
   });
   // Drain both pipes in parallel — leaving stderr unread can deadlock long
   // installs once the OS pipe buffer fills (#97). Captured stderr is folded
@@ -268,10 +279,17 @@ async function orchestrate(
   manifestPath: string,
   name: string,
   runCommand: (cmd: readonly string[]) => Promise<RunResult>,
+  opts: { noMirror?: boolean } = {},
 ): Promise<OrchestrateOk | OrchestrateError> {
   const vaultRegistered = findService("parachute-vault", manifestPath) !== undefined;
+  // `--no-mirror` opts this create out of the default internal live mirror
+  // (§3 default_mirror knob). Only meaningful on the `create` branch — the
+  // bootstrap `install` path provisions the default vault and follows the
+  // server-wide knob.
   const cmd = vaultRegistered
-    ? ["parachute-vault", "create", name, "--json"]
+    ? opts.noMirror
+      ? ["parachute-vault", "create", name, "--json", "--no-mirror"]
+      : ["parachute-vault", "create", name, "--json"]
     : ["parachute", "install", "vault"];
   let result: RunResult;
   try {
@@ -320,6 +338,102 @@ async function orchestrate(
   return { ok: true, createJson };
 }
 
+/**
+ * Result of {@link provisionVault} — the programmatic vault-provisioning
+ * core shared by the authed HTTP handler and the invite-redeem path.
+ *
+ *   - `created: true`  — a fresh vault was provisioned this call. `entry`
+ *     describes it; `createJson` (when present) carries the single-emit
+ *     bootstrap creds.
+ *   - `created: false` — the vault already existed (idempotent). `entry`
+ *     describes the existing vault; no `createJson`.
+ */
+export type ProvisionVaultResult =
+  | {
+      ok: true;
+      created: boolean;
+      entry: WellKnownVaultEntry;
+      createJson: VaultCreateJson | null;
+    }
+  | { ok: false; status: number; message: string };
+
+/**
+ * Provision (or no-op if it exists) a vault by name — the auth-free core
+ * lifted out of {@link handleCreateVault} so the invite-redeem flow can
+ * provision a vault for a freshly-created account WITHOUT a host:admin
+ * bearer (the redeemer holds no admin authority; the invite IS the
+ * authorization). The HTTP handler keeps the host:admin gate in front of
+ * this; the invite path calls it directly after validating the invite.
+ *
+ * Idempotent-safe: if the vault already exists this returns
+ * `created:false` with the existing entry rather than re-running the CLI —
+ * a redeem retry (or a name collision) lands the user on the existing
+ * vault instead of erroring.
+ *
+ * Name validation matches `parachute-vault create`'s rules. Callers that
+ * accept an untrusted name (the invite redeemer naming their own vault)
+ * MUST pass it through here so the same regex + reserved-name gate the
+ * `/vaults` API edge enforces applies.
+ */
+export async function provisionVault(
+  name: string,
+  deps: {
+    issuer: string;
+    manifestPath?: string;
+    runCommand?: CreateVaultDeps["runCommand"];
+    /** `'off'` appends `--no-mirror`; anything else follows the server knob. */
+    defaultMirror?: string;
+  },
+): Promise<ProvisionVaultResult> {
+  const manifestPath = deps.manifestPath ?? SERVICES_MANIFEST_PATH;
+  const runCommand = deps.runCommand ?? defaultRunCommand;
+
+  if (!VAULT_NAME_PATTERN.test(name)) {
+    return {
+      ok: false,
+      status: 400,
+      message: "vault name must contain only lowercase letters, numbers, hyphens, and underscores",
+    };
+  }
+  if (RESERVED_VAULT_NAMES.has(name)) {
+    return { ok: false, status: 400, message: `"${name}" is a reserved vault name` };
+  }
+
+  // Idempotency: if the vault already exists, return the existing entry.
+  const existing = findExistingVault(manifestPath, name);
+  if (existing) {
+    return {
+      ok: true,
+      created: false,
+      entry: buildEntry(name, existing.path, existing.version, deps.issuer),
+      createJson: null,
+    };
+  }
+
+  const result = await orchestrate(manifestPath, name, runCommand, {
+    noMirror: deps.defaultMirror === "off",
+  });
+  if (!result.ok) {
+    return { ok: false, status: result.status, message: result.message };
+  }
+
+  // Re-read services.json: the CLI just wrote it.
+  const created = findExistingVault(manifestPath, name);
+  if (!created) {
+    return {
+      ok: false,
+      status: 500,
+      message: `vault "${name}" was provisioned but is not in services.json — manual recovery required`,
+    };
+  }
+  return {
+    ok: true,
+    created: true,
+    entry: buildEntry(name, created.path, created.version, deps.issuer),
+    createJson: result.createJson,
+  };
+}
+
 export async function handleCreateVault(req: Request, deps: CreateVaultDeps): Promise<Response> {
   if (req.method !== "POST") {
     return new Response("method not allowed", { status: 405 });
@@ -341,35 +455,29 @@ export async function handleCreateVault(req: Request, deps: CreateVaultDeps): Pr
   }
   const { name } = parsed.body;
 
-  // Idempotency: if the vault already exists, return 200 + existing entry.
-  // Skip the CLI shell-out — re-POST is usually a UI retry.
-  const existing = findExistingVault(manifestPath, name);
-  if (existing) {
-    return new Response(
-      JSON.stringify(buildEntry(name, existing.path, existing.version, deps.issuer)),
-      {
-        status: 200,
-        headers: { "content-type": "application/json" },
-      },
-    );
-  }
-
-  const result = await orchestrate(manifestPath, name, runCommand);
-  if (!result.ok) {
-    return jsonError(result.status, "server_error", result.message);
+  const provisioned = await provisionVault(name, {
+    issuer: deps.issuer,
+    manifestPath,
+    runCommand,
+  });
+  if (!provisioned.ok) {
+    // parseBody already enforced the name regex/reserved gate, so a
+    // provisionVault 400 here would be a redundant re-check; map any
+    // non-ok to its status. invalid_request for 400, server_error otherwise.
+    const error = provisioned.status === 400 ? "invalid_request" : "server_error";
+    return jsonError(provisioned.status, error, provisioned.message);
   }
 
-  // Re-read services.json: the CLI just wrote it.
-  const created = findExistingVault(manifestPath, name);
-  if (!created) {
-    return jsonError(
-      500,
-      "server_error",
-      `vault "${name}" was provisioned but is not in services.json — manual recovery required`,
-    );
+  // Idempotent re-POST: existing vault → 200, no single-emit creds.
+  if (!provisioned.created) {
+    return new Response(JSON.stringify(provisioned.entry), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
   }
 
-  const entry = buildEntry(name, created.path, created.version, deps.issuer);
+  const entry = provisioned.entry;
+  const result = { createJson: provisioned.createJson };
   // 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.