@openparachute/hub 0.5.13 → 0.5.14-rc.10

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}
@@ -82,7 +89,7 @@ Environment:
 
 Examples:
   parachute install vault                                   # installs, runs init, starts vault
-  parachute install app                                     # installs app (auto-bootstraps Notes)
+  parachute install surface                                 # installs surface (auto-bootstraps Notes)
   parachute install notes                                   # back-compat: legacy notes-daemon (Phase 2 deprecating)
   parachute install scribe                                  # installs, prompts for provider, starts scribe
   parachute install scribe --scribe-provider groq --scribe-key gsk_…
@@ -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: admin)
+  --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
 
@@ -188,7 +313,7 @@ Example:
   parachute-vault  1940  0.2.4    active  12345  2h 13m  2ms      bun-linked → parachute-vault @ 8aa167b
     → http://127.0.0.1:1940/vault/default/mcp
   parachute-app    1946  0.2.0    active  12346  2h 12m  3ms      npm (0.2.0-rc.4)
-    → http://127.0.0.1:1946/app/notes
+    → http://127.0.0.1:1946/surface/notes
 `;
 }
 
@@ -466,29 +591,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

@@ -278,6 +278,48 @@ const MIGRATIONS: readonly Migration[] = [
       UPDATE clients SET same_hub = 0;
     `,
   },
+  {
+    version: 10,
+    sql: `
+      -- Multi-user Phase 2 PR 2 (hub#252 follow-up, design
+      -- 2026-05-20-multi-user-phase-1.md §Phase 2). Lifts the single
+      -- \`users.assigned_vault TEXT\` column into a many-to-many
+      -- \`user_vaults\` table so one user can have access to multiple
+      -- vaults (e.g. a personal vault + a family-shared vault).
+      --
+      -- Schema:
+      --   * (user_id, vault_name) composite PK — one row per (user, vault).
+      --     ON DELETE CASCADE on user_id so user deletion drops the
+      --     assignments without us having to clean up manually.
+      --   * \`role\` TEXT DEFAULT 'write' — reserved for forward-compat per-
+      --     vault role granularity. Phase 1 had no role model; this column
+      --     gives later PRs a column to land scope-narrowing in without a
+      --     second migration. All backfilled rows default to 'write'.
+      --   * index on \`vault_name\` for the inverse lookup ("who has access
+      --     to vault X?") — useful when admin removes a vault and we want
+      --     to warn about pinned users.
+      --
+      -- Backfill: every existing row in \`users\` with a non-null
+      -- \`assigned_vault\` becomes a single (user_id, vault_name) row in
+      -- \`user_vaults\`. Rows with NULL \`assigned_vault\` (admin posture)
+      -- get no \`user_vaults\` entry — they remain "no narrowing" per
+      -- vaultScopeForUser semantics. After backfill the \`assigned_vault\`
+      -- column is dropped.
+      CREATE TABLE user_vaults (
+        user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+        vault_name TEXT NOT NULL,
+        role TEXT NOT NULL DEFAULT 'write',
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (user_id, vault_name)
+      );
+      CREATE INDEX user_vaults_vault ON user_vaults (vault_name);
+      INSERT INTO user_vaults (user_id, vault_name, role, created_at)
+      SELECT id, assigned_vault, 'write', created_at
+      FROM users
+      WHERE assigned_vault IS NOT NULL;
+      ALTER TABLE users DROP COLUMN assigned_vault;
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {

package/src/hub-server.ts

@@ -23,7 +23,7 @@
  *   /admin/login, /admin/logout                → 301 → /login, /logout
  *
  *   # Notes-as-app migration Phase 2 (parachute-app design doc §16).
- *   /notes, /notes/, /notes/*                  → 301 → /app/notes[/...]
+ *   /notes, /notes/, /notes/*                  → 301 → /surface/notes[/...]
  *                                                (opt-out via
  *                                                 hub_settings.notes_redirect_disabled)
  *
@@ -65,6 +65,7 @@
  *   /api/users                    (GET + POST) → list / create user (host:admin)
  *   /api/users/vaults             (GET)        → vault-name list for assigned-vault picker (host:admin)
  *   /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
  *   /logout                       (POST)       → end admin session
  *   /account/change-password      (GET + POST) → user self-service change-password
@@ -117,7 +118,11 @@ import {
 import { handleHostAdminToken } from "./admin-host-admin-token.ts";
 import { handleVaultAdminToken } from "./admin-vault-admin-token.ts";
 import { handleCreateVault } from "./admin-vaults.ts";
-import { handleAccountChangePasswordGet, handleAccountChangePasswordPost } from "./api-account.ts";
+import {
+  handleAccountChangePasswordGet,
+  handleAccountChangePasswordPost,
+  handleAccountHomeGet,
+} from "./api-account.ts";
 import { handleApiHub } from "./api-hub.ts";
 import { handleApiMe } from "./api-me.ts";
 import { handleApiMintToken } from "./api-mint-token.ts";
@@ -132,6 +137,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";
@@ -141,6 +147,8 @@ import {
   handleDeleteUser,
   handleListUsers,
   handleListVaults,
+  handleResetUserPassword,
+  handleUpdateUserVaults,
 } from "./api-users.ts";
 import { buildChromeForRequest, injectChromeIntoResponse } from "./chrome-strip.ts";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "./config.ts";
@@ -170,6 +178,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,
@@ -266,10 +276,7 @@ export function parseArgs(argv: string[], env: NodeJS.ProcessEnv = process.env):
   if (hostname === undefined) hostname = env.PARACHUTE_BIND_HOST || "127.0.0.1";
   if (wellKnownDir === undefined) wellKnownDir = WELL_KNOWN_DIR;
   if (issuer === undefined) {
-    const fromEnv =
-      env.PARACHUTE_HUB_ORIGIN ??
-      env.RENDER_EXTERNAL_URL ??
-      flyDefaultOrigin(env);
+    const fromEnv = env.PARACHUTE_HUB_ORIGIN ?? env.RENDER_EXTERNAL_URL ?? flyDefaultOrigin(env);
     if (fromEnv) issuer = fromEnv.replace(/\/+$/, "") || undefined;
   }
   return { port, hostname, wellKnownDir, dbPath: dbPath ?? hubDbPath(), issuer };
@@ -442,10 +449,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
@@ -456,6 +474,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);
@@ -515,10 +535,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);
   }
 }
 
@@ -532,7 +562,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).
@@ -553,7 +587,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);
 }
 
 /**
@@ -609,7 +647,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
@@ -645,7 +687,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);
 }
 
 /**
@@ -1118,8 +1166,7 @@ export function hubFetch(
           // browser POSTs and must be trusted even when the operator's
           // configured issuer points elsewhere. See origin-check.ts
           // jsdoc for the failure case this closes.
-          platformOrigin:
-            process.env.RENDER_EXTERNAL_URL ?? flyDefaultOrigin(process.env),
+          platformOrigin: process.env.RENDER_EXTERNAL_URL ?? flyDefaultOrigin(process.env),
         }),
     };
   };
@@ -1199,7 +1246,7 @@ export function hubFetch(
     }
 
     // Notes-as-app migration Phase 2 (parachute-app design doc §16).
-    // `/notes/*` 301-redirects to `/app/notes/*` so legacy bookmarks land on
+    // `/notes/*` 301-redirects to `/surface/notes/*` so legacy bookmarks land on
     // the apps-hosted Notes. Default-on; operators on notes-as-module-only
     // installs can opt out via `hub_settings.notes_redirect_disabled = true`
     // (see hub-settings.ts). The opt-out exists so a legacy operator
@@ -1259,6 +1306,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
@@ -1908,6 +1965,44 @@ export function hubFetch(
         manifestPath,
       });
     }
+    // Phase 2 PR 1 — `/api/users/:id/reset-password` (admin-initiated
+    // password reset for non-admin users). Routed BEFORE the per-id DELETE
+    // catch-all so the trailing `/reset-password` segment isn't mistaken
+    // for part of a user id. Same `host:admin` Bearer gate as the other
+    // /api/users surfaces.
+    {
+      const resetMatch = pathname.match(/^\/api\/users\/([^/]+)\/reset-password$/);
+      if (resetMatch) {
+        if (!getDb) return dbNotConfigured();
+        const id = decodeURIComponent(resetMatch[1] ?? "");
+        if (!id) {
+          return new Response("not found", { status: 404 });
+        }
+        return handleResetUserPassword(req, id, {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          manifestPath,
+        });
+      }
+    }
+    // Phase 2 PR 2 — `/api/users/:id/vaults` (replace a user's vault
+    // assignments). Routed before the per-id DELETE catch-all so the
+    // trailing `/vaults` segment isn't mistaken for part of a user id.
+    {
+      const vaultsMatch = pathname.match(/^\/api\/users\/([^/]+)\/vaults$/);
+      if (vaultsMatch) {
+        if (!getDb) return dbNotConfigured();
+        const id = decodeURIComponent(vaultsMatch[1] ?? "");
+        if (!id) {
+          return new Response("not found", { status: 404 });
+        }
+        return handleUpdateUserVaults(req, id, {
+          db: getDb(),
+          issuer: oauthDeps(req).issuer,
+          manifestPath,
+        });
+      }
+    }
     if (pathname.startsWith("/api/users/")) {
       if (!getDb) return dbNotConfigured();
       const id = decodeURIComponent(pathname.slice("/api/users/".length));
@@ -1961,6 +2056,24 @@ export function hubFetch(
       return new Response("method not allowed", { status: 405 });
     }
 
+    // /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
+    // a 403 wall on the admin SPA. Admin users also land here when they
+    // hit `/account/` directly, with a "you're the administrator → /admin/"
+    // exit ramp. Bare `/account` 301-redirects to `/account/` so links
+    // without the trailing slash work.
+    if (pathname === "/account" || pathname === "/account/") {
+      if (req.method !== "GET") return new Response("method not allowed", { status: 405 });
+      if (pathname === "/account") {
+        return new Response(null, { status: 301, headers: { location: "/account/" } });
+      }
+      if (!getDb) return dbNotConfigured();
+      const db = getDb();
+      const hubOrigin = resolveIssuer(req, db, configuredIssuer);
+      return handleAccountHomeGet(req, { db, hubOrigin });
+    }
+
     // Legacy `/admin/config` (server-rendered module-config portal, #46)
     // retired post-SPA-rework. 301 → the SPA home so any bookmark or stale
     // post-login redirect lands somewhere useful. The route stays here in
@@ -1982,7 +2095,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 });
     }
@@ -2009,7 +2122,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
@@ -2032,7 +2145,7 @@ export function hubFetch(
  * Inject the persistent chrome strip (workstream G) into a proxied response.
  *
  * Skips the rewrite when the response is non-200, non-HTML, on an opt-out
- * path (e.g. `/app/notes/*`), or larger than `MAX_INJECT_SIZE_BYTES`.
+ * path (e.g. `/surface/notes/*`), or larger than `MAX_INJECT_SIZE_BYTES`.
  * `injectChromeIntoResponse` is the no-side-effects implementation; this
  * wrapper threads in the session-aware chrome HTML and a `set-cookie`
  * append when a fresh CSRF cookie was minted.

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
@@ -71,7 +82,7 @@ export type HubSettingKey =
   | "hub_origin"
   // Notes-as-app migration Phase 2 (parachute-app design doc §16).
   // When unset (default) or "false", hub serves a 301 redirect from
-  // `/notes/*` → `/app/notes/*` so existing bookmarks transparently
+  // `/notes/*` → `/surface/notes/*` so existing bookmarks transparently
   // follow the operator to the apps-hosted Notes. When "true", the
   // redirect is skipped and `/notes/*` falls through to the existing
   // services.json-driven proxy — the escape hatch for operators
@@ -372,7 +383,7 @@ export function setHubOrigin(db: Database, value: string | null): void {
 // --- domain helpers: notes-as-app redirect (parachute-app §16 Phase 2) ----
 
 /**
- * Read whether the `/notes/*` → `/app/notes/*` redirect is disabled. Default
+ * Read whether the `/notes/*` → `/surface/notes/*` redirect is disabled. Default
  * is `false` (redirect on) — Phase 2 migrates operators to apps-hosted
  * Notes, so the bookmark-friendly path is the default-on behavior. Only an
  * operator running notes-as-a-module without parachute-app installed should