@seekrit/mcp 0.4.0 → 0.6.0

package/dist/index.js

@@ -664,7 +664,7 @@ function isServiceToken(value) {
 }
 //#endregion
 //#region ../cli/package.json
-var version$1 = "0.20.0";
+var version$1 = "0.24.0";
 const PROJECT_FILE = "seekrit.json";
 function globalConfigPath() {
 	return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "seekrit", "config.json");
@@ -726,13 +726,16 @@ var SeekritClient = class {
 	baseUrl;
 	auth;
 	fetchImpl;
+	client;
 	constructor(options) {
 		this.baseUrl = options.baseUrl.replace(/\/$/, "");
 		this.auth = options.auth;
 		this.fetchImpl = options.fetch ?? ((...args) => fetch(...args));
+		this.client = options.client;
 	}
 	async request(method, path, body) {
 		const headers = { accept: "application/json" };
+		if (this.client) headers["x-seekrit-client"] = this.client;
 		if (this.auth.type === "bearer") headers.authorization = `Bearer ${this.auth.token}`;
 		else if (this.auth.type === "dynamic") {
 			const token = await this.auth.getToken();
@@ -883,6 +886,19 @@ var SeekritClient = class {
 	deleteSecret(orgId, envId, name) {
 		return this.request("DELETE", `/v1/orgs/${orgId}/envs/${envId}/secrets/${name}`);
 	}
+	/** A secret's append-only history, newest version first. */
+	listSecretVersions(orgId, envId, name, query = {}) {
+		const qs = query.limit === void 0 ? "" : `?limit=${query.limit}`;
+		return this.request("GET", `/v1/orgs/${orgId}/envs/${envId}/secrets/${name}/versions${qs}`);
+	}
+	/**
+	* Roll a secret back to an earlier version. Keyless — the server copies the
+	* ciphertext it already stores, so this appends a new version rather than
+	* rewinding, and needs no DEK on the caller's side.
+	*/
+	restoreSecret(orgId, envId, name, version) {
+		return this.request("POST", `/v1/orgs/${orgId}/envs/${envId}/secrets/${name}/restore`, { version });
+	}
 	/** The calling principal's wrapped DEK for this environment. */
 	getMyEnvKey(orgId, envId) {
 		return this.request("GET", `/v1/orgs/${orgId}/envs/${envId}/key`);
@@ -992,6 +1008,10 @@ var SeekritClient = class {
 	disableKmsKey(orgId, keyId) {
 		return this.request("POST", `/v1/orgs/${orgId}/kms/keys/${keyId}/disable`);
 	}
+	/** Soft-delete a key: it drops out of every listing and read path. */
+	deleteKmsKey(orgId, keyId) {
+		return this.request("DELETE", `/v1/orgs/${orgId}/kms/keys/${keyId}`);
+	}
 	/** The broker's public key — wrap the admin credential to it before registering a target. */
 	getLeaseBrokerKey(orgId) {
 		return this.request("GET", `/v1/orgs/${orgId}/leases/broker-key`);
@@ -1108,6 +1128,8 @@ function promptHidden(question) {
 }
 //#endregion
 //#region ../cli/src/context.ts
+/** Sent as `x-seekrit-client` so the API attributes usage to the CLI (analytics). */
+const CLI_CLIENT = `cli/${version$1}`;
 /**
 * Build the client context from configured credentials, or return null when
 * none are set. `seekrit run` uses this to degrade to a plain launcher instead
@@ -1138,7 +1160,8 @@ function tryBuildContext(dotenvVars = {}) {
 	return {
 		client: new SeekritClient({
 			baseUrl: apiUrl,
-			auth
+			auth,
+			client: CLI_CLIENT
 		}),
 		auth
 	};
@@ -1349,7 +1372,8 @@ async function mintAdminToken(apiUrl, creds) {
 			type: "m2m",
 			clientId: creds.clientId,
 			clientSecret: creds.clientSecret
-		}
+		},
+		client: `cli/${version$1}`
 	});
 	const { orgs } = await client.listOrgs();
 	const org = orgs[0];
@@ -1418,14 +1442,23 @@ function parseDotenv(content) {
 	}
 	return out;
 }
-//#endregion
-//#region ../cli/src/secrets.ts
 /** Fetch + decrypt every secret in a single environment. */
 async function fetchDecryptedSecrets(ctx, orgId, envId) {
 	const [dek, { secrets }] = await Promise.all([getDek(ctx, orgId, envId), ctx.client.listSecrets(orgId, envId)]);
 	const entries = await Promise.all(secrets.map(async (secret) => [secret.name, await decryptSecret(dek, secret.ciphertext, secretAad(envId, secret.name))]));
 	return Object.fromEntries(entries);
 }
+/**
+* Decrypt one historical version of a secret. Ciphertext is bound to
+* `(envId, name)` as AAD and neither changes across versions, so an old blob
+* opens with the environment's current data key — no special handling needed.
+*/
+async function fetchDecryptedVersion(ctx, orgId, envId, name, version) {
+	const [dek, { versions }] = await Promise.all([getDek(ctx, orgId, envId), ctx.client.listSecretVersions(orgId, envId, name, { limit: 200 })]);
+	const row = versions.find((v) => v.version === version);
+	if (!row) fail(`${name} has no version ${version} in its ${versions.length} newest versions`);
+	return decryptSecret(dek, row.ciphertext, secretAad(envId, name));
+}
 async function encryptAndSetSecret(ctx, orgId, envId, name, value) {
 	const ciphertext = await encryptSecret(await getDek(ctx, orgId, envId), value, secretAad(envId, name));
 	await ctx.client.setSecret(orgId, envId, name, ciphertext);
@@ -1505,6 +1538,76 @@ function errText(err) {
 		isError: 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
+* with zero context in a few lines.
+*/
+function serverInstructions() {
+	return [
+		"seekrit is a zero-knowledge secrets manager. This is the LOCAL CRYPTO plane —",
+		"it runs on this machine, next to your key, so it's the one server that can",
+		"actually read or write a secret VALUE (everything else can only see structure).",
+		"",
+		"Auth comes from SEEKRIT_TOKEN (a skt_… token), SEEKRIT_CLIENT_ID +",
+		"SEEKRIT_CLIENT_SECRET (machine credentials — an admin token is minted and",
+		"cached automatically on first use), or the config saved by `seekrit login`.",
+		"Decrypting under a user session (not a token) additionally needs",
+		"SEEKRIT_PASSPHRASE set in this server's env — there's no TTY to prompt on.",
+		"",
+		"Model: org → apps/groups → environments → secrets. Call `whoami` first, then",
+		"`get_started` for the recommended end-to-end recipe. Prefer `run_command` over",
+		"`get_secret reveal:true` — it injects secrets into a subprocess so plaintext",
+		"never enters your context or the transcript."
+	].join("\n");
+}
+/** The `get_started` tool body: the recommended first-project flow end to end. */
+function getStartedText() {
+	return [
+		"# Standing up a project with seekrit (agent, end to end)",
+		"",
+		"This server is the crypto plane — every step below runs locally, next to your",
+		"key, so secret values never leave this machine.",
+		"",
+		"## 1. Confirm identity",
+		"`whoami` — see who you're authenticated as and which orgs you can reach. If it",
+		"fails, check SEEKRIT_TOKEN / SEEKRIT_CLIENT_ID+SEEKRIT_CLIENT_SECRET / saved",
+		"login in this server's env.",
+		"",
+		"## 2. Provision structure",
+		"- `create_org` (user session only — a service token can't own one) if you",
+		"  don't have one yet, otherwise skip to the next step.",
+		"- `create_app` — an application to hold environments.",
+		"- `create_env` — generates the data key on this machine and grants it to you.",
+		"- `create_group` + `compose_group` (optional) — a reusable secret bag layered",
+		"  under one or more app environments.",
+		"",
+		"## 3. Store secrets",
+		"- `set_secret` — encrypts a value locally and stores the ciphertext.",
+		"- `list_secrets` — confirm names + versions (never returns values).",
+		"- `list_secret_versions` + `restore_secret` — undo a bad write by rolling",
+		"  back to an earlier version (keyless, and history is append-only).",
+		"",
+		"## 4. Use secrets without exposing them",
+		"- `run_command -- <cmd>` — inject secrets into a subprocess; prefer this.",
+		"- `export_env` — materialize a `.env` file when a tool needs one on disk.",
+		"- `get_secret reveal:true` — only when the value itself is what's needed.",
+		"",
+		"## 5. Propagate access",
+		"- `create_token` bound to an app+env — a runtime credential for CI/another",
+		"  agent to decrypt with (pass `admin:true` instead for a provisioning token).",
+		"- `grant_env` — give another member or token access to an env's data key.",
+		"- `configure_project` — link a directory to an org/app (writes seekrit.json)",
+		"  so a bound token can infer its target without flags.",
+		"",
+		"## 6. Verify",
+		"`audit` — every write, grant, and revocation is recorded; read it back.",
+		"",
+		"Also available: `kms_*` (client-side managed encrypt/sign keys) and",
+		"`create_pg_lease`/`create_mysql_lease` (short-lived database credentials whose",
+		"password is generated here and never stored anywhere in plaintext)."
+	].join("\n");
+}
 /** Build the client context or throw a friendly, agent-readable error. */
 function getCtx() {
 	const ctx = tryBuildContext();
@@ -1600,7 +1703,7 @@ async function runMcpServer(options = {}) {
 	const server = new McpServer({
 		name: "seekrit",
 		version: options.version ?? version$1
-	});
+	}, { instructions: serverInstructions() });
 	/** Register a tool whose handler returns data (serialized) or throws (→ isError). */
 	const tool = (name, description, shape, handler) => {
 		server.registerTool(name, {
@@ -1614,6 +1717,15 @@ async function runMcpServer(options = {}) {
 			}
 		}));
 	};
+	server.registerTool("get_started", {
+		description: "The recommended first-project recipe: provision structure, store secrets, and use them without exposing values. Call this before doing anything else.",
+		inputSchema: {},
+		annotations: {
+			title: "get_started",
+			readOnlyHint: true,
+			openWorldHint: false
+		}
+	}, async () => jsonText(getStartedText()));
 	tool("whoami", "Show the authenticated identity, its role, and accessible orgs.", {}, async () => {
 		const ctx = getCtx();
 		if (isTokenAuth(ctx) && ctx.auth.type === "bearer") {
@@ -1987,10 +2099,11 @@ 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).", {
+	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). Pass `version` to read an earlier version instead of the current one.", {
 		...targetShape,
 		name: z.string(),
-		reveal: z.boolean().optional()
+		reveal: z.boolean().optional(),
+		version: z.number().int().positive().optional().describe("an earlier version from list_secret_versions (default: current)")
 	}, async (o) => {
 		const ctx = getCtx();
 		const { orgId, envId } = await resolveTargetEnv(ctx, o);
@@ -2000,11 +2113,20 @@ async function runMcpServer(options = {}) {
 			if (!row) throw new Error(`no secret named ${o.name}`);
 			return {
 				name: row.name,
-				version: row.version,
+				version: o.version ?? row.version,
 				revealed: false
 			};
 		}
 		ensureDecryptable(ctx);
+		if (o.version !== void 0) {
+			const value = await fetchDecryptedVersion(ctx, orgId, envId, o.name, o.version);
+			return {
+				name: o.name,
+				version: o.version,
+				value,
+				revealed: true
+			};
+		}
 		const values = await fetchDecryptedSecrets(ctx, orgId, envId);
 		if (!(o.name in values)) throw new Error(`no secret named ${o.name}`);
 		return {
@@ -2013,6 +2135,39 @@ 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.", {
+		...targetShape,
+		name: z.string(),
+		limit: z.number().int().min(1).max(200).optional().describe("default 20")
+	}, async (o) => {
+		const ctx = getCtx();
+		const { orgId, envId } = await resolveTargetEnv(ctx, o);
+		const { versions, currentVersion } = await ctx.client.listSecretVersions(orgId, envId, o.name, { limit: o.limit ?? 20 });
+		return {
+			currentVersion,
+			versions: versions.map((v) => ({
+				version: v.version,
+				createdAt: v.createdAt,
+				createdBy: `${v.createdByType}:${v.createdById}`,
+				restoredFromVersion: v.restoredFromVersion
+			}))
+		};
+	});
+	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.", {
+		...targetShape,
+		name: z.string(),
+		version: z.number().int().positive()
+	}, async (o) => {
+		const ctx = getCtx();
+		const { orgId, envId } = await resolveTargetEnv(ctx, o);
+		const { secret, restoredFrom } = await ctx.client.restoreSecret(orgId, envId, o.name, o.version);
+		return {
+			ok: true,
+			name: o.name,
+			restoredFrom,
+			version: secret.version
+		};
+	});
 	tool("delete_secret", "Delete a secret from an environment.", {
 		...targetShape,
 		name: z.string()
@@ -2301,7 +2456,7 @@ async function runMcpServer(options = {}) {
 /**
 * `@seekrit/mcp` — a standalone, `npx`-able entrypoint for seekrit's MCP server.
 *
-* This is a thin wrapper: the server itself (all 27 tools, the crypto plane of
+* This is a thin wrapper: the server itself (every tool, the crypto plane of
 * the two-server design) lives in `@seekrit/cli` and is shared with the
 * `seekrit mcp` subcommand — this package just publishes it as its own binary so
 * an agent can run it with zero prior install:
@@ -2314,7 +2469,7 @@ async function runMcpServer(options = {}) {
 * `seekrit mcp`. tsdown bundles the shared server source in at build time, so the
 * published package is self-contained and needs no `@seekrit/cli` install.
 */
-runMcpServer({ version: "0.4.0" }).catch((err) => {
+runMcpServer({ version: "0.6.0" }).catch((err) => {
 	const message = err instanceof Error ? err.message : String(err);
 	process.stderr.write(`seekrit-mcp: fatal: ${message}\n`);
 	process.exit(1);

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@seekrit/mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "npx-able MCP server for seekrit — let Claude Code and other MCP clients provision, manage, and inject end-to-end encrypted secrets.",
+  "mcpName": "dev.seekrit/mcp",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -22,7 +23,7 @@
   "devDependencies": {
     "@types/node": "^26.1.0",
     "tsdown": "^0.22.3",
-    "@seekrit/cli": "0.20.0"
+    "@seekrit/cli": "0.24.0"
   },
   "scripts": {
     "build": "tsdown",