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

package/src/env-file.ts

@@ -68,6 +68,16 @@ export function upsertEnvLine(lines: string[], key: string, value: string): stri
   return next;
 }
 
+/**
+ * Drop every `KEY=…` line for `key`, preserving the order of the rest.
+ * Returns a new array; the input is untouched. No-op (returns a copy) when
+ * the key isn't present.
+ */
+export function removeEnvLine(lines: string[], key: string): string[] {
+  const prefix = `${key}=`;
+  return lines.filter((line) => !line.startsWith(prefix));
+}
+
 export function writeEnvFile(path: string, lines: readonly string[]): void {
   mkdirSync(dirname(path), { recursive: true });
   const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;

package/src/help.ts

@@ -5,7 +5,14 @@ export function topLevelHelp(): string {
   const services = knownServices().join(" | ");
   return `parachute ${pkg.version} — top-level CLI for the Parachute ecosystem
 
+Fresh install? Start here — works the same on a laptop or a remote server:
+  parachute init                    one quick step → admin wizard in your browser
+                                    (offers optional exposure on remote boxes)
+
 Usage:
+  parachute init                    bring hub up, offer exposure, open admin wizard
+                                    (also lets you walk the wizard in the CLI; --cli-wizard)
+  parachute setup-wizard --hub-url <url>  walk /admin/setup in the terminal
   parachute setup                   interactive walk-through: install services + configure
   parachute install <service>       install and register a service
                                     services: ${services}
@@ -100,6 +107,124 @@ Aliases:
 `;
 }
 
+export function initHelp(): string {
+  return `parachute init — get the admin wizard open in one step
+
+Usage:
+  parachute init [--no-browser] [--no-expose-prompt]
+                 [--expose none|tailnet|cloudflare]
+                 [--cli-wizard | --browser-wizard]
+
+What it does:
+  Fresh-install front door, one command for both laptops AND remote
+  servers (EC2, DigitalOcean, Hetzner, any VPS). The admin SPA already
+  walks operators through the rest (install vault, set up the admin
+  user, install scribe / runner / app); this command's only job is to
+  get you to that wizard.
+
+  Idempotent — every re-run is safe:
+    1. If the hub isn't running, start it.
+    2. If the hub isn't already exposed, in a terminal, offer to set up
+       exposure (Tailscale Funnel, Cloudflare Tunnel, or stay loopback).
+       The default highlights "no thanks" on laptops and Cloudflare on
+       servers (SSH session detected). Skip with --no-expose-prompt or
+       pin non-interactively with --expose.
+    3. Print the canonical admin URL (loopback when not exposed, the
+       tailnet / cloudflare FQDN when exposure is active).
+    4. In a terminal, offer to open the URL in your browser
+       (macOS \`open\`, Linux \`xdg-open\`). Skip with --no-browser or
+       run from a non-TTY shell.
+
+  If your hub is up + exposure is already set up + a vault is already
+  configured, init just confirms "looks good — here's your URL" and
+  exits 0.
+
+Flags:
+  --no-browser              just print the URL; don't offer to launch a browser
+  --no-expose-prompt        skip the exposure question; fall through to localhost URL
+  --expose <choice>         non-interactive exposure override:
+                              none       — stay loopback-only
+                              tailnet    — set up Tailscale Funnel (private to your tailnet)
+                              cloudflare — set up Cloudflare Tunnel (your own domain)
+  --cli-wizard              skip the "browser or CLI?" prompt and walk the wizard
+                            in this terminal (hub#168 Cut 4)
+  --browser-wizard          skip the prompt and open the browser wizard directly
+
+Examples:
+  parachute init                              # laptop: prompts, defaults to "no expose"
+  parachute init                              # ssh'd server: prompts, defaults to Cloudflare
+  parachute init --no-expose-prompt           # skip the question; just print localhost URL
+  parachute init --expose cloudflare          # CI/scripted: chain straight into Cloudflare
+  parachute init --expose tailnet             # CI/scripted: chain straight into Tailscale
+  parachute init --no-browser                 # don't shell out to open / xdg-open
+  parachute init --cli-wizard                 # walk the wizard in this terminal (hub#168)
+`;
+}
+
+export function setupWizardHelp(): string {
+  return `parachute setup-wizard — terminal mirror of /admin/setup (hub#168)
+
+Usage:
+  parachute setup-wizard --hub-url <url>
+                         [--account-username <name>] [--account-password <pw>]
+                         [--bootstrap-token <token>]
+                         [--vault-mode create|import|skip] [--vault-name <name>]
+                         [--vault-import-url <url>] [--vault-import-pat <pat>] [--vault-import-replace]
+                         [--expose-mode localhost|tailnet|public]
+
+What it does:
+  Walks the same three-step setup flow the browser wizard does, in your
+  terminal. Hits the same backend handlers (POST /admin/setup/account,
+  /admin/setup/vault, /admin/setup/expose) — so any wizard bug fix lands
+  in both surfaces.
+
+  Step 1: admin account (username + password).
+  Step 2: vault (create / import from git / skip).
+  Step 3: expose mode (localhost / tailnet / public).
+
+  Idempotent: re-running picks up at the next undone step. Already-done
+  steps are skipped without prompts. Same as the browser wizard.
+
+  Run-from-flag: every prompt accepts a paired CLI flag so an entirely
+  scripted setup works (CI, ansible, etc.). Mirrors the existing
+  PARACHUTE_INITIAL_ADMIN_* env-seed path.
+
+Flags:
+  --hub-url <url>                base URL of the hub (required; e.g.
+                                 http://127.0.0.1:1939). \`parachute init\`
+                                 passes this in when chaining; standalone
+                                 callers supply it explicitly.
+  --account-username <name>      pre-supply the admin username (default: owner)
+  --account-password <pw>        pre-supply the admin password (required when
+                                 non-interactive)
+  --bootstrap-token <token>      one-time bootstrap token when the hub is in
+                                 container/serve mode. Reads PARACHUTE_BOOTSTRAP_TOKEN
+                                 from the env if not passed.
+  --vault-mode create|import|skip   pre-pick the vault step's branch
+  --vault-name <name>            pre-supply the vault name (create / import)
+  --vault-import-url <url>       remote URL for import mode (HTTPS or SSH git URL)
+  --vault-import-pat <pat>       PAT for private repo import (optional)
+  --vault-import-replace         use replace mode (default is merge)
+  --skip-vault                   shorthand for --vault-mode skip
+  --expose-mode <mode>           pre-pick the expose-mode answer
+
+Examples:
+  parachute setup-wizard --hub-url http://127.0.0.1:1939
+      # walks all three steps interactively
+
+  parachute setup-wizard --hub-url http://127.0.0.1:1939 \\
+    --account-username admin --account-password 'long-pw-here' \\
+    --vault-mode create --vault-name default \\
+    --expose-mode localhost
+      # fully non-interactive (CI-friendly)
+
+  parachute setup-wizard --hub-url http://127.0.0.1:1939 \\
+    --vault-import-url https://github.com/me/my-vault.git \\
+    --vault-import-pat ghp_xxx
+      # imports an existing vault export from GitHub
+`;
+}
+
 export function setupHelp(): string {
   return `parachute setup — interactive walk-through to install + configure services
 
@@ -201,6 +326,7 @@ Usage:
   parachute expose public  --tailnet
   parachute expose public  --cloudflare --domain <hostname>
   parachute expose public  off --cloudflare
+  parachute expose cloudflare --domain <hostname>           # alias for the above
 
 Status:
   tailnet is the supported exposure shape. The hub's OAuth + per-module
@@ -256,6 +382,7 @@ Examples:
   parachute expose public off                              # stop the Funnel
   parachute expose public --cloudflare --domain vault.example.com
                                                            # stable URL via cloudflared
+  parachute expose cloudflare --domain vault.example.com   # alias for the line above
   parachute expose public off --cloudflare                 # stop the cloudflared tunnel
 
 Tailscale Funnel constraints:
@@ -466,29 +593,44 @@ Examples:
 }
 
 export function migrateHelp(): string {
-  return `parachute migrate — archive legacy files at the ecosystem root
+  return `parachute migrate — archive known-legacy files at the ecosystem root
 
 Usage:
-  parachute migrate [--dry-run] [--yes]
+  parachute migrate [--list] [--dry-run] [--yes]
 
 What it does:
-  Scans ~/.parachute/ for files and directories that don't belong to the
-  post-restructure layout. Recognized entries — per-service dirs
-  (vault/, notes/, scribe/, channel/, hub/; legacy lens/ also kept),
-  services.json,
-  expose-state.json, well-known/ — stay in place. Anything else (plus
-  known legacy cruft like daily.db, server.yaml) is moved under
-  ~/.parachute/.archive-<YYYY-MM-DD>/, never deleted.
-
-  Dotfiles at the root (.env, .DS_Store, prior .archive-* dirs) are left
-  alone.
+  Scans ~/.parachute/ for files and directories that match the
+  known-legacy allowlist (daily.db*, server.yaml, channel.log/err,
+  channel.start.sh, top-level logs/, tokens.db*, and the legacy lens/
+  directory). Matching entries are moved under
+  ~/.parachute/.archive-<YYYY-MM-DD>/ — never deleted.
+
+  Anything *not* on the allowlist is left in place with an "[unknown —
+  skipping]" note. The hub doesn't presume to know what every module
+  (or your own setup) puts at the root, so the default is conservative:
+  if it isn't a known-legacy pattern, migrate leaves it alone. Remove
+  unknowns manually if you're sure.
+
+  Dotfiles at the root (.env, .DS_Store, prior .archive-* dirs) are
+  never touched.
+
+Safety:
+  - Refuses to sweep while any service is running — stop them first
+    (\`parachute stop\`) or preview with \`--list\`.
+  - SQLite-shape files (\`*.db\`, \`*.db-wal\`, \`*.db-shm\`) get a
+    \`[live-db]\` label and pull an extra confirmation; wal/shm
+    consistency depends on all three moving together.
+  - Plan annotates each entry: \`[safe]\` / \`[live-db]\` /
+    \`[unknown — skipping]\`, with skipped items printed last.
+  - In a non-TTY shell (CI / piped), refuses without \`--yes\`.
 
 Flags:
-  --dry-run     print the plan; make no changes
-  --yes, -y     skip the confirmation prompt
+  --list        print the plan; make no changes (friendly preview)
+  --dry-run     synonym for --list (kept for back-compat)
+  --yes, -y     skip the confirmation prompt; required in non-TTY shells
 
 Examples:
-  parachute migrate --dry-run       see what would move, without touching anything
+  parachute migrate --list          see what would move, without touching anything
   parachute migrate                 interactive sweep (prompts before acting)
   parachute migrate --yes           sweep without prompting
 `;

package/src/hub-db.ts

@@ -2,7 +2,8 @@
  * Hub-local SQLite database. Opens `~/.parachute/hub.db` (overridable via
  * `$PARACHUTE_HOME`). Holds everything the hub owns as the ecosystem's OAuth
  * issuer — signing keys (v1), users + opaque refresh tokens (v2), OAuth
- * clients + auth-codes + grants + browser sessions (v3).
+ * clients + auth-codes + grants + browser sessions (v3), and TOTP 2FA
+ * enrollment on the users row (v11, hub#473).
  *
  * Each open() runs `migrate()` to bring the schema up to date. A
  * `schema_version` table records every applied migration so re-opens are
@@ -320,6 +321,43 @@ const MIGRATIONS: readonly Migration[] = [
       ALTER TABLE users DROP COLUMN assigned_vault;
     `,
   },
+  {
+    version: 11,
+    sql: `
+      -- Real TOTP 2FA at the hub login layer (hub#473). Three nullable
+      -- columns on \`users\`:
+      --
+      --   * totp_secret (TEXT, nullable) — the base32-encoded RFC 6238 TOTP
+      --     secret. NULL means "2FA not enrolled" — the canonical "is 2FA on
+      --     for this user?" signal. Stored as the plaintext base32 string
+      --     (not encrypted at rest): hub.db already holds the argon2id
+      --     password hashes AND the OAuth signing private keys in plaintext
+      --     PEM (signing_keys.private_key_pem), so the TOTP secret sits at
+      --     the same operator-local trust boundary — encrypting one column
+      --     while leaving the signing key in the clear would be security
+      --     theatre. A future at-rest-encryption pass (hub#474 follow-up)
+      --     would cover all three (password hashes are already one-way; the
+      --     signing key + TOTP secret are the recoverable secrets).
+      --   * totp_backup_codes (TEXT, nullable) — JSON array of argon2id-HASHED
+      --     single-use recovery codes. Same hash family as passwords
+      --     (@node-rs/argon2). Plaintext codes are shown to the user exactly
+      --     once at enrollment and never stored. A code is removed from the
+      --     array when consumed. NULL / "[]" means "no backup codes left."
+      --   * totp_enrolled_at (TEXT, nullable) — ISO-8601 timestamp of the
+      --     last successful enrollment. NULL until first enroll; informational
+      --     (admin UI / account page "2FA enabled since …").
+      --
+      -- Backfill: every existing user pre-dates this migration and gets NULL
+      -- for all three — i.e. "2FA not enrolled." Their /login flow stays
+      -- password-only (the login handler only requires a TOTP step when
+      -- totp_secret IS NOT NULL), so existing operators keep signing in
+      -- exactly as before. No backfill UPDATE needed — the column default is
+      -- NULL.
+      ALTER TABLE users ADD COLUMN totp_secret TEXT;
+      ALTER TABLE users ADD COLUMN totp_backup_codes TEXT;
+      ALTER TABLE users ADD COLUMN totp_enrolled_at TEXT;
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {

package/src/hub-server.ts

@@ -67,11 +67,20 @@
  *   /api/users/<id>               (DELETE)     → hard-delete user + revoke tokens (host:admin)
  *   /api/users/<id>/reset-password (POST)      → admin-initiated password reset (host:admin)
  *   /login                        (GET + POST) → operator password login
+ *   /login/2fa                    (POST)       → second-factor (TOTP/backup) step
+ *                                                 (hub#473; reached after a correct
+ *                                                 password for a 2FA-enrolled user)
  *   /logout                       (POST)       → end admin session
  *   /account/change-password      (GET + POST) → user self-service change-password
  *                                                 (force-redirect target for users
  *                                                 with password_changed=false; also
  *                                                 reachable directly to rotate)
+ *   /account/2fa                  (GET + POST) → user self-service 2FA enroll/disenroll
+ *                                                 (hub#473; QR + backup codes)
+ *   /account/vault-token/<name>   (POST)       → friend mints a scoped
+ *                                                 vault:<name>:read|write bearer for
+ *                                                 an ASSIGNED vault (headless clients;
+ *                                                 session + assignment + scope-capped)
  *   /admin/config*                             → 301 → /admin/vaults (legacy
  *                                                portal retired post-SPA-rework)
  *
@@ -108,11 +117,13 @@ import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import pkg from "../package.json" with { type: "json" };
+import { handleAccountVaultTokenPost } from "./account-vault-token.ts";
 import { handleApproveClient, handleGetClient } from "./admin-clients.ts";
 import { handleListGrants, handleRevokeGrant } from "./admin-grants.ts";
 import {
   handleAdminLoginGet,
   handleAdminLoginPost,
+  handleAdminLoginTotpPost,
   handleAdminLogoutPost,
 } from "./admin-handlers.ts";
 import { handleHostAdminToken } from "./admin-host-admin-token.ts";
@@ -137,6 +148,7 @@ import {
   parseModulesPath,
 } from "./api-modules-ops.ts";
 import { handleApiModules, handleApiModulesChannel } from "./api-modules.ts";
+import { handleApiReady } from "./api-ready.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";
@@ -177,6 +189,8 @@ import {
 import { renderNotFoundPage } from "./oauth-ui.ts";
 import { buildHubBoundOrigins } from "./origin-check.ts";
 import { clearPid, writePid } from "./process-state.ts";
+import { toResponse as proxyErrorToResponse, renderProxyError } from "./proxy-error-ui.ts";
+import { classifyUpstream } from "./proxy-state.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
 import {
   FIRST_PARTY_FALLBACKS,
@@ -196,6 +210,7 @@ import {
 } from "./setup-wizard.ts";
 import { getAllPublicKeys } from "./signing-keys.ts";
 import type { Supervisor } from "./supervisor.ts";
+import { handleTwoFactorGet, handleTwoFactorPost } from "./two-factor-handlers.ts";
 import { getUserById, userCount } from "./users.ts";
 import {
   WELL_KNOWN_DIR,
@@ -446,10 +461,21 @@ export function layerOf(req: Request): RequestLayer {
  * / agent / vault want the prefix), so the decision lives one layer up in
  * `proxyToService` / `proxyToVault`.
  *
- * Returns 502 when the loopback fetch fails — port valid, target unreachable
- * (service crashed, port shifted, mid-restart). `serviceLabel` is folded into
- * the error message so 502 bodies say `vault upstream unreachable` /
- * `scribe upstream unreachable` etc.
+ * Returns a boot-readiness-classified response when the loopback fetch fails
+ * — port valid, target unreachable (service crashed, port shifted, mid-
+ * restart, OR module is still inside its boot window). The response is
+ * classified by `classifyUpstream` into:
+ *
+ *   - **transient** (still booting): 503 + Retry-After. HTML page polls
+ *     /api/ready up to 5 attempts on a 2s cadence; JSON includes
+ *     retry_after_ms + max_attempts.
+ *   - **persistent** (crashed / never started): 502, no auto-retry. HTML
+ *     surfaces a /admin/modules link; JSON includes admin_url.
+ *
+ * `serviceLabel` is the services.json entry name (`parachute-vault`,
+ * `scribe`, …) folded into the response body for operator clarity.
+ * `short` is the canonical short (`vault`/`scribe`/`notes`) — used as
+ * the supervisor map key + pidfile directory key for classification.
  *
  * Hop-by-hop notes: WebSocket upgrades and HTTP/2 trailers don't traverse
  * fetch-based proxies cleanly. No on-box service uses either today; if one
@@ -460,6 +486,8 @@ async function proxyRequest(
   req: Request,
   port: number,
   serviceLabel: string,
+  short: string,
+  supervisor: Supervisor | undefined,
   targetPath?: string,
 ): Promise<Response> {
   const url = new URL(req.url);
@@ -519,10 +547,20 @@ async function proxyRequest(
     return await fetch(upstream, init);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    return new Response(JSON.stringify({ error: `${serviceLabel} upstream unreachable: ${msg}` }), {
-      status: 502,
-      headers: { "content-type": "application/json" },
+    // Classify the failure (transient boot-window vs persistent crash) and
+    // render either an HTML page or a JSON error per the request's Accept.
+    // See `proxy-state.ts` for the classification logic + `proxy-error-ui.ts`
+    // for the two response shapes (closes hub#443).
+    const classifyOpts: Parameters<typeof classifyUpstream>[1] = {};
+    if (supervisor !== undefined) classifyOpts.supervisor = supervisor;
+    const state = classifyUpstream(short, classifyOpts);
+    const rendered = renderProxyError(req, {
+      short,
+      serviceLabel,
+      state,
+      upstreamError: msg,
     });
+    return proxyErrorToResponse(rendered);
   }
 }
 
@@ -536,7 +574,11 @@ async function proxyRequest(
  * fall through to the SPA shell fallback for unknown vault names (the seam
  * #173 introduced).
  */
-async function proxyToVault(req: Request, manifestPath: string): Promise<Response | undefined> {
+async function proxyToVault(
+  req: Request,
+  manifestPath: string,
+  supervisor: Supervisor | undefined,
+): Promise<Response | undefined> {
   // Lenient — see hub#406. One bad services.json row no longer takes
   // down vault routing the way it used to take down /admin/setup and
   // /api/modules (the symptom Aaron hit 2026-05-26).
@@ -557,7 +599,11 @@ async function proxyToVault(req: Request, manifestPath: string): Promise<Respons
   // both proxies keeps the dispatch surface consistent for future readers.
   const stripPrefix = stripPrefixFor(match.entry);
   const targetPath = stripPrefix ? url.pathname.slice(match.mount.length) || "/" : undefined;
-  return proxyRequest(req, match.port, "vault", targetPath);
+  // Vault's short is the literal "vault" — fixed by KNOWN_MODULES. Multiple
+  // vault instances share the same supervisor key under hub's current
+  // single-vault-per-hub model; if multi-vault-per-hub ever ships, the
+  // classifier will need a per-instance key.
+  return proxyRequest(req, match.port, "vault", "vault", supervisor, targetPath);
 }
 
 /**
@@ -613,7 +659,11 @@ export function findServiceUpstream(
  *
  * Returns `undefined` when no service claims the pathname; caller 404s.
  */
-async function proxyToService(req: Request, manifestPath: string): Promise<Response | undefined> {
+async function proxyToService(
+  req: Request,
+  manifestPath: string,
+  supervisor: Supervisor | undefined,
+): Promise<Response | undefined> {
   // Lenient read on the hot-path — a single malformed services.json
   // entry (e.g. a module installed at a buggy version that wrote
   // `port: 0`) used to cascade into 500s for every route on this hub
@@ -649,7 +699,13 @@ async function proxyToService(req: Request, manifestPath: string): Promise<Respo
   // services).
   const stripPrefix = stripPrefixFor(match.entry);
   const targetPath = stripPrefix ? url.pathname.slice(match.mount.length) || "/" : undefined;
-  return proxyRequest(req, match.port, match.entry.name, targetPath);
+  // Resolve canonical short for classification — falls back to the
+  // services.json name when the entry isn't a KNOWN_MODULES / FALLBACK
+  // shape (third-party services have no canonical short; the classifier
+  // will land in "persistent" by default which is the safer choice for
+  // unknown lifecycle).
+  const short = shortNameForManifest(match.entry.name) ?? match.entry.name;
+  return proxyRequest(req, match.port, match.entry.name, short, supervisor, targetPath);
 }
 
 /**
@@ -1262,6 +1318,16 @@ export function hubFetch(
       );
     }
 
+    // Boot-readiness probe (hub#443). Used by the transient-state proxy
+    // error page's inline poll script to detect when a still-booting
+    // module has come up. Public + DB-free so it works during the pre-
+    // admin lockout (the page that polls it is itself served pre-auth).
+    if (pathname === "/api/ready") {
+      const readyDeps: Parameters<typeof handleApiReady>[1] = {};
+      if (deps?.supervisor !== undefined) readyDeps.supervisor = deps.supervisor;
+      return handleApiReady(req, readyDeps);
+    }
+
     // First-boot setup wizard (hub#259). Three steps server-rendered:
     //   GET  /admin/setup            — derive state, render the right step
     //   POST /admin/setup/account    — create the admin row, set session
@@ -1975,6 +2041,17 @@ export function hubFetch(
       return new Response("method not allowed", { status: 405 });
     }
 
+    // /login/2fa — second-factor step (hub#473). POST-only: reached only
+    // after a correct password POST for a 2FA-enrolled user handed back a
+    // pending-login cookie + rendered the challenge page. A bare GET (e.g.
+    // browser back button) has no form to render usefully, so 405 → the
+    // operator restarts at /login.
+    if (pathname === "/login/2fa") {
+      if (!getDb) return dbNotConfigured();
+      if (req.method === "POST") return handleAdminLoginTotpPost(getDb(), req);
+      return new Response("method not allowed", { status: 405 });
+    }
+
     if (pathname === "/logout") {
       if (!getDb) return dbNotConfigured();
       if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
@@ -2002,6 +2079,35 @@ export function hubFetch(
       return new Response("method not allowed", { status: 405 });
     }
 
+    // /account/2fa — user self-service TOTP 2FA enroll / disenroll (hub#473).
+    // Both GET (render state) and POST (start/confirm/disable) require an
+    // active session; the handler does the session check + 302 to /login when
+    // missing, same posture as /account/change-password.
+    if (pathname === "/account/2fa") {
+      if (!getDb) return dbNotConfigured();
+      const twoFactorDeps = { db: getDb() };
+      if (req.method === "GET") return handleTwoFactorGet(req, twoFactorDeps);
+      if (req.method === "POST") return handleTwoFactorPost(req, twoFactorDeps);
+      return new Response("method not allowed", { status: 405 });
+    }
+
+    // /account/vault-token/<name> — friend-facing scoped vault token mint.
+    // POST-only, session-gated, assignment-capped: a non-admin friend mints a
+    // `vault:<name>:read|write` bearer for a vault they're ASSIGNED to, for
+    // scripts / headless clients that can't do browser OAuth. The handler
+    // enforces session → assignment → scope-cap (never `:admin`, never a
+    // vault outside the assignment, never a broader verb than the role
+    // grants) + CSRF + per-user rate limit. Must precede the `/account/`
+    // match below (more specific prefix). See `account-vault-token.ts`.
+    if (pathname.startsWith("/account/vault-token/")) {
+      if (!getDb) return dbNotConfigured();
+      if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+      const vaultName = decodeURIComponent(pathname.slice("/account/vault-token/".length));
+      const db = getDb();
+      const hubOrigin = resolveIssuer(req, db, configuredIssuer);
+      return handleAccountVaultTokenPost(req, vaultName, { db, hubOrigin });
+    }
+
     // /account/ — friend-facing user home (multi-user Phase 1 follow-up).
     // Companion to the first-admin gate on `/admin/host-admin-token`: a
     // signed-in non-admin (friend) lands here instead of bouncing against
@@ -2041,7 +2147,7 @@ export function hubFetch(
     // here anymore (the SPA moved to /admin), so we can't accidentally
     // mask a backend 404 with HTML.
     if (pathname.startsWith("/vault/")) {
-      const proxied = await proxyToVault(req, manifestPath);
+      const proxied = await proxyToVault(req, manifestPath, deps?.supervisor);
       if (proxied) return decorateWithChrome(proxied, req, pathname, getDb);
       return new Response("not found", { status: 404 });
     }
@@ -2068,7 +2174,7 @@ export function hubFetch(
     // here only after every hub-owned prefix above has had its turn — so
     // `/`, `/admin/*`, `/oauth/*`, `/.well-known/*`, `/hub/*`, `/vault/*`,
     // `/api/*` are excluded by ordering, not by an explicit denylist (#182).
-    const proxied = await proxyToService(req, manifestPath);
+    const proxied = await proxyToService(req, manifestPath, deps?.supervisor);
     if (proxied) return decorateWithChrome(proxied, req, pathname, getDb);
 
     // Branded fall-through 404 (closes hub#392) — the operator who mistyped

package/src/hub-settings.ts

@@ -42,6 +42,17 @@ export type HubSettingKey =
   // (vault's first-boot may write its own paths shape that the wizard
   // can't trust to match `<name>` exactly until the spawn settles).
   | "setup_vault_name"
+  // hub#168 Cut 2: operator explicitly chose Skip on the vault step.
+  // The vault module is installed (init.ts ran `install vault
+  // --no-create` per Cut 1), but no first-vault instance was created
+  // or imported. `deriveWizardState` consults this flag to advance
+  // past the vault step on subsequent GETs even though `hasVault`
+  // remains false. Value is the literal string "true" when set; absent
+  // means "operator hasn't skipped". Cleared if the operator later
+  // creates a vault from the admin SPA — that path can either delete
+  // this row directly or let the next wizard GET notice `hasVault ===
+  // true` and ignore the skip flag.
+  | "setup_vault_skipped"
   // hub#275: which dist-tag the runtime module installer uses
   // (`bun add -g <pkg>@<channel>`). `"latest"` (default) tracks the
   // stable channel; `"rc"` follows the release-candidate chain so