@openparachute/vault 0.4.8 → 0.4.9-rc.11

package/src/mcp-install-interactive.ts

@@ -190,9 +190,9 @@ export async function runInteractiveInstall(
         "Choices:",
         "  Enter       → mint a hub JWT with vault:read scope (recommended).",
         "  write       → mint with vault:write (mutations).",
-        "  admin       → mint a vault-DB pvt_* with vault:admin (schema management;",
-        "                hub policy reserves per-vault admin for operator-only paths,",
-        "                so this auto-routes to legacy-pat).",
+        "  admin       → mint a hub JWT with vault:<name>:admin (schema management).",
+        "                Requires parachute:host:admin on the operator token (the",
+        "                default operator.token carries it). NOT legacy-pat.",
         "  paste       → use an existing token instead of minting.",
         "  legacy      → mint a vault-DB pvt_* (self-hosted-without-hub).",
       ].join("\n"),
@@ -212,22 +212,13 @@ export async function runInteractiveInstall(
       // JWT's scope. (vault#292 review F2.)
       scope = await askScope(io);
     } else if (answer === "admin") {
-      // `vault:<name>:admin` is non-requestable via hub mint-token by
-      // policy — only the session-cookie-gated `/admin/vault-admin-token/:name`
-      // endpoint can mint per-vault admin scopes (see
-      // `parachute-hub/src/scope-explanations.ts:VAULT_ADMIN_RE` and
-      // `api-mint-token.ts`'s non-requestable guard). Hub returns
-      // HTTP 400 invalid_scope: "scope vault:<name>:admin is not
-      // requestable via mint-token; use OAuth flow or operator rotation".
-      //
-      // Auto-route to legacy-pat which mints a vault-DB pvt_* with full
-      // permissions — that's the right shape for an operator who wants
-      // admin scope on a local MCP entry. Print a one-line explanation
-      // so the switch isn't silent.
-      io.log("  → admin requires a vault-DB pvt_* (hub policy: per-vault admin");
-      io.log("    is operator-only, not mintable via the public mint-token API).");
-      io.log("    Switching to legacy-pat mode with vault:admin scope.");
-      mode = "legacy-pat";
+      // `vault:<name>:admin` is now mintable via hub mint-token when the
+      // operator's bearer carries `parachute:host:admin` (hub PR-A, hub#449).
+      // The default operator.token carries host-admin, so this is the
+      // canonical admin path — no more legacy-pat fallback. The verb
+      // extraction downstream narrows `vault:admin` → `vault:<name>:admin`.
+      io.log("  → admin will be minted as a scope-narrowed hub JWT (vault:" + vaultName + ":admin).");
+      mode = "mint";
       scope = "vault:admin";
     } else {
       mode = "mint";
@@ -243,7 +234,7 @@ export async function runInteractiveInstall(
     const answer = await askPersistent(io, "Which? [paste / legacy]", "paste", {
       help: [
         "  paste  → use an existing bearer (hub JWT, pvt_*, anything).",
-        "  legacy → mint a vault-DB pvt_* token (deprecated, vault#288).",
+        "  legacy → mint a vault-DB pvt_* token (deprecated, vault#282).",
       ].join("\n"),
       validate: (s) => (s === "paste" || s === "legacy" ? null : "expected: paste or legacy"),
     });
@@ -288,7 +279,7 @@ export async function runInteractiveInstall(
   if (mode === "mint") {
     io.log(`  Scope: ${scope} → narrowed to vault:${vaultName}:${scope.split(":")[1]}.`);
   } else if (mode === "legacy-pat") {
-    io.log(`  Scope: ${scope}. The pvt_* token is vault-DB-resident (vault#288 deprecation).`);
+    io.log(`  Scope: ${scope}. The pvt_* token is vault-DB-resident (vault#282 deprecation).`);
   } else {
     // mode === "token" (paste). The pasted bearer carries its own scope
     // claim — we don't inspect or override it; whatever scope the issuer

package/src/mcp-install.test.ts

@@ -27,6 +27,7 @@ import {
   readOperatorToken,
   removeMcpConfig,
   resolveInstallTarget,
+  revokeHubJwt,
 } from "./mcp-install.ts";
 
 const CLI = path.resolve(import.meta.dir, "cli.ts");
@@ -428,6 +429,107 @@ describe("mintHubJwt", () => {
     });
     expect("kind" in res && res.kind === "api-error").toBe(true);
   });
+
+  test("forwards permissions claim to hub when provided (vault#403, MGT)", async () => {
+    const calls: Array<{ body: any }> = [];
+    const mockFetch: typeof fetch = async (_url, init) => {
+      calls.push({ body: JSON.parse(String(init?.body)) });
+      return new Response(
+        JSON.stringify({
+          jti: "jti-tag",
+          token: "eyJ.signed.jwt",
+          expires_at: "2026-08-09T00:00:00.000Z",
+          scope: "vault:default:read",
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    };
+    await mintHubJwt({
+      hubOrigin: "https://hub.example",
+      operatorToken: "bearer",
+      scope: "vault:default:read",
+      permissions: { scoped_tags: ["task"] },
+      fetchImpl: mockFetch,
+    });
+    expect(calls[0]!.body.permissions).toEqual({ scoped_tags: ["task"] });
+  });
+
+  test("omits permissions from the body when not provided", async () => {
+    const calls: Array<{ body: any }> = [];
+    const mockFetch: typeof fetch = async (_url, init) => {
+      calls.push({ body: JSON.parse(String(init?.body)) });
+      return new Response(
+        JSON.stringify({
+          jti: "j",
+          token: "eyJ.x.y",
+          expires_at: "2026-08-09T00:00:00.000Z",
+          scope: "vault:default:read",
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    };
+    await mintHubJwt({
+      hubOrigin: "https://hub.example",
+      operatorToken: "bearer",
+      scope: "vault:default:read",
+      fetchImpl: mockFetch,
+    });
+    expect("permissions" in calls[0]!.body).toBe(false);
+  });
+});
+
+describe("revokeHubJwt (vault#403, MGT)", () => {
+  test("happy path posts jti + caller bearer, returns revoked_at", async () => {
+    const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
+    const mockFetch: typeof fetch = async (url, init) => {
+      calls.push({ url: String(url), init });
+      return new Response(
+        JSON.stringify({ jti: "hub_jti_1", revoked_at: "2026-05-28T00:00:00.000Z" }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    };
+    const res = await revokeHubJwt({
+      hubOrigin: "https://hub.example",
+      operatorToken: "caller-bearer",
+      jti: "hub_jti_1",
+      fetchImpl: mockFetch,
+    });
+    expect("revoked_at" in res).toBe(true);
+    expect(calls[0]!.url).toBe("https://hub.example/api/auth/revoke-token");
+    expect(new Headers(calls[0]!.init?.headers).get("authorization")).toBe("Bearer caller-bearer");
+    expect(JSON.parse(String(calls[0]!.init?.body)).jti).toBe("hub_jti_1");
+  });
+
+  test("network error returns { kind: 'network' }", async () => {
+    const mockFetch: typeof fetch = async () => { throw new Error("connection refused"); };
+    const res = await revokeHubJwt({
+      hubOrigin: "https://hub.example",
+      operatorToken: "b",
+      jti: "j",
+      fetchImpl: mockFetch,
+    });
+    expect(res).toEqual({ kind: "network", cause: "connection refused", origin: "https://hub.example" });
+  });
+
+  test("API error surfaces hub error + description", async () => {
+    const mockFetch: typeof fetch = async () =>
+      new Response(
+        JSON.stringify({ error: "insufficient_scope", error_description: "bearer lacks parachute:host:auth" }),
+        { status: 403, headers: { "Content-Type": "application/json" } },
+      );
+    const res = await revokeHubJwt({
+      hubOrigin: "https://hub.example",
+      operatorToken: "b",
+      jti: "j",
+      fetchImpl: mockFetch,
+    });
+    expect(res).toEqual({
+      kind: "api-error",
+      status: 403,
+      error: "insufficient_scope",
+      description: "bearer lacks parachute:host:auth",
+    });
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -523,44 +625,53 @@ describe("mcp-install flag parsing", () => {
     expect(res.stderr).toMatch(/No hub origin configured/);
   });
 
-  test("rejects --mint --scope vault:admin pre-flight (hub policy: per-vault admin is non-requestable)", () => {
-    // Regression for the symptom Aaron hit on hub 0.5.12-rc.2 / vault
-    // 0.4.7-rc.1: `parachute vault mcp-install` with the "admin" mint
-    // option sent `vault:default:admin` to `POST /api/auth/mint-token`,
-    // and hub responded:
-    //
-    //   Hub mint-token rejected (HTTP 400, invalid_scope):
-    //   scope vault:default:admin is not requestable via mint-token;
-    //   use OAuth flow or operator rotation
-    //
-    // The combination is invalid by hub policy (see
-    // `parachute-hub/src/scope-explanations.ts:VAULT_ADMIN_RE` and
-    // `api-mint-token.ts`'s non-requestable guard) — per-vault admin
-    // is operator-only, mintable only through the session-cookie-gated
-    // `/admin/vault-admin-token/:name` SPA path.
+  test("--mint --scope vault:admin is no longer pre-flight-rejected — it reaches the hub mint call (hub PR-A / hub#449)", () => {
+    // Before hub PR-A (hub#449), vault rejected `--mint --scope vault:admin`
+    // pre-flight because hub's mint-token endpoint refused per-vault admin
+    // by policy. PR-A made hub mint `vault:<name>:admin` when the operator
+    // bearer carries `parachute:host:admin` (the default operator.token
+    // does), so admin is now a normal mint. This test confirms the
+    // pre-flight reject is GONE: admin passes the operator-token + hub-origin
+    // checks and reaches the actual `POST /api/auth/mint-token` call.
     //
-    // The fix rejects the combination pre-flight in vault's mcp-install
-    // with a clear remediation pointing at `--legacy-pat --scope vault:admin`
-    // (which mints a vault-DB pvt_* with admin scope — the right shape
-    // for a local MCP entry needing schema management).
+    // We point at an unreachable loopback origin so the mint fails fast in
+    // the network branch — the assertion is on what's ABSENT (the old
+    // "not requestable" / legacy-pat-remediation copy), proving admin is no
+    // longer special-cased before the network hit.
     setupBareVault(tmp, "default");
     fs.writeFileSync(path.join(tmp, "operator.token"), "operator-bearer-stub");
     const res = runCli(
       ["mcp-install", "--mint", "--scope", "vault:admin"],
       tmp,
-      { PARACHUTE_HUB_ORIGIN: "https://hub.example.org" },
+      { PARACHUTE_HUB_ORIGIN: "http://127.0.0.1:1" },
     );
+    // Still exits 1 (the loopback hub is unreachable), but via the network
+    // branch — not the old admin pre-flight reject.
     expect(res.exitCode).toBe(1);
-    // Surface the policy reason so the operator knows why this combo is
-    // rejected (not a transient bug).
-    expect(res.stderr).toMatch(/not requestable via mint-token/);
-    // Point at the working remediation.
-    expect(res.stderr).toMatch(/--legacy-pat --scope vault:admin/);
-    // Pre-flight must fire BEFORE the operator-token / hub-origin checks
-    // pass the request to the network — no "Hub unreachable" / "No hub
-    // origin configured" leak.
+    // The old policy-reject copy must be gone.
+    expect(res.stderr).not.toMatch(/not requestable via mint-token/);
+    expect(res.stderr).not.toMatch(/--legacy-pat --scope vault:admin/);
+    // It got past the operator-token + hub-origin pre-flight checks.
+    expect(res.stderr).not.toMatch(/No operator token found/);
     expect(res.stderr).not.toMatch(/No hub origin configured/);
-    expect(res.stderr).not.toMatch(/Hub unreachable/);
+    // It actually attempted the mint and hit the network failure branch.
+    expect(res.stderr).toMatch(/Hub unreachable/);
+  });
+
+  test("`--help` text says vault:admin is mintable via --mint (regression guard for hub#449)", () => {
+    // The P0 on vault#397 review: the `usage()` mcp-install block still said
+    // admin "requires --legacy-pat" / "rejected pre-flight" after hub#449 made
+    // it mintable. Three comment blocks were updated but this literal slipped.
+    // This test pins the help string so the regression can't recur silently.
+    const res = runCli(["--help"], tmp);
+    expect(res.exitCode).toBe(0);
+    // Help text wraps across lines, so collapse whitespace before matching.
+    const help = res.stdout.replace(/\s+/g, " ");
+    // Admin is mintable via --mint now.
+    expect(help).toMatch(/--scope vault:admin IS mintable via --mint/);
+    // The old false claims must be gone.
+    expect(help).not.toMatch(/rejected pre-flight/);
+    expect(help).not.toMatch(/the only path for --scope vault:admin/);
   });
 });
 
@@ -835,7 +946,7 @@ describe("mcp-install end-to-end", () => {
     // see what they're opting into.
     expect(res.stderr).toMatch(/--legacy-pat mints a vault-DB pvt_/);
     expect(res.stderr).toMatch(/canonical install going forward/);
-    expect(res.stderr).toMatch(/vault#288/);
+    expect(res.stderr).toMatch(/vault#282/);
     expect(res.stderr).toMatch(/planned removal 0\.6\.0/);
     const config = readJson(path.join(tmp, ".claude.json"));
     const bearer = config.mcpServers["parachute-vault"].headers.Authorization;

package/src/mcp-install.ts

@@ -257,18 +257,34 @@ export type MintHubJwtError =
 
 export interface MintHubJwtOpts {
   hubOrigin: string;
+  /**
+   * Bearer presented on the mint-token request. For the CLI install path this
+   * is `~/.parachute/operator.token`; for the manage-token MCP proxy
+   * (vault#403, MGT) it's the RAW caller bearer the MCP session presented (a
+   * hub JWT carrying `vault:<name>:admin`). Hub's capability-attenuation guard
+   * (hub#452) decides what the bearer may mint.
+   */
   operatorToken: string;
   scope: string;
   subject?: string;
   expiresInSeconds?: number;
+  /**
+   * Optional `permissions` claim forwarded verbatim to hub's mint-token body
+   * (e.g. `{ scoped_tags: [...] }` so the minted JWT carries the tag
+   * restriction vault enforces via C0). Omitted from the request body when
+   * undefined. See `parachute-hub/src/api-mint-token.ts` (permissions claim).
+   */
+  permissions?: Record<string, unknown>;
   /** Test seam — defaults to global fetch. */
   fetchImpl?: typeof fetch;
 }
 
 /**
- * POST to `<hub>/api/auth/mint-token`. The operator-token bearer must carry
- * `parachute:host:auth` (the admin scope-set covers it). Returns the minted
- * JWT or a discriminated error the caller turns into a clear message.
+ * POST to `<hub>/api/auth/mint-token`. The bearer must carry minting authority
+ * per hub's attenuation rules — `parachute:host:auth` (CLI operator token) or
+ * `vault:<name>:admin` (the manage-token MCP proxy's caller bearer). Returns
+ * the minted JWT or a discriminated error the caller turns into a clear
+ * message.
  *
  * Network errors are caught and returned as `{ kind: "network" }` rather
  * than bubbling — the CLI doesn't want stack traces, and the operator wants
@@ -281,6 +297,7 @@ export async function mintHubJwt(opts: MintHubJwtOpts): Promise<MintedHubJwt | M
     expires_in: opts.expiresInSeconds ?? HUB_MINT_DEFAULT_TTL_SECONDS,
   };
   if (opts.subject) body.subject = opts.subject;
+  if (opts.permissions !== undefined) body.permissions = opts.permissions;
 
   const fetchFn = opts.fetchImpl ?? fetch;
   let res: Response;
@@ -334,6 +351,95 @@ export async function mintHubJwt(opts: MintHubJwtOpts): Promise<MintedHubJwt | M
   };
 }
 
+// ---------------------------------------------------------------------------
+// Hub revoke-token client (vault#403, MGT)
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated failure modes from `revokeHubJwt`. `network` mirrors
+ * `mintHubJwt`; `api-error` carries hub's `{ error, error_description }`.
+ * Note: hub's revoke-token is idempotent (re-revoking an already-revoked
+ * jti returns 200), so a successful idempotent re-revoke is NOT an error.
+ */
+export type RevokeHubJwtError =
+  | { kind: "network"; cause: string; origin: string }
+  | { kind: "api-error"; status: number; error: string; description: string };
+
+export interface RevokeHubJwtOpts {
+  hubOrigin: string;
+  /**
+   * RAW caller bearer. As of hub#454, a `vault:<N>:admin` hub JWT is
+   * sufficient to revoke any jti whose scopes it could have minted (same-vault
+   * capability attenuation, symmetric to mint) — so the manage-token proxy
+   * forwards the caller's own `vault:<N>:admin` bearer here. A
+   * `parachute:host:auth` operator bearer also works (it can revoke anything).
+   */
+  operatorToken: string;
+  /** The hub jti to revoke. */
+  jti: string;
+  /** Test seam — defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+export interface RevokedHubJwt {
+  jti: string;
+  revoked_at: string;
+}
+
+/**
+ * POST to `<hub>/api/auth/revoke-token` with `{ jti }`.
+ *
+ * As of hub#454, hub's revoke-token applies capability attenuation symmetric
+ * to mint: a `vault:<N>:admin` bearer may revoke any jti whose scopes it could
+ * have minted (same-vault subsets), and `parachute:host:auth` may revoke
+ * anything. So the manage-token proxy's caller `vault:<N>:admin` bearer is the
+ * expected-success path for revoking tokens it minted within that vault's
+ * authority — `parachute:host:auth` is no longer required.
+ *
+ * Idempotent on hub's side (re-revoking an already-revoked jti returns 200).
+ * Network failures are caught and returned, not thrown.
+ */
+export async function revokeHubJwt(opts: RevokeHubJwtOpts): Promise<RevokedHubJwt | RevokeHubJwtError> {
+  const url = `${opts.hubOrigin.replace(/\/$/, "")}/api/auth/revoke-token`;
+  const fetchFn = opts.fetchImpl ?? fetch;
+  let res: Response;
+  try {
+    res = await fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${opts.operatorToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ jti: opts.jti }),
+    });
+  } catch (err) {
+    const cause = err instanceof Error ? err.message : String(err);
+    return { kind: "network", cause, origin: opts.hubOrigin };
+  }
+
+  if (!res.ok) {
+    let error = "unknown_error";
+    let description = `HTTP ${res.status}`;
+    try {
+      const payload = (await res.json()) as { error?: unknown; error_description?: unknown };
+      if (typeof payload.error === "string") error = payload.error;
+      if (typeof payload.error_description === "string") description = payload.error_description;
+    } catch {}
+    return { kind: "api-error", status: res.status, error, description };
+  }
+
+  const payload = (await res.json()) as Partial<RevokedHubJwt>;
+  if (typeof payload.jti !== "string" || typeof payload.revoked_at !== "string") {
+    return {
+      kind: "api-error",
+      status: res.status,
+      error: "malformed_response",
+      description: "hub revoke-token response is missing required fields (jti/revoked_at)",
+    };
+  }
+  return { jti: payload.jti, revoked_at: payload.revoked_at };
+}
+
 // ---------------------------------------------------------------------------
 // `mcp-config` — emit the JSON shape `claude -p --mcp-config '<json>'` expects
 // ---------------------------------------------------------------------------