@openparachute/hub 0.5.13 → 0.5.14-rc.10

package/README.md

@@ -61,33 +61,122 @@ Operators who want env-var-driven seeding (CI, scripted deploys) can still set `
 
 ## First 5 minutes
 
+One command gets you from a fresh install to the setup wizard:
+
 ```sh
 # 1. Install the hub (one line — installs the `parachute` binary)
 bun add -g @openparachute/hub
 
-# 2. Install a service (runs `bun add -g @openparachute/vault` + `parachute-vault init`)
-parachute install vault
+# 2. parachute init — the unified front door (laptop, EC2, any VPS).
+#    It starts the hub, offers to expose it, always installs the vault
+#    module, then drops you into the setup wizard.
+parachute init
+```
 
-# 3. Start the service in the background (PID + logs tracked under ~/.parachute/vault/)
-parachute start vault
+`parachute init` is idempotent — every re-run is safe. End to end it:
+
+1. **Starts the hub** if it isn't already running (port `1939`).
+2. **Offers to expose it** so you can reach the wizard from other devices. In a
+   terminal you pick: stay loopback-only, your **tailnet** (`tailscale serve` —
+   private to your own Tailscale devices), or a **Cloudflare Tunnel** (public
+   HTTPS on your own domain). The default highlights "no thanks — loopback" on a
+   laptop and pre-selects Cloudflare on an SSH'd server. Skip with
+   `--no-expose-prompt`, or pin non-interactively with
+   `--expose none|tailnet|cloudflare`.
+3. **Installs the vault module** — always — so the wizard can offer
+   create / import / skip. No vault *instance* is created yet; that's the
+   wizard's call.
+4. **Drops you into the setup wizard.** Browser by default (opens
+   `/admin/setup`); pick the in-terminal walk-through with `--cli-wizard`, or
+   force the browser with `--browser-wizard`. It prints the canonical admin URL
+   either way — loopback when you're not exposed, the tailnet / Cloudflare FQDN
+   when you are.
+
+The wizard walks the same three steps in the browser and the CLI:
+
+- **Account** — create the admin operator for this hub (username + password).
+- **Vault** — *create* a fresh vault (default name `default`), *import* one from
+  a git repo (a previously-exported Parachute vault on any HTTPS / SSH remote;
+  PAT optional for private repos), or *skip* and create one later. The vault
+  module is installed regardless of which you pick.
+- **Expose** — record how this hub is reached (localhost / tailnet / public) so
+  the done screen surfaces the right URLs.
+
+The done screen hands you a copy-pasteable `claude mcp add` command (with a
+freshly-minted operator token), a link to start using your vault, and the admin
+UI. Verify the stack any time:
 
-# 4. Check it landed — reads ~/.parachute/services.json, shows process state + probes health
+```sh
 parachute status
 # SERVICE          PORT  VERSION  PROCESS  PID    UPTIME  HEALTH  LATENCY
-# parachute-vault  1940  0.2.4    running  12345  12s     ok      2ms
+# parachute-hub    1939  0.5.14   running  12344  20s     ok      1ms
+# parachute-vault  1940  0.4.5    running  12345  12s     ok      2ms
+```
 
-# 5. Use it. Vault is up on 127.0.0.1:1940; Claude Code picked up the MCP
-#    on your next session. Point any other local MCP client (Codex, Goose,
-#    OpenCode, Cursor, Zed, Cline, your own agent) at:
-#      http://127.0.0.1:1940/vault/default/mcp
+Vault is up on `127.0.0.1:1940`; Claude Code picks up the MCP on your next
+session. Point any other local MCP client (Codex, Goose, OpenCode, Cursor, Zed,
+Cline, your own agent) at `http://127.0.0.1:1940/vault/<name>/mcp`.
 
-# 6. Expose across your tailnet — HTTPS, MagicDNS, only your devices.
-#    The supported exposure shape today; public-internet exposure is
-#    exploratory (see "Public exposure" below).
-parachute expose tailnet
+### Want the wizard in the terminal instead of the browser?
+
+```sh
+parachute init --cli-wizard
 ```
 
-Tear down with `parachute expose tailnet off`. The public layer (`expose public off`) tears down independently — `off` only affects the layer you name.
+…or drive the wizard directly against an already-running hub:
+
+```sh
+parachute setup-wizard --hub-url http://127.0.0.1:1939
+```
+
+`setup-wizard` is the in-terminal mirror of `/admin/setup` — same handlers, same
+Account → Vault → Expose walk. Every prompt has a paired flag for scripted /
+non-interactive setup (`--account-username`, `--account-password`,
+`--vault-mode create|import|skip`, `--vault-name`, `--vault-import-url`,
+`--expose-mode localhost|tailnet|public`, …); run `parachute setup-wizard --help`
+for the full list.
+
+### Prefer to drive installs by hand?
+
+`parachute init` → wizard is the recommended path, but the per-module commands
+still work and are additive:
+
+```sh
+parachute install vault   # install + register + create first vault + start one module
+parachute setup           # older interactive multi-pick: survey + install vault/notes/scribe
+parachute start vault     # PID + logs tracked under ~/.parachute/vault/
+```
+
+### Expose across your tailnet
+
+```sh
+parachute expose tailnet  # HTTPS, MagicDNS, only your devices (the supported shape today)
+```
+
+Tear down with `parachute expose tailnet off`. The public layer (`expose public off`) tears down independently — `off` only affects the layer you name. Public-internet exposure is exploratory (see "Public exposure" below).
+
+### Onboarding a team member
+
+Want to give a friend or teammate their own account on your hub? The flow is
+self-service end to end:
+
+1. **Create the user.** In the admin UI, open **Users → Create User**: pick a
+   username, set a temporary password, and (optionally) assign one or more
+   vaults. The success banner echoes the exact sign-in URL.
+2. **Hand them three things:** your hub's sign-in URL (`<hub-origin>/login`),
+   their username, and the temporary password you set.
+3. **They sign in and set their own password.** On first sign-in they're
+   prompted to change it — they can't reach the rest of the hub until they do.
+4. **Later changes are self-service.** A signed-in user changes their password
+   anytime from their account home at `/account/` (reachable via the **Account**
+   link in the top-right once signed in).
+5. **You can reset it for them.** If they're locked out, the **Reset password**
+   button on the Users row sets a new temporary password and re-arms the
+   force-change-on-next-sign-in prompt.
+
+The first admin (the wizard / env-seeded account) is unrestricted and can't be
+deleted or reset from the Users page — it changes its own password at
+`/account/change-password` directly.
 
 ## Service lifecycle
 
@@ -313,6 +402,11 @@ Public-internet exposure (`parachute expose public`) is exploratory — see "Pub
 Run `parachute --help` for the top-level list, and `parachute <subcommand> --help` for details on any individual command.
 
 ```
+parachute init                    fresh-install front door: start hub, offer expose,
+                                  install vault module, open the setup wizard
+parachute setup-wizard --hub-url <url>
+                                  in-terminal mirror of /admin/setup (Account/Vault/Expose)
+parachute setup                   older interactive multi-pick service installer
 parachute install <service>       install and register a service
 parachute status                  show installed services, process state, health
 parachute start   [service]       start services in the background

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.13",
-  "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
+  "version": "0.5.14-rc.10",
+  "description": "parachute \u2014 the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {
     "access": "public"

package/src/__tests__/account-home-ui.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Renderer tests for the friend-facing `/account/` home (multi-user
+ * Phase 1 follow-up). The page is a pure function over its opts — these
+ * tests pin the load-bearing shape:
+ *
+ *   - Assigned-vault branch: Notes CTA href encodes the hub+vault URL,
+ *     vault name shows in the body, AND a per-tile MCP connect block
+ *     surfaces the endpoint + `claude mcp add` command (OAuth, no token)
+ *     with copy buttons — the multi-user friend-connect surface.
+ *   - Admin (no assigned vault) branch: link to /admin/ visible.
+ *   - Defensive third branch (non-admin + no vault): "ask the operator"
+ *     copy renders.
+ *   - Common scaffolding: username in welcome, sign-out POST form,
+ *     change-password link.
+ */
+import { describe, expect, test } from "bun:test";
+import {
+  accountClaudeMcpAddCommand,
+  accountMcpEndpoint,
+  renderAccountHome,
+} from "../account-home-ui.ts";
+
+const HUB_ORIGIN = "https://hub.example";
+const CSRF = "test-csrf-token";
+
+describe("renderAccountHome", () => {
+  test("assigned-vault branch — Notes CTA carries the encoded hub+vault URL", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["alice"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+    });
+    // Welcome header includes the username.
+    expect(html).toContain("Welcome, alice");
+    // Vault name renders as inline content in the vault card.
+    expect(html).toContain("<strong>alice</strong>");
+    // Notes "Open" CTA — same shape as setup-wizard's renderStartUsingTile.
+    // The href encodes `${hubOrigin}/vault/<name>` via encodeURIComponent.
+    const encodedVaultUrl = encodeURIComponent(`${HUB_ORIGIN}/vault/alice`);
+    expect(html).toContain(`https://notes.parachute.computer/add?url=${encodedVaultUrl}`);
+    expect(html).toContain('target="_blank"');
+    expect(html).toContain('rel="noopener"');
+    // The friend-connect surface: MCP endpoint + `claude mcp add` command,
+    // each with a copy button. OAuth path (no token in the command).
+    expect(html).toContain(`${HUB_ORIGIN}/vault/alice/mcp`);
+    expect(html).toContain(
+      `claude mcp add --transport http parachute-alice ${HUB_ORIGIN}/vault/alice/mcp`,
+    );
+    expect(html).toContain('data-testid="copy-mcp-endpoint"');
+    expect(html).toContain('data-testid="copy-mcp-add-command"');
+    // The connect command must NOT embed a token — the OAuth path needs none.
+    expect(html).not.toContain("--header");
+    expect(html).not.toContain("Authorization: Bearer");
+    // Copy-button progressive-enhancement script is present.
+    expect(html).toContain("navigator.clipboard");
+  });
+
+  test("assigned-vault branch — trailing slash on hubOrigin is normalized", () => {
+    // The handler resolves origin per-request via `resolveIssuer`; some
+    // operators set a hub_origin setting with a trailing slash. The
+    // renderer must produce a clean `/vault/<name>` join either way.
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["alice"],
+      passwordChanged: true,
+      hubOrigin: `${HUB_ORIGIN}/`,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+    });
+    const cleanEncoded = encodeURIComponent(`${HUB_ORIGIN}/vault/alice`);
+    expect(html).toContain(`https://notes.parachute.computer/add?url=${cleanEncoded}`);
+    // The MCP endpoint + connect command also drop the trailing slash — no
+    // `//vault` double-slash sneaks in.
+    expect(html).toContain(`${HUB_ORIGIN}/vault/alice/mcp`);
+    expect(html).not.toContain(`${HUB_ORIGIN}//vault`);
+  });
+
+  test("admin branch — null assignedVault + isFirstAdmin renders an /admin/ link", () => {
+    const html = renderAccountHome({
+      username: "admin",
+      assignedVaults: [],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: true,
+      csrfToken: CSRF,
+    });
+    expect(html).toContain("Welcome, admin");
+    expect(html).toContain("hub administrator");
+    expect(html).toContain('href="/admin/"');
+    // Should NOT carry the Notes CTA (no vault).
+    expect(html).not.toContain("notes.parachute.computer/add");
+  });
+
+  test("defensive branch — non-admin with null assignedVault renders an 'ask operator' message", () => {
+    // Shouldn't normally occur in Phase 1 (PR 2's /api/users always
+    // assigns a vault on create), but the renderer carries a clear
+    // explanation rather than a blank card if a row gets into that
+    // state via hand-edit or migration race.
+    const html = renderAccountHome({
+      username: "ghost",
+      assignedVaults: [],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+    });
+    expect(html).toContain("Welcome, ghost");
+    expect(html).toContain("Ask the hub operator");
+    // No /admin/ link in this branch — they have no admin role.
+    expect(html).not.toContain('href="/admin/"');
+    // No Notes CTA.
+    expect(html).not.toContain("notes.parachute.computer/add");
+  });
+
+  test("account card — change-password link and sign-out form are present", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["alice"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+    });
+    // Change-password link points at the existing /account/change-password
+    // route (server-rendered HTML, separate handler).
+    expect(html).toContain('href="/account/change-password"');
+    // Sign-out form POSTs to /logout (existing handler), CSRF token
+    // round-trips via the renderCsrfHiddenInput helper.
+    expect(html).toContain('action="/logout"');
+    expect(html).toContain('method="POST"');
+    expect(html).toContain(CSRF);
+    // Username renders inside the account card too.
+    expect(html).toContain("<code>alice</code>");
+  });
+
+  test("multi-vault branch — renders one tile per assigned vault (Phase 2 PR 2)", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["personal", "family"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+    });
+    // Plural heading.
+    expect(html).toContain("Your vaults");
+    // Each vault name appears.
+    expect(html).toContain("<strong>personal</strong>");
+    expect(html).toContain("<strong>family</strong>");
+    // One CTA per vault with the right encoded URL.
+    const personalEncoded = encodeURIComponent(`${HUB_ORIGIN}/vault/personal`);
+    const familyEncoded = encodeURIComponent(`${HUB_ORIGIN}/vault/family`);
+    expect(html).toContain(`https://notes.parachute.computer/add?url=${personalEncoded}`);
+    expect(html).toContain(`https://notes.parachute.computer/add?url=${familyEncoded}`);
+    // One per-vault MCP connect block per tile (endpoint + command).
+    expect(html).toContain(`${HUB_ORIGIN}/vault/personal/mcp`);
+    expect(html).toContain(`${HUB_ORIGIN}/vault/family/mcp`);
+    expect(html).toContain(
+      `claude mcp add --transport http parachute-personal ${HUB_ORIGIN}/vault/personal/mcp`,
+    );
+    expect(html).toContain(
+      `claude mcp add --transport http parachute-family ${HUB_ORIGIN}/vault/family/mcp`,
+    );
+    // Two tiles → two copy-endpoint buttons.
+    expect(html.split('data-testid="copy-mcp-endpoint"').length - 1).toBe(2);
+    // The copy script is emitted once at the section level, not per-tile.
+    expect(html.split("<script>").length - 1).toBe(1);
+  });
+
+  test("accountMcpEndpoint / accountClaudeMcpAddCommand build the canonical shapes", () => {
+    expect(accountMcpEndpoint("https://hub.example", "work")).toBe(
+      "https://hub.example/vault/work/mcp",
+    );
+    expect(accountClaudeMcpAddCommand("https://hub.example", "work")).toBe(
+      "claude mcp add --transport http parachute-work https://hub.example/vault/work/mcp",
+    );
+  });
+
+  test("escapes hostile content in username and vault name", () => {
+    // Defense-in-depth: usernames pass validateUsername (lowercase alnum
+    // + `_-`), so HTML metacharacters won't normally make it through. But
+    // the renderer is a pure function over arbitrary string input and the
+    // escape is load-bearing if the validator ever loosens.
+    const html = renderAccountHome({
+      username: "<script>alert(1)</script>",
+      assignedVaults: ["<vault>"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+    });
+    // The injected username/vault metacharacters are escaped — the only
+    // `<script>` tag in the output is the page's own copy-button helper, so
+    // we assert on the injected payload specifically rather than a blanket
+    // "no <script>" (the connect block legitimately emits one).
+    expect(html).not.toContain("<script>alert(1)</script>");
+    expect(html).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
+    expect(html).toContain("&lt;vault&gt;");
+    // The escaped vault name also flows into the connect command + endpoint.
+    expect(html).toContain("parachute-&lt;vault&gt;");
+  });
+});

package/src/__tests__/admin-handlers.test.ts

@@ -426,6 +426,80 @@ describe("loginRedirectTarget — force-change-password (multi-user PR 3)", () =
     expect(res.headers.get("location")).toBe("/admin/tokens");
   });
 
+  test("non-admin (friend) targeting /admin/* gets rewritten to /account/", async () => {
+    // Multi-user follow-up: a signed-in friend account hitting an /admin/*
+    // URL via post-login `next=` would otherwise land on the admin SPA,
+    // which 403s on `/admin/host-admin-token` (first-admin gate) and
+    // bounces them back via the SPA-side 403 handler. Rewriting at the
+    // login boundary skips the bouncing-around UX. Friend has
+    // passwordChanged=true so the force-change path doesn't pre-empt.
+    await createUser(harness.db, "admin", "admin-pw", { passwordChanged: true });
+    await createUser(harness.db, "alice", "alice-pw", {
+      allowMulti: true,
+      passwordChanged: true,
+    });
+    const { body, headers } = formBody({
+      [CSRF_FIELD_NAME]: TEST_CSRF,
+      username: "alice",
+      password: "alice-pw",
+      next: "/admin/users",
+    });
+    const req = new Request("http://hub.test/login", {
+      method: "POST",
+      headers: { ...headers, cookie: CSRF_COOKIE },
+      body,
+    });
+    const res = await handleAdminLoginPost(harness.db, req);
+    expect(res.status).toBe(302);
+    expect(res.headers.get("location")).toBe("/account/");
+  });
+
+  test("admin targeting /admin/* still lands at the original next= (rewrite doesn't fire for admin)", async () => {
+    // Belt-and-suspenders for the friend rewrite above: the same next=
+    // for the admin user must NOT redirect to /account/.
+    await createUser(harness.db, "admin", "admin-pw", { passwordChanged: true });
+    const { body, headers } = formBody({
+      [CSRF_FIELD_NAME]: TEST_CSRF,
+      username: "admin",
+      password: "admin-pw",
+      next: "/admin/users",
+    });
+    const req = new Request("http://hub.test/login", {
+      method: "POST",
+      headers: { ...headers, cookie: CSRF_COOKIE },
+      body,
+    });
+    const res = await handleAdminLoginPost(harness.db, req);
+    expect(res.status).toBe(302);
+    expect(res.headers.get("location")).toBe("/admin/users");
+  });
+
+  test("non-admin (friend) keeps non-/admin next= intact (e.g. /oauth/authorize, /vault/...)", async () => {
+    // Legitimate user destinations — OAuth consent + per-vault routes —
+    // must pass through unchanged. Friends sign in through /login as part
+    // of the OAuth user-consent flow; rewriting their next= to /account/
+    // would break that.
+    await createUser(harness.db, "admin", "admin-pw", { passwordChanged: true });
+    await createUser(harness.db, "alice", "alice-pw", {
+      allowMulti: true,
+      passwordChanged: true,
+    });
+    const { body, headers } = formBody({
+      [CSRF_FIELD_NAME]: TEST_CSRF,
+      username: "alice",
+      password: "alice-pw",
+      next: "/oauth/authorize?client_id=abc",
+    });
+    const req = new Request("http://hub.test/login", {
+      method: "POST",
+      headers: { ...headers, cookie: CSRF_COOKIE },
+      body,
+    });
+    const res = await handleAdminLoginPost(harness.db, req);
+    expect(res.status).toBe(302);
+    expect(res.headers.get("location")).toBe("/oauth/authorize?client_id=abc");
+  });
+
   test("password_changed=false defense-in-depth: unsafe next= is sanitized before encoding", async () => {
     // safeNext rewrites unsafe next values to /admin/vaults BEFORE the
     // redirect-target helper runs. The change-password URL should never

package/src/__tests__/admin-host-admin-token.test.ts

@@ -56,6 +56,31 @@ async function withSession(): Promise<{ cookie: string; userId: string }> {
   return { cookie, userId: user.id };
 }
 
+/**
+ * Seed an admin (first-created user) + a second non-admin "friend"
+ * account, return cookies + ids for both. Used by the first-admin-gate
+ * tests.
+ */
+async function withAdminAndFriend(): Promise<{
+  adminCookie: string;
+  adminId: string;
+  friendCookie: string;
+  friendId: string;
+}> {
+  const admin = await createUser(harness.db, "admin", "admin-passphrase");
+  const friend = await createUser(harness.db, "alice", "alice-passphrase", {
+    allowMulti: true,
+  });
+  const adminSession = createSession(harness.db, { userId: admin.id });
+  const friendSession = createSession(harness.db, { userId: friend.id });
+  return {
+    adminCookie: buildSessionCookie(adminSession.id, Math.floor(SESSION_TTL_MS / 1000)),
+    adminId: admin.id,
+    friendCookie: buildSessionCookie(friendSession.id, Math.floor(SESSION_TTL_MS / 1000)),
+    friendId: friend.id,
+  };
+}
+
 describe("handleHostAdminToken", () => {
   test("401 when no session cookie is present", async () => {
     const req = new Request(`${ISSUER}/admin/host-admin-token`);
@@ -124,6 +149,43 @@ describe("handleHostAdminToken", () => {
     expect(scopes).toContain("parachute:host:auth");
   });
 
+  test("403 not_admin when a signed-in non-first-admin (friend) hits the endpoint", async () => {
+    // Privesc closure: without the first-admin gate, any signed-in
+    // friend account could mint a JWT carrying parachute:host:admin +
+    // parachute:host:auth — the SPA bearer that gates vault provisioning,
+    // grants, and the token registry. The friend's session is valid;
+    // the endpoint must refuse because the session.userId doesn't match
+    // the first-admin row.
+    const { friendCookie } = await withAdminAndFriend();
+    rotateSigningKey(harness.db);
+    const req = new Request(`${ISSUER}/admin/host-admin-token`, {
+      headers: { cookie: friendCookie },
+    });
+    const res = await handleHostAdminToken(req, { db: harness.db, issuer: ISSUER });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: string; error_description: string };
+    expect(body.error).toBe("not_admin");
+    // The wire description steers the SPA-side handler toward /account/.
+    expect(body.error_description).toContain("/account/");
+  });
+
+  test("first-admin path still succeeds when a friend exists alongside", async () => {
+    // Belt-and-suspenders for the gate above: adding a second user must
+    // not break the admin's own happy path. Same DB, same query — the
+    // admin's session.userId matches the earliest-created row, so the
+    // gate passes.
+    const { adminCookie, adminId } = await withAdminAndFriend();
+    rotateSigningKey(harness.db);
+    const req = new Request(`${ISSUER}/admin/host-admin-token`, {
+      headers: { cookie: adminCookie },
+    });
+    const res = await handleHostAdminToken(req, { db: harness.db, issuer: ISSUER });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { token: string };
+    const validated = await validateAccessToken(harness.db, body.token, ISSUER);
+    expect(validated.payload.sub).toBe(adminId);
+  });
+
   // Regression for the end-to-end bug that motivated adding `:host:auth`
   // here: the SPA's session-bearer was rejected by `/api/auth/tokens` (and
   // its peers) because it carried `:host:admin` only. This test mints

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

@@ -152,6 +152,50 @@ describe("handleVaultAdminToken", () => {
     expect(scopeClaim.split(/\s+/)).toContain("vault:work:admin");
   });
 
+  test("403 not_admin when the session belongs to a non-first-admin user", async () => {
+    // Multi-user Phase 1 privesc gate (mirrors host-admin-token). The first-
+    // created user is the hub admin; subsequent users are friends pinned to
+    // a single vault and must NOT be able to mint vault:<name>:admin via
+    // this endpoint. The session check alone would let them — that's the
+    // whole reason this gate exists.
+    await createUser(harness.db, "operator", "hunter2-admin");
+    const friend = await createUser(harness.db, "friend", "hunter2-friend", {
+      assignedVaults: ["work"],
+      allowMulti: true,
+    });
+    const session = createSession(harness.db, { userId: friend.id });
+    const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
+    const req = new Request(`${ISSUER}/admin/vault-admin-token/work`, { headers: { cookie } });
+    const res = await handleVaultAdminToken(req, "work", {
+      db: harness.db,
+      issuer: ISSUER,
+      knownVaultNames: known("work", "default"),
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: string; error_description: string };
+    expect(body.error).toBe("not_admin");
+    expect(body.error_description).toContain("/account/");
+  });
+
+  test("first admin still mints when other users exist", async () => {
+    // Regression: the first-admin gate must not regress the operator's
+    // happy path when there are friends in the DB.
+    const admin = await createUser(harness.db, "operator", "hunter2-admin");
+    await createUser(harness.db, "friend", "hunter2-friend", {
+      assignedVaults: ["work"],
+      allowMulti: true,
+    });
+    const session = createSession(harness.db, { userId: admin.id });
+    const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
+    const req = new Request(`${ISSUER}/admin/vault-admin-token/work`, { headers: { cookie } });
+    const res = await handleVaultAdminToken(req, "work", {
+      db: harness.db,
+      issuer: ISSUER,
+      knownVaultNames: known("work"),
+    });
+    expect(res.status).toBe(200);
+  });
+
   test("audience is per-vault — different vaults get different aud claims", async () => {
     // Regression for PR #173 follow-up: a single shared audience constant
     // meant a token minted for vault `boulder` carried `aud: "hub"` and