@openparachute/vault 0.4.9-rc.2 → 0.4.9-rc.4

package/core/src/mcp.ts

@@ -20,6 +20,18 @@ export interface McpToolDef {
   description: string;
   inputSchema: Record<string, unknown>;
   execute: (params: Record<string, unknown>) => unknown | Promise<unknown>;
+  /**
+   * Minimum scope verb the caller must hold for THIS vault to see + invoke
+   * the tool. `read` for pure queries, `write` for mutations, `admin` for
+   * token-management surfaces (only `manage-token` in the current set —
+   * core's nine tools cap at `write`). The MCP HTTP layer filters
+   * `tools/list` by this field and verb-gates `tools/call` against it; the
+   * filter is the primary defense, the inner gate is defense-in-depth.
+   *
+   * Pre-v19 unstamped tools default to `write` at the dispatch layer so a
+   * future addition that forgets to stamp this gets the safer treatment.
+   */
+  requiredVerb: "read" | "write" | "admin";
 }
 
 // ---------------------------------------------------------------------------
@@ -102,6 +114,7 @@ export function generateMcpTools(store: Store): McpToolDef[] {
     // =====================================================================
     {
       name: "query-notes",
+      requiredVerb: "read",
       description: `Query notes. Returns notes matching the given filters.
 
 - **Single note**: pass \`id\` (accepts note ID or path, e.g., "Projects/README")
@@ -403,6 +416,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "create-note",
+      requiredVerb: "write",
       description: `Create one or more notes. Pass a single note's fields directly, or pass a \`notes\` array for batch creation. Each note accepts content, path, metadata, tags, links, and created_at.`,
       inputSchema: {
         type: "object",
@@ -518,6 +532,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "update-note",
+      requiredVerb: "write",
       description: `Update one or more notes. Accepts ID or path. Supports content, path, metadata updates plus tag and link mutations.
 
 - Three content-modification modes (mutually exclusive):
@@ -930,6 +945,14 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "delete-note",
+      // `write` — same destructive verb as update-note. Aaron's call
+      // 2026-05-27: "delete- in write; right now the only admin gated
+      // thing is tokens." Reserving `admin` for "operator-only
+      // capabilities" (token mgmt + future config writes). A future
+      // finer-grained model might split `vault:write:no-delete` for
+      // genuinely append-only callers — gating WITHIN write rather
+      // than promoting deletes out of it.
+      requiredVerb: "write",
       description: "Permanently delete a note and all its tags and links. Accepts ID or path.",
       inputSchema: {
         type: "object",
@@ -950,6 +973,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "list-tags",
+      requiredVerb: "read",
       description: `List tags with usage counts. Pass \`tag\` to get a single tag's full record (description, fields, relationships, parent_names, timestamps). Pass \`include_schema: true\` to include the full record for every tag.`,
       inputSchema: {
         type: "object",
@@ -1004,6 +1028,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "update-tag",
+      requiredVerb: "write",
       description: "Create or update a tag's identity row: description, indexed-field schemas, typed-link relationships, and hierarchy parents. If the tag doesn't exist, it's created. Fields are merged (new keys added, existing keys replaced); relationships and parent_names are replaced wholesale when provided. Pass null for fields/relationships/parent_names to clear that column. See parachute-patterns/patterns/tag-data-model.md.",
       inputSchema: {
         type: "object",
@@ -1159,6 +1184,10 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "delete-tag",
+      // `write` — Aaron's call 2026-05-27: admin reserved for token
+      // mgmt + future config writes; deletes are write-tier mutations.
+      // See delete-note rationale.
+      requiredVerb: "write",
       description: "Delete a tag, remove it from all notes, and delete its schema. Notes themselves are NOT deleted — just untagged.",
       inputSchema: {
         type: "object",
@@ -1191,6 +1220,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "find-path",
+      requiredVerb: "read",
       description: "Find the shortest path between two notes in the link graph. Accepts IDs or paths. Returns the chain of note IDs and relationships, or null if no path exists.",
       inputSchema: {
         type: "object",
@@ -1215,6 +1245,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "vault-info",
+      // `read` so vault:read callers can fetch stats. The
+      // description-update branch performs an inner write-check (see
+      // overrideVaultInfo in src/mcp-tools.ts) — do not promote this to
+      // `write` or read-only callers lose the stats projection.
+      requiredVerb: "read",
       description: "Get a comprehensive vault projection: name, description, tags-with-schemas (own + effective parents/fields per #270 inheritance), indexed metadata fields catalog, and query hints. Pass `include_stats: true` to add note/tag/link counts and the monthly distribution. Pass `description` to update the vault description (changes how AI agents behave in future sessions). Call this anytime mid-session to refresh schema context.",
       inputSchema: {
         type: "object",

package/core/src/schema.ts

@@ -2,7 +2,7 @@ import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
 import { rebuildIndexes } from "./indexed-fields.js";
 
-export const SCHEMA_VERSION = 18;
+export const SCHEMA_VERSION = 19;
 
 export const SCHEMA_SQL = `
 -- Notes: the universal record.
@@ -118,6 +118,20 @@ CREATE TABLE IF NOT EXISTS indexed_fields (
 --
 -- scope_tag / scope_path_prefix are deprecated Phase-0 columns — never
 -- enforced at runtime, kept only for schema stability.
+-- created_via (v19) records the provenance of a token. NULL means the
+-- legacy/unspecified path (CLI, REST mint, YAML import); 'mcp_mint' means
+-- the token was minted by the manage-token MCP tool, which lets the
+-- list/revoke surface of that tool restrict itself to its own session's
+-- mints (no cross-session token management from inside MCP).
+--
+-- parent_jti (v19) is the display id (t_hashprefix) of the token that
+-- minted this one, or the hub-JWT jti claim when minted from a hub
+-- session. Session-pinned list+revoke in manage-token filters on this.
+--
+-- revoked_at (v19) marks soft-revocation. Revoke from manage-token sets
+-- this rather than deleting the row, so the audit trail stays intact and
+-- the second revoke of the same jti is idempotent (returns ok=true).
+-- resolveToken treats a revoked_at-set row as not-found.
 CREATE TABLE IF NOT EXISTS tokens (
   token_hash TEXT PRIMARY KEY,
   label TEXT NOT NULL,
@@ -129,7 +143,10 @@ CREATE TABLE IF NOT EXISTS tokens (
   expires_at TEXT,
   created_at TEXT NOT NULL,
   last_used_at TEXT,
-  vault_name TEXT
+  vault_name TEXT,
+  created_via TEXT,
+  parent_jti TEXT,
+  revoked_at TEXT
 );
 
 -- OAuth: registered clients (Dynamic Client Registration)
@@ -380,6 +397,12 @@ export function initSchema(db: Database): void {
   // (markdown), unchanged in meaning. See vault#328.
   migrateToV18(db);
 
+  // Migrate v18 → v19: add MCP-mint provenance columns to `tokens`
+  // (created_via, parent_jti, revoked_at) for vault#376's manage-token tool.
+  // All three are nullable; existing rows backfill to NULL which means
+  // "non-MCP-minted, not revoked" — identical pre-v19 semantics.
+  migrateToV19(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -952,6 +975,32 @@ function migrateToV18(db: Database): void {
   }
 }
 
+/**
+ * Migrate v18 → v19: add `created_via`, `parent_jti`, `revoked_at` columns
+ * to `tokens` so manage-token can attribute mints to the MCP session that
+ * minted them, scope its list+revoke to those tokens, and soft-revoke
+ * (preserving the audit trail).
+ *
+ * All three columns are nullable; existing rows backfill to NULL with
+ * back-compat semantics — `created_via IS NULL` matches the CLI/REST-mint
+ * provenance, `revoked_at IS NULL` matches "still active". Idempotent —
+ * the column-existence guard means the migration is safe to re-run on a
+ * post-v19 vault. See vault#376.
+ */
+function migrateToV19(db: Database): void {
+  if (!hasTable(db, "tokens")) return;
+  const cols: [string, string][] = [
+    ["created_via", "TEXT"],
+    ["parent_jti", "TEXT"],
+    ["revoked_at", "TEXT"],
+  ];
+  for (const [col, type] of cols) {
+    if (!hasColumn(db, "tokens", col)) {
+      db.exec(`ALTER TABLE tokens ADD COLUMN ${col} ${type}`);
+    }
+  }
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.4.9-rc.2",
+  "version": "0.4.9-rc.4",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/auth.ts

@@ -91,6 +91,12 @@ function tryServerWideAuth(
     legacyDerived: false,
     scoped_tags: null,
     vault_name: null,
+    // No stable session id for the env-var operator token — every request
+    // is the operator-bearer, not a minted session. manage-token's session
+    // pin is a no-op for this caller (it'd still mint, but list/revoke
+    // would see no other operator mints; that's fine — env-var-bearer is
+    // explicitly the operator-channel, not a user surface).
+    caller_jti: null,
   };
 }
 
@@ -120,6 +126,15 @@ export interface AuthResult {
    * legacy / server-wide / hub JWT — no per-vault binding. See vault#257.
    */
   vault_name: string | null;
+  /**
+   * Session identifier (v19). For `pvt_*` tokens this is the display id
+   * (`t_<hashprefix>`) of the presented token. For hub JWTs it's the
+   * `jti` claim, when present. NULL for legacy YAML keys / server-wide
+   * env-var tokens / hub JWTs without a `jti`. Used by the manage-token
+   * MCP tool to stamp child tokens with `parent_jti` so list/revoke can
+   * scope to this session's mints. See vault#376.
+   */
+  caller_jti: string | null;
 }
 
 /**
@@ -134,6 +149,7 @@ function legacyAuthResult(permission: TokenPermission): AuthResult {
     legacyDerived: true,
     scoped_tags: null,
     vault_name: null,
+    caller_jti: null,
   };
 }
 
@@ -285,6 +301,7 @@ export async function authenticateVaultRequest(
           legacyDerived: resolved.legacyDerived,
           scoped_tags: resolved.scoped_tags,
           vault_name: resolved.vault_name,
+          caller_jti: resolved.jti,
         };
       }
     } catch {
@@ -396,7 +413,17 @@ async function authenticateHubJwt(
       hasScope(claims.scopes, SCOPE_WRITE) || hasScope(claims.scopes, SCOPE_ADMIN)
         ? "full"
         : "read";
-    return { permission, scopes: claims.scopes, legacyDerived: false, scoped_tags: null, vault_name: null };
+    return {
+      permission,
+      scopes: claims.scopes,
+      legacyDerived: false,
+      scoped_tags: null,
+      vault_name: null,
+      // claims.jti is `undefined` when the issuer didn't stamp one. Pass it
+      // through verbatim — manage-token's session-pin will be null in that
+      // case, and list/revoke from that session sees no mints.
+      caller_jti: claims.jti ?? null,
+    };
   } catch (err) {
     if (err instanceof HubJwtError) {
       // Revocation-related codes get sanitized client messages: server-side
@@ -511,6 +538,7 @@ export async function authenticateGlobalRequest(
           legacyDerived: resolved.legacyDerived,
           scoped_tags: resolved.scoped_tags,
           vault_name: resolved.vault_name,
+          caller_jti: resolved.jti,
         };
       }
     } catch {

package/src/mcp-http.ts

@@ -30,29 +30,19 @@ import { hasScopeForVault } from "./scopes.ts";
 import type { VaultVerb } from "./scopes.ts";
 
 /**
- * Required verb for each MCP tool. Tools that mutate note/tag state require
- * write; pure query tools need read. `vault-info` is listed as read because
- * read-only callers can fetch stats — the description-update branch inside
- * vault-info performs its own secondary write check (see `overrideVaultInfo`
- * in mcp-tools.ts). Do not assume the outer gate alone protects the inner
- * branch.
+ * Required verb for an MCP tool. Reads `tool.requiredVerb` from the tool
+ * metadata — every core tool stamps this (vault#376) so the filter is data,
+ * not a side-table that can drift. The discovery + dispatch paths below
+ * call this with the tool object so a future tool that forgets to stamp
+ * falls into the default-deny branch.
+ *
+ * Default-deny: unknown tools require `write`. Keeps accidental reads of
+ * a not-yet-mapped mutation tool from slipping past. (`admin` would be
+ * safer-still but would refuse vault-info-style read tools to write-scope
+ * callers; `write` is the right middle ground.)
  */
-const TOOL_REQUIRED_VERB: Record<string, VaultVerb> = {
-  "query-notes": "read",
-  "list-tags": "read",
-  "find-path": "read",
-  "vault-info": "read",
-  "create-note": "write",
-  "update-note": "write",
-  "delete-note": "write",
-  "update-tag": "write",
-  "delete-tag": "write",
-};
-
-function requiredVerbForTool(toolName: string): VaultVerb {
-  // Default-deny: unknown tools require write. Keeps accidental reads of
-  // a not-yet-mapped mutation tool from slipping past.
-  return TOOL_REQUIRED_VERB[toolName] ?? "write";
+function requiredVerbForTool(tool: { requiredVerb?: VaultVerb }): VaultVerb {
+  return tool.requiredVerb ?? "write";
 }
 
 /** Handle scoped MCP at /vault/{name}/mcp (single vault). */
@@ -90,9 +80,12 @@ async function handleMcp(
   // Filter the advertised tool list to what the caller's scopes actually
   // permit for THIS vault. Callers without write don't see mutation tools at
   // all — matches the prior behavior of the read/full permission model but
-  // now driven by per-vault scope inheritance.
+  // now driven by per-vault scope inheritance. With manage-token (vault#376)
+  // requiring `admin`, callers without admin don't see it at all — the AI
+  // never knows it could mint child tokens, eliminating that escalation
+  // vector by listing.
   const visibleTools = mcpTools.filter((t) =>
-    hasScopeForVault(auth.scopes, vaultName, requiredVerbForTool(t.name)),
+    hasScopeForVault(auth.scopes, vaultName, requiredVerbForTool(t)),
   );
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -106,18 +99,13 @@ async function handleMcp(
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
 
-    const neededVerb = requiredVerbForTool(name);
-    if (!hasScopeForVault(auth.scopes, vaultName, neededVerb)) {
-      return {
-        content: [{
-          type: "text" as const,
-          text: `Forbidden: tool '${name}' requires the 'vault:${neededVerb}' scope (or 'vault:${vaultName}:${neededVerb}'). Granted scopes: ${auth.scopes.join(" ") || "(none)"}.`,
-        }],
-        isError: true,
-      };
-    }
-
-    const tool = mcpTools.find((t) => t.name === name);
+    // Dispatch against the FILTERED tool list — tools the caller can't see
+    // in `tools/list` also can't be called explicitly. This matches the
+    // user-visible contract: "excluded tools throw 'tool not found' if
+    // called explicitly" (vault#376 spec). It also avoids leaking the
+    // existence of admin-only tools (manage-token) to write-scope sessions
+    // via differential error messages.
+    const tool = visibleTools.find((t) => t.name === name);
     if (!tool) {
       return {
         content: [{ type: "text" as const, text: `Unknown tool: ${name}` }],

package/src/mcp-tools.ts

@@ -14,14 +14,21 @@ import {
 } from "../core/src/vault-projection.ts";
 import { readVaultConfig, writeVaultConfig } from "./config.ts";
 import { getVaultStore } from "./vault-store.ts";
-import { hasScopeForVault } from "./scopes.ts";
+import { hasScopeForVault, parseScopes, validateMintedScopes, hasScope, SCOPE_WRITE, SCOPE_ADMIN } from "./scopes.ts";
 import type { AuthResult } from "./auth.ts";
 import {
   expandTokenTagScope,
   noteWithinTagScope,
   tagsWithinScope,
 } from "./tag-scope.ts";
-import { findTokensReferencingTag } from "./token-store.ts";
+import {
+  findTokensReferencingTag,
+  generateToken,
+  createToken,
+  listMcpMintedTokens,
+  softRevokeMcpToken,
+  type TokenPermission,
+} from "./token-store.ts";
 
 /**
  * Filter a vault projection to entries an in-scope tag contributes to.
@@ -110,6 +117,12 @@ export function generateScopedMcpTools(vaultName: string, auth?: AuthResult): Mc
   applyTagDependencyGuards(tools, vaultName);
   applyTagScopeWrappers(tools, vaultName, auth);
 
+  // manage-token is server-only (needs token-store + auth context), so it
+  // lives here rather than in core. Always appended to the surface; the
+  // `requiredVerb: "admin"` filter in mcp-http.ts hides it from non-admin
+  // callers. See vault#376.
+  tools.push(buildManageTokenTool(vaultName, auth));
+
   return tools;
 }
 
@@ -404,3 +417,274 @@ function overrideVaultInfo(
     return result;
   };
 }
+
+// ---------------------------------------------------------------------------
+// manage-token (vault#376) — single MCP tool with mint/revoke/list actions
+// ---------------------------------------------------------------------------
+
+/**
+ * TTL bounds for `manage-token` action=mint, in seconds. Short by design:
+ * the design doc (vault#376) calls the tool out as the "AI mints a token
+ * for one-shot scripted work, then revokes immediately" surface. A long
+ * TTL would defeat the safety story — if revoke fails (network blip,
+ * model error), the cap is the backstop. Operators wanting long-lived
+ * tokens still use the REST /vault/<name>/tokens endpoint.
+ */
+const MANAGE_TOKEN_DEFAULT_TTL_SECONDS = 900; // 15 minutes
+const MANAGE_TOKEN_MAX_TTL_SECONDS = 3600; // 1 hour
+
+function permissionForScopes(scopes: string[]): TokenPermission {
+  return hasScope(scopes, SCOPE_WRITE) || hasScope(scopes, SCOPE_ADMIN) ? "full" : "read";
+}
+
+/**
+ * Build the manage-token MCP tool, wired to the calling session's auth.
+ *
+ * Closure-captured context:
+ *   - `vaultName`: every mint pins `vault_name` to this; cross-vault mints
+ *     are rejected by `validateMintedScopes` (it refuses any
+ *     `vault:<other>:<verb>` scope).
+ *   - `auth.scopes`: defense-in-depth subset check on mint. The outer
+ *     filter already required vault:admin to see the tool, but a hand-
+ *     crafted JSON-RPC `tools/call` of `manage-token` from a non-admin
+ *     session would bypass the visibility filter — `validateMintedScopes`
+ *     plus the `hasScopeForVault(auth.scopes, vaultName, "admin")` guard
+ *     below catch that case.
+ *   - `auth.caller_jti`: stamped as `parent_jti` on each mint; list+revoke
+ *     scope to this jti so each MCP session sees only its own mints.
+ *     When NULL (legacy / env-var operator / hub JWT without jti), mints
+ *     still succeed but list/revoke return empty — the operator hits the
+ *     CLI / REST surface instead for revocation in that path.
+ *
+ * The execute function is async (token mint touches the store + DB) and
+ * returns a discriminated-union response shape: `{action, …}` with `action`
+ * matching the requested action. The MCP HTTP layer serializes the result
+ * via `JSON.stringify`, so caller-side parsing keys off the action field.
+ */
+function buildManageTokenTool(vaultName: string, auth: AuthResult | undefined): McpToolDef {
+  return {
+    name: "manage-token",
+    requiredVerb: "admin",
+    description:
+      "Mint, revoke, or list short-TTL vault tokens within this MCP session. " +
+      "Designed for one-shot AI-driven workflows: mint a narrow token, run a " +
+      "script with it, revoke immediately. Token lifetime defaults to 15 min " +
+      "(max 1 hour). Mints are pinned to this vault and to the caller's scope " +
+      "subset — you cannot escalate. List + revoke are scoped to tokens this " +
+      "session minted; CLI/REST-minted tokens are not surfaced here.\n\n" +
+      "Actions (discriminator: `action`):\n" +
+      "- `mint` — { scope: string|string[], ttl_seconds?: number, description?: string } → { action: \"mint\", token, jti, expires_at }\n" +
+      "- `revoke` — { jti: string } → { action: \"revoke\", ok: boolean }\n" +
+      "- `list` — (no inputs) → { action: \"list\", tokens: [...] }",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["mint", "revoke", "list"],
+          description: "Which action to perform. Required.",
+        },
+        scope: {
+          oneOf: [
+            { type: "string" },
+            { type: "array", items: { type: "string" } },
+          ],
+          description:
+            "(action=mint) Scope to grant. String like \"vault:write\" or array. Must be a subset of the caller's scope; cross-vault scopes are rejected.",
+        },
+        ttl_seconds: {
+          type: "number",
+          description: `(action=mint) Token lifetime in seconds. Default ${MANAGE_TOKEN_DEFAULT_TTL_SECONDS} (15 min), max ${MANAGE_TOKEN_MAX_TTL_SECONDS} (1 hour). Values outside (0, ${MANAGE_TOKEN_MAX_TTL_SECONDS}] are rejected.`,
+        },
+        description: {
+          type: "string",
+          description: "(action=mint, optional) Free-text label surfaced in the token list + audit trail.",
+        },
+        jti: {
+          type: "string",
+          description: "(action=revoke) The jti (e.g. `t_abc123…`) returned by a prior mint. Revoke is idempotent — second revoke also returns ok=true.",
+        },
+      },
+      required: ["action"],
+    },
+    execute: async (params) => {
+      const action = params.action;
+
+      // Defense-in-depth: the outer filter (mcp-http.ts visibleTools)
+      // already requires vault:admin for this vault to see manage-token,
+      // so reaching execute means the gate passed. A hand-crafted
+      // tools/call bypassing list would still hit the dispatch verb-check
+      // in handleScopedMcp. The block below is a third belt-and-suspenders
+      // check so a refactor of either layer can't lose the invariant
+      // silently.
+      if (!auth || !hasScopeForVault(auth.scopes, vaultName, "admin")) {
+        return {
+          action,
+          error: "Forbidden",
+          message: `manage-token requires the 'vault:admin' scope (or 'vault:${vaultName}:admin'). Granted: ${auth?.scopes.join(" ") || "(none)"}.`,
+        };
+      }
+
+      if (action === "mint") return await mintAction(params, vaultName, auth);
+      if (action === "revoke") return revokeAction(params, vaultName, auth);
+      if (action === "list") return listAction(vaultName, auth);
+
+      return {
+        error: "invalid_request",
+        message: `manage-token: unknown action "${String(action)}" — expected "mint" | "revoke" | "list".`,
+      };
+    },
+  };
+}
+
+async function mintAction(
+  params: Record<string, unknown>,
+  vaultName: string,
+  auth: AuthResult,
+): Promise<Record<string, unknown>> {
+  // Scope parsing: accept string or string[]. Empty/missing is rejected
+  // explicitly (no implicit "full scope" default — manage-token always
+  // narrows). The validateMintedScopes call then enforces:
+  //   - shape (recognized vault scope)
+  //   - vault-pin (cross-vault rejected)
+  //   - subset of caller's scope on this vault.
+  let requested: string[];
+  if (typeof params.scope === "string") {
+    requested = parseScopes(params.scope);
+  } else if (Array.isArray(params.scope)) {
+    requested = params.scope.filter((s): s is string => typeof s === "string" && s.length > 0);
+  } else {
+    return {
+      action: "mint",
+      error: "invalid_request",
+      message: "manage-token mint: `scope` is required (string or string[]).",
+    };
+  }
+  if (requested.length === 0) {
+    return {
+      action: "mint",
+      error: "invalid_request",
+      message: "manage-token mint: at least one scope required.",
+    };
+  }
+
+  const validation = validateMintedScopes(requested, vaultName, auth.scopes);
+  if (!validation.ok) {
+    return {
+      action: "mint",
+      error: "forbidden",
+      message: "manage-token mint: scope rejected (must be a subset of the caller's scope on this vault).",
+      rejected: validation.rejected,
+    };
+  }
+
+  // TTL bounds. Default 900 (15 min); explicit values must satisfy
+  // `0 < ttl <= MANAGE_TOKEN_MAX_TTL_SECONDS`. Zero, negative, NaN, and
+  // beyond-max all reject — the cap is the safety backstop if revoke fails,
+  // so it must be strict.
+  let ttl = MANAGE_TOKEN_DEFAULT_TTL_SECONDS;
+  if (params.ttl_seconds !== undefined && params.ttl_seconds !== null) {
+    if (typeof params.ttl_seconds !== "number" || !Number.isFinite(params.ttl_seconds)) {
+      return {
+        action: "mint",
+        error: "invalid_request",
+        message: "manage-token mint: ttl_seconds must be a finite number.",
+      };
+    }
+    if (params.ttl_seconds <= 0 || params.ttl_seconds > MANAGE_TOKEN_MAX_TTL_SECONDS) {
+      return {
+        action: "mint",
+        error: "invalid_request",
+        message: `manage-token mint: ttl_seconds must be in (0, ${MANAGE_TOKEN_MAX_TTL_SECONDS}]; got ${params.ttl_seconds}.`,
+      };
+    }
+    ttl = params.ttl_seconds;
+  }
+  const expiresAt = new Date(Date.now() + ttl * 1000).toISOString();
+
+  const description = typeof params.description === "string" && params.description.length > 0
+    ? params.description
+    : null;
+  const label = description ?? `mcp-mint (parent=${auth.caller_jti ?? "unknown"})`;
+
+  const store = getVaultStore(vaultName);
+  const { fullToken } = generateToken();
+  const created = createToken(store.db, fullToken, {
+    label,
+    permission: permissionForScopes(requested),
+    scopes: requested,
+    // Tag scoping: inherit the caller's allowlist verbatim. We don't expose
+    // a `tags` param on manage-token yet — the design doc keeps the v1
+    // surface minimal. When the caller is tag-scoped, the minted token
+    // carries the same allowlist (no narrowing, no widening); when the
+    // caller is unscoped, the mint is unscoped. Future widening of the
+    // surface should re-use tokens-routes.ts' validation path so the rules
+    // stay in lockstep.
+    scoped_tags: auth.scoped_tags,
+    vault_name: vaultName,
+    expires_at: expiresAt,
+    created_via: "mcp_mint",
+    parent_jti: auth.caller_jti,
+  });
+
+  return {
+    action: "mint",
+    token: fullToken,
+    jti: `t_${created.token_hash.slice(7, 19)}`,
+    expires_at: expiresAt,
+    scopes: requested,
+    scoped_tags: auth.scoped_tags,
+    vault_name: vaultName,
+  };
+}
+
+function revokeAction(
+  params: Record<string, unknown>,
+  vaultName: string,
+  auth: AuthResult,
+): Record<string, unknown> {
+  if (typeof params.jti !== "string" || params.jti.length === 0) {
+    return {
+      action: "revoke",
+      ok: false,
+      error: "invalid_request",
+      message: "manage-token revoke: `jti` is required (string).",
+    };
+  }
+  // Session-pin: revoke is restricted to tokens this MCP session minted.
+  // When auth.caller_jti is null (no stable session id — env-var operator,
+  // legacy YAML key, hub JWT without jti), there are no MCP-minted tokens
+  // attributable to this session, so revoke returns not_found.
+  if (!auth.caller_jti) {
+    return {
+      action: "revoke",
+      ok: false,
+      error: "not_found",
+      message: "manage-token revoke: this session has no stable id; revoke via the CLI or REST surface.",
+    };
+  }
+  const store = getVaultStore(vaultName);
+  const result = softRevokeMcpToken(store.db, params.jti, auth.caller_jti, vaultName);
+  if (!result.ok) {
+    // Idempotency: not-found returns ok=true so the AI's "mint → run →
+    // revoke" loop doesn't surface a confusing failure when a network
+    // blip causes a duplicate revoke call. The spec calls this out
+    // explicitly (vault#376). The "already minted by another session"
+    // case also lands here; we don't differentiate (no information leak
+    // about other sessions' jti space).
+    return { action: "revoke", ok: true, note: "no matching token in this session" };
+  }
+  return { action: "revoke", ok: true, already_revoked: result.already_revoked };
+}
+
+function listAction(vaultName: string, auth: AuthResult): Record<string, unknown> {
+  if (!auth.caller_jti) {
+    // No session id → no attributable mints. Return empty list rather
+    // than erroring, so callers can branch on tokens.length without
+    // exception handling.
+    return { action: "list", tokens: [] };
+  }
+  const store = getVaultStore(vaultName);
+  const tokens = listMcpMintedTokens(store.db, auth.caller_jti, vaultName);
+  return { action: "list", tokens };
+}