@seekrit/cli 0.31.0 → 0.33.0

package/dist/index.js

@@ -16,6 +16,12 @@ const ENTITLEMENT_KEYS = Object.keys({
 		description: "Client-side managed keys for application-layer encryption and signing.",
 		default: true
 	},
+	"feature.honey_tokens": {
+		kind: "feature",
+		label: "Honey tokens",
+		description: "Decoy credentials that alert the moment anyone tries to use them.",
+		default: true
+	},
 	"feature.leases": {
 		kind: "feature",
 		label: "Temporary access",
@@ -122,7 +128,7 @@ const PLAN_FAMILIES = {
 		id: "free",
 		name: "Free",
 		description: "Get started with the essentials.",
-		current: 1,
+		current: 3,
 		hidden: false
 	},
 	team: {
@@ -1119,6 +1125,9 @@ const AUDIT_ACTIONS = [
 	"token.created",
 	"token.revoked",
 	"token.deleted",
+	"honey_token.created",
+	"honey_token.deleted",
+	"honey_token.tripped",
 	"cli_session.approved",
 	"cli_session.denied",
 	"cli_session.revoked",
@@ -1177,7 +1186,8 @@ const NOTIFICATION_TYPES = [
 	"org_welcome",
 	"token_expiring",
 	"lease_expired",
-	"sync_failed"
+	"sync_failed",
+	"honey_token_tripped"
 ];
 /** UI-facing copy + default for each notification type. */
 const NOTIFICATION_TYPE_META = {
@@ -1225,6 +1235,11 @@ const NOTIFICATION_TYPE_META = {
 		label: "Third-party sync failed",
 		description: "A sync to an external destination failed repeatedly and stopped retrying. The destination is now holding stale values.",
 		defaultEnabled: true
+	},
+	honey_token_tripped: {
+		label: "Honey token tripped",
+		description: "Someone tried to use one of your organization's decoy credentials (throttled per token). Nothing legitimate holds one, so every trip is worth reading.",
+		defaultEnabled: true
 	}
 };
 //#endregion
@@ -1332,6 +1347,14 @@ z.object({
 	environmentId: z.string().min(1).nullish(),
 	expiresAt: z.iso.datetime().nullish()
 });
+z.object({
+	name: nameSchema,
+	tokenId: z.string().regex(/^skt_[0-9A-Za-z]+$/),
+	/** SHA-256 hash (base64url) of the full token string. */
+	tokenHash: z.string().min(1),
+	/** Where the decoy was planted, as a reminder for whoever reads the alert. */
+	placement: z.string().max(200).nullish()
+});
 const kmsKeyPurposeSchema = z.enum(["encrypt", "sign"]);
 const kmsKeySpecSchema = z.enum(["aes-256-gcm", "ecdsa-p256"]);
 /** A wrapped key grant supplied by the client (server never sees plaintext material). */
@@ -2684,6 +2707,14 @@ async function createServiceToken() {
 		publicKeyJwk
 	};
 }
+async function createHoneyToken() {
+	const { token, tokenId, tokenHash } = await createServiceToken();
+	return {
+		token,
+		tokenId,
+		tokenHash
+	};
+}
 async function parseServiceToken(token) {
 	const match = /^(skt_[0-9A-Za-z]+)_([A-Za-z0-9_-]+)$/.exec(token);
 	if (!match) throw new SeekritCryptoError("MALFORMED_TOKEN", "not a valid seekrit service token");
@@ -2720,7 +2751,7 @@ function isCliSessionToken(value) {
 }
 //#endregion
 //#region package.json
-var version = "0.31.0";
+var version = "0.33.0";
 //#endregion
 //#region ../../packages/api-client/src/index.ts
 var SeekritApiError = class extends Error {
@@ -3032,6 +3063,16 @@ var SeekritClient = class {
 	deleteToken(orgId, tokenId) {
 		return this.request("DELETE", `/v1/orgs/${orgId}/tokens/${tokenId}/permanent`);
 	}
+	listHoneyTokens(orgId) {
+		return this.request("GET", `/v1/orgs/${orgId}/honey-tokens`);
+	}
+	createHoneyToken(orgId, input) {
+		return this.request("POST", `/v1/orgs/${orgId}/honey-tokens`, input);
+	}
+	/** Delete a decoy outright — there is no access to revoke first. */
+	deleteHoneyToken(orgId, honeyTokenId) {
+		return this.request("DELETE", `/v1/orgs/${orgId}/honey-tokens/${honeyTokenId}`);
+	}
 	/** Keys the caller can see: all org keys for admins, granted keys otherwise. */
 	listKmsKeys(orgId) {
 		return this.request("GET", `/v1/orgs/${orgId}/kms/keys`);
@@ -5233,6 +5274,52 @@ function registerGroupCommands(program) {
 	});
 }
 //#endregion
+//#region src/honey.ts
+/**
+* Honey tokens — decoy credentials that unlock nothing and alert when used.
+*
+* Minted client-side like real tokens (the API only ever sees a hash), printed
+* once, and then planted wherever a thief would rummage. The CLI is the natural
+* home for this: `seekrit honey-token create` piped straight into the file,
+* commit, config, or CI variable you want watched.
+*/
+function registerHoneyTokenCommands(program) {
+	const honey = program.command("honey-token").description("plant decoy credentials that alert when anyone tries to use them");
+	honey.command("create").description("mint a decoy credential; prints it once").requiredOption("--name <name>", "display name, e.g. legacy-ci-bait").option("--org <slug>").option("--placement <note>", "where you're planting it (echoed in the alert email)").action(async (options) => {
+		const ctx = buildContext();
+		const orgRef = await resolveOrg(ctx, options.org);
+		const created = await createHoneyToken();
+		await ctx.client.createHoneyToken(orgRef.id, {
+			name: options.name,
+			tokenId: created.tokenId,
+			tokenHash: created.tokenHash,
+			placement: options.placement ?? null
+		});
+		console.error("decoy created — save it now, it is not stored. Plant it somewhere a thief would look, NOT anywhere your own tooling reads: a deploy script that tries it by mistake trips the alarm just as loudly. It grants nothing.");
+		console.log(created.token);
+	});
+	honey.command("list").alias("ls").description("list decoy credentials and whether any have been tripped").option("--org <slug>").option("--json", "print the raw API response").action(async (options) => {
+		const ctx = buildContext();
+		const orgRef = await resolveOrg(ctx, options.org);
+		const { honeyTokens } = await ctx.client.listHoneyTokens(orgRef.id);
+		emit(options, { honeyTokens }, () => printTable(honeyTokens, [
+			col("name", (t) => t.name),
+			col("status", (t) => t.tripCount > 0 ? `TRIPPED ${t.tripCount}×` : "untouched"),
+			col("planted in", (t) => t.placement ?? "—"),
+			col("last tripped", (t) => t.lastTrippedAt ?? "never"),
+			col("last source", (t) => t.lastTripIp ?? "—"),
+			col("id", (t) => t.id)
+		], "no decoys planted — create one with `seekrit honey-token create`"));
+	});
+	honey.command("delete <honeyTokenId>").alias("rm").description("delete a decoy (stops it alerting)").option("--org <slug>").option("--yes", "skip the confirmation prompt").action(async (honeyTokenId, options) => {
+		const ctx = buildContext();
+		const orgRef = await resolveOrg(ctx, options.org);
+		await confirmDestructive(options.yes, `Delete ${honeyTokenId}? Wherever you planted it goes back to being unwatched — pull the bait too.`);
+		await ctx.client.deleteHoneyToken(orgRef.id, honeyTokenId);
+		console.error(`${honeyTokenId} deleted`);
+	});
+}
+//#endregion
 //#region src/logsink.ts
 /** Collect repeated `--header Name: value` flags into a map. */
 function collectHeader(value, acc = {}) {
@@ -7307,6 +7394,7 @@ program.command("export").description("print decrypted secrets (dotenv, json, or
 	console.log(formatSecrets(values, options.format));
 });
 registerAccessCommands(program);
+registerHoneyTokenCommands(program);
 const token = program.command("token").description("manage service tokens (CI, docker, agents)");
 token.command("create").description("create a service token (runtime, or --admin for provisioning); prints it once").requiredOption("--name <name>", "display name, e.g. ci-deploy").option("--org <slug>").option("--app <slug>", "application to bind the token to (runtime tokens)").option("--env <slug>", "environment to bind the token to (runtime tokens)").option("--admin", "mint an org-scoped admin token that can provision structure (no env binding required)").option("--allow <group=env>", "also grant an alternate group slice (for `run --with`)", collectKv).option("--no-grant", "skip auto-granting the env + composed group keys").action(async (options) => {
 	const ctx = buildContext();
@@ -7395,7 +7483,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.31.0",
+  "version": "0.33.0",
   "description": "End-to-end encrypted secrets manager CLI — inject decrypted secrets into any command.",
   "type": "module",
   "publishConfig": {
@@ -27,9 +27,9 @@
     "@types/node": "^26.1.0",
     "tsdown": "^0.22.3",
     "vitest": "^4.1.9",
-    "@seekrit/core": "0.0.1",
     "@seekrit/api-client": "0.0.1",
-    "@seekrit/crypto": "0.0.1"
+    "@seekrit/crypto": "0.0.1",
+    "@seekrit/core": "0.0.1"
   },
   "scripts": {
     "build": "tsdown",