@openparachute/hub 0.5.13 → 0.5.14-rc.10

package/src/admin-login-ui.ts

@@ -67,7 +67,7 @@ function header(): string {
         <div class="brand">
           <span class="brand-mark" aria-hidden="true">${brandMarkSvg(20, "admin-login")}</span>
           <span class="brand-name">${WORDMARK_TEXT}</span>
-          <span class="brand-tag">admin</span>
+          <span class="brand-tag">sign in</span>
         </div>`;
 }
 
@@ -87,8 +87,8 @@ export function renderAdminLogin(props: AdminLoginProps): string {
     <div class="card">
       <div class="card-header">
         ${header()}
-        <h1>Sign in</h1>
-        <p class="subtitle">to administer this hub</p>
+        <h1>Sign in to your Parachute account</h1>
+        <p class="subtitle">Hub operators and invited members sign in here.</p>
       </div>
       ${error}
       <form method="POST" action="/login" class="auth-form">
@@ -105,7 +105,7 @@ export function renderAdminLogin(props: AdminLoginProps): string {
         <button type="submit" class="btn btn-primary">Sign in</button>
       </form>
     </div>`;
-  return baseDocument("Sign in to Parachute Hub admin", body);
+  return baseDocument("Sign in — Parachute", body);
 }
 
 // --- error page ------------------------------------------------------------

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

@@ -18,10 +18,16 @@
  * masking a typo as a real (but unusable) credential. Resolved via the
  * already-built well-known doc — same source of truth the SPA's vault list
  * reads.
+ *
+ * Multi-user Phase 1 gate: the session must belong to the first admin (the
+ * single hub admin under the Phase 1 model — see `users.ts:isFirstAdmin`).
+ * Friends pinned to a vault use the OAuth flow to get vault:<name>:read/write
+ * for their assigned vault; they don't get vault admin via this endpoint.
  */
 import type { Database } from "bun:sqlite";
 import { signAccessToken } from "./jwt-sign.ts";
 import { findSession, parseSessionCookie } from "./sessions.ts";
+import { isFirstAdmin } from "./users.ts";
 
 /** Short TTL — matches host-admin-token. SPA re-fetches on near-expiry. */
 export const VAULT_ADMIN_TOKEN_TTL_SECONDS = 10 * 60;
@@ -57,6 +63,17 @@ export async function handleVaultAdminToken(
   if (!session) {
     return jsonError(401, "unauthenticated", "no admin session — sign in at /login first");
   }
+  // Multi-user Phase 1 privesc gate (mirrors host-admin-token). vault:<name>:admin
+  // is the per-vault operator scope used by the vault admin SPA — friends pinned
+  // to a vault get vault:<name>:read/write via OAuth, never admin. Without this
+  // gate, any signed-in friend can mint a vault admin token for any vault.
+  if (!isFirstAdmin(deps.db, session.userId)) {
+    return jsonError(
+      403,
+      "not_admin",
+      "vault admin token mint is restricted to the hub admin — your account home is at /account/",
+    );
+  }
   const scope = `vault:${vaultName}:admin`;
   // Per-vault audience: vault validates the JWT's `aud` claim against
   // `vault.<name>` derived from its own URL-bound config (vault src/auth.ts

package/src/admin-vaults.ts

@@ -12,16 +12,24 @@
  *   Content-Type: application/json
  *   { "name": "<vault-name>" }
  *
- *   201 → { name, url, version, token?, paths? }
- *           // vault freshly created. `token` (single-emit `pvt_*`) and
- *           // filesystem `paths` are present when the create path took the
- *           // `parachute-vault create --json` branch — that's the only time
- *           // the just-emitted token is captured. The first-vault-on-host
- *           // bootstrap (`parachute install vault`) doesn't emit JSON yet,
- *           // so a fresh-box response carries name/url/version only.
+ *   201 → { name, url, version, token?, token_guidance?, paths? }
+ *           // vault freshly created. `token` is a hub-issued ACCESS token
+ *           // (a JWT scoped `vault:<name>:admin`) captured from the
+ *           // `parachute-vault create --json` branch — NOT a `pvt_*` vault
+ *           // token (those were dropped). Post-DROP `token` may be the
+ *           // empty string `""` when the bootstrap mint was unavailable
+ *           // (e.g. a loopback origin the hub can't mint against); in that
+ *           // case `token_guidance` carries the vault's human-readable
+ *           // reason, forwarded verbatim so the SPA can explain the gap.
+ *           // `paths` is the new vault's filesystem layout. The
+ *           // first-vault-on-host bootstrap (`parachute install vault`)
+ *           // doesn't emit JSON yet, so a fresh-box response carries
+ *           // name/url/version only.
  *   200 → { name, url, version }
  *           // idempotent re-POST: existing vault. Never includes `token` —
- *           // tokens are single-emit at create time, not retrievable later.
+ *           // the create-time access token isn't retrievable later. The
+ *           // caller branches on HTTP status (201 vs 200), not on `token`
+ *           // truthiness, so an empty-token 201 isn't confused with a 200.
  *   400 → { error: "invalid_request", error_description: ... }
  *   401/403 → bearer-auth failure
  *   500 → orchestration failure
@@ -50,7 +58,7 @@
 import type { Database } from "bun:sqlite";
 import { type AdminAuthError, adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
 import { SERVICES_MANIFEST_PATH } from "./config.ts";
-import { findService, readManifest, readManifestLenient } from "./services-manifest.ts";
+import { findService, type readManifest, readManifestLenient } from "./services-manifest.ts";
 import { type WellKnownVaultEntry, isVaultEntry, vaultInstanceNameFor } from "./well-known.ts";
 
 /** Scope required to call POST /vaults. */
@@ -74,7 +82,20 @@ export interface CreateVaultRequest {
 /** Output shape of `parachute-vault create --json` (vault PR #184). */
 export interface VaultCreateJson {
   name: string;
+  /**
+   * Hub-issued access token (a JWT scoped `vault:<name>:admin`) the vault
+   * minted at create time. Post the pvt_* DROP this is the empty string
+   * `""` when no hub origin was reachable to mint against (e.g. a loopback
+   * create) — the field is always present but may be empty.
+   */
   token: string;
+  /**
+   * Vault-supplied human-readable reason no token was minted, present only
+   * when `token` is empty (e.g. "no hub origin reachable to mint against").
+   * Optional — older vaults that always minted don't emit it. Forwarded
+   * verbatim to the caller so the SPA can explain the empty-token state.
+   */
+  token_guidance?: string;
   paths: {
     vault_dir: string;
     vault_db: string;
@@ -239,8 +260,9 @@ interface OrchestrateError {
  * Run the orchestration step. Picks `parachute install` (bootstrap) vs
  * `parachute-vault create --json` (subsequent) based on whether vault is
  * already registered in services.json. The create branch parses stdout for
- * the just-emitted `pvt_*` token + filesystem paths so the caller can talk
- * to the new vault — those creds are single-emit.
+ * the just-minted hub access token (a `vault:<name>:admin` JWT, possibly
+ * empty post-DROP), the optional `token_guidance`, and filesystem paths so
+ * the caller can talk to the new vault — the access token is single-emit.
  */
 async function orchestrate(
   manifestPath: string,
@@ -348,14 +370,25 @@ export async function handleCreateVault(req: Request, deps: CreateVaultDeps): Pr
   }
 
   const entry = buildEntry(name, created.path, created.version, deps.issuer);
-  // Token + filesystem paths are single-emit at create time. We surface them
-  // here so the caller can immediately bootstrap a connection to the new
-  // vault. Idempotent re-POSTs intentionally never include them.
+  // Access token (a `vault:<name>:admin` JWT, possibly empty post-DROP) +
+  // filesystem paths are single-emit at create time. We surface them here so
+  // the caller can immediately bootstrap a connection to the new vault.
+  // `token_guidance` (when the vault couldn't mint) is forwarded verbatim so
+  // the SPA can explain the empty-token state rather than rendering a blank.
+  // Idempotent re-POSTs intentionally never include any of these.
   const body: WellKnownVaultEntry & {
     token?: string;
+    token_guidance?: string;
     paths?: VaultCreateJson["paths"];
   } = result.createJson
-    ? { ...entry, token: result.createJson.token, paths: result.createJson.paths }
+    ? {
+        ...entry,
+        token: result.createJson.token,
+        ...(result.createJson.token_guidance
+          ? { token_guidance: result.createJson.token_guidance }
+          : {}),
+        paths: result.createJson.paths,
+      }
     : entry;
 
   return new Response(JSON.stringify(body), {

package/src/api-account.ts

@@ -48,6 +48,8 @@
 import type { Database } from "bun:sqlite";
 import { hash as argonHash } from "@node-rs/argon2";
 import { type ChangePasswordMode, renderChangePassword } from "./account-change-password-ui.ts";
+import { renderAccountHome } from "./account-home-ui.ts";
+import { POST_LOGIN_DEFAULT } from "./admin-handlers.ts";
 import { renderAdminError } from "./admin-login-ui.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
 import { changePasswordRateLimiter } from "./rate-limit.ts";
@@ -57,6 +59,7 @@ import {
   PASSWORD_MAX_LEN,
   UserNotFoundError,
   getUserById,
+  isFirstAdmin,
   validatePassword,
   verifyPassword,
 } from "./users.ts";
@@ -69,12 +72,10 @@ export interface ApiAccountDeps {
 
 /**
  * Where to land after a successful password change when no `next` param
- * is present. Matches `POST_LOGIN_DEFAULT` in `admin-handlers.ts` — the
- * admin SPA's vault list. Kept as a local const (not imported) so this
- * file doesn't accidentally couple to admin-handlers' internals; if the
- * default ever diverges the two should reconcile via a shared config.
+ * is present. Re-exported from `admin-handlers.ts` so login + change-
+ * password share a single source of truth (reviewer fold on hub#425).
  */
-const POST_CHANGE_DEFAULT = "/admin/vaults";
+const POST_CHANGE_DEFAULT = POST_LOGIN_DEFAULT;
 
 function safeNext(raw: string | null | undefined): string {
   if (!raw) return POST_CHANGE_DEFAULT;
@@ -234,7 +235,20 @@ export async function handleAccountChangePasswordPost(
   const currentPassword = String(form.get("current_password") ?? "");
   const newPassword = String(form.get("new_password") ?? "");
   const confirmPassword = String(form.get("new_password_confirm") ?? "");
-  const next = safeNext(String(form.get("next") ?? ""));
+  // Friend-facing redirect: non-admin users who would otherwise land in the
+  // admin SPA (because POST_CHANGE_DEFAULT = /admin/vaults) get bounced to
+  // /account/ directly. Without this, the SPA loads, hits 403 on its host-
+  // admin-token mint, then redirects to /account/ via the SPA's auth.ts —
+  // a visible two-hop flash for the friend. The login-redirect path
+  // (admin-handlers.ts:118) does the same rewrite at sign-in time; this
+  // mirrors it for the change-password POST. (hub#425 reviewer fold —
+  // operator runbook accuracy: the doc said "lands at /account/", but
+  // without this fix the user briefly sees the admin shell.)
+  const rawNext = safeNext(String(form.get("next") ?? ""));
+  const next =
+    !isFirstAdmin(deps.db, user.id) && (rawNext === "/admin" || rawNext.startsWith("/admin/"))
+      ? "/account/"
+      : rawNext;
   const mode = modeFor(user.passwordChanged);
 
   // Rate-limit gate (hub#282). Fires *after* CSRF (so a junk cross-site
@@ -437,6 +451,58 @@ export async function handleAccountChangePasswordPost(
   });
 }
 
+/**
+ * GET /account/ — friend-facing user home (multi-user Phase 1 follow-up).
+ *
+ * Companion surface to the first-admin gate on
+ * `/admin/host-admin-token`: friend users who can't reach the admin
+ * SPA need a coherent landing page that shows their assigned vault, a
+ * sign-out form, and a link to rotate their password. The admin lands
+ * here too (via the SPA's 403 redirect path) but mostly bounces back
+ * to `/admin/` immediately — for admins this is a "wait, what?" exit
+ * ramp.
+ *
+ * Auth: requires an active session. Session-less requests 302 to
+ * `/login?next=/account/` — same posture as `handleAccountChangePasswordGet`.
+ *
+ * `hubOrigin` is passed in by the route handler (resolved per-request
+ * via `resolveIssuer` in `hub-server.ts`). The page uses it to build
+ * the canonical Notes "Open" CTA URL and to show as inline code in
+ * the "use a custom client" disclosure.
+ */
+export interface AccountHomeDeps extends ApiAccountDeps {
+  /** Canonical hub origin for this request (e.g. `https://my-hub.example`). */
+  hubOrigin: string;
+}
+
+export function handleAccountHomeGet(req: Request, deps: AccountHomeDeps): Response {
+  const session = findActiveSession(deps.db, req);
+  if (!session) {
+    return redirect(`/login?next=${encodeURIComponent("/account/")}`);
+  }
+  const user = getUserById(deps.db, session.userId);
+  if (!user) {
+    // Stale session pointing at a deleted user — hand back to /login;
+    // the orphaned session row will time out on its own.
+    return redirect("/login");
+  }
+  const adminFlag = isFirstAdmin(deps.db, user.id);
+  const csrf = ensureCsrfToken(req);
+  const extra: Record<string, string> = csrf.setCookie ? { "set-cookie": csrf.setCookie } : {};
+  return htmlResponse(
+    renderAccountHome({
+      username: user.username,
+      assignedVaults: user.assignedVaults,
+      passwordChanged: user.passwordChanged,
+      hubOrigin: deps.hubOrigin,
+      isFirstAdmin: adminFlag,
+      csrfToken: csrf.token,
+    }),
+    200,
+    extra,
+  );
+}
+
 /**
  * Flip `users.password_changed` from 0 to 1 for the given user.
  * Idempotent — running against an already-`true` row is a no-op.

package/src/api-mint-token.ts

@@ -8,10 +8,31 @@
  *   - the future admin SPA when the operator wants to mint a one-shot
  *     scope-narrow token without dropping to a terminal.
  *
- * Auth: `Authorization: Bearer <token>` where `token`'s `scope` claim
- * contains `parachute:host:auth`. The operator's local operator.token
- * (admin scope-set) covers this; a narrow `--scope-set=auth` operator
- * token also covers this.
+ * Auth — capability attenuation: any bearer may mint a token whose authority
+ * is a SUBSET of its own. A requested scope `s` is grantable (`canGrant`) iff:
+ *
+ *   1. `s` is requestable AND the bearer holds `parachute:host:auth`
+ *      — host:auth mints any requestable scope (vault/scribe verbs, etc.).
+ *   2. `s` is `vault:<N>:admin` AND the bearer holds `parachute:host:admin`
+ *      — box-wide admin attenuates to one named vault's admin.
+ *   3. `s` is `vault:<N>:<verb>` (verb ∈ read/write/admin) AND the bearer
+ *      holds `vault:<N>:admin` for the SAME `<N>` — a vault-admin attenuates
+ *      to any same-vault subset, including an equal-level admin.
+ *
+ * Otherwise `s` is refused (400 `invalid_scope`). This single rule subsumes
+ * the former two-part guard: the old hard `parachute:host:auth` gate is now
+ * rule 1, and PR-A's `host:admin → vault:<name>:admin` carve-out (hub#449) is
+ * now rule 2. Rule 3 is new — it lets a `vault:<name>:admin` bearer mint
+ * same-vault sub-tokens (the canonical headless path to per-vault admin,
+ * replacing deprecated `pvt_*` — vault#282 — and the path the SPA tokens
+ * page uses via session → /admin/host-admin-token → here). Cross-vault and
+ * host-authority escalation are always blocked: a `vault:work:admin` bearer
+ * can never mint `vault:other:*` or any `parachute:host:*`.
+ *
+ * Entry gate: the bearer must hold at least one minting authority —
+ * `parachute:host:auth`, `parachute:host:admin`, or some `vault:<*>:admin`.
+ * A bearer with none (e.g. a read-only token) gets 403 `insufficient_scope`
+ * before any per-scope check; it cannot mint anything.
  *
  * Why a separate endpoint instead of extending /admin/host-admin-token:
  * that endpoint is session-cookie-gated for the SPA's needs and only
@@ -26,14 +47,38 @@
 import type { Database } from "bun:sqlite";
 import { inferAudience } from "./jwt-audience.ts";
 import { recordTokenMint, signAccessToken, validateAccessToken } from "./jwt-sign.ts";
-import { isNonRequestableScope } from "./scope-explanations.ts";
+import {
+  MINT_HOST_ADMIN_SCOPE,
+  MINT_HOST_AUTH_SCOPE,
+  canGrant,
+  hasMintingAuthority,
+} from "./scope-attenuation.ts";
+import {
+  isVaultAdminScope,
+  isWellFormedOrNonVaultScope,
+  vaultScopeName,
+} from "./scope-explanations.ts";
+
+// Re-export `canGrant` so existing importers (and the symmetric revoke path)
+// have a single name to reach for; the implementation lives in the shared
+// `scope-attenuation.ts` module alongside `hasMintingAuthority`.
+export { canGrant } from "./scope-attenuation.ts";
 
 /** Default lifetime when --expires-in / `expires_in` is omitted. Matches the CLI. */
 export const API_MINT_TOKEN_DEFAULT_TTL_SECONDS = 90 * 24 * 60 * 60;
 /** Hard cap. Matches the CLI's --expires-in upper bound. */
 export const API_MINT_TOKEN_MAX_TTL_SECONDS = 365 * 24 * 60 * 60;
-/** Scope required on the bearer token to call this endpoint. */
-export const API_MINT_TOKEN_REQUIRED_SCOPE = "parachute:host:auth";
+/**
+ * Bearer scope that authorises minting any *requestable* scope (rule 1 of the
+ * attenuation model). Re-exported alias of the shared `MINT_HOST_AUTH_SCOPE`
+ * for back-compat with existing importers.
+ */
+export const API_MINT_TOKEN_HOST_AUTH_SCOPE = MINT_HOST_AUTH_SCOPE;
+/**
+ * Bearer scope that authorises minting `vault:<name>:admin` (rule 2).
+ * Re-exported alias of the shared `MINT_HOST_ADMIN_SCOPE`.
+ */
+export const API_MINT_TOKEN_VAULT_ADMIN_BEARER_SCOPE = MINT_HOST_ADMIN_SCOPE;
 /** client_id stamped on minted tokens. Matches the CLI flow's value. */
 export const API_MINT_TOKEN_CLIENT_ID = "parachute-hub";
 
@@ -87,12 +132,17 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
     return jsonError(401, "unauthenticated", `bearer token invalid — ${msg}`);
   }
 
-  // 3. Scope gate.
-  if (!bearerScopes.includes(API_MINT_TOKEN_REQUIRED_SCOPE)) {
+  // 3. Entry gate — the bearer must hold at least one minting authority
+  //    (`parachute:host:auth`, `parachute:host:admin`, or some
+  //    `vault:<*>:admin`). A bearer with none can mint nothing under the
+  //    attenuation model, so we 403 before per-scope checks. Per-scope
+  //    grantability (which authority covers which scope) is enforced below
+  //    via `canGrant`.
+  if (!hasMintingAuthority(bearerScopes)) {
     return jsonError(
       403,
       "insufficient_scope",
-      `bearer token lacks ${API_MINT_TOKEN_REQUIRED_SCOPE}`,
+      `bearer token holds no minting authority (need ${API_MINT_TOKEN_HOST_AUTH_SCOPE}, ${API_MINT_TOKEN_VAULT_ADMIN_BEARER_SCOPE}, or vault:<name>:admin)`,
     );
   }
 
@@ -117,19 +167,40 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
     return jsonError(400, "invalid_request", "scope must contain at least one scope");
   }
 
-  // Privilege-diffusion guard: mint paths cannot themselves mint tokens
-  // carrying non-requestable scopes (parachute:host:admin, the host:*
-  // narrow scopes, vault:<name>:admin). Holder of `parachute:host:auth`
-  // can mint vault/scribe/agent verb scopes for downstream services, but
-  // cannot mint another `:auth` (or any other non-requestable) without
-  // forced re-auth via the operator.token rotation path. Same set the
-  // public OAuth flow already rejects.
-  const blocked = scopes.filter((s) => isNonRequestableScope(s));
+  // Shape guard (defensive hygiene — adversarial audit 2026-05-28): reject any
+  // scope that is shaped like a *named* per-vault scope but malformed —
+  // `vault:work:ADMIN` (uppercase verb), `vault::admin` (empty name),
+  // `vault:work:read:admin` (extra segment), `VAULT:work:admin` (uppercase
+  // resource). These slip past `isNonRequestableScope`'s strict regexes, so
+  // `canGrant` rule 1 would admit them as "requestable" and mint a junk
+  // registry row. They grant zero access today (the vault consumer's
+  // `decomposeVaultScope` rejects all four), so this is NOT exploitable now —
+  // the check is a backstop against a future consumer-normalization regression
+  // plus registry hygiene. It's an input-shape check, orthogonal to authority,
+  // so it runs for ALL callers before any `canGrant` attenuation. Non-vault
+  // scopes and the unnamed `vault:<verb>` forms are unaffected.
+  const malformed = scopes.filter((s) => !isWellFormedOrNonVaultScope(s));
+  if (malformed.length > 0) {
+    return jsonError(
+      400,
+      "invalid_scope",
+      `malformed vault scope ${malformed.join(", ")}; expected vault:<name>:<read|write|admin>`,
+    );
+  }
+
+  // Capability-attenuation guard: every requested scope must be a subset of
+  // the bearer's own authority under `canGrant` (rules in the file docstring).
+  // A `parachute:host:auth` bearer mints any requestable scope; a
+  // `parachute:host:admin` bearer additionally mints `vault:<name>:admin`; a
+  // `vault:<name>:admin` bearer mints same-vault subsets only. Anything else
+  // — host:* escalation, cross-vault, a non-requestable with no covering
+  // authority — is blocked. One blocked scope rejects the whole request.
+  const blocked = scopes.filter((s) => !canGrant(bearerScopes, s));
   if (blocked.length > 0) {
     return jsonError(
       400,
       "invalid_scope",
-      `scope ${blocked.join(", ")} is not requestable via mint-token; use OAuth flow or operator rotation`,
+      `scope ${blocked.join(", ")} is not grantable by this bearer; use OAuth flow or operator rotation`,
     );
   }
 
@@ -183,6 +254,40 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
     permissionsCanonical = JSON.stringify(permissionsClaim);
   }
 
+  // Derive the `vault_scope` pin. Collect the set of vault names `<N>` from
+  // every requested `vault:<N>:<verb>` scope that was authorized via a
+  // vault-scoped authority — rule 2 (host:admin → vault:<N>:admin) or rule 3
+  // (vault:<N>:admin → same-vault subset). These are the vault-scoped mints,
+  // so we pin the token to those vault(s): it can ONLY ever be used against
+  // them (defense-in-depth + least privilege), matching the canonical
+  // session-path mint in `admin-vault-admin-token.ts`.
+  //
+  // Pure `parachute:host:auth` requestable mints (a `vault:<N>:read/write`
+  // granted by rule 1 with no covering vault-admin authority) stay UNpinned
+  // (`[]`) — the "no per-user restriction" sentinel; the scope string +
+  // audience are the authorization-bearing gate there, as before. We
+  // distinguish by checking the bearer's own vault-scoped authority: a vault
+  // name is pinned only when the bearer held `vault:<N>:admin` (rule 3) or
+  // host:admin and the scope is admin (rule 2).
+  //
+  // Note: `audience` is single-valued and `inferAudience` is first-wins, so a
+  // multi-vault request gets `aud=vault.<first>` and only authenticates
+  // against that vault. Mint one token per vault for the multi-vault case.
+  // The canonical consumers (mcp-install, SPA tokens page) request a single
+  // vault.
+  const bearerHasHostAdmin = bearerScopes.includes(API_MINT_TOKEN_VAULT_ADMIN_BEARER_SCOPE);
+  const vaultScopePinSet = new Set<string>();
+  for (const s of scopes) {
+    const name = vaultScopeName(s);
+    if (name === null) continue;
+    const grantedByVaultAdminBearer = bearerScopes.includes(`vault:${name}:admin`); // rule 3
+    const grantedByHostAdminForAdmin = isVaultAdminScope(s) && bearerHasHostAdmin; // rule 2
+    if (grantedByVaultAdminBearer || grantedByHostAdminForAdmin) {
+      vaultScopePinSet.add(name);
+    }
+  }
+  const vaultScopePin = [...vaultScopePinSet];
+
   // 6. Mint + register.
   const minted = await signAccessToken(deps.db, {
     sub: subject,
@@ -192,11 +297,14 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
     issuer: deps.issuer,
     ttlSeconds,
     // Operator-driven CLI/API mint — the bearer already cleared the
-    // `parachute:host:auth` privilege gate, so there's no per-user vault
-    // pin to enforce. Empty `vault_scope` is the "no restriction"
-    // sentinel; the `scopes` themselves remain authorization-bearing as
-    // before.
-    vaultScope: [],
+    // attenuation guard. `vault_scope` is `[]` (no restriction) for any
+    // verb scope granted by rule 1, or the named vault(s) for vault-scoped
+    // mints authorized via rule 2 / rule 3 (see above). The pin tracks the
+    // grant rule, not the bearer: a host:admin bearer minting
+    // `vault:work:write` goes through rule 1 (write is requestable), so it
+    // ALSO gets `vault_scope:[]` — only its `vault:work:admin` mints (rule 2)
+    // are pinned.
+    vaultScope: vaultScopePin,
     ...(permissionsClaim !== undefined ? { extraClaims: { permissions: permissionsClaim } } : {}),
     ...(deps.now !== undefined ? { now: deps.now } : {}),
   });

package/src/api-modules-ops.ts

@@ -36,6 +36,7 @@ import type { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 import { CURATED_MODULES, type CuratedModuleShort } from "./api-modules.ts";
+import { isLinked as defaultIsLinked } from "./bun-link.ts";
 import { PARACHUTE_INSTALL_CHANNEL_ENV } from "./commands/install.ts";
 import { getModuleInstallChannel } from "./hub-settings.ts";
 import { validateAccessToken } from "./jwt-sign.ts";
@@ -187,6 +188,21 @@ export interface ApiModulesOpsDeps {
    * null when not found.
    */
   findGlobalInstall?: (pkg: string) => string | null;
+  /**
+   * Override `isLinked` (test seam). Production probes bun's globals
+   * for a symlink-shaped entry under `<prefix>/node_modules/<pkg>` —
+   * true iff the package was installed via `bun link` from a local
+   * checkout. When true, `runInstall` skips `bun add -g <pkg>`
+   * entirely; the linked checkout already provides the binary on
+   * PATH and `bun add -g` would either be a wasted npm round-trip
+   * or fail outright on unrelated global-lockfile noise (smoke
+   * 2026-05-27 finding 1).
+   *
+   * Mirrors the CLI install path's `isLinked` short-circuit in
+   * `commands/install.ts`. Both paths use the same `src/bun-link.ts`
+   * helper so they can't drift again.
+   */
+  isLinked?: (pkg: string) => boolean;
   /**
    * Extra env vars merged onto the supervised child at spawn time (hub#267).
    *
@@ -543,23 +559,43 @@ export async function runInstall(
   // without a hub restart.
   const channel = resolveApiInstallChannel(channelOverride, deps);
   const spec_str = `${spec.package}@${channel}`;
-  registry.update(opId, { status: "running" }, `running bun add -g ${spec_str}`);
-  const code = await run(["bun", "add", "-g", spec_str]);
-  if (code !== 0) {
-    // Bun 1.2.x lockfile-recovery noise: probe the global prefix
-    // before treating non-zero as fatal. Mirrors the same defense in
-    // commands/install.ts.
-    const findGlobalInstall = deps.findGlobalInstall;
-    const probed = findGlobalInstall?.(spec.package) ?? null;
-    if (!probed) {
-      registry.update(
-        opId,
-        { status: "failed", error: `bun add -g exited ${code}` },
-        `bun add -g ${spec_str} failed (exit ${code})`,
-      );
-      return;
+  // bun-link short-circuit (smoke 2026-05-27, finding 1): mirror the
+  // CLI install path's `isLinked` check. When the package is already
+  // linked globally via `bun link <abspath>` (the standard local-dev
+  // shape — Aaron + every workspace contributor runs this way), the
+  // linked checkout already provides the binary on PATH. `bun add -g`
+  // is at best a wasted ~3s npm round-trip and at worst a hard failure
+  // on unrelated global-lockfile noise (one stale entry can crash the
+  // whole `bun add`, failing the wizard's vault step even though the
+  // linked vault is fine). The wizard's parallel install path diverged
+  // pre-this-fix; the shared `src/bun-link.ts` keeps both paths in
+  // lockstep going forward.
+  const isLinked = deps.isLinked ?? defaultIsLinked;
+  if (isLinked(spec.package)) {
+    registry.update(
+      opId,
+      { status: "running" },
+      `${spec.package} is already linked globally (bun link) — skipping bun add -g`,
+    );
+  } else {
+    registry.update(opId, { status: "running" }, `running bun add -g ${spec_str}`);
+    const code = await run(["bun", "add", "-g", spec_str]);
+    if (code !== 0) {
+      // Bun 1.2.x lockfile-recovery noise: probe the global prefix
+      // before treating non-zero as fatal. Mirrors the same defense in
+      // commands/install.ts.
+      const findGlobalInstall = deps.findGlobalInstall;
+      const probed = findGlobalInstall?.(spec.package) ?? null;
+      if (!probed) {
+        registry.update(
+          opId,
+          { status: "failed", error: `bun add -g exited ${code}` },
+          `bun add -g ${spec_str} failed (exit ${code})`,
+        );
+        return;
+      }
+      registry.update(opId, {}, `bun add reported exit ${code} but package landed at ${probed}`);
     }
-    registry.update(opId, {}, `bun add reported exit ${code} but package landed at ${probed}`);
   }
 
   // Seed services.json if absent (the install flow does this for the