@seekrit/cli 0.24.0 → 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",
@@ -1978,7 +2124,7 @@ function isServiceToken(value) {
 }
 //#endregion
 //#region package.json
-var version = "0.24.0";
+var version = "0.25.0";
 //#endregion
 //#region ../../packages/api-client/src/index.ts
 var SeekritApiError = class extends Error {
@@ -4095,11 +4241,41 @@ function collect$1(value, acc) {
 	acc.push(value);
 	return acc;
 }
-/** 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
@@ -4143,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 = {};
@@ -4163,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
 	};
 }
 /**
@@ -4188,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
@@ -4521,11 +4711,11 @@ 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").option("--version <n>", "print an earlier version instead of the current one")).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);
 	let value;
-	if (options.version === void 0) value = (await fetchDecryptedSecrets(ctx, orgId, envId))[name];
+	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);
@@ -4591,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
 	});
 }
 /**
@@ -4617,7 +4808,7 @@ async function materializeForRun(options) {
 		const provenance = {};
 		overlayEnvFiles(values, provenance, envFiles);
 		return {
-			values,
+			...interpolateValues(values, options.interpolate !== false),
 			provenance
 		};
 	}
@@ -4732,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, {
@@ -4781,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) => {
@@ -4909,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-t-sJ_SvE.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) => {

package/dist/{mcp-t-sJ_SvE.js → mcp-COWsshZZ.js}

@@ -573,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()
@@ -587,10 +587,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). Pass `version` to read an earlier version instead of the current one.", {
+	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(),
+		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();
@@ -615,7 +616,7 @@ async function runMcpServer(options = {}) {
 				revealed: true
 			};
 		}
-		const values = await fetchDecryptedSecrets(ctx, orgId, envId);
+		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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seekrit/cli",
-  "version": "0.24.0",
+  "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",