@openparachute/vault 0.4.9-rc.9 → 0.5.0-rc.2

package/src/mcp-install-interactive.ts

@@ -47,7 +47,7 @@ export interface InteractiveIO {
  * shared backend `installMcpConfig`.
  */
 export interface InstallDecision {
-  mode: "mint" | "token" | "legacy-pat";
+  mode: "mint" | "token";
   scope: "vault:read" | "vault:write" | "vault:admin";
   installScope: InstallScope;
   vaultName: string;
@@ -175,9 +175,10 @@ export async function runInteractiveInstall(
     io.log("");
   }
 
-  // 4. Auth mode + scope. The branching point: hub-mint available, or
-  //    not. When neither operator.token nor hub is configured, we fall
-  //    through to paste/legacy.
+  // 4. Auth mode + scope. The branching point: hub-mint available, or not.
+  //    vault#282 Stage 2 dropped the legacy vault-DB pvt_* mint — vault is a
+  //    pure hub resource-server. When no hub-mint path exists, the only option
+  //    is pasting an existing bearer (hub JWT or VAULT_AUTH_TOKEN).
   const canMint = ctx.hubReachable && ctx.operatorTokenPresent;
   let mode: InstallDecision["mode"];
   let scope: InstallDecision["scope"] = "vault:read";
@@ -190,71 +191,43 @@ 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).",
         "  paste       → use an existing token instead of minting.",
-        "  legacy      → mint a vault-DB pvt_* (self-hosted-without-hub).",
       ].join("\n"),
       validate: (s) => {
-        const ok = ["mint", "write", "admin", "paste", "legacy"];
+        const ok = ["mint", "write", "admin", "paste"];
         return ok.includes(s) ? null : `expected one of: ${ok.join(", ")}`;
       },
     });
     if (answer === "paste") {
       mode = "token";
       pastedToken = await askToken(io);
-    } else if (answer === "legacy") {
-      mode = "legacy-pat";
-      // Legacy path mints a vault-DB pvt_* with scope narrowing — same
-      // verb choice as the mint path. Prompt for it explicitly so the
-      // operator gets the same control they get when widening a hub
-      // 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 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. 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";
       if (answer === "write") scope = "vault:write";
     }
   } else {
-    // No hub-mint path available — explain why and offer the alternatives.
+    // No hub-mint path available — explain why and fall back to paste. There
+    // is no local pvt_* mint anymore (vault#282 Stage 2): without a hub, the
+    // operator pastes an existing bearer or sets VAULT_AUTH_TOKEN.
     const reason = !ctx.hubReachable
       ? "no hub origin configured (PARACHUTE_HUB_ORIGIN unset, no active expose-state)"
       : "no operator token at ~/.parachute/operator.token";
     io.log(`Hub-mint isn't available — ${reason}.`);
-    io.log("Two options: paste an existing token, or mint a vault-DB pvt_* (deprecated).");
-    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).",
-      ].join("\n"),
-      validate: (s) => (s === "paste" || s === "legacy" ? null : "expected: paste or legacy"),
-    });
-    if (answer === "paste") {
-      mode = "token";
-      pastedToken = await askToken(io);
-    } else {
-      mode = "legacy-pat";
-      // Same scope prompt as the canMint legacy branch (F2).
-      scope = await askScope(io);
-    }
+    io.log("Paste an existing bearer (a hub JWT, or your VAULT_AUTH_TOKEN operator bearer).");
+    mode = "token";
+    pastedToken = await askToken(io);
   }
   io.log("");
 
@@ -274,8 +247,7 @@ export async function runInteractiveInstall(
     env: ctx.env,
     ...(updateLocation?.entryKey ? { existingEntryKey: updateLocation.entryKey } : {}),
   });
-  const bearerPreview =
-    mode === "token" ? "<your token>" : mode === "mint" ? "<hub-jwt>" : "<pvt_*>";
+  const bearerPreview = mode === "token" ? "<your token>" : "<hub-jwt>";
 
   io.log(`Here's what I'll write to ${targetLabel}:`);
   io.log("");
@@ -287,8 +259,6 @@ export async function runInteractiveInstall(
   io.log("");
   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).`);
   } else {
     // mode === "token" (paste). The pasted bearer carries its own scope
     // claim — we don't inspect or override it; whatever scope the issuer
@@ -348,29 +318,6 @@ function pathTail(p: string): string {
   return parts.slice(-2).join("/") || p;
 }
 
-/**
- * Prompt for scope when minting a vault-DB pvt_* (legacy-pat). Mirrors
- * the mint path's "widen with write/admin" wording so the legacy and
- * hub-mint branches surface scope as the same kind of choice. Mint's
- * own scope prompt is inline at the auth-mode step (legacy is the
- * extra round we couldn't fold there without ambiguity).
- */
-async function askScope(io: InteractiveIO): Promise<InstallDecision["scope"]> {
-  const answer = await askPersistent(io, "Press Enter for vault:read (least privilege), or type 'write' or 'admin' to widen", "read", {
-    help: [
-      "Scopes for the legacy pvt_* token:",
-      "  read   → vault:read (default — listing + reading only).",
-      "  write  → vault:write (mutations: create, update, delete notes).",
-      "  admin  → vault:admin (full, including schema management).",
-    ].join("\n"),
-    validate: (s) => {
-      const ok = ["read", "write", "admin"];
-      return ok.includes(s) ? null : `expected one of: ${ok.join(", ")}`;
-    },
-  });
-  return `vault:${answer}` as InstallDecision["scope"];
-}
-
 /**
  * Prompt for a token. Uses `ask` rather than `askPassword` so the operator
  * can see what they pasted (most clients show the token in plain text in

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",
+    });
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -449,12 +551,6 @@ describe("mcp-install flag parsing", () => {
     expect(res.stderr).toMatch(/mutually exclusive/);
   });
 
-  test("rejects mutually exclusive --token and --legacy-pat", () => {
-    const res = runCli(["mcp-install", "--token", "abc", "--legacy-pat"], tmp);
-    expect(res.exitCode).toBe(1);
-    expect(res.stderr).toMatch(/mutually exclusive/);
-  });
-
   test("rejects --token without a value", () => {
     const res = runCli(["mcp-install", "--token"], tmp);
     expect(res.exitCode).toBe(1);
@@ -523,44 +619,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/);
   });
 });
 
@@ -825,21 +930,17 @@ describe("mcp-install end-to-end", () => {
     expect(config.mcpServers["parachute-vault-default"]).toBeUndefined();
   });
 
-  test("--legacy-pat mints a vault-DB pvt_* token and prints deprecation warning", () => {
+  test("--legacy-pat is gone (vault#282 Stage 2) — no pvt_* mint path remains", () => {
+    // The flag was removed: vault is a pure hub resource-server, so there's no
+    // local pvt_* mint. With no operator.token in this sandbox, the default
+    // --mint path can't reach a hub and exits non-zero with actionable
+    // guidance — and crucially no `pvt_*` bearer is ever written.
     setupBareVault(tmp, "default");
     const res = runCli(["mcp-install", "--install-scope", "user", "--legacy-pat"], tmp);
-    expect(res.exitCode).toBe(0);
-    // Deprecation warning lands on stderr (we used `console.error` for the
-    // notice so it's visible without polluting stdout). The message names
-    // the tracking issue + planned-removal milestone so operators can
-    // 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(/planned removal 0\.6\.0/);
-    const config = readJson(path.join(tmp, ".claude.json"));
-    const bearer = config.mcpServers["parachute-vault"].headers.Authorization;
-    expect(bearer).toMatch(/^Bearer pvt_/);
+    expect(res.exitCode).not.toBe(0);
+    expect(res.stderr).toMatch(/operator token|hub origin/i);
+    expect(res.stdout).not.toMatch(/pvt_/);
+    expect(res.stderr).not.toMatch(/pvt_/);
   });
 
   test("--dry-run describes the write without touching disk or hitting the hub", () => {
@@ -1025,16 +1126,16 @@ describe("mcp-install interactive dispatch", () => {
   });
 
   test("any install-shaping flag bypasses the walkthrough", () => {
-    // --legacy-pat triggers the flag-driven path even on a TTY. The
-    // walkthrough mustn't fire when a flag is present, so its
-    // "Setting up…" banner must not appear in output.
+    // A recognized flag (`--token`) triggers the flag-driven path. The
+    // walkthrough mustn't fire when a flag is present, so its "Setting up…"
+    // banner must not appear in output. (vault#282 Stage 2 removed --legacy-pat
+    // — --token is the deterministic no-hub-needed flag-driven path now.)
     setupBareVault(tmp, "default");
-    const res = runCli(["mcp-install", "--legacy-pat"], tmp);
+    const res = runCli(["mcp-install", "--install-scope", "user", "--token", "hub.jwt.value"], tmp);
     expect(res.exitCode).toBe(0);
     expect(res.stdout).not.toMatch(/Setting up Parachute Vault/);
-    // The deprecation banner *should* show — confirms flag-driven path
-    // ran end-to-end.
-    expect(res.stderr).toMatch(/--legacy-pat mints a vault-DB pvt_/);
+    // The supplied-token path ran end-to-end (skips minting).
+    expect(res.stdout).toMatch(/Using supplied token/);
   });
 });
 

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
 // ---------------------------------------------------------------------------