@seekrit/cli 0.23.4 → 0.25.0

package/README.md

@@ -58,7 +58,7 @@ Run `seekrit <command> --help` for full flags. The
 | `init --org --app --env` | Link this directory to an environment (`seekrit.json`). |
 | `org create` / `app create` / `env create` | Create organizations, apps, and environments. |
 | `secrets list` | List secret names (never values). |
-| `secrets get <name>` | Decrypt and print one secret value. |
+| `secrets get <name> [--raw]` | Decrypt and print one secret value (`--raw` skips `${OTHER_SECRET}` expansion). |
 | `secrets set <name> [value]` | Encrypt and store a secret (reads stdin if value is omitted or `-`). |
 | `secrets rm <name>` | Delete a secret. |
 | `run <command…>` | Run a command with decrypted secrets in its environment. |
@@ -71,6 +71,11 @@ Run `seekrit <command> --help` for full flags. The
 (e.g. `seekrit run -- node app.js --port 3000`). `secrets set NAME -` reads the
 value from stdin, so you can pipe: `printf '%s' "$VALUE" | seekrit secrets set NAME -`.
 
+A value may reference another secret as `${OTHER_SECRET}`: stored literally,
+expanded on read against the merged environment (`--no-interpolate` on
+`run`/`export` opts out). See the
+[references guide](https://seekrit.dev/docs/guides/references).
+
 ## Service tokens (CI, Docker, agents)
 
 A service token carries its own private key in the token string; the server

package/dist/index.js

@@ -143,6 +143,152 @@ const SUBSCRIPTION_STATUSES = [
 	"canceled",
 	"paused"
 ];
+//#endregion
+//#region ../../packages/core/src/interpolate.ts
+/**
+* Secret references: `${OTHER_SECRET}` inside a secret value.
+*
+* This is the **canonical specification** of the expansion. It is pure string
+* work over an already-decrypted variable set, so it runs wherever plaintext
+* legitimately exists — the CLI, the browser, the language SDKs, and the Rust
+* clients (`crates/seekrit-core/src/interpolate.rs` mirrors it, pinned by the
+* shared golden fixture in `apps/run/testdata/vectors.json`).
+*
+* Expansion happens at **read time**, on the client, never on write and never
+* on the server: the API only ever holds the ciphertext of the literal
+* `${OTHER_SECRET}` text, so referencing costs nothing against the
+* zero-knowledge invariant. It also means a reference stays live — rotating
+* `DB_PASSWORD` updates every value that references it, with no re-encryption.
+*
+* The rules, in full:
+*
+* - `${NAME}` is replaced with the value of `NAME` in the *same fully-merged
+*   set* — after group → app-env → `.env` layering, so a reference always sees
+*   the value that layer precedence actually selected.
+* - `NAME` must be a valid secret name (`[A-Za-z_][A-Za-z0-9_]*`, matching
+*   `secretNameSchema`). Anything else — `${1}`, `${FOO:-bar}`, `${a.b}` — is
+*   left exactly as written, so shell and CI template syntax passes through
+*   untouched.
+* - A reference to a name that is not in the set is **left literal** and
+*   reported in {@link InterpolationResult.unresolved}. Erroring would mean a
+*   stored value that happens to contain `${GITHUB_SHA}` could break a whole
+*   environment's resolve; leaving it alone is the safe default, and the report
+*   is there to surface typos (`seekrit run --explain` prints it).
+* - Expansion is recursive: a referenced value may itself contain references.
+* - `$${NAME}` is an escape producing the literal text `${NAME}`. A `$$` not
+*   followed by `{` is ordinary text (passwords full of `$` are safe).
+* - A reference **cycle** throws {@link InterpolationError}. Unlike an unknown
+*   name, a cycle can only be a configuration mistake — every name in it
+*   exists — and there is no value that could be correct to emit.
+*
+* `process.env` is deliberately *not* a reference source: `seekrit run` layers
+* the live shell on top of the resolved set afterwards, and letting a stored
+* secret pull in arbitrary host environment variables would be a surprising
+* (and machine-dependent) way to change a secret's value.
+*/
+/** A reference name — the same grammar as `secretNameSchema`. */
+const REFERENCE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+* Cap on a single expanded value. Nested references can multiply length
+* (`A=${B}${B}`, `B=${C}${C}`, …), which memoization makes fast but does not
+* make small. A megabyte is far above any real secret and far below anything
+* that would exhaust a container.
+*/
+const MAX_EXPANDED_LENGTH = 1048576;
+/**
+* Split a value into literal runs and references — the single tokenizer every
+* rule above is expressed in terms of, so expansion and inspection can never
+* disagree about what counts as a reference.
+*/
+function* scan(text) {
+	let i = 0;
+	while (i < text.length) {
+		const dollar = text.indexOf("$", i);
+		if (dollar === -1) {
+			yield { literal: text.slice(i) };
+			return;
+		}
+		if (dollar > i) yield { literal: text.slice(i, dollar) };
+		if (text[dollar + 1] === "$" && text[dollar + 2] === "{") {
+			yield { literal: "${" };
+			i = dollar + 3;
+			continue;
+		}
+		const close = text[dollar + 1] === "{" ? text.indexOf("}", dollar + 2) : -1;
+		const reference = close === -1 ? null : text.slice(dollar + 2, close);
+		if (reference !== null && REFERENCE_NAME.test(reference)) {
+			yield {
+				reference,
+				raw: text.slice(dollar, close + 1)
+			};
+			i = close + 1;
+			continue;
+		}
+		yield { literal: "$" };
+		i = dollar + 1;
+	}
+}
+var InterpolationError = class extends Error {
+	code;
+	/**
+	* For `cycle`, the reference chain that closed on itself, starting and ending
+	* on the same name (`["A", "B", "A"]`). For `too_large`, the single name
+	* whose expansion blew the cap.
+	*/
+	chain;
+	constructor(code, message, chain) {
+		super(message);
+		this.name = "InterpolationError";
+		this.code = code;
+		this.chain = chain;
+	}
+};
+/**
+* Expand `${NAME}` references throughout a decrypted variable set.
+*
+* Pure: the input is never mutated. Throws {@link InterpolationError} on a
+* reference cycle (see the module comment for the complete rule set).
+*/
+function interpolateSecrets(values) {
+	const resolved = /* @__PURE__ */ new Map();
+	const unresolved = /* @__PURE__ */ new Set();
+	const expanded = [];
+	/** The chain currently being expanded — the cycle detector. */
+	const stack = [];
+	/** Expand one present name's value, memoized so each is expanded once. */
+	function resolve(name) {
+		const cached = resolved.get(name);
+		if (cached !== void 0) return cached;
+		const cycleAt = stack.indexOf(name);
+		if (cycleAt !== -1) {
+			const chain = [...stack.slice(cycleAt), name];
+			throw new InterpolationError("cycle", `secret reference cycle: ${chain.join(" → ")}`, chain);
+		}
+		stack.push(name);
+		let out = "";
+		for (const segment of scan(values[name])) if ("literal" in segment) out += segment.literal;
+		else if (Object.hasOwn(values, segment.reference)) out += resolve(segment.reference);
+		else {
+			unresolved.add(segment.reference);
+			out += segment.raw;
+		}
+		stack.pop();
+		if (out.length > MAX_EXPANDED_LENGTH) throw new InterpolationError("too_large", `${name} expands to more than ${MAX_EXPANDED_LENGTH} bytes — check its references`, [name]);
+		resolved.set(name, out);
+		return out;
+	}
+	const result = {};
+	for (const name of Object.keys(values)) {
+		const value = resolve(name);
+		result[name] = value;
+		if (value !== values[name]) expanded.push(name);
+	}
+	return {
+		values: result,
+		expanded,
+		unresolved: [...unresolved].sort()
+	};
+}
 z.enum([
 	"postgres",
 	"mysql",
@@ -708,6 +854,8 @@ z.object({
 z.object({ 
 /** Opaque versioned ciphertext blob from @seekrit/crypto. */
 ciphertext: z.string().min(1).max(65536) });
+z.object({ version: z.number().int().positive() });
+z.object({ limit: z.coerce.number().int().min(1).max(200).default(50) });
 z.object({
 	publicKeyJwk: z.string().min(1),
 	/**
@@ -1152,7 +1300,7 @@ function encryptAad(ref, context) {
 function dataKeyAad(keyId, version) {
 	return `${keyId}/${version}`;
 }
-function parseVersion(versionStr) {
+function parseVersion$1(versionStr) {
 	const version = Number(versionStr);
 	if (!Number.isInteger(version) || version < 1) throw new SeekritCryptoError("MALFORMED_BLOB", "invalid key version in KMS blob");
 	return version;
@@ -1164,7 +1312,7 @@ function kmsBlobKeyRef(blob) {
 	const [keyId, versionStr] = splitBlob(blob, prefix, 4);
 	return {
 		keyId,
-		version: parseVersion(versionStr)
+		version: parseVersion$1(versionStr)
 	};
 }
 /** Encrypt a value under a managed key. `context` (bound as AAD) defaults to empty. */
@@ -1193,7 +1341,7 @@ async function kmsDecrypt(material, blob, context = "") {
 	const [keyId, versionStr, ivB64, ctB64] = splitBlob(blob, ENCRYPT_PREFIX, 4);
 	const ref = {
 		keyId,
-		version: parseVersion(versionStr)
+		version: parseVersion$1(versionStr)
 	};
 	const key = await importAesKey(material, "decrypt");
 	try {
@@ -1976,7 +2124,7 @@ function isServiceToken(value) {
 }
 //#endregion
 //#region package.json
-var version = "0.23.4";
+var version = "0.25.0";
 //#endregion
 //#region ../../packages/api-client/src/index.ts
 var SeekritApiError = class extends Error {
@@ -2153,6 +2301,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`);
@@ -4080,13 +4241,52 @@ function collect$1(value, acc) {
 	acc.push(value);
 	return acc;
 }
-//#endregion
-//#region src/secrets.ts
-/** Fetch + decrypt every secret in a single environment. */
-async function fetchDecryptedSecrets(ctx, orgId, envId) {
+/**
+* Fetch + decrypt every secret in a single environment.
+*
+* `${OTHER_SECRET}` references are expanded (see `@seekrit/core`'s
+* `interpolate`) unless `raw` is set. Only this environment's own secrets are in
+* scope here — a reference to a secret inherited from a composed group is left
+* literal, because the group layers aren't fetched. `materializeEnv` is the
+* fully-layered view.
+*/
+async function fetchDecryptedSecrets(ctx, orgId, envId, opts = {}) {
 	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);
+	return interpolateValues(Object.fromEntries(entries), !opts.raw).values;
+}
+/**
+* Expand `${OTHER_SECRET}` references in a merged variable set. A cycle becomes
+* the CLI's standard fatal exit — it is a config bug with no correct value to
+* emit. Pass `enabled: false` (`--no-interpolate`) to hand the set back as-is.
+*/
+function interpolateValues(values, enabled = true) {
+	if (!enabled) return {
+		values,
+		interpolated: [],
+		unresolvedRefs: []
+	};
+	try {
+		const { values: expandedValues, expanded, unresolved } = interpolateSecrets(values);
+		return {
+			values: expandedValues,
+			interpolated: expanded,
+			unresolvedRefs: unresolved
+		};
+	} catch (err) {
+		return fail(err instanceof Error ? err.message : String(err));
+	}
+}
+/**
+* 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));
@@ -4119,6 +4319,9 @@ async function importSecrets(ctx, orgId, envId, entries) {
 * Each layer's DEK is unwrapped once with the principal's private key and its
 * ciphertext decrypted locally. `process.env` is NOT applied here — callers
 * that spawn a process layer it on top so the live shell always wins.
+*
+* `${OTHER_SECRET}` references are expanded last, against the merged set, so a
+* reference always resolves to whichever layer won the name.
 */
 async function materializeEnv(ctx, opts) {
 	const query = {};
@@ -4139,11 +4342,12 @@ async function materializeEnv(ctx, opts) {
 			provenance[secret.name] = label;
 		}
 	}
+	const loadedEnvFiles = overlayEnvFiles(values, provenance, opts.envFiles);
 	return {
-		values,
+		...interpolateValues(values, opts.interpolate !== false),
 		provenance,
 		scope,
-		loadedEnvFiles: overlayEnvFiles(values, provenance, opts.envFiles)
+		loadedEnvFiles
 	};
 }
 /**
@@ -4164,11 +4368,21 @@ function overlayEnvFiles(values, provenance, envFiles) {
 	}
 	return loaded;
 }
-/** Print a name → source table to stderr (never the secret values). */
-function printExplain(provenance) {
+/**
+* Print a name → source table to stderr (never the secret values). Names whose
+* value had references expanded are marked, and dangling references are called
+* out afterwards — a typo'd `${NAME}` is otherwise invisible, since it is
+* deliberately passed through as literal text.
+*/
+function printExplain(provenance, refs = {}) {
+	const interpolated = new Set(refs.interpolated ?? []);
 	const names = Object.keys(provenance).sort();
 	const width = names.reduce((w, n) => Math.max(w, n.length), 0);
-	for (const name of names) process.stderr.write(`${name.padEnd(width)}  ${provenance[name]}\n`);
+	for (const name of names) {
+		const marker = interpolated.has(name) ? "  (interpolated)" : "";
+		process.stderr.write(`${name.padEnd(width)}  ${provenance[name]}${marker}\n`);
+	}
+	if (refs.unresolved?.length) process.stderr.write(`\nunresolved reference(s), left as literal text: ${refs.unresolved.join(", ")}\n`);
 }
 //#endregion
 //#region src/ssh.ts
@@ -4480,6 +4694,12 @@ group.command("env").description("manage a group’s environments (per-slug valu
 	});
 	console.error(`created ${groupRef.slug}@${created.environment.slug} (${created.environment.id})`);
 });
+/** Parse a positive integer flag/argument (version numbers, page sizes). */
+function parseVersion(raw) {
+	const n = Number(raw);
+	if (!Number.isInteger(n) || n < 1) fail(`expected a positive whole number, got "${raw}"`);
+	return n;
+}
 /** Attach the environment-selection flags shared by every `secrets` command. */
 function withTarget(cmd) {
 	return cmd.option("--org <slug>", "organization slug").option("--app <slug>", "application slug (defaults to seekrit.json)").option("--group <slug>", "target a group environment instead of an app").requiredOption("--env <slug>", "environment slug");
@@ -4491,10 +4711,12 @@ withTarget(secrets.command("list").description("list secret names (no values)"))
 	const { secrets: rows } = await ctx.client.listSecrets(orgId, envId);
 	for (const row of rows) console.log(`${row.name}\tv${row.version}\t${row.updatedAt}`);
 });
-withTarget(secrets.command("get <name>").description("decrypt and print one secret value")).action(async (name, options) => {
+withTarget(secrets.command("get <name>").description("decrypt and print one secret value").option("--raw", "print the stored value without expanding ${OTHER_SECRET} references").option("--version <n>", "print an earlier version instead of the current one")).action(async (name, options) => {
 	const ctx = buildContext();
 	const { orgId, envId } = await resolveEnvTarget(ctx, options);
-	const value = (await fetchDecryptedSecrets(ctx, orgId, envId))[name];
+	let value;
+	if (options.version === void 0) value = (await fetchDecryptedSecrets(ctx, orgId, envId, { raw: options.raw }))[name];
+	else value = await fetchDecryptedVersion(ctx, orgId, envId, name, parseVersion(options.version));
 	if (value === void 0) fail(`no secret named ${name}`);
 	process.stdout.write(value);
 	if (process.stdout.isTTY) process.stdout.write("\n");
@@ -4530,6 +4752,22 @@ withTarget(secrets.command("import [file]").description("bulk-import secrets fro
 	const { created, updated } = await importSecrets(ctx, orgId, envId, entries);
 	console.error(`imported ${created.length + updated.length} secret(s) into ${label} (${created.length} new, ${updated.length} updated)`);
 });
+withTarget(secrets.command("history <name>").description("list a secret's versions (metadata only — no values)").option("--limit <n>", `how many versions to show (max 200)`, "20")).action(async (name, options) => {
+	const ctx = buildContext();
+	const { orgId, envId } = await resolveEnvTarget(ctx, options);
+	const { versions, currentVersion } = await ctx.client.listSecretVersions(orgId, envId, name, { limit: parseVersion(options.limit) });
+	for (const v of versions) {
+		const marks = [v.version === currentVersion ? "current" : null, v.restoredFromVersion === null ? null : `restored from v${v.restoredFromVersion}`].filter(Boolean);
+		const note = marks.length > 0 ? `\t${marks.join(", ")}` : "";
+		console.log(`v${v.version}\t${v.createdAt}\t${v.createdByType}:${v.createdById}${note}`);
+	}
+});
+withTarget(secrets.command("restore <name> <version>").description("roll a secret back to an earlier version (stored as a new version)")).action(async (name, version, options) => {
+	const ctx = buildContext();
+	const { orgId, envId } = await resolveEnvTarget(ctx, options);
+	const { secret, restoredFrom } = await ctx.client.restoreSecret(orgId, envId, name, parseVersion(version));
+	console.error(`${name} restored from v${restoredFrom} — now v${secret.version}`);
+});
 withTarget(secrets.command("rm <name>").description("delete a secret")).action(async (name, options) => {
 	const ctx = buildContext();
 	const { orgId, envId } = await resolveEnvTarget(ctx, options);
@@ -4543,7 +4781,8 @@ async function materialize(ctx, options) {
 	return materializeEnv(ctx, {
 		envId,
 		with: options.with,
-		envFiles: options.envFile ?? [".env"]
+		envFiles: options.envFile ?? [".env"],
+		interpolate: options.interpolate
 	});
 }
 /**
@@ -4569,7 +4808,7 @@ async function materializeForRun(options) {
 		const provenance = {};
 		overlayEnvFiles(values, provenance, envFiles);
 		return {
-			values,
+			...interpolateValues(values, options.interpolate !== false),
 			provenance
 		};
 	}
@@ -4684,13 +4923,16 @@ 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("--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)").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("--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) => {
 	const [cmd, ...args] = commandParts;
 	if (!cmd) fail("no command given");
-	const { values, provenance } = await materializeForRun(options);
+	const { values, provenance, interpolated, unresolvedRefs } = await materializeForRun(options);
 	if (options.explain) {
 		for (const name of Object.keys(values)) if (process.env[name] !== void 0 && process.env[name] !== values[name]) provenance[name] = "env";
-		printExplain(provenance);
+		printExplain(provenance, {
+			interpolated,
+			unresolved: unresolvedRefs
+		});
 	}
 	const posix = process.platform !== "win32";
 	const child = spawn(cmd, args, {
@@ -4733,14 +4975,17 @@ 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("--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("--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("--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) => {
 	if (![
 		"dotenv",
 		"json",
 		"shell"
 	].includes(options.format)) fail("format must be dotenv, json, or shell");
-	const { values, provenance } = await materialize(buildContext(), options);
-	if (options.explain) printExplain(provenance);
+	const { values, provenance, interpolated, unresolvedRefs } = await materialize(buildContext(), options);
+	if (options.explain) printExplain(provenance, {
+		interpolated,
+		unresolved: unresolvedRefs
+	});
 	console.log(formatSecrets(values, options.format));
 });
 program.command("grant").description("give a member or service token access to an environment's key").option("--org <slug>").option("--app <slug>").option("--group <slug>", "grant a group environment instead of an app").requiredOption("--env <slug>").option("--user <email>", "grant to an org member by email").option("--token <tokenId>", "grant to a service token by id (skt_…)").action(async (options) => {
@@ -4861,7 +5106,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-CbNXG37n.js");
+	const { runMcpServer } = await import("./mcp-COWsshZZ.js");
 	await runMcpServer();
 });
 program.command("audit").description("show the org audit trail").option("--org <slug>").option("--limit <n>", "entries to fetch", "50").action(async (options) => {
@@ -4875,4 +5120,4 @@ program.parseAsync(argv).catch((err) => {
 	fail(err instanceof Error ? err.message : String(err));
 });
 //#endregion
-export { generateDataKey as A, importSigningKey as C, verifyMessage as D, signatureKeyRef as E, wrapDek as F, generateDek as I, toBase64 as L, kmsBlobKeyRef as M, kmsDecrypt as N, generatePostgresCredential as O, kmsEncrypt as P, generateSigningKeyMaterial as S, signMessage as T, writeProjectConfig as _, kmsCallerIdentity as a, isServiceToken as b, kmsResolveRecipient as c, resolveGroup as d, resolveOrg as f, setFailThrows as g, tryBuildContext as h, ensureM2mAdminToken as i, generateEncryptKeyMaterial as j, generateMysqlCredential as k, resolveAppEnv as l, isTokenAuth as m, fetchDecryptedSecrets as n, kmsRecoverMaterial as o, getDek as p, materializeEnv as r, kmsResolveKey as s, encryptAndSetSecret as t, resolveEnvTarget as u, version as v, importVerifyingKey as w, parseServiceToken as x, createServiceToken as y };
+export { generateMysqlCredential as A, generateSigningKeyMaterial as C, signatureKeyRef as D, signMessage as E, kmsEncrypt as F, wrapDek as I, generateDek as L, generateEncryptKeyMaterial as M, kmsBlobKeyRef as N, verifyMessage as O, kmsDecrypt as P, toBase64 as R, parseServiceToken as S, importVerifyingKey as T, setFailThrows as _, ensureM2mAdminToken as a, createServiceToken as b, kmsResolveKey as c, resolveEnvTarget as d, resolveGroup as f, tryBuildContext as g, isTokenAuth as h, materializeEnv as i, generateDataKey as j, generatePostgresCredential as k, kmsResolveRecipient as l, getDek as m, fetchDecryptedSecrets as n, kmsCallerIdentity as o, resolveOrg as p, fetchDecryptedVersion as r, kmsRecoverMaterial as s, encryptAndSetSecret as t, resolveAppEnv as u, writeProjectConfig as v, importSigningKey as w, isServiceToken as x, version as y };

package/dist/{mcp-CbNXG37n.js → mcp-COWsshZZ.js}

@@ -1,4 +1,4 @@
-import { A as generateDataKey, C as importSigningKey, D as verifyMessage, E as signatureKeyRef, F as wrapDek, I as generateDek, L as toBase64, M as kmsBlobKeyRef, N as kmsDecrypt, O as generatePostgresCredential, P as kmsEncrypt, S as generateSigningKeyMaterial, T as signMessage, _ as writeProjectConfig, a as kmsCallerIdentity, b as isServiceToken, c as kmsResolveRecipient, d as resolveGroup, f as resolveOrg, g as setFailThrows, h as tryBuildContext, i as ensureM2mAdminToken, j as generateEncryptKeyMaterial, k as generateMysqlCredential, l as resolveAppEnv, m as isTokenAuth, n as fetchDecryptedSecrets, o as kmsRecoverMaterial, p as getDek, r as materializeEnv, s as kmsResolveKey, t as encryptAndSetSecret, u as resolveEnvTarget, v as version, w as importVerifyingKey, x as parseServiceToken, y as createServiceToken } from "./index.js";
+import { A as generateMysqlCredential, C as generateSigningKeyMaterial, D as signatureKeyRef, E as signMessage, F as kmsEncrypt, I as wrapDek, L as generateDek, M as generateEncryptKeyMaterial, N as kmsBlobKeyRef, O as verifyMessage, P as kmsDecrypt, R as toBase64, S as parseServiceToken, T as importVerifyingKey, _ as setFailThrows, a as ensureM2mAdminToken, b as createServiceToken, c as kmsResolveKey, d as resolveEnvTarget, f as resolveGroup, g as tryBuildContext, h as isTokenAuth, i as materializeEnv, j as generateDataKey, k as generatePostgresCredential, l as kmsResolveRecipient, m as getDek, n as fetchDecryptedSecrets, o as kmsCallerIdentity, p as resolveOrg, r as fetchDecryptedVersion, s as kmsRecoverMaterial, t as encryptAndSetSecret, u as resolveAppEnv, v as writeProjectConfig, w as importSigningKey, x as isServiceToken, y as version } from "./index.js";
 import { spawn } from "node:child_process";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -73,6 +73,8 @@ function getStartedText() {
 		"## 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.",
@@ -571,7 +573,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.", {
+	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.", {
 		...targetShape,
 		name: z.string(),
 		value: z.string()
@@ -585,10 +587,12 @@ 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). 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).", {
 		...targetShape,
 		name: z.string(),
-		reveal: z.boolean().optional()
+		reveal: z.boolean().optional(),
+		raw: z.boolean().optional().describe("skip ${OTHER_SECRET} expansion (with reveal)"),
+		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);
@@ -598,12 +602,21 @@ 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);
-		const values = await fetchDecryptedSecrets(ctx, orgId, envId);
+		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, { raw: o.raw });
 		if (!(o.name in values)) throw new Error(`no secret named ${o.name}`);
 		return {
 			name: o.name,
@@ -611,6 +624,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()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seekrit/cli",
-  "version": "0.23.4",
+  "version": "0.25.0",
   "description": "End-to-end encrypted secrets manager CLI — inject decrypted secrets into any command.",
   "type": "module",
   "publishConfig": {
@@ -27,8 +27,8 @@
     "@types/node": "^26.1.0",
     "tsdown": "^0.22.3",
     "@seekrit/api-client": "0.0.1",
-    "@seekrit/core": "0.0.1",
-    "@seekrit/crypto": "0.0.1"
+    "@seekrit/crypto": "0.0.1",
+    "@seekrit/core": "0.0.1"
   },
   "scripts": {
     "build": "tsdown",