@openparachute/hub 0.5.14-rc.14 → 0.5.14-rc.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.14-rc.14",
+  "version": "0.5.14-rc.16",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

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

@@ -57,6 +57,23 @@ describe("renderAccountHome", () => {
     expect(html).not.toContain("Authorization: Bearer");
     // Copy-button progressive-enhancement script is present.
     expect(html).toContain("navigator.clipboard");
+    // Friendlier framing: the block leads with "connect your AI assistant"
+    // rather than MCP jargon up top.
+    expect(html).toContain('data-testid="connect-ai-heading"');
+    expect(html).toContain("Connect your AI");
+    // BOTH connect methods render as distinct, labelled blocks.
+    expect(html).toContain('data-testid="connect-method-claude-code"');
+    expect(html).toContain("Claude Code");
+    expect(html).toContain('data-testid="connect-method-claude-ai"');
+    expect(html).toContain("Claude.ai");
+    // The Claude.ai path mirrors the install.njk canonical phrasing
+    // (Settings → Connectors → Add custom connector, paste the endpoint).
+    expect(html).toContain("Connectors");
+    expect(html).toContain("Add custom connector");
+    // A brief "any other MCP client" line is present (no bloat — just one).
+    expect(html).toContain('data-testid="connect-any-client-hint"');
+    // Notes CTA still present, now framed as the browser-UI option.
+    expect(html).toContain('data-testid="open-notes-cta"');
   });
 
   test("assigned-vault branch — trailing slash on hubOrigin is normalized", () => {
@@ -112,11 +129,16 @@ describe("renderAccountHome", () => {
       twoFactorEnabled: false,
     });
     expect(html).toContain("Welcome, ghost");
-    expect(html).toContain("Ask the hub operator");
+    // The message explains WHY there's nothing to connect (no vault yet) and
+    // gives a clear next step — not just a bare "ask your admin".
+    expect(html).toContain("Ask the hub operator to assign you a vault");
+    expect(html).toContain("don't have a vault yet");
     // 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");
+    // No connect block — you can't connect a vault you don't have.
+    expect(html).not.toContain('data-testid="mcp-connect"');
   });
 
   test("account card — change-password link and sign-out form are present", () => {
@@ -240,4 +262,138 @@ describe("renderAccountHome", () => {
     // The escaped vault name also flows into the connect command + endpoint.
     expect(html).toContain("parachute-<vault>");
   });
+
+  // --- friend vault-token mint affordance (the new surface) ----------------
+
+  test("mint affordance — read+write tile offers both verbs, POSTs to the right path", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["work"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      mintableVerbs: { work: ["read", "write"] },
+    });
+    // The collapsible mint block is present, framed as secondary (headless).
+    expect(html).toContain('data-testid="token-mint"');
+    expect(html).toContain("Mint an access token");
+    expect(html).toContain("for scripts / headless clients");
+    // Both verb radios render.
+    expect(html).toContain('data-testid="mint-verb-read"');
+    expect(html).toContain('data-testid="mint-verb-write"');
+    // Form POSTs to the per-vault endpoint with the CSRF token embedded.
+    expect(html).toContain('action="/account/vault-token/work"');
+    expect(html).toContain('method="POST"');
+    expect(html).toContain('data-testid="mint-form"');
+    expect(html).toContain(CSRF);
+    // Recommends the no-token path as default.
+    expect(html).toContain("no-token");
+  });
+
+  test("mint affordance — a read-only role offers ONLY the read verb", () => {
+    // Today every assignment is write-role, but the renderer is verb-blind to
+    // the role: it shows exactly the verbs it's handed. A read-only cap must
+    // never surface a write radio (the server would reject it anyway).
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["work"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      mintableVerbs: { work: ["read"] },
+    });
+    expect(html).toContain('data-testid="mint-verb-read"');
+    expect(html).not.toContain('data-testid="mint-verb-write"');
+  });
+
+  test("mint affordance — never offers an admin verb", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["work"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      mintableVerbs: { work: ["read", "write"] },
+    });
+    expect(html).not.toContain('value="admin"');
+    expect(html).not.toContain('data-testid="mint-verb-admin"');
+  });
+
+  test("mint affordance — absent when no mintable verbs (admin / no-vault / unmapped role)", () => {
+    // Admin branch: no tiles at all, so no mint block.
+    const admin = renderAccountHome({
+      username: "admin",
+      assignedVaults: [],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: true,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+    });
+    expect(admin).not.toContain('data-testid="token-mint"');
+    // Assigned vault but empty verb list (fail-closed unknown role) → no block.
+    const empty = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["work"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      mintableVerbs: { work: [] },
+    });
+    expect(empty).not.toContain('data-testid="token-mint"');
+  });
+
+  test("minted-token banner — shows the token once with a save-it warning, no revoke claim", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["work"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      mintableVerbs: { work: ["read", "write"] },
+      mintedToken: {
+        vaultName: "work",
+        verb: "read",
+        token: "eyJhbGciOi.FAKE.TOKEN",
+        expiresInDays: 90,
+      },
+    });
+    expect(html).toContain('data-testid="minted-token-banner"');
+    expect(html).toContain("eyJhbGciOi.FAKE.TOKEN");
+    expect(html).toContain('data-testid="copy-minted-token"');
+    // Explicit "won't be shown again" + the scope + the TTL.
+    expect(html).toContain("won't be shown again");
+    expect(html).toContain("vault:work:read");
+    expect(html).toContain("90 days");
+    // No false revoke-yourself promise (no friend-facing revoke today).
+    expect(html).toContain("ask the hub operator");
+  });
+
+  test("mint error banner — surfaces an inline authorization error", () => {
+    const html = renderAccountHome({
+      username: "alice",
+      assignedVaults: ["work"],
+      passwordChanged: true,
+      hubOrigin: HUB_ORIGIN,
+      isFirstAdmin: false,
+      csrfToken: CSRF,
+      twoFactorEnabled: false,
+      mintableVerbs: { work: ["read", "write"] },
+      mintError: 'You\'re not assigned to a vault named "other".',
+    });
+    expect(html).toContain('data-testid="mint-error-banner"');
+    expect(html).toContain("not assigned");
+    // Error render must NOT also show a token.
+    expect(html).not.toContain('data-testid="minted-token-banner"');
+  });
 });

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

@@ -0,0 +1,355 @@
+/**
+ * Security tests for the friend-facing scoped vault token mint —
+ * `POST /account/vault-token/<name>` (`handleAccountVaultTokenPost`).
+ *
+ * This is a new auth-mint surface, so the authorization is tested
+ * adversarially. The spine:
+ *   - No session            → 401 (no mint).
+ *   - Assigned vault        → 200, token carries `vault:<name>:<verb>`,
+ *                             `aud=vault.<name>`, `iss=<hub>`, sub=user.
+ *   - UNassigned vault      → 403 (cannot mint for a vault not in the
+ *                             user's `user_vaults` assignment — blocks
+ *                             cross-vault).
+ *   - `admin` verb          → rejected (not in the form vocabulary).
+ *   - Broader/garbage verb  → rejected.
+ *   - First admin           → 403 (no `user_vaults` rows → unrestricted
+ *                             admins use the SPA path, not this one).
+ *   - CSRF missing/mismatch → 400.
+ *   - Rate limit            → 429 after the bucket fills.
+ *   - The minted token is a valid hub JWT the vault would accept.
+ */
+import type { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ACCOUNT_VAULT_TOKEN_TTL_SECONDS } from "../account-home-ui.ts";
+import { handleAccountVaultTokenPost } from "../account-vault-token.ts";
+import { CSRF_FIELD_NAME, buildCsrfCookie, generateCsrfToken } from "../csrf.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { validateAccessToken } from "../jwt-sign.ts";
+import { __resetForTests } from "../rate-limit.ts";
+import { SESSION_TTL_MS, buildSessionCookie, createSession } from "../sessions.ts";
+import { createUser } from "../users.ts";
+
+const ISSUER = "https://hub.test";
+
+interface Harness {
+  db: Database;
+  cleanup: () => void;
+}
+
+function makeHarness(): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "phub-account-vault-token-"));
+  const db = openHubDb(hubDbPath(dir));
+  return {
+    db,
+    cleanup: () => {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+let harness: Harness;
+beforeEach(() => {
+  harness = makeHarness();
+  __resetForTests();
+});
+afterEach(() => {
+  harness.cleanup();
+  __resetForTests();
+});
+
+const deps = () => ({ db: harness.db, hubOrigin: ISSUER });
+
+/** A shared CSRF token + matching cookie value for the double-submit handshake. */
+function csrfPair(): { token: string; cookieFragment: string } {
+  const token = generateCsrfToken();
+  // buildCsrfCookie(...) → "parachute_hub_csrf=<token>; HttpOnly; ...". We only
+  // need the name=value fragment to join with the session cookie.
+  const cookie = buildCsrfCookie(token, { secure: false }).split(";")[0] ?? "";
+  return { token, cookieFragment: cookie };
+}
+
+/** Build the first-admin operator + a friend assigned to `vaults`. */
+async function seedFriend(
+  vaults: string[],
+): Promise<{ friendId: string; cookie: string; csrfToken: string }> {
+  await createUser(harness.db, "operator", "operator-password-123");
+  const friend = await createUser(harness.db, "friend", "friend-password-123", {
+    assignedVaults: vaults,
+    allowMulti: true,
+  });
+  const session = createSession(harness.db, { userId: friend.id });
+  const { token, cookieFragment } = csrfPair();
+  const sessionCookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000));
+  const cookie = `${sessionCookie}; ${cookieFragment}`;
+  return { friendId: friend.id, cookie, csrfToken: token };
+}
+
+function mintReq(
+  vaultName: string,
+  opts: { cookie?: string; csrfToken?: string; verb?: string; omitCsrf?: boolean } = {},
+): Request {
+  const body = new URLSearchParams();
+  if (!opts.omitCsrf && opts.csrfToken !== undefined) body.set(CSRF_FIELD_NAME, opts.csrfToken);
+  if (opts.verb !== undefined) body.set("verb", opts.verb);
+  const headers: Record<string, string> = {
+    "content-type": "application/x-www-form-urlencoded",
+  };
+  if (opts.cookie) headers.cookie = opts.cookie;
+  return new Request(`${ISSUER}/account/vault-token/${encodeURIComponent(vaultName)}`, {
+    method: "POST",
+    headers,
+    body: body.toString(),
+  });
+}
+
+describe("handleAccountVaultTokenPost — happy path (assigned vault)", () => {
+  test("200 mints vault:<name>:read for an assigned vault, valid hub JWT", async () => {
+    const { friendId, cookie, csrfToken } = await seedFriend(["work"]);
+    const res = await handleAccountVaultTokenPost(
+      mintReq("work", { cookie, csrfToken, verb: "read" }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(200);
+    expect(res.headers.get("cache-control")).toBe("no-store");
+    const html = await res.text();
+    expect(html).toContain('data-testid="minted-token-banner"');
+
+    // Pull the token out of the show-once banner and validate it as a hub JWT.
+    const m = html.match(/data-testid="minted-token-value">([^<]+)</);
+    expect(m).not.toBeNull();
+    const token = m![1] as string;
+    const validated = await validateAccessToken(harness.db, token, ISSUER);
+    expect(validated.payload.sub).toBe(friendId);
+    expect(validated.payload.iss).toBe(ISSUER);
+    expect(validated.payload.aud).toBe("vault.work");
+    const scopeClaim = (validated.payload as { scope?: string }).scope ?? "";
+    expect(scopeClaim.split(/\s+/)).toEqual(["vault:work:read"]);
+    // vault_scope pin — token can only ever be used against `work`.
+    expect((validated.payload as { vault_scope?: string[] }).vault_scope).toEqual(["work"]);
+
+    // TTL ≈ 90 days.
+    const expMs = new Date((validated.payload.exp ?? 0) * 1000).getTime();
+    const skew = expMs - Date.now();
+    expect(skew).toBeGreaterThan((ACCOUNT_VAULT_TOKEN_TTL_SECONDS - 60) * 1000);
+    expect(skew).toBeLessThan((ACCOUNT_VAULT_TOKEN_TTL_SECONDS + 60) * 1000);
+  });
+
+  test("200 mints vault:<name>:write when verb=write (default-role assignment)", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work"]);
+    const res = await handleAccountVaultTokenPost(
+      mintReq("work", { cookie, csrfToken, verb: "write" }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    const token = html.match(/data-testid="minted-token-value">([^<]+)</)?.[1] as string;
+    const validated = await validateAccessToken(harness.db, token, ISSUER);
+    const scopeClaim = (validated.payload as { scope?: string }).scope ?? "";
+    expect(scopeClaim.split(/\s+/)).toEqual(["vault:work:write"]);
+  });
+
+  test("a friend assigned to multiple vaults can mint for each, never cross-vault", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work", "home"]);
+    for (const v of ["work", "home"]) {
+      const res = await handleAccountVaultTokenPost(
+        mintReq(v, { cookie, csrfToken, verb: "read" }),
+        v,
+        deps(),
+      );
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      const token = html.match(/data-testid="minted-token-value">([^<]+)</)?.[1] as string;
+      const validated = await validateAccessToken(harness.db, token, ISSUER);
+      expect(validated.payload.aud).toBe(`vault.${v}`);
+    }
+    // ...but a vault NOT in {work, home} is refused.
+    const res = await handleAccountVaultTokenPost(
+      mintReq("secret", { cookie, csrfToken, verb: "read" }),
+      "secret",
+      deps(),
+    );
+    expect(res.status).toBe(403);
+  });
+});
+
+describe("handleAccountVaultTokenPost — authorization gates (adversarial)", () => {
+  test("401 when no session cookie is present", async () => {
+    // Even with a CSRF token, no session = no identity = no mint.
+    const { token, cookieFragment } = csrfPair();
+    const res = await handleAccountVaultTokenPost(
+      mintReq("work", { cookie: cookieFragment, csrfToken: token, verb: "read" }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(401);
+  });
+
+  test("403 when minting for a vault the friend is NOT assigned to (cross-vault)", async () => {
+    // Friend is assigned to `work` only; attempts `other`.
+    const { cookie, csrfToken } = await seedFriend(["work"]);
+    const res = await handleAccountVaultTokenPost(
+      mintReq("other", { cookie, csrfToken, verb: "read" }),
+      "other",
+      deps(),
+    );
+    expect(res.status).toBe(403);
+    const html = await res.text();
+    expect(html).toContain('data-testid="mint-error-banner"');
+    expect(html).toContain("not assigned");
+    // Critically: no token was minted.
+    expect(html).not.toContain('data-testid="minted-token-banner"');
+  });
+
+  test("a non-assigned friend cannot mint even for a vault that EXISTS for another user", async () => {
+    // Two friends; friend B is assigned to `shared`, friend A is not.
+    await createUser(harness.db, "operator", "operator-password-123");
+    const friendB = await createUser(harness.db, "bee", "bee-password-12345", {
+      assignedVaults: ["shared"],
+      allowMulti: true,
+    });
+    expect(friendB.id).toBeTruthy();
+    const friendA = await createUser(harness.db, "aay", "aay-password-12345", {
+      assignedVaults: ["mine"],
+      allowMulti: true,
+    });
+    const sessionA = createSession(harness.db, { userId: friendA.id });
+    const { token, cookieFragment } = csrfPair();
+    const cookie = `${buildSessionCookie(sessionA.id, Math.floor(SESSION_TTL_MS / 1000))}; ${cookieFragment}`;
+    const res = await handleAccountVaultTokenPost(
+      mintReq("shared", { cookie, csrfToken: token, verb: "read" }),
+      "shared",
+      deps(),
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test("403 — the first admin cannot mint here (no user_vaults rows; uses SPA path)", async () => {
+    // The first-created user is the unrestricted admin: empty assignedVaults,
+    // so vaultVerbsForUserVault returns null for every vault → 403. Admins
+    // mint via /admin/vault-admin-token, not this friend surface.
+    const admin = await createUser(harness.db, "operator", "operator-password-123");
+    const session = createSession(harness.db, { userId: admin.id });
+    const { token, cookieFragment } = csrfPair();
+    const cookie = `${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}; ${cookieFragment}`;
+    const res = await handleAccountVaultTokenPost(
+      mintReq("work", { cookie, csrfToken: token, verb: "read" }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test("admin verb is rejected — never mints vault:<name>:admin", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work"]);
+    const res = await handleAccountVaultTokenPost(
+      mintReq("work", { cookie, csrfToken, verb: "admin" }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(400);
+    const html = await res.text();
+    expect(html).not.toContain('data-testid="minted-token-banner"');
+    expect(html).not.toContain("vault:work:admin");
+  });
+
+  test("a garbage / broader verb is rejected", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work"]);
+    for (const verb of ["host", "delete", "read write", "*", ""]) {
+      const res = await handleAccountVaultTokenPost(
+        mintReq("work", { cookie, csrfToken, verb }),
+        "work",
+        deps(),
+      );
+      expect(res.status).toBe(400);
+    }
+  });
+
+  test("a syntactically invalid vault name is rejected before any mint", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work"]);
+    const res = await handleAccountVaultTokenPost(
+      mintReq("has..dots", { cookie, csrfToken, verb: "read" }),
+      "has..dots",
+      deps(),
+    );
+    expect(res.status).toBe(400);
+  });
+});
+
+describe("handleAccountVaultTokenPost — CSRF + method + rate limit", () => {
+  test("405 on non-POST", async () => {
+    const { cookie } = await seedFriend(["work"]);
+    const req = new Request(`${ISSUER}/account/vault-token/work`, {
+      method: "GET",
+      headers: { cookie },
+    });
+    const res = await handleAccountVaultTokenPost(req, "work", deps());
+    expect(res.status).toBe(405);
+  });
+
+  test("400 when the CSRF token is missing", async () => {
+    const { cookie } = await seedFriend(["work"]);
+    const res = await handleAccountVaultTokenPost(
+      mintReq("work", { cookie, omitCsrf: true, verb: "read" }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("400 when the CSRF form token does not match the cookie", async () => {
+    const { cookie } = await seedFriend(["work"]);
+    // Send a different (non-matching) CSRF token in the form than the cookie.
+    const res = await handleAccountVaultTokenPost(
+      mintReq("work", { cookie, csrfToken: generateCsrfToken(), verb: "read" }),
+      "work",
+      deps(),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("429 once the per-user mint bucket fills (10 / 10 min)", async () => {
+    const { cookie, csrfToken } = await seedFriend(["work"]);
+    // 10 admitted, 11th denied.
+    for (let i = 0; i < 10; i++) {
+      const res = await handleAccountVaultTokenPost(
+        mintReq("work", { cookie, csrfToken, verb: "read" }),
+        "work",
+        deps(),
+      );
+      expect(res.status).toBe(200);
+    }
+    const denied = await handleAccountVaultTokenPost(
+      mintReq("work", { cookie, csrfToken, verb: "read" }),
+      "work",
+      deps(),
+    );
+    expect(denied.status).toBe(429);
+  });
+
+  test("CSRF failure does NOT burn a rate-limit slot", async () => {
+    // A cross-site POST with a bad CSRF token should 400 before the bucket is
+    // touched — otherwise an attacker could exhaust the victim's mint bucket.
+    const { cookie, csrfToken } = await seedFriend(["work"]);
+    for (let i = 0; i < 15; i++) {
+      const res = await handleAccountVaultTokenPost(
+        mintReq("work", { cookie, csrfToken: generateCsrfToken(), verb: "read" }),
+        "work",
+        deps(),
+      );
+      expect(res.status).toBe(400);
+    }
+    // The legitimate mint still succeeds — the bucket was never touched.
+    const ok = await handleAccountVaultTokenPost(
+      mintReq("work", { cookie, csrfToken, verb: "read" }),
+      "work",
+      deps(),
+    );
+    expect(ok.status).toBe(200);
+  });
+});

package/src/__tests__/hub-server.test.ts

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { buildCsrfCookie, generateCsrfToken } from "../csrf.ts";
 import { HUB_SVC, hubPortPath } from "../hub-control.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import {
@@ -16,6 +17,7 @@ import { setNotesRedirectDisabled } from "../hub-settings.ts";
 import { clearNotesRedirectLogState } from "../notes-redirect.ts";
 import { pidPath } from "../process-state.ts";
 import { type ServiceEntry, writeManifest } from "../services-manifest.ts";
+import { buildSessionCookie, createSession } from "../sessions.ts";
 import { rotateSigningKey } from "../signing-keys.ts";
 import type { ModuleState, Supervisor } from "../supervisor.ts";
 import { createUser } from "../users.ts";
@@ -4171,3 +4173,98 @@ describe("hubFetch persistent chrome strip injection (workstream G)", () => {
     }
   });
 });
+
+describe("POST /account/vault-token/<name> — friend scoped mint (routed end-to-end)", () => {
+  // Drive the real dispatch (`hubFetch`) so the route wiring + precedence
+  // (the `/account/vault-token/` prefix must win over `/account/` and the
+  // SPA catch-all) is exercised, not just the handler in isolation.
+  async function seed(h: Harness, assignedVaults: string[]) {
+    const db = openHubDb(hubDbPath(h.dir));
+    rotateSigningKey(db); // mint needs an active signing key
+    await createUser(db, "operator", "operator-password-123");
+    const friend = await createUser(db, "friend", "friend-password-123", {
+      assignedVaults,
+      allowMulti: true,
+    });
+    const session = createSession(db, { userId: friend.id });
+    const csrf = generateCsrfToken();
+    const cookie = `${buildSessionCookie(session.id, 3600, { secure: false })}; ${
+      buildCsrfCookie(csrf, { secure: false }).split(";")[0]
+    }`;
+    return { db, friendId: friend.id, cookie, csrf };
+  }
+
+  function postBody(csrf: string, verb: string): string {
+    const b = new URLSearchParams();
+    b.set("__csrf", csrf);
+    b.set("verb", verb);
+    return b.toString();
+  }
+
+  test("assigned vault → 200 with a token banner, routed through hubFetch", async () => {
+    const h = makeHarness();
+    writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+    const { db, cookie, csrf } = await seed(h, ["work"]);
+    try {
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        issuer: "https://hub.test",
+      })(
+        req("/account/vault-token/work", {
+          method: "POST",
+          headers: { cookie, "content-type": "application/x-www-form-urlencoded" },
+          body: postBody(csrf, "read"),
+        }),
+      );
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      expect(html).toContain('data-testid="minted-token-banner"');
+      expect(html).toContain("vault:work:read");
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  test("unassigned vault → 403, no token, routed through hubFetch", async () => {
+    const h = makeHarness();
+    writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+    const { db, cookie, csrf } = await seed(h, ["work"]);
+    try {
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+        issuer: "https://hub.test",
+      })(
+        req("/account/vault-token/other", {
+          method: "POST",
+          headers: { cookie, "content-type": "application/x-www-form-urlencoded" },
+          body: postBody(csrf, "read"),
+        }),
+      );
+      expect(res.status).toBe(403);
+      const html = await res.text();
+      expect(html).not.toContain('data-testid="minted-token-banner"');
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+
+  test("GET on the mint path → 405 (POST-only)", async () => {
+    const h = makeHarness();
+    writeManifest({ services: [vaultEntry("work")] }, h.manifestPath);
+    const { db } = await seed(h, ["work"]);
+    try {
+      const res = await hubFetch(h.dir, {
+        getDb: () => db,
+        manifestPath: h.manifestPath,
+      })(req("/account/vault-token/work"));
+      expect(res.status).toBe(405);
+    } finally {
+      db.close();
+      h.cleanup();
+    }
+  });
+});