@openparachute/hub 0.5.10-rc.9 → 0.5.10

package/src/setup-wizard.ts

@@ -665,21 +665,111 @@ function renderMcpTile(
   const bareCmd = `claude mcp add --transport http parachute-${vaultName} ${hubOrigin}/vault/${vaultName}/mcp`;
   if (mintedToken) {
     // The token contents are surfaced once + then forgotten by the
-    // server (single-use hub_setting). Render the full command with
-    // the Bearer header pre-filled. The `--header` value is shell-
-    // quoted (double quotes) — bash + zsh both consume it as one arg.
+    // server (single-use hub_setting). Two visible variants of the
+    // command live in the DOM:
+    //
+    //   * `pre#mcp-cmd` — what the operator sees. The Bearer token is
+    //     replaced with a fixed-width row of • so shoulder-surfers,
+    //     screencasts, and over-the-shoulder photos don't capture
+    //     credentials by default. This is the "discoverable but not
+    //     shoulder-surf-able" framing Aaron asked for.
+    //   * `script#mcp-cmd-real` (type=text/plain) — the real command
+    //     with the live token, stashed in a non-rendering script tag.
+    //     The Copy + Show handlers read from this so the operator's
+    //     terminal paste still gets the real header without the page
+    //     ever painting the token.
+    //
+    // The view-source threat model is unchanged from rc.9 — the token
+    // is part of the response body either way. The improvement is
+    // *visibly hidden by default*, which is what an over-the-shoulder
+    // observer needs (and what existing screencasts of the wizard
+    // currently leak).
+    //
+    // Show toggles textContent between masked + real and flips a
+    // data-state attribute so a screencast / pair-programming session
+    // can briefly reveal-and-rehide without the operator losing the
+    // line of sight on which mode they're in. Auto-hide after 10s so
+    // a forgotten reveal doesn't leak the token into a subsequent
+    // recording.
     const fullCmd = `${bareCmd} --header "Authorization: Bearer ${mintedToken}"`;
+    // Clamp the dot count to a 8–40 range so very-short or very-long
+    // tokens don't render comically — token format is fixed-width
+    // (JTI-derived), so this is purely visual.
+    const maskedToken = "•".repeat(Math.max(8, Math.min(40, mintedToken.length)));
+    const maskedCmd = `${bareCmd} --header "Authorization: Bearer ${maskedToken}"`;
+    // The real command rides in a hidden <script type="application/json">
+    // block as a JSON-encoded string. <script> element content is parsed
+    // as raw text (no entity references), so HTML escaping would put
+    // literal `&quot;` into the string — and Copy would paste that into
+    // the operator's terminal. JSON encoding (with `</` escaped so the
+    // sequence can't prematurely close the tag) round-trips safely:
+    // textContent returns the JSON, JSON.parse decodes back to the
+    // exact bytes of the original command. Caught while smoke-testing
+    // the rc.11 reveal/copy UX — pre-fix, the copied command included
+    // `&quot;` placeholders that broke shell parsing.
+    const fullCmdJson = JSON.stringify(fullCmd).replace(/<\//g, "<\\/");
     return `<div class="done-tile">
       <h2>Connect Claude Code (MCP)</h2>
       <p>Wire <code>vault:${safeVault}</code> into Claude Code as an MCP server:</p>
-      <div class="mcp-cmd-wrap">
-        <pre id="mcp-cmd">${escapeHtml(fullCmd)}</pre>
-        <button type="button" class="btn btn-copy" data-target="mcp-cmd"
-          onclick="(function(b){var el=document.getElementById(b.dataset.target);if(!el)return;navigator.clipboard.writeText(el.textContent||'').then(function(){b.textContent='Copied ✓';setTimeout(function(){b.textContent='Copy';},2000);});})(this)">Copy</button>
+      <div class="mcp-cmd-wrap" data-state="masked">
+        <pre id="mcp-cmd">${escapeHtml(maskedCmd)}</pre>
+        <script type="application/json" id="mcp-cmd-real">${fullCmdJson}</script>
+        <div class="mcp-cmd-actions">
+          <button type="button" class="btn btn-mcp-aux" id="mcp-cmd-show">Show token</button>
+          <button type="button" class="btn btn-copy" id="mcp-cmd-copy">Copy</button>
+        </div>
       </div>
       <p class="fine">We minted this token for your first MCP connection.
-        It's a full-scope operator token tied to your admin account; manage
-        and revoke tokens at <a href="/admin/tokens"><code>/admin/tokens</code></a>.</p>
+        It's masked above so it's safe to leave open on screen; Copy
+        copies the real command. It's a full-scope operator token tied
+        to your admin account; manage and revoke tokens at
+        <a href="/admin/tokens"><code>/admin/tokens</code></a>.</p>
+      <script>
+        (function () {
+          var wrap = document.querySelector('.mcp-cmd-wrap[data-state]');
+          var pre = document.getElementById('mcp-cmd');
+          var real = document.getElementById('mcp-cmd-real');
+          var copyBtn = document.getElementById('mcp-cmd-copy');
+          var showBtn = document.getElementById('mcp-cmd-show');
+          if (!wrap || !pre || !real || !copyBtn || !showBtn) return;
+          var realCmd;
+          try { realCmd = JSON.parse(real.textContent || '""'); }
+          catch (e) { realCmd = ''; }
+          var maskedCmd = pre.textContent || '';
+          var revealTimer = null;
+          function setMasked() {
+            pre.textContent = maskedCmd;
+            wrap.setAttribute('data-state', 'masked');
+            showBtn.textContent = 'Show token';
+            if (revealTimer) { clearTimeout(revealTimer); revealTimer = null; }
+          }
+          function setRevealed() {
+            pre.textContent = realCmd;
+            wrap.setAttribute('data-state', 'revealed');
+            showBtn.textContent = 'Hide token';
+            // Auto-hide after 10s so a stray reveal doesn't leak the
+            // token into a screencast capture that started after the
+            // click.
+            if (revealTimer) { clearTimeout(revealTimer); revealTimer = null; }
+            revealTimer = setTimeout(setMasked, 10000);
+          }
+          showBtn.addEventListener('click', function () {
+            if (wrap.getAttribute('data-state') === 'masked') setRevealed();
+            else setMasked();
+          });
+          copyBtn.addEventListener('click', function () {
+            // Copy ALWAYS pulls from the real command — the operator's
+            // terminal needs the live token regardless of whether the
+            // page is currently masked. This is the load-bearing path:
+            // the visible mask is a UX nicety; the clipboard must
+            // carry the real header.
+            navigator.clipboard.writeText(realCmd).then(function () {
+              copyBtn.textContent = 'Copied ✓';
+              setTimeout(function () { copyBtn.textContent = 'Copy'; }, 2000);
+            });
+          });
+        })();
+      </script>
     </div>`;
   }
   return `<div class="done-tile">
@@ -999,7 +1089,12 @@ export async function handleSetupAccountPost(
     return htmlResponse(renderAccountStep({ csrfToken, username, errorMessage: fieldErr }), 400);
   }
   try {
-    const user = await createUser(deps.db, username, password);
+    // Wizard-admin chose their password through this very form; skip the
+    // multi-user-Phase-1 force-change-password redirect by landing
+    // `password_changed=true`. `assignedVault` stays null — admin posture
+    // (the wizard never asks the first admin to pin themselves to a
+    // single vault; that's a non-admin user pattern).
+    const user = await createUser(deps.db, username, password, { passwordChanged: true });
     const session = createSession(deps.db, { userId: user.id });
     const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000), {
       secure: isHttpsRequest(req),
@@ -1701,9 +1796,15 @@ const STYLES = `
   .btn-secondary:hover {
     background: ${PALETTE.accentSoft};
   }
-  /* Copy button rides at the right edge of the MCP command pre. Compact
-     vertical sizing so it doesn't dwarf the snippet on narrow widths;
-     full text wrap on the pre keeps the snippet readable behind it. */
+  /* Copy + Show buttons ride the right edge of the MCP command pre.
+     Compact vertical sizing so they don't dwarf the snippet on narrow
+     widths; full text wrap on the pre keeps the snippet readable
+     behind them. The Show button toggles the visible mask on the
+     auto-minted Bearer token (rc.11 — discoverable
+     but not shoulder-surf-able). Both buttons share a small flex
+     container so they stack predictably on the wrap; layout-wise we
+     keep the right-edge padding on .mcp-cmd-wrap pre so the buttons
+     never overlap the command text. */
   .mcp-cmd-wrap {
     position: relative;
     margin: 0.5rem 0;
@@ -1712,17 +1813,21 @@ const STYLES = `
     background: ${PALETTE.bg};
     border: 1px solid ${PALETTE.borderLight};
     border-radius: 6px;
-    padding: 0.5rem 5.5rem 0.5rem 0.75rem;
+    padding: 0.5rem 8.5rem 0.5rem 0.75rem;
     overflow-x: auto;
     font-size: 0.82rem;
     margin: 0;
     white-space: pre-wrap;
     word-break: break-all;
   }
-  .btn-copy {
+  .mcp-cmd-actions {
     position: absolute;
     top: 0.35rem;
     right: 0.35rem;
+    display: flex;
+    gap: 0.3rem;
+  }
+  .btn-copy, .btn-mcp-aux {
     padding: 0.25rem 0.6rem;
     font-size: 0.78rem;
     min-height: auto;
@@ -1731,11 +1836,24 @@ const STYLES = `
     border: 1px solid ${PALETTE.border};
     border-radius: 4px;
     cursor: pointer;
+    font: inherit;
+    font-size: 0.78rem;
   }
-  .btn-copy:hover {
+  .btn-copy:hover, .btn-mcp-aux:hover {
     border-color: ${PALETTE.accent};
     color: ${PALETTE.accent};
   }
+  .mcp-cmd-wrap[data-state="revealed"] pre {
+    /* Subtle visual cue that the token is currently visible — a warm
+       border so the operator notices on a screencast even at low
+       resolution. */
+    border-color: #d4a017;
+    background: rgba(212, 160, 23, 0.04);
+  }
+  .mcp-cmd-wrap[data-state="revealed"] .btn-mcp-aux {
+    border-color: #d4a017;
+    color: #6b4a00;
+  }
   /* Install-tile section (hub#272 Item B). Lives above the .done-grid;
      primary "what's next?" surface. Tiles render in a responsive grid
      that collapses to one column on narrow viewports. */

package/src/users.ts

@@ -25,6 +25,25 @@ export interface User {
   passwordHash: string;
   createdAt: string;
   updatedAt: string;
+  /**
+   * Whether the user has changed their password since account creation.
+   * `false` means the user signed up with an admin-typed default password
+   * and the force-change-password flow at sign-in time should redirect
+   * them to `/account/change-password`. The wizard's first admin and env-
+   * seeded admins land as `true` (they chose their own password). Stored
+   * as `users.password_changed INTEGER 0|1` (added in migration v8).
+   */
+  passwordChanged: boolean;
+  /**
+   * The vault instance name this user is pinned to (Phase 1 multi-user is
+   * single-vault-per-user). `null` means "no per-vault restriction" — the
+   * default for admin accounts, where the OAuth issuer mints tokens for
+   * any requested vault. Non-null pins the issuer to narrow scopes to
+   * `vault:<assigned_vault>:<verb>`. No FK; vault names resolve through
+   * `services.json` at mint time. Stored as `users.assigned_vault TEXT`
+   * (added in migration v8).
+   */
+  assignedVault: string | null;
 }
 
 export class SingleUserModeError extends Error {
@@ -56,6 +75,8 @@ interface Row {
   password_hash: string;
   created_at: string;
   updated_at: string;
+  password_changed: number;
+  assigned_vault: string | null;
 }
 
 function rowToUser(r: Row): User {
@@ -65,6 +86,8 @@ function rowToUser(r: Row): User {
     passwordHash: r.password_hash,
     createdAt: r.created_at,
     updatedAt: r.updated_at,
+    passwordChanged: r.password_changed === 1,
+    assignedVault: r.assigned_vault,
   };
 }
 
@@ -72,6 +95,23 @@ export interface CreateUserOpts {
   /** Allow creating an additional user when one already exists. Off by default. */
   allowMulti?: boolean;
   now?: () => Date;
+  /**
+   * Whether the new user has already chosen their password. Default `false`
+   * — the admin-creates-user path (PR 2) lands new accounts with the bit
+   * unset so the user is force-redirected to change it on first sign-in
+   * (PR 3). The wizard's first-admin path and env-seeded admin path pass
+   * `true` (they chose their own password through the wizard form / env
+   * vars; no force-change needed).
+   */
+  passwordChanged?: boolean;
+  /**
+   * Vault instance name to pin the user to (Phase 1 single-vault). `null`
+   * (default) means "no restriction" — admin posture. The OAuth issuer
+   * (PR 4) reads this at mint time to narrow scopes. No validation here:
+   * the API endpoint (PR 2) is responsible for checking against
+   * `services.json` before passing through.
+   */
+  assignedVault?: string | null;
 }
 
 export async function createUser(
@@ -87,10 +127,14 @@ export async function createUser(
   const id = randomUUID();
   const passwordHash = await argonHash(password);
   const stamp = (opts.now?.() ?? new Date()).toISOString();
+  const passwordChanged = opts.passwordChanged === true ? 1 : 0;
+  const assignedVault = opts.assignedVault ?? null;
   try {
     db.prepare(
-      "INSERT INTO users (id, username, password_hash, created_at, updated_at) VALUES (?, ?, ?, ?, ?)",
-    ).run(id, username, passwordHash, stamp, stamp);
+      `INSERT INTO users
+         (id, username, password_hash, created_at, updated_at, password_changed, assigned_vault)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    ).run(id, username, passwordHash, stamp, stamp, passwordChanged, assignedVault);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes("UNIQUE") && msg.includes("users.username")) {
@@ -98,7 +142,15 @@ export async function createUser(
     }
     throw err;
   }
-  return { id, username, passwordHash, createdAt: stamp, updatedAt: stamp };
+  return {
+    id,
+    username,
+    passwordHash,
+    createdAt: stamp,
+    updatedAt: stamp,
+    passwordChanged: passwordChanged === 1,
+    assignedVault,
+  };
 }
 
 export function getUserByUsername(db: Database, username: string): User | null {
@@ -106,6 +158,22 @@ export function getUserByUsername(db: Database, username: string): User | null {
   return row ? rowToUser(row) : null;
 }
 
+/**
+ * Case-insensitive username lookup. Username validation already pins
+ * the canonical form to lowercase (`[a-z0-9_-]`), so the only way a
+ * mixed-case lookup ever fires is a defense-in-depth check at the
+ * admin-create-user boundary — a future loosening of the validator
+ * (or a hand-edited row) wouldn't accidentally allow `Bob` to land
+ * alongside an existing `bob`. SQLite's `COLLATE NOCASE` does the work
+ * with no schema change.
+ */
+export function getUserByUsernameCI(db: Database, username: string): User | null {
+  const row = db
+    .query<Row, [string]>("SELECT * FROM users WHERE username = ? COLLATE NOCASE")
+    .get(username);
+  return row ? rowToUser(row) : null;
+}
+
 export function getUserById(db: Database, id: string): User | null {
   const row = db.query<Row, [string]>("SELECT * FROM users WHERE id = ?").get(id);
   return row ? rowToUser(row) : null;
@@ -142,3 +210,142 @@ export async function setPassword(
     .run(passwordHash, stamp, userId);
   if (result.changes === 0) throw new UserNotFoundError(userId);
 }
+
+/**
+ * Hard-delete a user row and clean up FK-dependent rows.
+ *
+ * Schema reality at v8:
+ *   - `tokens.user_id` is nullable (made nullable in migration v6). The
+ *     plan from the design doc is "tokens stay with `revoked_at` set so
+ *     the audit trail of 'this user existed and held these tokens'
+ *     survives." But the FK is RESTRICT-on-delete, so we need to null
+ *     out `tokens.user_id` after revoking to actually delete the
+ *     parent users row. The audit trail survives via the `subject`
+ *     column we backfill from the username plus the existing
+ *     `created_at`, `scopes`, `client_id`, `revoked_at` fields.
+ *   - `sessions.user_id` and `grants.user_id` are NOT NULL with a
+ *     non-cascading FK. Both are deleted before the users row drops.
+ *
+ * Returns false when no user matches the id (idempotent — the API
+ * layer translates that to 404). Returns true on a successful delete.
+ *
+ * Caller is responsible for the first-admin-undeletable check; this
+ * helper enforces no policy beyond the schema hygiene.
+ */
+export function deleteUser(db: Database, userId: string): boolean {
+  const row = db.query<Row, [string]>("SELECT * FROM users WHERE id = ?").get(userId);
+  if (!row) return false;
+  const now = new Date().toISOString();
+  db.transaction(() => {
+    // 1. Revoke + retain tokens for audit. Mark every un-revoked token
+    //    revoked, then null out user_id on every token (revoked or
+    //    not) so the FK doesn't block the users delete. Backfill
+    //    `subject` with the username so the audit trail isn't anchored
+    //    to a primary key that just vanished.
+    db.prepare("UPDATE tokens SET revoked_at = ? WHERE user_id = ? AND revoked_at IS NULL").run(
+      now,
+      userId,
+    );
+    db.prepare(
+      "UPDATE tokens SET subject = COALESCE(subject, ?), user_id = NULL WHERE user_id = ?",
+    ).run(row.username, userId);
+    // 2. Drop sessions + grants. Both have non-cascading FKs on user_id;
+    //    leaving rows behind would RESTRICT the users delete below.
+    db.prepare("DELETE FROM sessions WHERE user_id = ?").run(userId);
+    db.prepare("DELETE FROM grants WHERE user_id = ?").run(userId);
+    // 3. Drop the user row itself.
+    db.prepare("DELETE FROM users WHERE id = ?").run(userId);
+  })();
+  return true;
+}
+
+/**
+ * Username validation (multi-user Phase 1, design 2026-05-20-multi-user-phase-1.md §4).
+ *
+ * Rules — settled with Aaron pre-PR-1:
+ *   * Charset: `[a-z0-9_-]` (lowercase letters, digits, underscore, hyphen).
+ *     Lowercase-only sidesteps "Bob vs bob" case-folding bugs across every
+ *     downstream surface (URLs, log lines, the admin SPA's row keys).
+ *   * Length: 2-32 chars inclusive. Hard floor on 1-char names (no `a`,
+ *     `b`, …) because those are too easy to typo into someone else's
+ *     account; hard ceiling on 32 because URL paths and log lines stay
+ *     scannable. (Same shape vault-side scope verbs use.)
+ *   * Reserved list (case-insensitive): admin, root, system, setup,
+ *     parachute, hub. Keeps URL-shaped surfaces safe (Phase 2 may add
+ *     `/users/<username>` paths; reserving the namespace now is cheap).
+ *     Regex already pins lowercase, but the case-folded check is defense
+ *     in depth: if a future loosening lets capitals through, the reserved
+ *     check still triggers on `Admin`, `ROOT`, etc.
+ *
+ * Discriminated-union return: callers branch on `valid` rather than
+ * throwing. PR 2's `POST /api/users` returns a 400 with the `reason`
+ * surfaced in the response body.
+ */
+export const USERNAME_RESERVED = ["admin", "root", "system", "setup", "parachute", "hub"] as const;
+
+const USERNAME_REGEX = /^[a-z0-9_-]+$/;
+const USERNAME_MIN_LEN = 2;
+const USERNAME_MAX_LEN = 32;
+
+export type ValidateUsernameResult =
+  | { valid: true; name: string }
+  | { valid: false; reason: "format" | "length" | "reserved" };
+
+export function validateUsername(name: string): ValidateUsernameResult {
+  // Length check first — a 0-char string fails the regex on emptiness but
+  // "length" is the more honest diagnostic.
+  if (name.length < USERNAME_MIN_LEN || name.length > USERNAME_MAX_LEN) {
+    return { valid: false, reason: "length" };
+  }
+  // The regex deliberately allows leading/trailing `_` and `-` (so
+  // `_-_`, `--alice`, `-foo`, `bar_` all pass the format gate). Stricter
+  // rules can land later if real-world users hit confusion. Vault's
+  // parallel username validator has the same shape — cross-repo parity
+  // matters more than aesthetic edge-case rejection here.
+  if (!USERNAME_REGEX.test(name)) {
+    return { valid: false, reason: "format" };
+  }
+  // Reserved-words check is case-insensitive even though the regex already
+  // pins lowercase — see comment above.
+  const lower = name.toLowerCase();
+  if (USERNAME_RESERVED.some((r) => r === lower)) {
+    return { valid: false, reason: "reserved" };
+  }
+  return { valid: true, name };
+}
+
+/**
+ * Password validation (multi-user Phase 1, design §5).
+ *
+ * Single rule: minimum 12 characters. No complexity classes — modern
+ * guidance (NIST 800-63B) prefers passphrase length over forced-symbol
+ * mixes, and Aaron settled on 12 as the floor pre-PR-1. No max length
+ * (argon2id absorbs whatever the user submits).
+ *
+ * Same discriminated-union shape as `validateUsername` — PR 2's create-
+ * user / reset-password endpoints (and PR 3's `/account/change-password`
+ * form) wire the `reason` into the response.
+ */
+export const PASSWORD_MIN_LEN = 12;
+
+/**
+ * Upper bound for incoming password bodies. Not enforced inside
+ * `validatePassword` itself — the validator's contract is "length floor,
+ * no complexity rules" and adding a ceiling would muddy it. Exposed as
+ * a constant so PR 2's `POST /api/users` (and PR 3's change-password
+ * form) can cap incoming bodies before argon2id touches them. Defense
+ * against a CPU-DoS shape where an unauthenticated POST submits a
+ * megabyte password and forces a long argon2id hash. 256 chars is
+ * comfortably above any human-chosen passphrase (Diceware 8-word
+ * passphrases run ~55 chars).
+ */
+export const PASSWORD_MAX_LEN = 256;
+
+export type ValidatePasswordResult = { valid: true } | { valid: false; reason: "too_short" };
+
+export function validatePassword(password: string): ValidatePasswordResult {
+  if (password.length < PASSWORD_MIN_LEN) {
+    return { valid: false, reason: "too_short" };
+  }
+  return { valid: true };
+}

package/src/vault-names.ts

@@ -0,0 +1,57 @@
+/**
+ * Vault-name list — the single source of truth for "which vault instances are
+ * registered on this hub right now."
+ *
+ * Multi-user Phase 1, PR 4 of 5 (design
+ * [`parachute.computer/design/2026-05-20-multi-user-phase-1.md`](https://parachute.computer/design/2026-05-20-multi-user-phase-1/)).
+ * Consolidates the two pre-PR-4 copies that read services.json and emitted
+ * vault names — one was private inside `oauth-handlers.ts` (used by the
+ * consent vault picker + post-consent narrowing), the other was private
+ * inside `api-users.ts` (used by `GET /api/users/vaults` for the admin SPA's
+ * assigned-vault dropdown + `POST /api/users` validation). PR 4 wires a third
+ * caller — server-side defense in `handleConsentSubmit` refusing mints
+ * whose picked vault disagrees with the user's `assigned_vault` — so the
+ * two private copies became three, and a duplicated read-and-derive helper
+ * for "what vaults exist" is exactly the shape that needs a single owner.
+ *
+ * Lives next to `well-known.ts` (which already owns `isVaultEntry` +
+ * `vaultInstanceNameFor`) rather than inside it: well-known's role is the
+ * `/.well-known/parachute.json` document shape, and a free-floating list
+ * helper would muddy that file's surface. Standalone module keeps the
+ * focused-purpose contract.
+ *
+ * Walks both manifest shapes: single-entry-multi-path (`parachute-vault`
+ * with `paths: ["/vault/work", "/vault/personal"]`) and per-vault entries
+ * (`parachute-vault-work`) by delegating each (name, path) pair to
+ * `vaultInstanceNameFor`. Entries with no paths still resolve to a name via
+ * the helper's manifest-suffix fallback (hub#143).
+ */
+import { type ServicesManifest, readManifest } from "./services-manifest.ts";
+import { isVaultEntry, vaultInstanceNameFor } from "./well-known.ts";
+
+/**
+ * Emit each vault instance's name from an in-memory manifest. Sorted output
+ * keeps callers (consent picker dropdown, admin SPA dropdown, server-side
+ * defense lookup) deterministic without each having to wrap in their own
+ * `.sort()`.
+ */
+export function listVaultNames(manifest: ServicesManifest): string[] {
+  const names = new Set<string>();
+  for (const svc of manifest.services) {
+    if (!isVaultEntry(svc)) continue;
+    const paths = svc.paths.length > 0 ? svc.paths : [undefined];
+    for (const path of paths) {
+      names.add(vaultInstanceNameFor(svc.name, path));
+    }
+  }
+  return Array.from(names).sort();
+}
+
+/**
+ * Read-from-disk convenience for callers that already have a manifest path
+ * (e.g. `/api/users/vaults` reading the live `services.json`). Equivalent to
+ * `listVaultNames(readManifest(manifestPath))`.
+ */
+export function listVaultNamesFromPath(manifestPath: string): string[] {
+  return listVaultNames(readManifest(manifestPath));
+}