@seekrit/cli 0.30.0 → 0.32.0

package/dist/index.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { z } from "zod";
 import { Command } from "commander";
 import { homedir, hostname, tmpdir, userInfo } from "node:os";
 import { dirname, join, parse } from "node:path";
 import { createInterface } from "node:readline";
 import { Writable } from "node:stream";
+import { createHash } from "node:crypto";
 /** All catalog keys as a runtime array (for iteration / zod enums). */
 const ENTITLEMENT_KEYS = Object.keys({
 	"feature.kms": {
@@ -2719,7 +2720,7 @@ function isCliSessionToken(value) {
 }
 //#endregion
 //#region package.json
-var version = "0.30.0";
+var version = "0.32.0";
 //#endregion
 //#region ../../packages/api-client/src/index.ts
 var SeekritApiError = class extends Error {
@@ -3406,7 +3407,8 @@ function tryBuildContext(dotenvVars = {}) {
 			auth,
 			client: CLI_CLIENT
 		}),
-		auth
+		auth,
+		apiUrl
 	};
 }
 function buildContext() {
@@ -4812,6 +4814,163 @@ function registerBranchCommands(program) {
 		console.error(`deleted branch ${app.slug}#${target.slug}`);
 	});
 }
+/** Domain separators — must match `crates/seekrit-cache`. */
+const KEY_DOMAIN = "seekrit-lkg-cache-v1";
+const TOKEN_DOMAIN = "seekrit-token-fp-v1";
+/** 24h: long enough to ride out an outage, short enough to bound the tail. */
+const DEFAULT_MAX_AGE_MS = 1440 * 60 * 1e3;
+/**
+* Derive the key for one resolve request. Overrides are sorted, so flag order
+* never splits the cache. Byte-for-byte identical to `CacheKey::new` in
+* `crates/seekrit-cache`.
+*/
+function cacheKey(apiUrl, token, branch, overrides = {}) {
+	const pairs = Object.entries(overrides).map(([group, env]) => `${group}:${env}`).sort();
+	return {
+		key: createHash("sha256").update([
+			KEY_DOMAIN,
+			apiUrl.replace(/\/+$/, ""),
+			token,
+			branch ?? "",
+			pairs.join(",")
+		].join("\n")).digest("hex"),
+		tokenFingerprint: tokenFingerprint(token)
+	};
+}
+/** The hex SHA-256 identifying a token without storing it. */
+function tokenFingerprint(token) {
+	return createHash("sha256").update(`${TOKEN_DOMAIN}\n${token}`).digest("hex");
+}
+/**
+* `$XDG_CACHE_HOME/seekrit`, else `~/.cache/seekrit` — beside the config
+* directory holding the credential, never a shared temp directory.
+*/
+function defaultCacheDir() {
+	return join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "seekrit");
+}
+/** Render an age for a log line, rounded to its largest whole unit. */
+function humanize(ms) {
+	const secs = Math.floor(ms / 1e3);
+	if (secs < 60) return `${secs}s`;
+	if (secs < 3600) return `${Math.floor(secs / 60)}m`;
+	if (secs < 86400) return `${Math.floor(secs / 3600)}h`;
+	return `${Math.floor(secs / 86400)}d`;
+}
+/**
+* Whether a failed resolve means the API was *unreachable* (the cache may stand
+* in) rather than *refusing us* (it must not). A refusal is an answer, and
+* revocation is supposed to take effect the moment it arrives.
+*/
+function mayFallBack(err) {
+	if (err instanceof SeekritApiError) return err.status >= 500 || err.status === 429;
+	return true;
+}
+/** An opened cache, bound to one resolve request. */
+var LkgCache = class {
+	dir;
+	maxAgeMs;
+	id;
+	constructor(id, options = {}) {
+		this.id = id;
+		this.dir = options.dir ?? defaultCacheDir();
+		this.maxAgeMs = options.maxAgeMs ?? 864e5;
+	}
+	path() {
+		return join(this.dir, `${this.id.key}.json`);
+	}
+	read() {
+		const path = this.path();
+		if (!existsSync(path)) return { kind: "missing" };
+		let envelope;
+		try {
+			envelope = JSON.parse(readFileSync(path, "utf8"));
+		} catch (err) {
+			return {
+				kind: "unusable",
+				reason: `corrupt cache entry: ${message(err)}`
+			};
+		}
+		if (envelope.version !== 1) return {
+			kind: "unusable",
+			reason: `cache entry is format v${envelope.version}, this build reads v1`
+		};
+		if (envelope.tokenFingerprint !== this.id.tokenFingerprint) return {
+			kind: "unusable",
+			reason: "cache entry belongs to a different token"
+		};
+		if (typeof envelope.body !== "string") return {
+			kind: "unusable",
+			reason: "cache entry has no body"
+		};
+		const ageMs = Math.max(0, Date.now() - envelope.fetchedAt * 1e3);
+		if (ageMs >= this.maxAgeMs) return {
+			kind: "expired",
+			ageMs
+		};
+		return {
+			kind: "hit",
+			body: envelope.body,
+			ageMs
+		};
+	}
+	/**
+	* Record a freshly-fetched response. Written to a temporary file and renamed,
+	* so a concurrent reader sees either the old entry or the new one — never a
+	* half-written file. Throws only on genuinely unexpected I/O; callers treat a
+	* failed write as a warning, never as a failed resolve.
+	*/
+	write(body) {
+		mkdirSync(this.dir, {
+			recursive: true,
+			mode: 448
+		});
+		const envelope = {
+			version: 1,
+			fetchedAt: Math.floor(Date.now() / 1e3),
+			tokenFingerprint: this.id.tokenFingerprint,
+			body
+		};
+		const tmp = join(this.dir, `${this.id.key}.${process.pid}.tmp`);
+		try {
+			writeFileSync(tmp, JSON.stringify(envelope), { mode: 384 });
+			renameSync(tmp, this.path());
+		} catch (err) {
+			rmSync(tmp, { force: true });
+			throw err;
+		}
+		this.pruneExpired();
+	}
+	/** Drop this entry — used when the API refuses the token. */
+	invalidate() {
+		rmSync(this.path(), { force: true });
+	}
+	/**
+	* Delete entries past their usefulness (a rotated token or a changed
+	* `--with` leaves one nothing will read again). Best-effort and silent, and
+	* it only ever touches files this cache named: `<64 hex>.json`.
+	*/
+	pruneExpired() {
+		let names;
+		try {
+			names = readdirSync(this.dir);
+		} catch {
+			return;
+		}
+		for (const name of names) {
+			if (!/^[0-9a-f]{64}\.json$/.test(name)) continue;
+			const path = join(this.dir, name);
+			let expired = true;
+			try {
+				const envelope = JSON.parse(readFileSync(path, "utf8"));
+				expired = Math.max(0, Date.now() - envelope.fetchedAt * 1e3) >= this.maxAgeMs;
+			} catch {}
+			if (expired) rmSync(path, { force: true });
+		}
+	}
+};
+function message(err) {
+	return err instanceof Error ? err.message : String(err);
+}
 //#endregion
 //#region src/format.ts
 function shellQuote(value) {
@@ -6070,7 +6229,7 @@ async function materializeEnv(ctx, opts) {
 		if (!opts.envId) fail("specify --app and --env, or authenticate with a service token (SEEKRIT_TOKEN)");
 		query.env = opts.envId;
 	}
-	const { scope, layers } = await ctx.client.resolve(query);
+	const { scope, layers } = await resolveWithCache(ctx, query, opts.cache);
 	const privateKey = await getPrivateKey(ctx);
 	const values = {};
 	const provenance = {};
@@ -6094,6 +6253,46 @@ async function materializeEnv(ctx, opts) {
 	};
 }
 /**
+* Resolve, going through the last-known-good cache when one is configured.
+*
+* Always live first: the cache exists for when the call cannot land, not to
+* save a round trip, so a recovered network is picked up on the very next
+* invocation. A *refused* resolve (401/403/…) drops the entry rather than
+* falling back to it — otherwise revoking a token would keep working offline
+* until the entry aged out.
+*/
+async function resolveWithCache(ctx, query, cache) {
+	if (!cache) return ctx.client.resolve(query);
+	try {
+		const response = await ctx.client.resolve(query);
+		try {
+			cache.write(JSON.stringify(response));
+		} catch (err) {
+			warn(`could not update the cache: ${errorMessage(err)}`);
+		}
+		return response;
+	} catch (err) {
+		if (!mayFallBack(err)) {
+			cache.invalidate();
+			throw err;
+		}
+		const found = cache.read();
+		if (found.kind === "hit") {
+			warn(`${errorMessage(err)} — using cached secrets fetched ${humanize(found.ageMs)} ago`);
+			return JSON.parse(found.body);
+		}
+		if (found.kind === "expired") warn(`cached secrets are ${humanize(found.ageMs)} old, past --cache-max-age`);
+		else if (found.kind === "unusable") warn(`ignoring the cached secrets: ${found.reason}`);
+		throw err;
+	}
+}
+function warn(text) {
+	process.stderr.write(`seekrit: ${text}\n`);
+}
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/**
 * Overlay `.env` files onto an existing value/provenance set (later files win).
 * Missing files are skipped. Returns the files that were actually loaded. Used
 * both by {@link materializeEnv} and by `seekrit run`'s degraded path, where
@@ -6840,8 +7039,55 @@ withTarget(secrets.command("rm <name>").description("delete a secret")).action(a
 	await ctx.client.deleteSecret(orgId, envId, name);
 	console.error(`${name} deleted`);
 });
+/**
+* Open the last-known-good cache for this request, or `undefined` when it is
+* off. `dotenvVars` carries `SEEKRIT_*` values read from a `.env` file, so the
+* flags follow the same `flag > env > .env` precedence as the credentials.
+*
+* **Service tokens only.** A user session's private key is fetched from the API
+* and unlocked with a passphrase, so caching the resolve response alone would
+* not make an offline run work — and the token is what the cache key is built
+* from. `--cache` under user auth is a no-op we say out loud rather than a
+* silent one.
+*/
+function openCache(ctx, options, dotenvVars = {}) {
+	const lookup = (key) => process.env[key] ?? dotenvVars[key];
+	const truthy = (value) => [
+		"1",
+		"true",
+		"yes",
+		"on"
+	].includes((value ?? "").trim().toLowerCase());
+	if (!(options.cache ?? truthy(lookup("SEEKRIT_CACHE")))) return void 0;
+	if (!isTokenAuth(ctx)) {
+		process.stderr.write("seekrit: --cache needs a service token (SEEKRIT_TOKEN); continuing without it\n");
+		return;
+	}
+	const token = ctx.auth.type === "bearer" ? ctx.auth.token : "";
+	const maxAgeRaw = options.cacheMaxAge ?? lookup("SEEKRIT_CACHE_MAX_AGE");
+	const maxAgeMs = maxAgeRaw ? parseDurationMs(maxAgeRaw) : DEFAULT_MAX_AGE_MS;
+	const branch = options.branch ?? process.env.SEEKRIT_BRANCH ?? dotenvVars.SEEKRIT_BRANCH;
+	return new LkgCache(cacheKey(ctx.apiUrl, token, branch, options.with), {
+		dir: options.cacheDir ?? lookup("SEEKRIT_CACHE_DIR"),
+		maxAgeMs
+	});
+}
+/** `30s` / `15m` / `24h` / `7d` / bare seconds → ms. Matches the Rust parser. */
+function parseDurationMs(raw) {
+	const match = /^(\d+)\s*([smhd]?)$/.exec(raw.trim());
+	if (!match) fail(`--cache-max-age: not a duration: "${raw}" (try 15m, 24h, 7d)`);
+	const value = Number(match[1]);
+	if (value === 0) fail("--cache-max-age: must be greater than zero");
+	return value * ({
+		"": 1,
+		s: 1,
+		m: 60,
+		h: 3600,
+		d: 86400
+	}[match[2] ?? ""] ?? 1) * 1e3;
+}
 /** Resolve the layered environment for the current principal. */
-async function materialize(ctx, options) {
+async function materialize(ctx, options, dotenvVars = {}) {
 	let envId;
 	if (!isTokenAuth(ctx)) envId = (await resolveAppEnv(ctx, options)).envId;
 	return materializeEnv(ctx, {
@@ -6849,7 +7095,8 @@ async function materialize(ctx, options) {
 		branch: options.branch ?? process.env.SEEKRIT_BRANCH,
 		with: options.with,
 		envFiles: options.envFile ?? [".env"],
-		interpolate: options.interpolate
+		interpolate: options.interpolate,
+		cache: openCache(ctx, options, dotenvVars)
 	});
 }
 /**
@@ -6871,7 +7118,7 @@ async function materializeForRun(options) {
 		return await materialize(ctx, {
 			...options,
 			branch
-		});
+		}, dotenvVars);
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		console.error(`seekrit: continuing without seekrit-managed secrets: ${message}`);
@@ -6994,7 +7241,7 @@ async function reapStragglers(pids, signal) {
 		process.kill(pid, "SIGKILL");
 	} catch {}
 }
-program.command("run").description("run a command with decrypted secrets injected (process env > .env > app > group)").passThroughOptions().option("--org <slug>").option("--app <slug>", "application slug (token path infers this)").option("--env <slug>", "environment slug (token path infers this)").option("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice for this run", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").argument("<command...>", "command to run (prefix with -- to pass flags)").action(async (commandParts, options) => {
+program.command("run").description("run a command with decrypted secrets injected (process env > .env > app > group)").passThroughOptions().option("--org <slug>").option("--app <slug>", "application slug (token path infers this)").option("--env <slug>", "environment slug (token path infers this)").option("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice for this run", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").option("--cache", "keep a last-known-good copy of the encrypted response and fall back to it when the API is unreachable (off by default; SEEKRIT_CACHE=1)").option("--cache-dir <path>", "where to keep it (default: $XDG_CACHE_HOME/seekrit)").option("--cache-max-age <duration>", "how stale a cached copy may be and still be used, e.g. 15m, 24h, 7d (default: 24h)").argument("<command...>", "command to run (prefix with -- to pass flags)").action(async (commandParts, options) => {
 	const [cmd, ...args] = commandParts;
 	if (!cmd) fail("no command given");
 	const { values, provenance, interpolated, unresolvedRefs } = await materializeForRun(options);
@@ -7046,7 +7293,7 @@ program.command("run").description("run a command with decrypted secrets injecte
 	});
 	child.on("error", (err) => fail(`failed to start ${cmd}: ${err.message}`));
 });
-program.command("export").description("print decrypted secrets (dotenv, json, or shell)").option("--org <slug>").option("--app <slug>", "application slug (token path infers this)").option("--env <slug>", "environment slug (token path infers this)").option("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").option("--format <format>", "dotenv | json | shell", "dotenv").action(async (options) => {
+program.command("export").description("print decrypted secrets (dotenv, json, or shell)").option("--org <slug>").option("--app <slug>", "application slug (token path infers this)").option("--env <slug>", "environment slug (token path infers this)").option("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").option("--cache", "keep a last-known-good copy of the encrypted response and fall back to it when the API is unreachable (off by default; SEEKRIT_CACHE=1)").option("--cache-dir <path>", "where to keep it (default: $XDG_CACHE_HOME/seekrit)").option("--cache-max-age <duration>", "how stale a cached copy may be and still be used, e.g. 15m, 24h, 7d (default: 24h)").option("--format <format>", "dotenv | json | shell", "dotenv").action(async (options) => {
 	if (![
 		"dotenv",
 		"json",
@@ -7148,7 +7395,7 @@ registerMongoCommands(program);
 registerKmsCommands(program);
 registerRecoveryCommands(program);
 program.command("mcp").description("run an MCP server over stdio so AI agents can drive seekrit").action(async () => {
-	const { runMcpServer } = await import("./mcp-DLplPOvz.js");
+	const { runMcpServer } = await import("./mcp-DR-zla_u.js");
 	await runMcpServer();
 });
 registerAuditCommands(program);

package/dist/{mcp-DLplPOvz.js → mcp-DR-zla_u.js}

@@ -26,6 +26,16 @@ function errText(err) {
 		isError: true
 	};
 }
+/** Read-only and safe to repeat — every list/inspect tool. */
+const ro = {
+	readOnly: true,
+	idempotent: true
+};
+/** Removes or overwrites something; repeating it lands in the same state. */
+const destructive = {
+	destructive: true,
+	idempotent: true
+};
 /**
 * Short primer surfaced as the MCP server `instructions`. Most clients show
 * this to the model on connect, so it has to orient an agent that lands here
@@ -194,10 +204,17 @@ async function runMcpServer(options = {}) {
 		version: options.version ?? version
 	}, { instructions: serverInstructions() });
 	/** Register a tool whose handler returns data (serialized) or throws (→ isError). */
-	const tool = (name, description, shape, handler) => {
+	const tool = (name, description, hints, shape, handler) => {
 		server.registerTool(name, {
 			description,
-			inputSchema: shape
+			inputSchema: shape,
+			annotations: {
+				title: name,
+				readOnlyHint: hints.readOnly ?? false,
+				destructiveHint: hints.destructive ?? false,
+				idempotentHint: hints.idempotent ?? false,
+				openWorldHint: true
+			}
 		}, (async (args) => {
 			try {
 				return jsonText(await handler(args));
@@ -215,7 +232,7 @@ async function runMcpServer(options = {}) {
 			openWorldHint: false
 		}
 	}, async () => jsonText(getStartedText()));
-	tool("whoami", "Show the authenticated identity, its role, and accessible orgs.", {}, async () => {
+	tool("whoami", "Show the authenticated identity, its role, and accessible orgs.", ro, {}, async () => {
 		const ctx = getCtx();
 		if (isTokenAuth(ctx) && ctx.auth.type === "bearer") {
 			const { tokenId } = await parseServiceToken(ctx.auth.token);
@@ -236,13 +253,13 @@ async function runMcpServer(options = {}) {
 			...await ctx.client.me()
 		};
 	});
-	tool("list_orgs", "List organizations the caller can access.", {}, async () => (await getCtx().client.listOrgs()).orgs);
-	tool("list_apps", "List applications in an organization.", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_orgs", "List organizations the caller can access.", ro, {}, async () => (await getCtx().client.listOrgs()).orgs);
+	tool("list_apps", "List applications in an organization.", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listApps(orgRef.id)).apps;
 	});
-	tool("list_envs", "List environments of an application.", {
+	tool("list_envs", "List environments of an application.", ro, {
 		org: z.string().optional(),
 		app: z.string()
 	}, async ({ org, app }) => {
@@ -253,7 +270,7 @@ async function runMcpServer(options = {}) {
 		if (!appRow) throw new Error(`no app "${app}" in ${orgRef.slug}`);
 		return (await ctx.client.listEnvs(orgRef.id, appRow.id)).environments;
 	});
-	tool("list_branches", "List ephemeral branch configs in an application (optionally just one environment's).", {
+	tool("list_branches", "List ephemeral branch configs in an application (optionally just one environment's).", ro, {
 		org: z.string().optional(),
 		app: z.string(),
 		env: z.string().optional()
@@ -271,12 +288,12 @@ async function runMcpServer(options = {}) {
 		});
 		return (await ctx.client.listBranches(parent.orgId, parent.envId)).branches;
 	});
-	tool("list_groups", "List shared groups (reusable secret bags) in an organization.", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_groups", "List shared groups (reusable secret bags) in an organization.", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listGroups(orgRef.id)).groups;
 	});
-	tool("list_group_envs", "List a group's environments (per-slug value sets).", {
+	tool("list_group_envs", "List a group's environments (per-slug value sets).", ro, {
 		org: z.string().optional(),
 		group: z.string()
 	}, async ({ org, group }) => {
@@ -287,7 +304,7 @@ async function runMcpServer(options = {}) {
 		});
 		return (await ctx.client.listGroupEnvs(g.orgId, g.id)).environments;
 	});
-	tool("list_env_groups", "List the groups composed into an application environment (precedence order).", {
+	tool("list_env_groups", "List the groups composed into an application environment (precedence order).", ro, {
 		org: z.string().optional(),
 		app: z.string(),
 		env: z.string()
@@ -300,17 +317,17 @@ async function runMcpServer(options = {}) {
 		});
 		return (await ctx.client.listEnvGroups(target.orgId, target.envId)).groups;
 	});
-	tool("list_members", "List organization members and their public keys (for granting access).", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_members", "List organization members and their public keys (for granting access).", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listMembers(orgRef.id)).members;
 	});
-	tool("kms_list_keys", "List managed KMS keys the caller can see (metadata only).", { org: z.string().optional() }, async ({ org }) => {
+	tool("kms_list_keys", "List managed KMS keys the caller can see (metadata only).", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listKmsKeys(orgRef.id)).keys;
 	});
-	tool("kms_create_key", "Create an org-scoped managed key. Material is generated locally and wrapped to each grantee (self plus any listed users/tokens); the server never sees it. Use the CLI for app/group-scoped keys.", {
+	tool("kms_create_key", "Create an org-scoped managed key. Material is generated locally and wrapped to each grantee (self plus any listed users/tokens); the server never sees it. Use the CLI for app/group-scoped keys.", { idempotent: false }, {
 		org: z.string().optional(),
 		name: z.string(),
 		purpose: z.enum(["encrypt", "sign"]),
@@ -351,7 +368,7 @@ async function runMcpServer(options = {}) {
 		});
 		return key;
 	});
-	tool("kms_grant", "Grant a principal (user email or token id) use of a key's current version.", {
+	tool("kms_grant", "Grant a principal (user email or token id) use of a key's current version.", { idempotent: true }, {
 		org: z.string().optional(),
 		key: z.string(),
 		user: z.string().optional(),
@@ -376,7 +393,7 @@ async function runMcpServer(options = {}) {
 			key: k.name
 		};
 	});
-	tool("kms_encrypt", "Encrypt a value under a managed encrypt key; returns a ce1 ciphertext blob. `context` (if given) is bound as AAD and must be supplied identically to decrypt.", {
+	tool("kms_encrypt", "Encrypt a value under a managed encrypt key; returns a ce1 ciphertext blob. `context` (if given) is bound as AAD and must be supplied identically to decrypt.", { readOnly: true }, {
 		org: z.string().optional(),
 		key: z.string(),
 		plaintext: z.string(),
@@ -393,7 +410,7 @@ async function runMcpServer(options = {}) {
 			version: currentVersion
 		}, plaintext, context ?? "") };
 	});
-	tool("kms_decrypt", "Decrypt a ce1 blob. Supply the same `context` used to encrypt.", {
+	tool("kms_decrypt", "Decrypt a ce1 blob. Supply the same `context` used to encrypt.", ro, {
 		org: z.string().optional(),
 		key: z.string(),
 		ciphertext: z.string(),
@@ -407,7 +424,7 @@ async function runMcpServer(options = {}) {
 		const { material } = await kmsRecoverMaterial(ctx, orgRef.id, k.id, ref.version);
 		return { plaintext: await kmsDecrypt(material, ciphertext, context ?? "") };
 	});
-	tool("kms_generate_data_key", "Generate a data key under a managed encrypt key (envelope encryption). Returns the plaintext key (base64) and its wrapped form to store.", {
+	tool("kms_generate_data_key", "Generate a data key under a managed encrypt key (envelope encryption). Returns the plaintext key (base64) and its wrapped form to store.", { readOnly: true }, {
 		org: z.string().optional(),
 		key: z.string()
 	}, async ({ org, key }) => {
@@ -426,7 +443,7 @@ async function runMcpServer(options = {}) {
 			wrapped: dk.wrapped
 		};
 	});
-	tool("kms_sign", "Sign a message with a managed signing key; returns an sg1 signature blob.", {
+	tool("kms_sign", "Sign a message with a managed signing key; returns an sg1 signature blob.", { readOnly: true }, {
 		org: z.string().optional(),
 		key: z.string(),
 		message: z.string()
@@ -442,7 +459,7 @@ async function runMcpServer(options = {}) {
 			version: currentVersion
 		}, message) };
 	});
-	tool("kms_verify", "Verify an sg1 signature over a message using a signing key's published public key (no grant needed).", {
+	tool("kms_verify", "Verify an sg1 signature over a message using a signing key's published public key (no grant needed).", ro, {
 		org: z.string().optional(),
 		key: z.string(),
 		signature: z.string(),
@@ -457,7 +474,7 @@ async function runMcpServer(options = {}) {
 		if (!pub) throw new Error(`no published public key for version ${ref.version}`);
 		return { valid: await verifyMessage(await importVerifyingKey(pub), signature, message) };
 	});
-	tool("list_secrets", "List secret names + versions in an environment (never values).", targetShape, async (o) => {
+	tool("list_secrets", "List secret names + versions in an environment (never values).", ro, targetShape, async (o) => {
 		const ctx = getCtx();
 		const { orgId, envId } = await resolveTargetEnv(ctx, o);
 		const { secrets } = await ctx.client.listSecrets(orgId, envId);
@@ -467,12 +484,12 @@ async function runMcpServer(options = {}) {
 			updatedAt: s.updatedAt
 		}));
 	});
-	tool("list_tokens", "List an organization's service tokens (never the secret token strings).", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_tokens", "List an organization's service tokens (never the secret token strings).", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listTokens(orgRef.id)).tokens;
 	});
-	tool("audit", "Read the organization's audit trail (most recent first).", {
+	tool("audit", "Read the organization's audit trail (most recent first).", ro, {
 		org: z.string().optional(),
 		limit: z.number().int().min(1).max(200).optional(),
 		action: z.string().optional().describe("filter by action, e.g. secret.updated")
@@ -484,14 +501,14 @@ async function runMcpServer(options = {}) {
 			action
 		})).entries;
 	});
-	tool("create_org", "Create an organization. Requires a user session — service tokens cannot own a Stytch org.", {
+	tool("create_org", "Create an organization. Requires a user session — service tokens cannot own a Stytch org.", { idempotent: false }, {
 		name: z.string(),
 		slug: z.string()
 	}, async ({ name, slug }) => (await getCtx().client.createOrg({
 		name,
 		slug
 	})).org);
-	tool("create_app", "Create an application in an organization.", {
+	tool("create_app", "Create an application in an organization.", { idempotent: false }, {
 		org: z.string().optional(),
 		name: z.string(),
 		slug: z.string()
@@ -503,7 +520,7 @@ async function runMcpServer(options = {}) {
 			slug
 		})).app;
 	});
-	tool("create_group", "Create a shared group (reusable secret bag) in an organization.", {
+	tool("create_group", "Create a shared group (reusable secret bag) in an organization.", { idempotent: false }, {
 		org: z.string().optional(),
 		name: z.string(),
 		slug: z.string()
@@ -515,7 +532,7 @@ async function runMcpServer(options = {}) {
 			slug
 		})).group;
 	});
-	tool("create_env", "Create an application environment. Generates the data key locally and grants it to the caller.", {
+	tool("create_env", "Create an application environment. Generates the data key locally and grants it to the caller.", { idempotent: false }, {
 		org: z.string().optional(),
 		app: z.string(),
 		name: z.string(),
@@ -533,7 +550,7 @@ async function runMcpServer(options = {}) {
 			wrappedDek
 		})).environment;
 	});
-	tool("create_branch", "Fork an environment into an ephemeral branch (a per-PR / preview config). The branch inherits the parent's secrets by layering at read time — nothing is copied or re-encrypted — and holds only the values you override on it. Generates the branch's data key locally, grants it to the caller, and shares it with the parent's other readers.", {
+	tool("create_branch", "Fork an environment into an ephemeral branch (a per-PR / preview config). The branch inherits the parent's secrets by layering at read time — nothing is copied or re-encrypted — and holds only the values you override on it. Generates the branch's data key locally, grants it to the caller, and shares it with the parent's other readers.", { idempotent: false }, {
 		org: z.string().optional(),
 		app: z.string(),
 		from: z.string().describe("the environment to branch"),
@@ -568,7 +585,7 @@ async function runMcpServer(options = {}) {
 			grants
 		})).branch;
 	});
-	tool("delete_branch", "Tear down a branch config and every value it overrode. The parent environment is untouched.", {
+	tool("delete_branch", "Tear down a branch config and every value it overrode. The parent environment is untouched.", destructive, {
 		org: z.string().optional(),
 		app: z.string(),
 		branch: z.string()
@@ -582,7 +599,7 @@ async function runMcpServer(options = {}) {
 		await ctx.client.deleteBranch(appRef.orgId, target.id);
 		return { deleted: target.slug };
 	});
-	tool("create_group_env", "Create a group environment. Generates the data key locally and grants it to the caller.", {
+	tool("create_group_env", "Create a group environment. Generates the data key locally and grants it to the caller.", { idempotent: false }, {
 		org: z.string().optional(),
 		group: z.string(),
 		name: z.string(),
@@ -600,7 +617,7 @@ async function runMcpServer(options = {}) {
 			wrappedDek
 		})).environment;
 	});
-	tool("compose_group", "Compose a group into an application environment (higher position wins on name clashes).", {
+	tool("compose_group", "Compose a group into an application environment (higher position wins on name clashes).", { idempotent: true }, {
 		org: z.string().optional(),
 		app: z.string(),
 		env: z.string(),
@@ -622,7 +639,7 @@ async function runMcpServer(options = {}) {
 			position
 		})).group;
 	});
-	tool("uncompose_group", "Remove a composed group from an application environment.", {
+	tool("uncompose_group", "Remove a composed group from an application environment.", { idempotent: true }, {
 		org: z.string().optional(),
 		app: z.string(),
 		env: z.string(),
@@ -641,7 +658,7 @@ async function runMcpServer(options = {}) {
 		await ctx.client.unlinkEnvGroup(target.orgId, target.envId, g.id);
 		return { ok: true };
 	});
-	tool("set_secret", "Encrypt a value locally and store it in an environment. A value may reference another secret as ${OTHER_SECRET}: the reference is stored literally and expanded whenever the secret is read, so it tracks the referenced value. Write $${OTHER_SECRET} for a literal.", {
+	tool("set_secret", "Encrypt a value locally and store it in an environment. A value may reference another secret as ${OTHER_SECRET}: the reference is stored literally and expanded whenever the secret is read, so it tracks the referenced value. Write $${OTHER_SECRET} for a literal.", { idempotent: false }, {
 		...targetShape,
 		name: z.string(),
 		value: z.string()
@@ -655,7 +672,7 @@ async function runMcpServer(options = {}) {
 			name: o.name
 		};
 	});
-	tool("get_secret", "Return one secret. By default only reports presence + version; pass reveal:true to decrypt the plaintext into this response (avoid unless the value is actually needed — prefer run_command). A revealed current value has its ${OTHER_SECRET} references expanded against this environment's own secrets; pass raw:true for the stored text instead. Pass `version` to read an earlier version instead of the current one (always as stored, never expanded).", {
+	tool("get_secret", "Return one secret. By default only reports presence + version; pass reveal:true to decrypt the plaintext into this response (avoid unless the value is actually needed — prefer run_command). A revealed current value has its ${OTHER_SECRET} references expanded against this environment's own secrets; pass raw:true for the stored text instead. Pass `version` to read an earlier version instead of the current one (always as stored, never expanded).", ro, {
 		...targetShape,
 		name: z.string(),
 		reveal: z.boolean().optional(),
@@ -692,7 +709,7 @@ async function runMcpServer(options = {}) {
 			revealed: true
 		};
 	});
-	tool("list_secret_versions", "List a secret's version history: who wrote each version, when, and which ones were restores. Never returns values — pair it with restore_secret to roll back, or get_secret(version, reveal:true) to inspect one.", {
+	tool("list_secret_versions", "List a secret's version history: who wrote each version, when, and which ones were restores. Never returns values — pair it with restore_secret to roll back, or get_secret(version, reveal:true) to inspect one.", ro, {
 		...targetShape,
 		name: z.string(),
 		limit: z.number().int().min(1).max(200).optional().describe("default 20")
@@ -710,7 +727,7 @@ async function runMcpServer(options = {}) {
 			}))
 		};
 	});
-	tool("restore_secret", "Roll a secret back to an earlier version. The stored ciphertext is replayed as a NEW version (history is append-only, nothing is overwritten). Keyless — no decryption happens, so this works even without a key.", {
+	tool("restore_secret", "Roll a secret back to an earlier version. The stored ciphertext is replayed as a NEW version (history is append-only, nothing is overwritten). Keyless — no decryption happens, so this works even without a key.", { idempotent: false }, {
 		...targetShape,
 		name: z.string(),
 		version: z.number().int().positive()
@@ -725,7 +742,7 @@ async function runMcpServer(options = {}) {
 			version: secret.version
 		};
 	});
-	tool("delete_secret", "Delete a secret from an environment.", {
+	tool("delete_secret", "Delete a secret from an environment.", destructive, {
 		...targetShape,
 		name: z.string()
 	}, async (o) => {
@@ -738,6 +755,9 @@ async function runMcpServer(options = {}) {
 		};
 	});
 	tool("run_command", "Run a command with the resolved secrets injected as environment variables, and return its exit code + captured output. Secret VALUES are never returned — this is the preferred way to use secrets. process env > .env > app env > groups.", {
+		destructive: true,
+		idempotent: false
+	}, {
 		command: z.string().describe("executable to run"),
 		args: z.array(z.string()).optional(),
 		org: z.string().optional(),
@@ -760,7 +780,7 @@ async function runMcpServer(options = {}) {
 			injectedVarCount: Object.keys(values).length
 		};
 	});
-	tool("export_env", "Write the resolved secrets to a dotenv file on disk and return the variable names written (never the values). Use to materialize a .env for local tooling.", {
+	tool("export_env", "Write the resolved secrets to a dotenv file on disk and return the variable names written (never the values). Use to materialize a .env for local tooling.", destructive, {
 		file: z.string().describe("path to write, e.g. .env"),
 		org: z.string().optional(),
 		app: z.string().optional(),
@@ -779,7 +799,7 @@ async function runMcpServer(options = {}) {
 			names: Object.keys(values).sort()
 		};
 	});
-	tool("create_token", "Mint a service token, printed once. Runtime tokens bind to one app environment (auto-granted its keys, so a command/agent can decrypt it). Pass admin:true for an org-scoped provisioning token (create apps/groups/envs, grant, mint tokens) — admin tokens need no env binding.", {
+	tool("create_token", "Mint a service token, printed once. Runtime tokens bind to one app environment (auto-granted its keys, so a command/agent can decrypt it). Pass admin:true for an org-scoped provisioning token (create apps/groups/envs, grant, mint tokens) — admin tokens need no env binding.", { idempotent: false }, {
 		name: z.string().describe("display name, e.g. ci-deploy or agent-session"),
 		org: z.string().optional(),
 		app: z.string().optional().describe("bind to this app (runtime tokens)"),
@@ -830,7 +850,7 @@ async function runMcpServer(options = {}) {
 			note: "save this now — the secret token string is not stored and cannot be retrieved"
 		};
 	});
-	tool("revoke_token", "Revoke a service token by id.", {
+	tool("revoke_token", "Revoke a service token by id.", destructive, {
 		org: z.string().optional(),
 		tokenId: z.string()
 	}, async ({ org, tokenId }) => {
@@ -842,7 +862,7 @@ async function runMcpServer(options = {}) {
 			tokenId
 		};
 	});
-	tool("grant_env", "Grant a member (by email) or service token (by id) access to an environment's data key. Re-wraps the DEK to the grantee — the caller must already hold the key.", {
+	tool("grant_env", "Grant a member (by email) or service token (by id) access to an environment's data key. Re-wraps the DEK to the grantee — the caller must already hold the key.", { idempotent: true }, {
 		...targetShape,
 		user: z.string().optional().describe("org member email"),
 		token: z.string().optional().describe("service token id (skt_…)")
@@ -887,12 +907,12 @@ async function runMcpServer(options = {}) {
 			principalId
 		};
 	});
-	tool("list_pg_targets", "List registered Postgres provisioning targets for temporary credentials.", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_pg_targets", "List registered Postgres provisioning targets for temporary credentials.", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listLeaseTargets(orgRef.id)).targets;
 	});
-	tool("create_pg_lease", "Mint a short-lived Postgres credential against a target and return a ready-to-use connection URL. The password is generated on THIS machine and only its SCRAM verifier is sent to the API — the plaintext never reaches seekrit or Postgres at rest. The role auto-expires; revoke early with revoke_pg_lease.", {
+	tool("create_pg_lease", "Mint a short-lived Postgres credential against a target and return a ready-to-use connection URL. The password is generated on THIS machine and only its SCRAM verifier is sent to the API — the plaintext never reaches seekrit or Postgres at rest. The role auto-expires; revoke early with revoke_pg_lease.", { idempotent: false }, {
 		org: z.string().optional(),
 		target: z.string().describe("target id or name"),
 		role: z.string().optional().describe("role name to create (default: random tmp_ name)"),
@@ -921,12 +941,12 @@ async function runMcpServer(options = {}) {
 			note: "short-lived credential; it auto-expires and the plaintext is not stored anywhere"
 		};
 	});
-	tool("list_pg_leases", "List Postgres leases (the ledger — never secret material).", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_pg_leases", "List Postgres leases (the ledger — never secret material).", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listLeases(orgRef.id)).leases;
 	});
-	tool("revoke_pg_lease", "Revoke a Postgres lease now (drops the role immediately).", {
+	tool("revoke_pg_lease", "Revoke a Postgres lease now (drops the role immediately).", destructive, {
 		org: z.string().optional(),
 		leaseId: z.string()
 	}, async ({ org, leaseId }) => {
@@ -938,12 +958,12 @@ async function runMcpServer(options = {}) {
 			leaseId
 		};
 	});
-	tool("list_mysql_targets", "List registered MySQL/MariaDB provisioning targets for temporary credentials.", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_mysql_targets", "List registered MySQL/MariaDB provisioning targets for temporary credentials.", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listLeaseTargets(orgRef.id)).targets.filter((t) => t.provider === "mysql");
 	});
-	tool("create_mysql_lease", "Mint a short-lived MySQL/MariaDB credential against a target and return a ready-to-use connection URL. The password is generated on THIS machine and only its mysql_native_password hash is sent to the API — the plaintext never reaches seekrit or MySQL at rest. The user auto-expires; revoke early with revoke_mysql_lease.", {
+	tool("create_mysql_lease", "Mint a short-lived MySQL/MariaDB credential against a target and return a ready-to-use connection URL. The password is generated on THIS machine and only its mysql_native_password hash is sent to the API — the plaintext never reaches seekrit or MySQL at rest. The user auto-expires; revoke early with revoke_mysql_lease.", { idempotent: false }, {
 		org: z.string().optional(),
 		target: z.string().describe("target id or name"),
 		user: z.string().optional().describe("user name to create (default: random tmp_ name)"),
@@ -973,12 +993,12 @@ async function runMcpServer(options = {}) {
 			note: "short-lived credential; it auto-expires and the plaintext is not stored anywhere"
 		};
 	});
-	tool("list_mysql_leases", "List MySQL/MariaDB leases (the ledger — never secret material).", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_mysql_leases", "List MySQL/MariaDB leases (the ledger — never secret material).", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listLeases(orgRef.id)).leases.filter((l) => l.provider === "mysql");
 	});
-	tool("revoke_mysql_lease", "Revoke a MySQL/MariaDB lease now (drops the user immediately).", {
+	tool("revoke_mysql_lease", "Revoke a MySQL/MariaDB lease now (drops the user immediately).", destructive, {
 		org: z.string().optional(),
 		leaseId: z.string()
 	}, async ({ org, leaseId }) => {
@@ -990,7 +1010,7 @@ async function runMcpServer(options = {}) {
 			leaseId
 		};
 	});
-	tool("configure_project", "Link a directory to an org/app by writing seekrit.json (like `seekrit init`). The environment is chosen by the service token at runtime.", {
+	tool("configure_project", "Link a directory to an org/app by writing seekrit.json (like `seekrit init`). The environment is chosen by the service token at runtime.", destructive, {
 		org: z.string(),
 		app: z.string(),
 		dir: z.string().optional()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seekrit/cli",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "End-to-end encrypted secrets manager CLI — inject decrypted secrets into any command.",
   "type": "module",
   "publishConfig": {
@@ -26,6 +26,7 @@
   "devDependencies": {
     "@types/node": "^26.1.0",
     "tsdown": "^0.22.3",
+    "vitest": "^4.1.9",
     "@seekrit/api-client": "0.0.1",
     "@seekrit/core": "0.0.1",
     "@seekrit/crypto": "0.0.1"
@@ -33,6 +34,7 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }
 }