@seekrit/cli 0.24.0 → 0.26.0

package/dist/index.js

@@ -51,6 +51,12 @@ const ENTITLEMENT_KEYS = Object.keys({
 		description: "Maximum environments under a single application.",
 		default: null
 	},
+	"branches.per_app.max": {
+		kind: "limit",
+		label: "Branch configs per application",
+		description: "Maximum ephemeral branch environments under a single application.",
+		default: null
+	},
 	"secrets.per_env.max": {
 		kind: "limit",
 		label: "Secrets per environment",
@@ -143,6 +149,197 @@ const SUBSCRIPTION_STATUSES = [
 	"canceled",
 	"paused"
 ];
+//#endregion
+//#region ../../packages/core/src/branches.ts
+/**
+* Branch (ephemeral) environments — a per-PR/preview overlay on an existing
+* application environment.
+*
+* A branch is an ordinary environment row with a parent and a TTL. It is an
+* **overlay, not a copy**: resolve returns the parent's layers and then the
+* branch's own on top, so a branch holds only the values that differ and
+* tracks the parent live. Nothing is re-encrypted at creation — a secret's
+* ciphertext is bound to `(environmentId, name)` as AAD, so copying blobs into
+* a new environment could not decrypt anyway, and a snapshot would immediately
+* drift from its base.
+*
+* Two rules keep the read path cheap and predictable, enforced here:
+*
+* - **Depth one.** A branch's parent must not itself be a branch, so resolve
+*   never recurses on the hot path.
+* - **Application environments only.** Group environments are pulled in by
+*   composition (matched by slug) and have no single parent to overlay.
+*/
+/** Longest life a branch may be given. Bounds sprawl even if nobody cleans up. */
+const MAX_BRANCH_TTL_SECONDS = 720 * 60 * 60;
+/**
+* Parse a human TTL — `30m`, `12h`, `7d`, `2w`, or bare seconds — into seconds.
+* Returns null for anything unparseable, so callers can report the input back.
+* `never` / `none` mean "no expiry" and yield `Infinity`, which
+* {@link planBranchCreate} rejects unless passed as an explicit `null`.
+*/
+function parseBranchTtl(input) {
+	const raw = input.trim().toLowerCase();
+	if (raw === "never" || raw === "none") return Number.POSITIVE_INFINITY;
+	const match = /^(\d+)\s*(s|m|h|d|w)?$/.exec(raw);
+	if (!match) return null;
+	const value = Number(match[1]);
+	const multiplier = {
+		s: 1,
+		m: 60,
+		h: 3600,
+		d: 86400,
+		w: 604800
+	}[match[2] ?? "s"];
+	if (multiplier === void 0) return null;
+	return value * multiplier;
+}
+//#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",
@@ -718,11 +915,22 @@ z.object({
 	*/
 	encryptedPrivateKey: z.string().min(1)
 });
-z.object({
+const grantEnvironmentKeySchema = z.object({
 	principalType: principalTypeSchema,
 	principalId: z.string().min(1),
 	wrappedDek: z.string().min(1)
 });
+z.object({
+	slug: slugSchema,
+	/** Display name; defaults to the slug. */
+	name: nameSchema.optional(),
+	ttlSeconds: z.number().int().min(60).max(MAX_BRANCH_TTL_SECONDS).nullish(),
+	/** The branch's own DEK, wrapped to the creator — generated client-side. */
+	wrappedDek: z.string().min(1),
+	recoveryWrappedDek: z.string().min(1).nullish(),
+	/** The same DEK wrapped to each of the parent's existing grant-holders. */
+	grants: z.array(grantEnvironmentKeySchema).max(500).default([])
+});
 z.object({
 	name: nameSchema,
 	tokenId: z.string().regex(/^skt_[0-9A-Za-z]+$/),
@@ -1978,7 +2186,7 @@ function isServiceToken(value) {
 }
 //#endregion
 //#region package.json
-var version = "0.24.0";
+var version = "0.26.0";
 //#endregion
 //#region ../../packages/api-client/src/index.ts
 var SeekritApiError = class extends Error {
@@ -2107,6 +2315,28 @@ var SeekritClient = class {
 	deleteEnv(orgId, envId) {
 		return this.request("DELETE", `/v1/orgs/${orgId}/envs/${envId}`);
 	}
+	/**
+	* The public keys of an environment's grant-holders, so a client can wrap a
+	* new DEK to each of them (see `createBranch`). No key material is returned.
+	*/
+	listGrantees(orgId, envId) {
+		return this.request("GET", `/v1/orgs/${orgId}/envs/${envId}/grantees`);
+	}
+	listBranches(orgId, envId) {
+		return this.request("GET", `/v1/orgs/${orgId}/envs/${envId}/branches`);
+	}
+	/** Every branch in an application, across all its environments. */
+	listAppBranches(orgId, appId) {
+		return this.request("GET", `/v1/orgs/${orgId}/apps/${appId}/branches`);
+	}
+	/** Fork `envId` into an ephemeral branch. `envId` is the parent, not the branch. */
+	createBranch(orgId, envId, input) {
+		return this.request("POST", `/v1/orgs/${orgId}/envs/${envId}/branches`, input);
+	}
+	/** Branches are environments, so tearing one down is `deleteEnv`. */
+	deleteBranch(orgId, branchId) {
+		return this.request("DELETE", `/v1/orgs/${orgId}/envs/${branchId}`);
+	}
 	listGroups(orgId) {
 		return this.request("GET", `/v1/orgs/${orgId}/groups`);
 	}
@@ -2142,6 +2372,7 @@ var SeekritClient = class {
 	resolve(query = {}) {
 		const params = new URLSearchParams();
 		if (query.env) params.set("env", query.env);
+		if (query.branch) params.set("branch", query.branch);
 		for (const [group, slug] of Object.entries(query.with ?? {})) params.append("with", `${group}:${slug}`);
 		const qs = params.size > 0 ? `?${params}` : "";
 		return this.request("GET", `/v1/resolve${qs}`);
@@ -2535,12 +2766,14 @@ async function resolveOrg(ctx, orgSlug) {
 }
 /**
 * Resolve an environment to operate on — an application env (`--app --env`,
-* or the config's app + `--env`) or a group env (`--group --env`).
+* or the config's app + `--env`), a branch of one (`--branch`), or a group env
+* (`--group --env`).
 */
 async function resolveEnvTarget(ctx, opts) {
 	const org = await resolveOrg(ctx, opts.org);
 	if (!opts.env) fail("specify --env");
 	if (opts.group) {
+		if (opts.branch) fail("--branch applies to application environments, not groups");
 		const { groups } = await ctx.client.listGroups(org.id);
 		const group = groups.find((g) => g.slug === opts.group || g.id === opts.group);
 		if (!group) fail(`no group "${opts.group}" in ${org.slug}`);
@@ -2553,34 +2786,59 @@ async function resolveEnvTarget(ctx, opts) {
 			label: `${group.slug}@${env.slug}`
 		};
 	}
-	const appSlug = opts.app ?? findProjectConfig()?.app;
-	if (!appSlug) fail("specify --app or --group (or run `seekrit init`)");
-	const { apps } = await ctx.client.listApps(org.id);
-	const app = apps.find((a) => a.slug === appSlug || a.id === appSlug);
-	if (!app) fail(`no app "${appSlug}" in ${org.slug}`);
+	const app = await resolveApp(ctx, opts);
 	const { environments } = await ctx.client.listEnvs(org.id, app.id);
 	const env = environments.find((e) => e.slug === opts.env || e.id === opts.env);
 	if (!env) fail(`no environment "${opts.env}" in ${app.slug}`);
+	if (opts.branch) {
+		const branch = await resolveBranch(ctx, app, opts.branch);
+		return {
+			orgId: org.id,
+			envId: branch.id,
+			label: `${app.slug}/${env.slug}#${branch.slug}`
+		};
+	}
 	return {
 		orgId: org.id,
 		envId: env.id,
 		label: `${app.slug}/${env.slug}`
 	};
 }
-/** Resolve an application environment, keeping ids + slugs (for token binding). */
-async function resolveAppEnv(ctx, opts) {
+/** Resolve the target application from a flag or the committed config. */
+async function resolveApp(ctx, opts) {
 	const org = await resolveOrg(ctx, opts.org);
 	const appSlug = opts.app ?? findProjectConfig()?.app;
 	if (!appSlug) fail("specify --app (or run `seekrit init`)");
-	if (!opts.env) fail("specify --env");
 	const { apps } = await ctx.client.listApps(org.id);
 	const app = apps.find((a) => a.slug === appSlug || a.id === appSlug);
 	if (!app) fail(`no app "${appSlug}" in ${org.slug}`);
-	const { environments } = await ctx.client.listEnvs(org.id, app.id);
+	return {
+		orgId: org.id,
+		orgSlug: org.slug,
+		id: app.id,
+		slug: app.slug
+	};
+}
+/**
+* Find a branch by slug (or id) anywhere in an application. Branch slugs share
+* the application's environment namespace, so one lookup is unambiguous — no
+* need to name the parent environment.
+*/
+async function resolveBranch(ctx, app, branchRef) {
+	const { branches } = await ctx.client.listAppBranches(app.orgId, app.id);
+	const branch = branches.find((b) => b.slug === branchRef || b.id === branchRef);
+	if (!branch) fail(`no branch "${branchRef}" in ${app.slug}`);
+	return branch;
+}
+/** Resolve an application environment, keeping ids + slugs (for token binding). */
+async function resolveAppEnv(ctx, opts) {
+	if (!opts.env) fail("specify --env");
+	const app = await resolveApp(ctx, opts);
+	const { environments } = await ctx.client.listEnvs(app.orgId, app.id);
 	const env = environments.find((e) => e.slug === opts.env || e.id === opts.env);
 	if (!env) fail(`no environment "${opts.env}" in ${app.slug}`);
 	return {
-		orgId: org.id,
+		orgId: app.orgId,
 		appId: app.id,
 		appSlug: app.slug,
 		envId: env.id,
@@ -2742,271 +3000,79 @@ function registerAwsCommands(program) {
 	});
 }
 //#endregion
-//#region src/dotenv.ts
-/**
-* Minimal `.env` parser: `KEY=VALUE`, `#` comments, an optional `export`
-* prefix, and single/double-quoted values (double quotes honor `\n \t \r \" \\`
-* escapes; unquoted values drop trailing ` # comments`). Multiline values are
-* not supported — keep those in seekrit itself.
-*/
-function parseDotenv(content) {
-	const out = {};
-	for (const raw of content.split(/\r?\n/)) {
-		let line = raw.trim();
-		if (!line || line.startsWith("#")) continue;
-		if (line.startsWith("export ")) line = line.slice(7).trimStart();
-		const eq = line.indexOf("=");
-		if (eq === -1) continue;
-		const key = line.slice(0, eq).trim();
-		if (!key) continue;
-		let value = line.slice(eq + 1).trim();
-		const quote = value[0];
-		if (value.length >= 2 && (quote === "\"" || quote === "'") && value.at(-1) === quote) {
-			value = value.slice(1, -1);
-			if (quote === "\"") value = value.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "	").replace(/\\"/g, "\"").replace(/\\\\/g, "\\");
-		} else {
-			const comment = value.indexOf(" #");
-			if (comment !== -1) value = value.slice(0, comment).trim();
-		}
-		out[key] = value;
-	}
-	return out;
-}
-//#endregion
-//#region src/format.ts
-function needsQuoting(value) {
-	return /[\s"'`$\\#]/.test(value) || value === "";
-}
-function dotenvQuote(value) {
-	if (!needsQuoting(value)) return value;
-	return `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("\n", "\\n")}"`;
-}
-function shellQuote(value) {
-	return `'${value.replaceAll("'", `'\\''`)}'`;
+//#region src/kms.ts
+/** Collect a repeatable option into a list. */
+function collect$6(value, acc = []) {
+	acc.push(value);
+	return acc;
 }
-function formatSecrets(values, format) {
-	const names = Object.keys(values).sort();
-	switch (format) {
-		case "json": return JSON.stringify(values, names, 2);
-		case "shell": return names.map((name) => `export ${name}=${shellQuote(values[name] ?? "")}`).join("\n");
-		case "dotenv": return names.map((name) => `${name}=${dotenvQuote(values[name] ?? "")}`).join("\n");
+/** The calling principal's identity + public key (for a self-grant). */
+async function kmsCallerIdentity(ctx) {
+	if (ctx.auth.type === "bearer" && isServiceToken(ctx.auth.token)) {
+		const { tokenId, privateKey } = await parseServiceToken(ctx.auth.token);
+		const { d: _d, key_ops: _ops, ext: _ext, ...pub } = await crypto.subtle.exportKey("jwk", privateKey);
+		return {
+			principalType: "service_token",
+			principalId: tokenId,
+			publicKeyJwk: JSON.stringify(pub)
+		};
 	}
+	const { user } = await ctx.client.me();
+	if (!user.publicKeyJwk) fail("run `seekrit keys setup` first");
+	return {
+		principalType: "user",
+		principalId: user.id,
+		publicKeyJwk: user.publicKeyJwk
+	};
 }
-//#endregion
-//#region src/gcp.ts
-/**
-* `seekrit gcp` — temporary GCP credentials via IAM Credentials
-* `generateAccessToken` (Vault-style dynamic secrets, the tier-2 sibling of
-* `seekrit aws`).
-*
-* Zero-knowledge for the leased credential: minting generates an ephemeral P-256
-* keypair on THIS machine and sends only the public key; GCP mints the token and
-* the broker returns it wrapped to that key, so the control plane only ever
-* relays ciphertext and only this machine can unwrap it. Registering a target
-* wraps the service-account key JSON to the broker's public key locally, so the
-* control plane never sees it either — the source service account needs only
-* `roles/iam.serviceAccountTokenCreator` on the target.
-*/
-/** Parse a duration like `30m`, `1h`, or a bare seconds count. */
-function parseTtlSeconds$5(input) {
-	const m = /^(\d+)\s*([smhd]?)$/.exec(input.trim());
-	if (!m) fail(`invalid --ttl "${input}" (try 30m, 1h, 12h)`);
-	return Number(m[1]) * ({
-		s: 1,
-		m: 60,
-		h: 3600,
-		d: 86400
-	}[m[2] || "s"] ?? 1);
+/** Look up an org member (by email) or service token (by id) as a grant recipient. */
+async function kmsResolveRecipient(ctx, orgId, who) {
+	if (who.user) {
+		const { members } = await ctx.client.listMembers(orgId);
+		const m = members.find((x) => x.email === who.user);
+		if (!m) fail(`no member ${who.user}`);
+		if (!m.publicKeyJwk) fail(`${who.user} has not completed key setup`);
+		return {
+			principalType: "user",
+			principalId: m.userId,
+			publicKeyJwk: m.publicKeyJwk
+		};
+	}
+	if (who.token) {
+		const { tokens } = await ctx.client.listTokens(orgId);
+		const t = tokens.find((x) => x.id === who.token);
+		if (!t) fail(`no service token ${who.token}`);
+		return {
+			principalType: "service_token",
+			principalId: t.id,
+			publicKeyJwk: t.publicKeyJwk
+		};
+	}
+	fail("specify --user <email> or --token <id>");
 }
-/** Collect a repeatable flag (e.g. --scope) into a list. */
-function collectList$1(value, acc = []) {
-	acc.push(value);
-	return acc;
+async function kmsResolveKey(ctx, orgId, ref) {
+	const { keys } = await ctx.client.listKmsKeys(orgId);
+	const key = keys.find((k) => k.id === ref || k.name === ref);
+	if (!key) fail(`no KMS key "${ref}"`);
+	return key;
 }
-/**
-* The service-account key JSON the broker impersonates with. From --key-file or
-* GOOGLE_APPLICATION_CREDENTIALS. Never leaves this machine unwrapped — it is
-* wrapped to the broker key before upload.
-*/
-function resolveServiceAccountKey(opts) {
-	const path = opts.keyFile ?? process.env.GOOGLE_APPLICATION_CREDENTIALS;
-	if (!path) fail("provide the source service-account key JSON via --key-file or GOOGLE_APPLICATION_CREDENTIALS (it needs roles/iam.serviceAccountTokenCreator on the target)");
-	const raw = readFileSync(path, "utf8").trim();
-	try {
-		const parsed = JSON.parse(raw);
-		if (typeof parsed.client_email !== "string" || typeof parsed.private_key !== "string") fail(`${path} is not a service-account key JSON (missing client_email/private_key)`);
-	} catch {
-		fail(`${path} is not valid JSON`);
-	}
-	return raw;
+/** Recover a key's material for one version (default: current), for the caller. */
+async function kmsRecoverMaterial(ctx, orgId, keyId, version) {
+	const mat = await ctx.client.getMyKmsKey(orgId, keyId);
+	const v = version ?? mat.currentVersion;
+	const grant = mat.grants.find((g) => g.version === v);
+	if (!grant) fail(`no grant for version ${v} of this key`);
+	return {
+		material: await unwrapDek(grant.wrappedKey, await getPrivateKey(ctx)),
+		version: v,
+		currentVersion: mat.currentVersion
+	};
 }
-function registerGcpCommands(program) {
-	const gcp = program.command("gcp").description("temporary GCP credentials (IAM generateAccessToken, zero-knowledge)");
-	const target = gcp.command("target").description("manage GCP service-account targets");
-	target.command("add").description("register an impersonable service account to issue temporary tokens from").requiredOption("--name <name>", "display name, e.g. prod-deploy").requiredOption("--service-account <email>", "the service account to impersonate, name@project.iam.gserviceaccount.com").option("--org <slug>").option("--scope <scope>", "OAuth scope to grant (repeatable; default cloud-platform)", collectList$1).option("--delegate <email>", "delegation-chain service account (repeatable)", collectList$1).option("--max-ttl <duration>", "clamp requested token lifetime, e.g. 1h").option("--key-file <path>", "source SA key JSON (else GOOGLE_APPLICATION_CREDENTIALS)").action(async (options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		const config = {
-			provider: "gcp",
-			executor: "in_do",
-			serviceAccount: options.serviceAccount,
-			...options.scope?.length ? { scopes: options.scope } : {},
-			...options.delegate?.length ? { delegates: options.delegate } : {},
-			...options.maxTtl ? { maxTtlSeconds: parseTtlSeconds$5(options.maxTtl) } : {}
-		};
-		const keyJson = resolveServiceAccountKey(options);
-		const { publicKeyJwk } = await ctx.client.getLeaseBrokerKey(org.id);
-		const wrappedAdminSecret = await wrapDek(new TextEncoder().encode(keyJson), publicKeyJwk);
-		const { target: created } = await ctx.client.registerLeaseTarget(org.id, {
-			name: options.name,
-			config,
-			wrappedAdminSecret
-		});
-		console.error(`registered GCP target ${created.name} (${created.id})`);
-		console.error("\nGrant the source SA the token-creator role, then `seekrit gcp lease`:\n");
-		console.log(gcpSetupInstructions(config));
-	});
-	target.command("list").description("list GCP service-account targets").option("--org <slug>").action(async (options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		const { targets } = await ctx.client.listLeaseTargets(org.id);
-		for (const t of targets) {
-			const cfg = t.config;
-			if (cfg.provider !== "gcp") continue;
-			console.log(`${t.id}\t${t.name}\t${cfg.serviceAccount}`);
-		}
-	});
-	target.command("setup <targetId>").description("reprint the IAM setup for a GCP target").option("--org <slug>").action(async (targetId, options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		const { targets } = await ctx.client.listLeaseTargets(org.id);
-		const t = targets.find((x) => x.id === targetId || x.name === targetId);
-		if (!t) fail(`no target "${targetId}" in ${org.slug}`);
-		const cfg = t.config;
-		if (cfg.provider !== "gcp") fail("not a gcp target (see `seekrit aws`/`seekrit ssh`)");
-		console.log(gcpSetupInstructions(cfg));
-	});
-	target.command("rm <targetId>").description("delete a GCP service-account target").option("--org <slug>").action(async (targetId, options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		await ctx.client.deleteLeaseTarget(org.id, targetId);
-		console.error(`deleted ${targetId}`);
-	});
-	gcp.command("lease <target>").description("mint a short-lived GCP access token; prints ready-to-source export lines").option("--org <slug>").option("--ttl <duration>", "token lifetime, e.g. 15m, 1h", "1h").option("--json", "print the full credential as JSON").action(async (targetRef, options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		const { targets } = await ctx.client.listLeaseTargets(org.id);
-		const t = targets.find((x) => x.id === targetRef || x.name === targetRef);
-		if (!t) fail(`no target "${targetRef}" in ${org.slug}`);
-		if (t.config.provider !== "gcp") fail(`"${t.name}" is not a gcp target (see \`seekrit aws\`)`);
-		const ttlSeconds = parseTtlSeconds$5(options.ttl);
-		if (ttlSeconds < 60) fail(`--ttl must be at least 60s`);
-		if (ttlSeconds > 43200) fail(`--ttl must be at most ${GCP_MAX_TTL_SECONDS / 3600}h`);
-		const recipient = await generateGcpRecipientKeyPair();
-		const { gcp: leased } = await ctx.client.mintLease(org.id, {
-			provider: "gcp",
-			targetId: t.id,
-			recipientPublicKey: recipient.publicKeyJwk,
-			ttlSeconds
-		});
-		const cred = await unwrapGcpCredential(leased.wrappedCredential, recipient.privateKeyJwk);
-		console.error(`leased ${cred.serviceAccount} — expires ${cred.expiration}`);
-		if (options.json) console.log(JSON.stringify(cred, null, 2));
-		else {
-			console.log(`export CLOUDSDK_AUTH_ACCESS_TOKEN=${cred.accessToken}`);
-			console.log(`export GOOGLE_OAUTH_ACCESS_TOKEN=${cred.accessToken}`);
-		}
-	});
-	gcp.command("leases").description("list GCP leases (the ledger — never secret material)").option("--org <slug>").action(async (options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		const { leases } = await ctx.client.listLeases(org.id);
-		for (const l of leases) {
-			if (l.provider !== "gcp") continue;
-			console.log(`${l.id}\t${l.status}\texpires ${l.expiresAt}`);
-		}
-	});
-	gcp.command("revoke <leaseId>").description("mark a lease revoked in the ledger (tokens stay valid until they expire)").option("--org <slug>").action(async (leaseId, options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		await ctx.client.revokeLease(org.id, leaseId);
-		console.error(`revoked ${leaseId} (issued tokens remain valid until they expire)`);
-	});
-}
-//#endregion
-//#region src/kms.ts
-/** Collect a repeatable option into a list. */
-function collect$6(value, acc = []) {
-	acc.push(value);
-	return acc;
-}
-/** The calling principal's identity + public key (for a self-grant). */
-async function kmsCallerIdentity(ctx) {
-	if (ctx.auth.type === "bearer" && isServiceToken(ctx.auth.token)) {
-		const { tokenId, privateKey } = await parseServiceToken(ctx.auth.token);
-		const { d: _d, key_ops: _ops, ext: _ext, ...pub } = await crypto.subtle.exportKey("jwk", privateKey);
-		return {
-			principalType: "service_token",
-			principalId: tokenId,
-			publicKeyJwk: JSON.stringify(pub)
-		};
-	}
-	const { user } = await ctx.client.me();
-	if (!user.publicKeyJwk) fail("run `seekrit keys setup` first");
-	return {
-		principalType: "user",
-		principalId: user.id,
-		publicKeyJwk: user.publicKeyJwk
-	};
-}
-/** Look up an org member (by email) or service token (by id) as a grant recipient. */
-async function kmsResolveRecipient(ctx, orgId, who) {
-	if (who.user) {
-		const { members } = await ctx.client.listMembers(orgId);
-		const m = members.find((x) => x.email === who.user);
-		if (!m) fail(`no member ${who.user}`);
-		if (!m.publicKeyJwk) fail(`${who.user} has not completed key setup`);
-		return {
-			principalType: "user",
-			principalId: m.userId,
-			publicKeyJwk: m.publicKeyJwk
-		};
-	}
-	if (who.token) {
-		const { tokens } = await ctx.client.listTokens(orgId);
-		const t = tokens.find((x) => x.id === who.token);
-		if (!t) fail(`no service token ${who.token}`);
-		return {
-			principalType: "service_token",
-			principalId: t.id,
-			publicKeyJwk: t.publicKeyJwk
-		};
-	}
-	fail("specify --user <email> or --token <id>");
-}
-async function kmsResolveKey(ctx, orgId, ref) {
-	const { keys } = await ctx.client.listKmsKeys(orgId);
-	const key = keys.find((k) => k.id === ref || k.name === ref);
-	if (!key) fail(`no KMS key "${ref}"`);
-	return key;
-}
-/** Recover a key's material for one version (default: current), for the caller. */
-async function kmsRecoverMaterial(ctx, orgId, keyId, version) {
-	const mat = await ctx.client.getMyKmsKey(orgId, keyId);
-	const v = version ?? mat.currentVersion;
-	const grant = mat.grants.find((g) => g.version === v);
-	if (!grant) fail(`no grant for version ${v} of this key`);
-	return {
-		material: await unwrapDek(grant.wrappedKey, await getPrivateKey(ctx)),
-		version: v,
-		currentVersion: mat.currentVersion
-	};
-}
-function registerKmsCommands(program) {
-	const kms = program.command("kms").description("managed keys for application-layer encryption & signing (client-side)");
-	kms.command("create").description("create a managed key (material is generated locally and wrapped, never sent)").requiredOption("--name <name>", "org-unique key name").requiredOption("--purpose <purpose>", "encrypt | sign").option("--org <slug>").option("--app <slug>", "scope the key to an application").option("--group <slug>", "scope the key to a group").option("--grant-user <email>", "also grant an org member (repeatable)", collect$6, []).option("--grant-token <tokenId>", "also grant a service token (repeatable)", collect$6, []).action(async (options) => {
-		if (options.purpose !== "encrypt" && options.purpose !== "sign") fail("--purpose must be encrypt or sign");
-		if (options.app && options.group) fail("pass at most one of --app or --group");
+function registerKmsCommands(program) {
+	const kms = program.command("kms").description("managed keys for application-layer encryption & signing (client-side)");
+	kms.command("create").description("create a managed key (material is generated locally and wrapped, never sent)").requiredOption("--name <name>", "org-unique key name").requiredOption("--purpose <purpose>", "encrypt | sign").option("--org <slug>").option("--app <slug>", "scope the key to an application").option("--group <slug>", "scope the key to a group").option("--grant-user <email>", "also grant an org member (repeatable)", collect$6, []).option("--grant-token <tokenId>", "also grant a service token (repeatable)", collect$6, []).action(async (options) => {
+		if (options.purpose !== "encrypt" && options.purpose !== "sign") fail("--purpose must be encrypt or sign");
+		if (options.app && options.group) fail("pass at most one of --app or --group");
 		const ctx = buildContext();
 		const org = await resolveOrg(ctx, options.org);
 		let toWrap;
@@ -3191,33 +3257,516 @@ function registerKmsCommands(program) {
 		const { material } = await kmsRecoverMaterial(ctx, org.id, key.id, ref.version);
 		console.log(toBase64(await decryptDataKey(material, wrapped)));
 	});
-	kms.command("sign").description("sign stdin with a signing key (prints an sg1 signature)").requiredOption("--key <name>", "key name or id").option("--org <slug>").action(async (options) => {
+	kms.command("sign").description("sign stdin with a signing key (prints an sg1 signature)").requiredOption("--key <name>", "key name or id").option("--org <slug>").action(async (options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		const key = await kmsResolveKey(ctx, org.id, options.key);
+		if (key.purpose !== "sign") fail(`${key.name} is a ${key.purpose} key`);
+		const { material, currentVersion } = await kmsRecoverMaterial(ctx, org.id, key.id);
+		const message = await readStdin();
+		const privateKey = await importSigningKey(material);
+		console.log(await signMessage(privateKey, {
+			keyId: key.id,
+			version: currentVersion
+		}, message));
+	});
+	kms.command("verify").description("verify an sg1 signature over stdin (exit 0 = valid)").requiredOption("--key <name>", "key name or id").requiredOption("--signature <sg1>", "the signature blob").option("--org <slug>").action(async (options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		const key = await kmsResolveKey(ctx, org.id, options.key);
+		const ref = signatureKeyRef(options.signature);
+		const { versions } = await ctx.client.getKmsPublicKeys(org.id, key.id);
+		const pub = versions.find((v) => v.version === ref.version)?.publicKeyJwk;
+		if (!pub) fail(`no published public key for version ${ref.version}`);
+		const message = await readStdin();
+		if (await verifyMessage(await importVerifyingKey(pub), options.signature, message)) console.error("valid");
+		else {
+			console.error("INVALID");
+			process.exitCode = 1;
+		}
+	});
+}
+//#endregion
+//#region src/recovery.ts
+/** Collect a repeatable option into a list. */
+function collect$5(value, acc = []) {
+	acc.push(value);
+	return acc;
+}
+/** Resolve a custodian reference: a `skt_…` token id, otherwise a member email. */
+function resolveCustodian(ctx, orgId, ref) {
+	return ref.startsWith("skt_") ? kmsResolveRecipient(ctx, orgId, { token: ref }) : kmsResolveRecipient(ctx, orgId, { user: ref });
+}
+/**
+* The env DEK additionally wrapped to the org recovery key, when recovery is
+* enabled — so a newly created environment is recovery-protected from birth.
+* Returns undefined when recovery is off (the env is backfilled by `recovery
+* sync` later).
+*/
+async function recoveryWrapForNewEnv(ctx, orgId, dek) {
+	let recoveryPublicKeyJwk;
+	try {
+		const { recovery } = await ctx.client.getRecovery(orgId);
+		recoveryPublicKeyJwk = recovery.enabled ? recovery.recoveryPublicKeyJwk : null;
+	} catch (e) {
+		if (e instanceof SeekritApiError && (e.status === 403 || e.status === 404)) return void 0;
+		throw e;
+	}
+	if (!recoveryPublicKeyJwk) return void 0;
+	return wrapDek(dek, recoveryPublicKeyJwk);
+}
+/**
+* Wrap every environment the caller can decrypt but that lacks a recovery grant,
+* and upload the grants. Idempotent — safe to re-run and to run from several
+* admins to complete coverage.
+*/
+async function syncRecoveryGrants(ctx, orgId) {
+	const { recovery } = await ctx.client.getRecovery(orgId);
+	if (!recovery.enabled || !recovery.recoveryPublicKeyJwk) fail("recovery is not enabled");
+	const recoveryPublicKeyJwk = recovery.recoveryPublicKeyJwk;
+	const privateKey = await getPrivateKey(ctx);
+	const grants = [];
+	let skipped = 0;
+	for (const environmentId of recovery.coverage.unprotectedEnvIds) {
+		let wrappedDek;
+		try {
+			({wrappedDek} = await ctx.client.getMyEnvKey(orgId, environmentId));
+		} catch (e) {
+			if (e instanceof SeekritApiError && (e.status === 403 || e.status === 404)) {
+				skipped++;
+				continue;
+			}
+			throw e;
+		}
+		const dek = await unwrapDek(wrappedDek, privateKey);
+		grants.push({
+			environmentId,
+			wrappedDek: await wrapDek(dek, recoveryPublicKeyJwk)
+		});
+	}
+	if (grants.length > 0) await ctx.client.uploadRecoveryGrants(orgId, { grants });
+	return {
+		wrapped: grants.length,
+		skipped
+	};
+}
+/** Generate + split a fresh recovery key across the given custodians. */
+async function buildRecoveryConfig(ctx, orgId, thresholdRaw, custodianRefs) {
+	const threshold = Number.parseInt(thresholdRaw, 10);
+	if (!Number.isInteger(threshold) || threshold < 1) fail("--threshold must be a positive integer");
+	if (custodianRefs.length === 0) fail("pass at least one --custodian <email|skt_id>");
+	if (threshold > custodianRefs.length) fail("--threshold cannot exceed the number of custodians");
+	const custodians = await Promise.all(custodianRefs.map((ref) => resolveCustodian(ctx, orgId, ref)));
+	const recovery = await generateRecoveryKey();
+	const shares = await splitRecoveryKey(recovery.privateKeyJwk, threshold, custodians);
+	return {
+		recoveryPublicKeyJwk: recovery.publicKeyJwk,
+		threshold,
+		shares: shares.map((s) => ({
+			principalType: s.principalType,
+			principalId: s.principalId,
+			shareIndex: s.shareIndex,
+			wrappedShare: s.wrappedShare
+		}))
+	};
+}
+function registerRecoveryCommands(program) {
+	const recovery = program.command("recovery").description("customer-controlled M-of-N recovery (zero-knowledge)");
+	recovery.command("status").description("show recovery configuration and environment coverage").option("--org <slug>").action(async (options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		const { recovery: status } = await ctx.client.getRecovery(org.id);
+		if (!status.enabled) {
+			console.log("recovery: disabled");
+			return;
+		}
+		console.log(`recovery: enabled (${status.threshold}-of-${status.shareCount})`);
+		console.log(`coverage: ${status.coverage.protected}/${status.coverage.total} environments protected`);
+		console.log("custodians:");
+		for (const cst of status.custodians) console.log(`  - ${cst.label ?? cst.principalId} (${cst.principalType}, share #${cst.shareIndex})`);
+		if (status.coverage.unprotectedEnvIds.length > 0) console.log(`${status.coverage.unprotectedEnvIds.length} environment(s) not yet protected — run \`seekrit recovery sync\``);
+	});
+	recovery.command("setup").description("enable recovery: split a fresh recovery key across custodians").requiredOption("--threshold <M>", "custodians required to recover (M in M-of-N)").option("--custodian <email|skt_id>", "a recovery custodian (repeatable)", collect$5, []).option("--org <slug>").action(async (options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		const config = await buildRecoveryConfig(ctx, org.id, options.threshold, options.custodian);
+		await ctx.client.configureRecovery(org.id, {
+			...config,
+			grants: []
+		});
+		console.error(`recovery enabled: ${config.threshold}-of-${config.shares.length}`);
+		const { wrapped, skipped } = await syncRecoveryGrants(ctx, org.id);
+		console.error(`recovery-protected ${wrapped} environment(s) you can decrypt`);
+		if (skipped > 0) console.error(`${skipped} environment(s) need another admin to run \`seekrit recovery sync\``);
+	});
+	recovery.command("sync").description("recovery-protect environments you can decrypt but that aren't yet covered").option("--org <slug>").action(async (options) => {
+		const ctx = buildContext();
+		const { wrapped, skipped } = await syncRecoveryGrants(ctx, (await resolveOrg(ctx, options.org)).id);
+		console.error(`recovery-protected ${wrapped} environment(s); skipped ${skipped} you cannot decrypt`);
+	});
+	recovery.command("rotate").description("rotate the recovery key (new keypair, custodians, and env re-wraps)").requiredOption("--threshold <M>", "custodians required to recover (M in M-of-N)").option("--custodian <email|skt_id>", "a recovery custodian (repeatable)", collect$5, []).option("--org <slug>").action(async (options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		const config = await buildRecoveryConfig(ctx, org.id, options.threshold, options.custodian);
+		await ctx.client.rotateRecovery(org.id, {
+			...config,
+			grants: []
+		});
+		console.error(`recovery rotated: ${config.threshold}-of-${config.shares.length}`);
+		const { wrapped, skipped } = await syncRecoveryGrants(ctx, org.id);
+		console.error(`re-wrapped ${wrapped} environment(s) you can decrypt to the new recovery key`);
+		if (skipped > 0) console.error(`${skipped} environment(s) still need another admin to run \`seekrit recovery sync\``);
+	});
+	recovery.command("disable").description("disable recovery and remove all recovery grants").option("--org <slug>").action(async (options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		await ctx.client.disableRecovery(org.id);
+		console.error("recovery disabled; recovery grants removed");
+	});
+	recovery.command("request").description("start a recovery ceremony (defaults to recovering access for yourself)").option("--target-user <email>", "recover access for another member").option("--target-token <id>", "recover access for a service token").option("--reason <text>", "note recorded in the audit trail").option("--org <slug>").action(async (options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		const target = options.targetUser || options.targetToken ? await kmsResolveRecipient(ctx, org.id, {
+			user: options.targetUser,
+			token: options.targetToken
+		}) : await kmsCallerIdentity(ctx);
+		const { request } = await ctx.client.createRecoveryRequest(org.id, {
+			targetPublicKeyJwk: target.publicKeyJwk,
+			targetType: target.principalType,
+			targetId: target.principalId,
+			reason: options.reason
+		});
+		console.error(`recovery request ${request.id} created (needs ${request.threshold} custodians)`);
+		console.error(`  custodians run:  seekrit recovery approve ${request.id}`);
+		console.error(`  then the target: seekrit recovery complete ${request.id}`);
+	});
+	recovery.command("approve").description("as a custodian, contribute your share to a recovery request").argument("<requestId>").option("--org <slug>").action(async (requestId, options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		const { request } = await ctx.client.getRecoveryRequest(org.id, requestId);
+		const myShare = await ctx.client.getMyRecoveryShare(org.id);
+		const privateKey = await getPrivateKey(ctx);
+		const contributedShare = await rewrapRecoveryShare(await unwrapRecoveryShare(myShare.wrappedShare, privateKey), request.targetPublicKeyJwk);
+		const res = await ctx.client.contributeRecoveryShare(org.id, requestId, {
+			shareIndex: myShare.shareIndex,
+			contributedShare
+		});
+		console.error(`contributed share #${myShare.shareIndex}: ${res.contributed}/${res.threshold} collected${res.quorumReached ? " — quorum reached" : ""}`);
+	});
+	recovery.command("complete").description("as the recovery target, reconstruct the key and restore your access").argument("<requestId>").option("--org <slug>").action(async (requestId, options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		const { request, contributions, quorumReached } = await ctx.client.getRecoveryRequest(org.id, requestId);
+		if (!quorumReached) fail(`only ${contributions.length}/${request.threshold} custodians have contributed`);
+		const me = await kmsCallerIdentity(ctx);
+		const targetPrivateKey = await getPrivateKey(ctx);
+		const recoveryPrivateKey = await combineRecoveryShares(await Promise.all(contributions.map((cont) => unwrapRecoveryShare(cont.contributedShare, targetPrivateKey))));
+		const { grants: recoveryEnvKeys } = await ctx.client.getRecoveryEnvKeys(org.id);
+		const restored = [];
+		for (const g of recoveryEnvKeys) {
+			const dek = await unwrapDek(g.wrappedDek, recoveryPrivateKey);
+			restored.push({
+				environmentId: g.environmentId,
+				wrappedDek: await wrapDek(dek, me.publicKeyJwk)
+			});
+		}
+		await ctx.client.completeRecoveryRequest(org.id, requestId, {
+			principalType: me.principalType,
+			principalId: me.principalId,
+			grants: restored
+		});
+		console.error(`recovery complete: restored access to ${restored.length} environment(s)`);
+	});
+	recovery.command("cancel").description("cancel an open recovery request").argument("<requestId>").option("--org <slug>").action(async (requestId, options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		await ctx.client.cancelRecoveryRequest(org.id, requestId);
+		console.error(`recovery request ${requestId} canceled`);
+	});
+}
+//#endregion
+//#region src/branches.ts
+/**
+* Resolve `--from` to the environment being branched.
+*
+* Not just `resolveAppEnv`: branch slugs live in the same namespace but are
+* excluded from the environment list, so naming one lands on "no environment
+* …". Branching a branch is a real thing people will try (depth is capped at
+* one), and it deserves an error that says so.
+*/
+async function resolveBranchParent(ctx, opts) {
+	const app = await resolveApp(ctx, opts);
+	const { environments } = await ctx.client.listEnvs(app.orgId, app.id);
+	const env = environments.find((e) => e.slug === opts.from || e.id === opts.from);
+	if (env) return {
+		orgId: app.orgId,
+		appId: app.id,
+		appSlug: app.slug,
+		envId: env.id,
+		envSlug: env.slug
+	};
+	const { branches } = await ctx.client.listAppBranches(app.orgId, app.id);
+	if (branches.some((b) => b.slug === opts.from || b.id === opts.from)) fail(`"${opts.from}" is itself a branch — branches are one level deep, so branch from the environment it overlays`);
+	fail(`no environment "${opts.from}" in ${app.slug}`);
+}
+/**
+* Branch (ephemeral) configs: `seekrit branch create pr-142 --from dev`.
+*
+* A branch overlays its parent instead of copying it, so creating one encrypts
+* nothing — it mints a data key for the branch's own overrides and wraps that
+* key to whoever should read them. Everything the branch inherits stays where
+* it is, and stays live.
+*/
+function registerBranchCommands(program) {
+	const branch = program.command("branch").description("ephemeral per-PR / preview configs layered on an environment");
+	branch.command("create <slug>").description("fork an environment into an ephemeral branch (inherits its secrets)").option("--org <slug>").option("--app <slug>", "application slug (defaults to seekrit.json)").requiredOption("--from <env>", "the environment to branch").option("--name <name>", "display name (defaults to the slug)").option("--ttl <duration>", "lifetime: 12h, 7d, 2w, … or `never`", "7d").option("--no-share", "don't give the parent's other readers access to this branch").action(async (slug, options) => {
+		const ctx = buildContext();
+		const parent = await resolveBranchParent(ctx, {
+			org: options.org,
+			app: options.app,
+			from: options.from
+		});
+		const parsedTtl = parseBranchTtl(options.ttl);
+		if (parsedTtl === null) fail(`invalid --ttl "${options.ttl}" (try 12h, 7d, 2w, or never)`);
+		const ttlSeconds = Number.isFinite(parsedTtl) ? parsedTtl : null;
+		const me = await kmsCallerIdentity(ctx);
+		const dek = generateDek();
+		const wrappedDek = await wrapDek(dek, me.publicKeyJwk);
+		const recoveryWrappedDek = await recoveryWrapForNewEnv(ctx, parent.orgId, dek);
+		const grants = [];
+		if (options.share !== false) {
+			const { grantees } = await ctx.client.listGrantees(parent.orgId, parent.envId);
+			for (const grantee of grantees) {
+				if (grantee.principalType === me.principalType && grantee.principalId === me.principalId) continue;
+				grants.push({
+					principalType: grantee.principalType,
+					principalId: grantee.principalId,
+					wrappedDek: await wrapDek(dek, grantee.publicKeyJwk)
+				});
+			}
+		}
+		const created = await ctx.client.createBranch(parent.orgId, parent.envId, {
+			slug,
+			name: options.name,
+			ttlSeconds,
+			wrappedDek,
+			recoveryWrappedDek,
+			grants
+		});
+		console.error(`created branch ${parent.appSlug}/${parent.envSlug}#${created.branch.slug} (${created.branch.id})`);
+		console.error(created.branch.expiresAt ? `expires ${created.branch.expiresAt}` : "no expiry — delete it explicitly when the PR closes");
+		if (grants.length > 0) console.error(`shared with ${grants.length} other reader(s)`);
+	});
+	branch.command("list").description("list branches in an application (or of one environment)").option("--org <slug>").option("--app <slug>", "application slug (defaults to seekrit.json)").option("--env <slug>", "only branches of this environment").action(async (options) => {
+		const ctx = buildContext();
+		if (options.env) {
+			const parent = await resolveAppEnv(ctx, options);
+			const { branches } = await ctx.client.listBranches(parent.orgId, parent.envId);
+			for (const b of branches) console.log(`${b.slug}\t${b.id}\t${b.expiresAt ?? "never"}`);
+			return;
+		}
+		const app = await resolveApp(ctx, options);
+		const { branches } = await ctx.client.listAppBranches(app.orgId, app.id);
+		for (const b of branches) console.log(`${b.slug}\t${b.id}\t${b.expiresAt ?? "never"}`);
+	});
+	branch.command("delete <slug>").alias("rm").description("tear down a branch and everything it overrode").option("--org <slug>").option("--app <slug>", "application slug (defaults to seekrit.json)").action(async (slug, options) => {
+		const ctx = buildContext();
+		const app = await resolveApp(ctx, options);
+		const target = await resolveBranch(ctx, app, slug);
+		await ctx.client.deleteBranch(app.orgId, target.id);
+		console.error(`deleted branch ${app.slug}#${target.slug}`);
+	});
+}
+//#endregion
+//#region src/dotenv.ts
+/**
+* Minimal `.env` parser: `KEY=VALUE`, `#` comments, an optional `export`
+* prefix, and single/double-quoted values (double quotes honor `\n \t \r \" \\`
+* escapes; unquoted values drop trailing ` # comments`). Multiline values are
+* not supported — keep those in seekrit itself.
+*/
+function parseDotenv(content) {
+	const out = {};
+	for (const raw of content.split(/\r?\n/)) {
+		let line = raw.trim();
+		if (!line || line.startsWith("#")) continue;
+		if (line.startsWith("export ")) line = line.slice(7).trimStart();
+		const eq = line.indexOf("=");
+		if (eq === -1) continue;
+		const key = line.slice(0, eq).trim();
+		if (!key) continue;
+		let value = line.slice(eq + 1).trim();
+		const quote = value[0];
+		if (value.length >= 2 && (quote === "\"" || quote === "'") && value.at(-1) === quote) {
+			value = value.slice(1, -1);
+			if (quote === "\"") value = value.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "	").replace(/\\"/g, "\"").replace(/\\\\/g, "\\");
+		} else {
+			const comment = value.indexOf(" #");
+			if (comment !== -1) value = value.slice(0, comment).trim();
+		}
+		out[key] = value;
+	}
+	return out;
+}
+//#endregion
+//#region src/format.ts
+function needsQuoting(value) {
+	return /[\s"'`$\\#]/.test(value) || value === "";
+}
+function dotenvQuote(value) {
+	if (!needsQuoting(value)) return value;
+	return `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("\n", "\\n")}"`;
+}
+function shellQuote(value) {
+	return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function formatSecrets(values, format) {
+	const names = Object.keys(values).sort();
+	switch (format) {
+		case "json": return JSON.stringify(values, names, 2);
+		case "shell": return names.map((name) => `export ${name}=${shellQuote(values[name] ?? "")}`).join("\n");
+		case "dotenv": return names.map((name) => `${name}=${dotenvQuote(values[name] ?? "")}`).join("\n");
+	}
+}
+//#endregion
+//#region src/gcp.ts
+/**
+* `seekrit gcp` — temporary GCP credentials via IAM Credentials
+* `generateAccessToken` (Vault-style dynamic secrets, the tier-2 sibling of
+* `seekrit aws`).
+*
+* Zero-knowledge for the leased credential: minting generates an ephemeral P-256
+* keypair on THIS machine and sends only the public key; GCP mints the token and
+* the broker returns it wrapped to that key, so the control plane only ever
+* relays ciphertext and only this machine can unwrap it. Registering a target
+* wraps the service-account key JSON to the broker's public key locally, so the
+* control plane never sees it either — the source service account needs only
+* `roles/iam.serviceAccountTokenCreator` on the target.
+*/
+/** Parse a duration like `30m`, `1h`, or a bare seconds count. */
+function parseTtlSeconds$5(input) {
+	const m = /^(\d+)\s*([smhd]?)$/.exec(input.trim());
+	if (!m) fail(`invalid --ttl "${input}" (try 30m, 1h, 12h)`);
+	return Number(m[1]) * ({
+		s: 1,
+		m: 60,
+		h: 3600,
+		d: 86400
+	}[m[2] || "s"] ?? 1);
+}
+/** Collect a repeatable flag (e.g. --scope) into a list. */
+function collectList$1(value, acc = []) {
+	acc.push(value);
+	return acc;
+}
+/**
+* The service-account key JSON the broker impersonates with. From --key-file or
+* GOOGLE_APPLICATION_CREDENTIALS. Never leaves this machine unwrapped — it is
+* wrapped to the broker key before upload.
+*/
+function resolveServiceAccountKey(opts) {
+	const path = opts.keyFile ?? process.env.GOOGLE_APPLICATION_CREDENTIALS;
+	if (!path) fail("provide the source service-account key JSON via --key-file or GOOGLE_APPLICATION_CREDENTIALS (it needs roles/iam.serviceAccountTokenCreator on the target)");
+	const raw = readFileSync(path, "utf8").trim();
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed.client_email !== "string" || typeof parsed.private_key !== "string") fail(`${path} is not a service-account key JSON (missing client_email/private_key)`);
+	} catch {
+		fail(`${path} is not valid JSON`);
+	}
+	return raw;
+}
+function registerGcpCommands(program) {
+	const gcp = program.command("gcp").description("temporary GCP credentials (IAM generateAccessToken, zero-knowledge)");
+	const target = gcp.command("target").description("manage GCP service-account targets");
+	target.command("add").description("register an impersonable service account to issue temporary tokens from").requiredOption("--name <name>", "display name, e.g. prod-deploy").requiredOption("--service-account <email>", "the service account to impersonate, name@project.iam.gserviceaccount.com").option("--org <slug>").option("--scope <scope>", "OAuth scope to grant (repeatable; default cloud-platform)", collectList$1).option("--delegate <email>", "delegation-chain service account (repeatable)", collectList$1).option("--max-ttl <duration>", "clamp requested token lifetime, e.g. 1h").option("--key-file <path>", "source SA key JSON (else GOOGLE_APPLICATION_CREDENTIALS)").action(async (options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		const config = {
+			provider: "gcp",
+			executor: "in_do",
+			serviceAccount: options.serviceAccount,
+			...options.scope?.length ? { scopes: options.scope } : {},
+			...options.delegate?.length ? { delegates: options.delegate } : {},
+			...options.maxTtl ? { maxTtlSeconds: parseTtlSeconds$5(options.maxTtl) } : {}
+		};
+		const keyJson = resolveServiceAccountKey(options);
+		const { publicKeyJwk } = await ctx.client.getLeaseBrokerKey(org.id);
+		const wrappedAdminSecret = await wrapDek(new TextEncoder().encode(keyJson), publicKeyJwk);
+		const { target: created } = await ctx.client.registerLeaseTarget(org.id, {
+			name: options.name,
+			config,
+			wrappedAdminSecret
+		});
+		console.error(`registered GCP target ${created.name} (${created.id})`);
+		console.error("\nGrant the source SA the token-creator role, then `seekrit gcp lease`:\n");
+		console.log(gcpSetupInstructions(config));
+	});
+	target.command("list").description("list GCP service-account targets").option("--org <slug>").action(async (options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		const { targets } = await ctx.client.listLeaseTargets(org.id);
+		for (const t of targets) {
+			const cfg = t.config;
+			if (cfg.provider !== "gcp") continue;
+			console.log(`${t.id}\t${t.name}\t${cfg.serviceAccount}`);
+		}
+	});
+	target.command("setup <targetId>").description("reprint the IAM setup for a GCP target").option("--org <slug>").action(async (targetId, options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		const { targets } = await ctx.client.listLeaseTargets(org.id);
+		const t = targets.find((x) => x.id === targetId || x.name === targetId);
+		if (!t) fail(`no target "${targetId}" in ${org.slug}`);
+		const cfg = t.config;
+		if (cfg.provider !== "gcp") fail("not a gcp target (see `seekrit aws`/`seekrit ssh`)");
+		console.log(gcpSetupInstructions(cfg));
+	});
+	target.command("rm <targetId>").description("delete a GCP service-account target").option("--org <slug>").action(async (targetId, options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		await ctx.client.deleteLeaseTarget(org.id, targetId);
+		console.error(`deleted ${targetId}`);
+	});
+	gcp.command("lease <target>").description("mint a short-lived GCP access token; prints ready-to-source export lines").option("--org <slug>").option("--ttl <duration>", "token lifetime, e.g. 15m, 1h", "1h").option("--json", "print the full credential as JSON").action(async (targetRef, options) => {
+		const ctx = buildContext();
+		const org = await resolveOrg(ctx, options.org);
+		const { targets } = await ctx.client.listLeaseTargets(org.id);
+		const t = targets.find((x) => x.id === targetRef || x.name === targetRef);
+		if (!t) fail(`no target "${targetRef}" in ${org.slug}`);
+		if (t.config.provider !== "gcp") fail(`"${t.name}" is not a gcp target (see \`seekrit aws\`)`);
+		const ttlSeconds = parseTtlSeconds$5(options.ttl);
+		if (ttlSeconds < 60) fail(`--ttl must be at least 60s`);
+		if (ttlSeconds > 43200) fail(`--ttl must be at most ${GCP_MAX_TTL_SECONDS / 3600}h`);
+		const recipient = await generateGcpRecipientKeyPair();
+		const { gcp: leased } = await ctx.client.mintLease(org.id, {
+			provider: "gcp",
+			targetId: t.id,
+			recipientPublicKey: recipient.publicKeyJwk,
+			ttlSeconds
+		});
+		const cred = await unwrapGcpCredential(leased.wrappedCredential, recipient.privateKeyJwk);
+		console.error(`leased ${cred.serviceAccount} — expires ${cred.expiration}`);
+		if (options.json) console.log(JSON.stringify(cred, null, 2));
+		else {
+			console.log(`export CLOUDSDK_AUTH_ACCESS_TOKEN=${cred.accessToken}`);
+			console.log(`export GOOGLE_OAUTH_ACCESS_TOKEN=${cred.accessToken}`);
+		}
+	});
+	gcp.command("leases").description("list GCP leases (the ledger — never secret material)").option("--org <slug>").action(async (options) => {
 		const ctx = buildContext();
 		const org = await resolveOrg(ctx, options.org);
-		const key = await kmsResolveKey(ctx, org.id, options.key);
-		if (key.purpose !== "sign") fail(`${key.name} is a ${key.purpose} key`);
-		const { material, currentVersion } = await kmsRecoverMaterial(ctx, org.id, key.id);
-		const message = await readStdin();
-		const privateKey = await importSigningKey(material);
-		console.log(await signMessage(privateKey, {
-			keyId: key.id,
-			version: currentVersion
-		}, message));
+		const { leases } = await ctx.client.listLeases(org.id);
+		for (const l of leases) {
+			if (l.provider !== "gcp") continue;
+			console.log(`${l.id}\t${l.status}\texpires ${l.expiresAt}`);
+		}
 	});
-	kms.command("verify").description("verify an sg1 signature over stdin (exit 0 = valid)").requiredOption("--key <name>", "key name or id").requiredOption("--signature <sg1>", "the signature blob").option("--org <slug>").action(async (options) => {
+	gcp.command("revoke <leaseId>").description("mark a lease revoked in the ledger (tokens stay valid until they expire)").option("--org <slug>").action(async (leaseId, options) => {
 		const ctx = buildContext();
 		const org = await resolveOrg(ctx, options.org);
-		const key = await kmsResolveKey(ctx, org.id, options.key);
-		const ref = signatureKeyRef(options.signature);
-		const { versions } = await ctx.client.getKmsPublicKeys(org.id, key.id);
-		const pub = versions.find((v) => v.version === ref.version)?.publicKeyJwk;
-		if (!pub) fail(`no published public key for version ${ref.version}`);
-		const message = await readStdin();
-		if (await verifyMessage(await importVerifyingKey(pub), options.signature, message)) console.error("valid");
-		else {
-			console.error("INVALID");
-			process.exitCode = 1;
-		}
+		await ctx.client.revokeLease(org.id, leaseId);
+		console.error(`revoked ${leaseId} (issued tokens remain valid until they expire)`);
 	});
 }
 //#endregion
@@ -3317,7 +3866,7 @@ function parseTtlSeconds$4(input) {
 	}[m[2] || "s"] ?? 1);
 }
 /** Collect a repeatable option into an array. */
-function collect$5(value, previous) {
+function collect$4(value, previous) {
 	return [...previous, value];
 }
 /** Parse `readWrite@app` → { role, db } for a custom target. */
@@ -3342,7 +3891,7 @@ function resolveAdminUri(uri) {
 function registerMongoCommands(program) {
 	const mongo = program.command("mongodb").description("temporary MongoDB credentials (createUser, zero-knowledge delivery)");
 	const target = mongo.command("target").description("manage MongoDB targets");
-	target.command("add").description("register a MongoDB cluster to issue temporary credentials from").requiredOption("--name <name>", "display name, e.g. prod-app").requiredOption("--database <db>", "the database leased users get access to, e.g. app").option("--uri <uri>", "admin connection string (else SEEKRIT_MONGODB_ADMIN_URL)").option("--org <slug>").option("--access <level>", "readonly | readwrite | custom", "readonly").option("--role <role@db>", "grant for a custom target (repeatable)", collect$5, []).option("--auth-source <db>", "authentication database (default admin)").option("--max-ttl <duration>", "clamp requested credential lifetime, e.g. 8h").option("--no-tls", "disable TLS to the cluster (TLS is on by default)").action(async (options) => {
+	target.command("add").description("register a MongoDB cluster to issue temporary credentials from").requiredOption("--name <name>", "display name, e.g. prod-app").requiredOption("--database <db>", "the database leased users get access to, e.g. app").option("--uri <uri>", "admin connection string (else SEEKRIT_MONGODB_ADMIN_URL)").option("--org <slug>").option("--access <level>", "readonly | readwrite | custom", "readonly").option("--role <role@db>", "grant for a custom target (repeatable)", collect$4, []).option("--auth-source <db>", "authentication database (default admin)").option("--max-ttl <duration>", "clamp requested credential lifetime, e.g. 8h").option("--no-tls", "disable TLS to the cluster (TLS is on by default)").action(async (options) => {
 		const ctx = buildContext();
 		const org = await resolveOrg(ctx, options.org);
 		const adminUri = resolveAdminUri(options.uri);
@@ -3502,7 +4051,7 @@ function generateUserName$1(prefix = "tmp") {
 function registerMysqlCommands(program) {
 	const mysql = program.command("mysql").description("temporary MySQL/MariaDB credentials (short-lived, zero-knowledge)");
 	const target = mysql.command("target").description("manage provisioning targets");
-	target.command("add").description("register a MySQL/MariaDB server to lease credentials from").requiredOption("--name <name>", "display name, e.g. prod-db").option("--org <slug>").requiredOption("--host <host>", "database host").option("--port <port>", "database port", "3306").requiredOption("--database <name>", "database to grant access to").option("--access <level>", "readonly | readwrite | custom", "readonly").option("--user-host <host>", "host part of created accounts ('name'@'<host>')", "%").option("--executor <mode>", "in_do | remote", "in_do").option("--provisioner-url <url>", "customer provisioner URL (remote executor)").option("--hmac-key <base64>", "shared HMAC key for the remote executor (or set SEEKRIT_PROVISIONER_HMAC_KEY); `seekrit provisioner keygen` mints one").option("--admin-url <url>", "in_do: admin mysql:// connection string (or set SEEKRIT_MYSQL_ADMIN_URL); wrapped locally").option("--create-statement <sql>", "custom CREATE template (repeatable)", collect$4, []).option("--revoke-statement <sql>", "custom REVOKE template (repeatable)", collect$4, []).action(async (options) => {
+	target.command("add").description("register a MySQL/MariaDB server to lease credentials from").requiredOption("--name <name>", "display name, e.g. prod-db").option("--org <slug>").requiredOption("--host <host>", "database host").option("--port <port>", "database port", "3306").requiredOption("--database <name>", "database to grant access to").option("--access <level>", "readonly | readwrite | custom", "readonly").option("--user-host <host>", "host part of created accounts ('name'@'<host>')", "%").option("--executor <mode>", "in_do | remote", "in_do").option("--provisioner-url <url>", "customer provisioner URL (remote executor)").option("--hmac-key <base64>", "shared HMAC key for the remote executor (or set SEEKRIT_PROVISIONER_HMAC_KEY); `seekrit provisioner keygen` mints one").option("--admin-url <url>", "in_do: admin mysql:// connection string (or set SEEKRIT_MYSQL_ADMIN_URL); wrapped locally").option("--create-statement <sql>", "custom CREATE template (repeatable)", collect$3, []).option("--revoke-statement <sql>", "custom REVOKE template (repeatable)", collect$3, []).action(async (options) => {
 		const ctx = buildContext();
 		const org = await resolveOrg(ctx, options.org);
 		const executor = options.executor === "remote" ? "remote" : "in_do";
@@ -3603,7 +4152,7 @@ function registerMysqlCommands(program) {
 	});
 }
 /** Collect a repeatable option into an array. */
-function collect$4(value, acc) {
+function collect$3(value, acc) {
 	acc.push(value);
 	return acc;
 }
@@ -3640,7 +4189,7 @@ function generateRoleName(prefix = "tmp") {
 function registerPgCommands(program) {
 	const pg = program.command("pg").description("temporary Postgres credentials (short-lived, zero-knowledge)");
 	const target = pg.command("target").description("manage provisioning targets");
-	target.command("add").description("register a Postgres cluster to lease credentials from").requiredOption("--name <name>", "display name, e.g. prod-db").option("--org <slug>").requiredOption("--host <host>", "database host").option("--port <port>", "database port", "5432").requiredOption("--database <name>", "database to connect to").option("--access <level>", "readonly | readwrite | custom", "readonly").option("--schema <name>", "schema for preset grants", "public").option("--executor <mode>", "in_do | remote", "in_do").option("--provisioner-url <url>", "customer provisioner URL (remote executor)").option("--hmac-key <base64>", "shared HMAC key for the remote executor (or set SEEKRIT_PROVISIONER_HMAC_KEY); `seekrit provisioner keygen` mints one").option("--admin-url <url>", "in_do: admin postgres:// connection string (or set SEEKRIT_PG_ADMIN_URL); wrapped locally").option("--create-statement <sql>", "custom CREATE template (repeatable)", collect$3, []).option("--revoke-statement <sql>", "custom REVOKE template (repeatable)", collect$3, []).action(async (options) => {
+	target.command("add").description("register a Postgres cluster to lease credentials from").requiredOption("--name <name>", "display name, e.g. prod-db").option("--org <slug>").requiredOption("--host <host>", "database host").option("--port <port>", "database port", "5432").requiredOption("--database <name>", "database to connect to").option("--access <level>", "readonly | readwrite | custom", "readonly").option("--schema <name>", "schema for preset grants", "public").option("--executor <mode>", "in_do | remote", "in_do").option("--provisioner-url <url>", "customer provisioner URL (remote executor)").option("--hmac-key <base64>", "shared HMAC key for the remote executor (or set SEEKRIT_PROVISIONER_HMAC_KEY); `seekrit provisioner keygen` mints one").option("--admin-url <url>", "in_do: admin postgres:// connection string (or set SEEKRIT_PG_ADMIN_URL); wrapped locally").option("--create-statement <sql>", "custom CREATE template (repeatable)", collect$2, []).option("--revoke-statement <sql>", "custom REVOKE template (repeatable)", collect$2, []).action(async (options) => {
 		const ctx = buildContext();
 		const org = await resolveOrg(ctx, options.org);
 		const executor = options.executor === "remote" ? "remote" : "in_do";
@@ -3754,209 +4303,11 @@ function registerPgCommands(program) {
 	});
 }
 /** Collect a repeatable option into an array. */
-function collect$3(value, acc) {
+function collect$2(value, acc) {
 	acc.push(value);
 	return acc;
 }
 //#endregion
-//#region src/recovery.ts
-/** Collect a repeatable option into a list. */
-function collect$2(value, acc = []) {
-	acc.push(value);
-	return acc;
-}
-/** Resolve a custodian reference: a `skt_…` token id, otherwise a member email. */
-function resolveCustodian(ctx, orgId, ref) {
-	return ref.startsWith("skt_") ? kmsResolveRecipient(ctx, orgId, { token: ref }) : kmsResolveRecipient(ctx, orgId, { user: ref });
-}
-/**
-* The env DEK additionally wrapped to the org recovery key, when recovery is
-* enabled — so a newly created environment is recovery-protected from birth.
-* Returns undefined when recovery is off (the env is backfilled by `recovery
-* sync` later).
-*/
-async function recoveryWrapForNewEnv(ctx, orgId, dek) {
-	let recoveryPublicKeyJwk;
-	try {
-		const { recovery } = await ctx.client.getRecovery(orgId);
-		recoveryPublicKeyJwk = recovery.enabled ? recovery.recoveryPublicKeyJwk : null;
-	} catch (e) {
-		if (e instanceof SeekritApiError && (e.status === 403 || e.status === 404)) return void 0;
-		throw e;
-	}
-	if (!recoveryPublicKeyJwk) return void 0;
-	return wrapDek(dek, recoveryPublicKeyJwk);
-}
-/**
-* Wrap every environment the caller can decrypt but that lacks a recovery grant,
-* and upload the grants. Idempotent — safe to re-run and to run from several
-* admins to complete coverage.
-*/
-async function syncRecoveryGrants(ctx, orgId) {
-	const { recovery } = await ctx.client.getRecovery(orgId);
-	if (!recovery.enabled || !recovery.recoveryPublicKeyJwk) fail("recovery is not enabled");
-	const recoveryPublicKeyJwk = recovery.recoveryPublicKeyJwk;
-	const privateKey = await getPrivateKey(ctx);
-	const grants = [];
-	let skipped = 0;
-	for (const environmentId of recovery.coverage.unprotectedEnvIds) {
-		let wrappedDek;
-		try {
-			({wrappedDek} = await ctx.client.getMyEnvKey(orgId, environmentId));
-		} catch (e) {
-			if (e instanceof SeekritApiError && (e.status === 403 || e.status === 404)) {
-				skipped++;
-				continue;
-			}
-			throw e;
-		}
-		const dek = await unwrapDek(wrappedDek, privateKey);
-		grants.push({
-			environmentId,
-			wrappedDek: await wrapDek(dek, recoveryPublicKeyJwk)
-		});
-	}
-	if (grants.length > 0) await ctx.client.uploadRecoveryGrants(orgId, { grants });
-	return {
-		wrapped: grants.length,
-		skipped
-	};
-}
-/** Generate + split a fresh recovery key across the given custodians. */
-async function buildRecoveryConfig(ctx, orgId, thresholdRaw, custodianRefs) {
-	const threshold = Number.parseInt(thresholdRaw, 10);
-	if (!Number.isInteger(threshold) || threshold < 1) fail("--threshold must be a positive integer");
-	if (custodianRefs.length === 0) fail("pass at least one --custodian <email|skt_id>");
-	if (threshold > custodianRefs.length) fail("--threshold cannot exceed the number of custodians");
-	const custodians = await Promise.all(custodianRefs.map((ref) => resolveCustodian(ctx, orgId, ref)));
-	const recovery = await generateRecoveryKey();
-	const shares = await splitRecoveryKey(recovery.privateKeyJwk, threshold, custodians);
-	return {
-		recoveryPublicKeyJwk: recovery.publicKeyJwk,
-		threshold,
-		shares: shares.map((s) => ({
-			principalType: s.principalType,
-			principalId: s.principalId,
-			shareIndex: s.shareIndex,
-			wrappedShare: s.wrappedShare
-		}))
-	};
-}
-function registerRecoveryCommands(program) {
-	const recovery = program.command("recovery").description("customer-controlled M-of-N recovery (zero-knowledge)");
-	recovery.command("status").description("show recovery configuration and environment coverage").option("--org <slug>").action(async (options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		const { recovery: status } = await ctx.client.getRecovery(org.id);
-		if (!status.enabled) {
-			console.log("recovery: disabled");
-			return;
-		}
-		console.log(`recovery: enabled (${status.threshold}-of-${status.shareCount})`);
-		console.log(`coverage: ${status.coverage.protected}/${status.coverage.total} environments protected`);
-		console.log("custodians:");
-		for (const cst of status.custodians) console.log(`  - ${cst.label ?? cst.principalId} (${cst.principalType}, share #${cst.shareIndex})`);
-		if (status.coverage.unprotectedEnvIds.length > 0) console.log(`${status.coverage.unprotectedEnvIds.length} environment(s) not yet protected — run \`seekrit recovery sync\``);
-	});
-	recovery.command("setup").description("enable recovery: split a fresh recovery key across custodians").requiredOption("--threshold <M>", "custodians required to recover (M in M-of-N)").option("--custodian <email|skt_id>", "a recovery custodian (repeatable)", collect$2, []).option("--org <slug>").action(async (options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		const config = await buildRecoveryConfig(ctx, org.id, options.threshold, options.custodian);
-		await ctx.client.configureRecovery(org.id, {
-			...config,
-			grants: []
-		});
-		console.error(`recovery enabled: ${config.threshold}-of-${config.shares.length}`);
-		const { wrapped, skipped } = await syncRecoveryGrants(ctx, org.id);
-		console.error(`recovery-protected ${wrapped} environment(s) you can decrypt`);
-		if (skipped > 0) console.error(`${skipped} environment(s) need another admin to run \`seekrit recovery sync\``);
-	});
-	recovery.command("sync").description("recovery-protect environments you can decrypt but that aren't yet covered").option("--org <slug>").action(async (options) => {
-		const ctx = buildContext();
-		const { wrapped, skipped } = await syncRecoveryGrants(ctx, (await resolveOrg(ctx, options.org)).id);
-		console.error(`recovery-protected ${wrapped} environment(s); skipped ${skipped} you cannot decrypt`);
-	});
-	recovery.command("rotate").description("rotate the recovery key (new keypair, custodians, and env re-wraps)").requiredOption("--threshold <M>", "custodians required to recover (M in M-of-N)").option("--custodian <email|skt_id>", "a recovery custodian (repeatable)", collect$2, []).option("--org <slug>").action(async (options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		const config = await buildRecoveryConfig(ctx, org.id, options.threshold, options.custodian);
-		await ctx.client.rotateRecovery(org.id, {
-			...config,
-			grants: []
-		});
-		console.error(`recovery rotated: ${config.threshold}-of-${config.shares.length}`);
-		const { wrapped, skipped } = await syncRecoveryGrants(ctx, org.id);
-		console.error(`re-wrapped ${wrapped} environment(s) you can decrypt to the new recovery key`);
-		if (skipped > 0) console.error(`${skipped} environment(s) still need another admin to run \`seekrit recovery sync\``);
-	});
-	recovery.command("disable").description("disable recovery and remove all recovery grants").option("--org <slug>").action(async (options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		await ctx.client.disableRecovery(org.id);
-		console.error("recovery disabled; recovery grants removed");
-	});
-	recovery.command("request").description("start a recovery ceremony (defaults to recovering access for yourself)").option("--target-user <email>", "recover access for another member").option("--target-token <id>", "recover access for a service token").option("--reason <text>", "note recorded in the audit trail").option("--org <slug>").action(async (options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		const target = options.targetUser || options.targetToken ? await kmsResolveRecipient(ctx, org.id, {
-			user: options.targetUser,
-			token: options.targetToken
-		}) : await kmsCallerIdentity(ctx);
-		const { request } = await ctx.client.createRecoveryRequest(org.id, {
-			targetPublicKeyJwk: target.publicKeyJwk,
-			targetType: target.principalType,
-			targetId: target.principalId,
-			reason: options.reason
-		});
-		console.error(`recovery request ${request.id} created (needs ${request.threshold} custodians)`);
-		console.error(`  custodians run:  seekrit recovery approve ${request.id}`);
-		console.error(`  then the target: seekrit recovery complete ${request.id}`);
-	});
-	recovery.command("approve").description("as a custodian, contribute your share to a recovery request").argument("<requestId>").option("--org <slug>").action(async (requestId, options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		const { request } = await ctx.client.getRecoveryRequest(org.id, requestId);
-		const myShare = await ctx.client.getMyRecoveryShare(org.id);
-		const privateKey = await getPrivateKey(ctx);
-		const contributedShare = await rewrapRecoveryShare(await unwrapRecoveryShare(myShare.wrappedShare, privateKey), request.targetPublicKeyJwk);
-		const res = await ctx.client.contributeRecoveryShare(org.id, requestId, {
-			shareIndex: myShare.shareIndex,
-			contributedShare
-		});
-		console.error(`contributed share #${myShare.shareIndex}: ${res.contributed}/${res.threshold} collected${res.quorumReached ? " — quorum reached" : ""}`);
-	});
-	recovery.command("complete").description("as the recovery target, reconstruct the key and restore your access").argument("<requestId>").option("--org <slug>").action(async (requestId, options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		const { request, contributions, quorumReached } = await ctx.client.getRecoveryRequest(org.id, requestId);
-		if (!quorumReached) fail(`only ${contributions.length}/${request.threshold} custodians have contributed`);
-		const me = await kmsCallerIdentity(ctx);
-		const targetPrivateKey = await getPrivateKey(ctx);
-		const recoveryPrivateKey = await combineRecoveryShares(await Promise.all(contributions.map((cont) => unwrapRecoveryShare(cont.contributedShare, targetPrivateKey))));
-		const { grants: recoveryEnvKeys } = await ctx.client.getRecoveryEnvKeys(org.id);
-		const restored = [];
-		for (const g of recoveryEnvKeys) {
-			const dek = await unwrapDek(g.wrappedDek, recoveryPrivateKey);
-			restored.push({
-				environmentId: g.environmentId,
-				wrappedDek: await wrapDek(dek, me.publicKeyJwk)
-			});
-		}
-		await ctx.client.completeRecoveryRequest(org.id, requestId, {
-			principalType: me.principalType,
-			principalId: me.principalId,
-			grants: restored
-		});
-		console.error(`recovery complete: restored access to ${restored.length} environment(s)`);
-	});
-	recovery.command("cancel").description("cancel an open recovery request").argument("<requestId>").option("--org <slug>").action(async (requestId, options) => {
-		const ctx = buildContext();
-		const org = await resolveOrg(ctx, options.org);
-		await ctx.client.cancelRecoveryRequest(org.id, requestId);
-		console.error(`recovery request ${requestId} canceled`);
-	});
-}
-//#endregion
 //#region src/redis.ts
 /**
 * `seekrit redis` — temporary Redis (6+) credentials (Vault-style dynamic
@@ -4095,11 +4446,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,10 +4524,14 @@ 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 = {};
 	if (opts.with && Object.keys(opts.with).length > 0) query.with = opts.with;
+	if (opts.branch) query.branch = opts.branch;
 	if (!isTokenAuth(ctx)) {
 		if (!opts.envId) fail("specify --app and --env, or authenticate with a service token (SEEKRIT_TOKEN)");
 		query.env = opts.envId;
@@ -4157,17 +4542,21 @@ async function materializeEnv(ctx, opts) {
 	const provenance = {};
 	for (const layer of layers) {
 		const dek = await unwrapDek(layer.wrappedDek, privateKey);
-		const label = layer.source === "group" ? `group:${layer.groupSlug}@${layer.slug}` : `app:${scope.appSlug}/${layer.slug}`;
+		let label;
+		if (layer.source === "group") label = `group:${layer.groupSlug}@${layer.slug}`;
+		else if (layer.source === "branch") label = `branch:${scope.appSlug}#${layer.slug}`;
+		else label = `app:${scope.appSlug}/${layer.slug}`;
 		for (const secret of layer.secrets) {
 			values[secret.name] = await decryptSecret(dek, secret.ciphertext, secretAad(layer.environmentId, secret.name));
 			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 +4577,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
@@ -4512,7 +4911,7 @@ function parseVersion(raw) {
 }
 /** 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");
+	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").option("--branch <slug>", "operate on a branch of --env").requiredOption("--env <slug>", "environment slug");
 }
 const secrets = program.command("secrets").description("manage secrets in an application or group environment");
 withTarget(secrets.command("list").description("list secret names (no values)")).action(async (options) => {
@@ -4521,11 +4920,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);
@@ -4590,8 +4989,10 @@ async function materialize(ctx, options) {
 	if (!isTokenAuth(ctx)) envId = (await resolveAppEnv(ctx, options)).envId;
 	return materializeEnv(ctx, {
 		envId,
+		branch: options.branch ?? process.env.SEEKRIT_BRANCH,
 		with: options.with,
-		envFiles: options.envFile ?? [".env"]
+		envFiles: options.envFile ?? [".env"],
+		interpolate: options.interpolate
 	});
 }
 /**
@@ -4609,7 +5010,11 @@ async function materializeForRun(options) {
 		await ensureM2mAdminToken(dotenvVars);
 		const ctx = tryBuildContext(dotenvVars);
 		if (!ctx) throw new Error("no credentials found (set SEEKRIT_TOKEN / SEEKRIT_DEV_USER or run `seekrit login`)");
-		return await materialize(ctx, options);
+		const branch = options.branch ?? process.env.SEEKRIT_BRANCH ?? dotenvVars.SEEKRIT_BRANCH;
+		return await materialize(ctx, {
+			...options,
+			branch
+		});
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		console.error(`seekrit: continuing without seekrit-managed secrets: ${message}`);
@@ -4617,7 +5022,7 @@ async function materializeForRun(options) {
 		const provenance = {};
 		overlayEnvFiles(values, provenance, envFiles);
 		return {
-			values,
+			...interpolateValues(values, options.interpolate !== false),
 			provenance
 		};
 	}
@@ -4732,13 +5137,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("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice for this run", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").argument("<command...>", "command to run (prefix with -- to pass flags)").action(async (commandParts, options) => {
 	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 +5189,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("--branch <slug>", "read a branch of that environment (or $SEEKRIT_BRANCH)").option("--with <group=env>", "override one group’s slice", collectKv).option("--env-file <path>", "a .env file to overlay (repeatable; default .env)", collectList).option("--explain", "print where each variable resolved from (to stderr)").option("--no-interpolate", "leave ${OTHER_SECRET} references as literal text").option("--format <format>", "dotenv | json | shell", "dotenv").action(async (options) => {
 	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) => {
@@ -4898,6 +5309,7 @@ token.command("delete <tokenId>").description("permanently delete a revoked serv
 	await ctx.client.deleteToken(orgRef.id, tokenId);
 	console.error(`${tokenId} deleted`);
 });
+registerBranchCommands(program);
 registerPgCommands(program);
 registerMysqlCommands(program);
 registerRedisCommands(program);
@@ -4909,7 +5321,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-DLplPOvz.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) => {
@@ -4923,4 +5335,4 @@ program.parseAsync(argv).catch((err) => {
 	fail(err instanceof Error ? err.message : String(err));
 });
 //#endregion
-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 };
+export { verifyMessage as A, toBase64 as B, isServiceToken as C, importVerifyingKey as D, importSigningKey as E, kmsBlobKeyRef as F, kmsDecrypt as I, kmsEncrypt as L, generateMysqlCredential as M, generateDataKey as N, signMessage as O, generateEncryptKeyMaterial as P, wrapDek as R, createServiceToken as S, generateSigningKeyMaterial as T, parseBranchTtl as V, isTokenAuth as _, ensureM2mAdminToken as a, writeProjectConfig as b, kmsResolveKey as c, resolveAppEnv as d, resolveBranch as f, getDek as g, resolveOrg as h, materializeEnv as i, generatePostgresCredential as j, signatureKeyRef as k, kmsResolveRecipient as l, resolveGroup as m, fetchDecryptedSecrets as n, kmsCallerIdentity as o, resolveEnvTarget as p, fetchDecryptedVersion as r, kmsRecoverMaterial as s, encryptAndSetSecret as t, resolveApp as u, tryBuildContext as v, parseServiceToken as w, version as x, setFailThrows as y, generateDek as z };