@seekrit/cli 1.6.5 → 1.7.1

package/dist/index.js

@@ -852,6 +852,12 @@ const ENTITLEMENT_KEYS = Object.keys({
 		description: "Single sign-on beyond the built-in providers.",
 		default: true
 	},
+	"feature.approvals": {
+		kind: "feature",
+		label: "Approval workflows",
+		description: "Require review before a change to a protected environment lands.",
+		default: true
+	},
 	"feature.sync": {
 		kind: "feature",
 		label: "Third-party sync",
@@ -1027,6 +1033,23 @@ function parseBranchTtl(input) {
 	return value * multiplier;
 }
 //#endregion
+//#region ../../packages/core/src/change-requests.ts
+const CHANGE_REQUEST_STATUSES = [
+	"open",
+	"applied",
+	"rejected",
+	"withdrawn",
+	"superseded"
+];
+/** Human summary of a queued change, for emails and CLI output. Never a value. */
+function describeChange(kind, name, restoreFrom) {
+	switch (kind) {
+		case "set": return `set ${name}`;
+		case "delete": return `delete ${name}`;
+		case "restore": return `restore ${name} to v${restoreFrom ?? "?"}`;
+	}
+}
+//#endregion
 //#region ../../packages/core/src/dotenv.ts
 /**
 * `.env` parsing and serialization — the canonical definition of what a `.env`
@@ -1999,7 +2022,16 @@ const AUDIT_ACTIONS = [
 	"agent.policy_published",
 	"agent.policy_rolled_back",
 	"agent.task_dispatched",
-	"agent.task_revoked"
+	"agent.task_revoked",
+	"env.protection_enabled",
+	"env.protection_updated",
+	"env.protection_disabled",
+	"change_request.opened",
+	"change_request.approved",
+	"change_request.rejected",
+	"change_request.withdrawn",
+	"change_request.applied",
+	"change_request.superseded"
 ];
 /**
 * Transactional notification emails seekrit can send. Each id is one
@@ -2019,7 +2051,9 @@ const NOTIFICATION_TYPES = [
 	"lease_expired",
 	"sync_failed",
 	"honey_token_tripped",
-	"secret_rotation_failed"
+	"secret_rotation_failed",
+	"change_request_opened",
+	"change_request_decided"
 ];
 /** UI-facing copy + default for each notification type. */
 const NOTIFICATION_TYPE_META = {
@@ -2063,6 +2097,16 @@ const NOTIFICATION_TYPE_META = {
 		description: "A temporary (leased) credential you own expired and was automatically revoked.",
 		defaultEnabled: true
 	},
+	change_request_opened: {
+		label: "Change request opened",
+		description: "Someone proposed a change to a protected environment and it is waiting for review.",
+		defaultEnabled: true
+	},
+	change_request_decided: {
+		label: "Change request decided",
+		description: "A change you proposed was approved and applied, rejected, or superseded.",
+		defaultEnabled: true
+	},
 	sync_failed: {
 		label: "Third-party sync failed",
 		description: "A sync to an external destination failed repeatedly and stopped retrying. The destination is now holding stale values.",
@@ -2130,7 +2174,12 @@ z.object({
 z.object({
 	groupId: z.string().min(1),
 	/** Precedence among an env's groups (higher wins). Appended if omitted. */
-	position: z.number().int().min(0).optional()
+	position: z.number().int().min(0).optional(),
+	/** Client-wrapped group DEK for each sync connection newly reading this group. */
+	syncGrants: z.array(z.object({
+		connectionId: z.string().min(1),
+		wrappedDek: z.string().min(1)
+	})).optional()
 });
 z.object({
 	name: nameSchema,
@@ -2149,6 +2198,17 @@ z.object({
 ciphertext: z.string().min(1).max(65536) });
 z.object({ version: z.number().int().positive() });
 z.object({ limit: z.coerce.number().int().min(1).max(200).default(50) });
+z.object({
+	requiredApprovals: z.number().int().min(1).max(10).default(1),
+	allowSelfApproval: z.boolean().default(false)
+});
+z.object({ comment: z.string().trim().max(1e3).optional() });
+z.string().trim().min(1).max(1e3);
+z.object({
+	status: z.enum(CHANGE_REQUEST_STATUSES).optional(),
+	envId: z.string().min(1).optional(),
+	limit: z.coerce.number().int().min(1).max(200).default(50)
+});
 z.object({
 	publicKeyJwk: z.string().min(1),
 	/**
@@ -5055,9 +5115,18 @@ async function createAgentTaskToken() {
 }
 //#endregion
 //#region package.json
-var version = "1.6.5";
+var version = "1.7.1";
 //#endregion
 //#region ../../packages/api-client/src/index.ts
+/**
+* The proposer's note travels as a header, not a body field: an unprotected
+* environment ignores it, so the same call works either way and no caller has
+* to know in advance whether a write will be queued.
+*/
+function changeNoteHeader(note) {
+	const trimmed = note?.trim();
+	return trimmed ? { "x-seekrit-change-note": trimmed } : void 0;
+}
 var SeekritApiError = class extends Error {
 	status;
 	code;
@@ -5079,8 +5148,11 @@ var SeekritClient = class {
 		this.fetchImpl = options.fetch ?? ((...args) => fetch(...args));
 		this.client = options.client;
 	}
-	async request(method, path, body) {
-		const headers = { accept: "application/json" };
+	async request(method, path, body, extraHeaders) {
+		const headers = {
+			accept: "application/json",
+			...extraHeaders
+		};
 		if (this.client) headers["x-seekrit-client"] = this.client;
 		if (this.auth.type === "bearer") headers.authorization = `Bearer ${this.auth.token}`;
 		else if (this.auth.type === "dynamic") {
@@ -5295,11 +5367,21 @@ var SeekritClient = class {
 	listSecrets(orgId, envId) {
 		return this.request("GET", `/v1/orgs/${orgId}/envs/${envId}/secrets`);
 	}
-	setSecret(orgId, envId, name, ciphertext) {
-		return this.request("PUT", `/v1/orgs/${orgId}/envs/${envId}/secrets/${name}`, { ciphertext });
+	/**
+	* Store a ciphertext. In a **protected** environment this does not write: the
+	* server queues the change for review and answers `{ queued: true,
+	* changeRequest }` (HTTP 202). Callers must branch on `queued` — reporting
+	* success on a queued change tells someone a secret rotated when it has not.
+	*
+	* `note` is the proposer's explanation, carried as a header so it is simply
+	* ignored by an unprotected environment.
+	*/
+	setSecret(orgId, envId, name, ciphertext, note) {
+		return this.request("PUT", `/v1/orgs/${orgId}/envs/${envId}/secrets/${name}`, { ciphertext }, changeNoteHeader(note));
 	}
-	deleteSecret(orgId, envId, name) {
-		return this.request("DELETE", `/v1/orgs/${orgId}/envs/${envId}/secrets/${name}`);
+	/** Queued for review in a protected environment — see {@link setSecret}. */
+	deleteSecret(orgId, envId, name, note) {
+		return this.request("DELETE", `/v1/orgs/${orgId}/envs/${envId}/secrets/${name}`, void 0, changeNoteHeader(note));
 	}
 	/** A secret's append-only history, newest version first. */
 	listSecretVersions(orgId, envId, name, query = {}) {
@@ -5311,8 +5393,45 @@ var SeekritClient = class {
 	* ciphertext it already stores, so this appends a new version rather than
 	* rewinding, and needs no DEK on the caller's side.
 	*/
-	restoreSecret(orgId, envId, name, version) {
-		return this.request("POST", `/v1/orgs/${orgId}/envs/${envId}/secrets/${name}/restore`, { version });
+	restoreSecret(orgId, envId, name, version, note) {
+		return this.request("POST", `/v1/orgs/${orgId}/envs/${envId}/secrets/${name}/restore`, { version }, changeNoteHeader(note));
+	}
+	/** An environment's protection settings, plus how many changes are waiting. */
+	getEnvironmentProtection(orgId, envId) {
+		return this.request("GET", `/v1/orgs/${orgId}/envs/${envId}/protection`);
+	}
+	/** Protect an environment, or change its settings. Admin only. */
+	setEnvironmentProtection(orgId, envId, input = {}) {
+		return this.request("PUT", `/v1/orgs/${orgId}/envs/${envId}/protection`, input);
+	}
+	/** Take the gate down. Queued changes stay queued. Admin only. */
+	deleteEnvironmentProtection(orgId, envId) {
+		return this.request("DELETE", `/v1/orgs/${orgId}/envs/${envId}/protection`);
+	}
+	listChangeRequests(orgId, query = {}) {
+		const params = new URLSearchParams();
+		if (query.status) params.set("status", query.status);
+		if (query.envId) params.set("envId", query.envId);
+		if (query.limit) params.set("limit", String(query.limit));
+		const qs = params.size > 0 ? `?${params}` : "";
+		return this.request("GET", `/v1/orgs/${orgId}/change-requests${qs}`);
+	}
+	getChangeRequest(orgId, id) {
+		return this.request("GET", `/v1/orgs/${orgId}/change-requests/${id}`);
+	}
+	/**
+	* Approve. When this is the approval that meets the threshold the change is
+	* applied in the same call, so `status` comes back `applied` — or
+	* `superseded`, if the secret moved on since the change was proposed.
+	*/
+	approveChangeRequest(orgId, id, comment) {
+		return this.request("POST", `/v1/orgs/${orgId}/change-requests/${id}/approve`, { comment });
+	}
+	rejectChangeRequest(orgId, id, comment) {
+		return this.request("POST", `/v1/orgs/${orgId}/change-requests/${id}/reject`, { comment });
+	}
+	withdrawChangeRequest(orgId, id) {
+		return this.request("POST", `/v1/orgs/${orgId}/change-requests/${id}/withdraw`);
 	}
 	/** The calling principal's wrapped DEK for this environment. */
 	getMyEnvKey(orgId, envId) {
@@ -7265,9 +7384,15 @@ async function fetchDecryptedVersion(ctx, orgId, envId, name, version) {
 	if (!row) fail(`${name} has no version ${version} in its ${versions.length} newest versions`);
 	return decryptSecret(dek, row.ciphertext, secretAad(envId, name));
 }
-async function encryptAndSetSecret(ctx, orgId, envId, name, value) {
+/**
+* Encrypt and store one value. Returns the change request when the environment
+* is protected and the write was queued instead of stored — callers must say so
+* rather than reporting a write that has not happened.
+*/
+async function encryptAndSetSecret(ctx, orgId, envId, name, value, note) {
 	const ciphertext = await encryptSecret(await getDek(ctx, orgId, envId), value, secretAad(envId, name));
-	await ctx.client.setSecret(orgId, envId, name, ciphertext);
+	const result = await ctx.client.setSecret(orgId, envId, name, ciphertext, note);
+	return result.queued ? result.changeRequest : null;
 }
 /**
 * Encrypt and store many secrets into one environment. The DEK is fetched once
@@ -7276,16 +7401,18 @@ async function encryptAndSetSecret(ctx, orgId, envId, name, value) {
 * overwritten; the result splits them into created vs. updated for a summary.
 * Callers validate the names first — a rejected name aborts before any write.
 */
-async function importSecrets(ctx, orgId, envId, entries) {
+async function importSecrets(ctx, orgId, envId, entries, note) {
 	const [dek, { secrets }] = await Promise.all([getDek(ctx, orgId, envId), ctx.client.listSecrets(orgId, envId)]);
 	const existing = new Set(secrets.map((s) => s.name));
 	const result = {
 		created: [],
-		updated: []
+		updated: [],
+		queued: []
 	};
 	for (const [name, value] of Object.entries(entries)) {
 		const ciphertext = await encryptSecret(dek, value, secretAad(envId, name));
-		await ctx.client.setSecret(orgId, envId, name, ciphertext);
+		const written = await ctx.client.setSecret(orgId, envId, name, ciphertext, note);
+		if (written.queued) result.queued.push(written.changeRequest);
 		(existing.has(name) ? result.updated : result.created).push(name);
 	}
 	return result;
@@ -7524,6 +7651,32 @@ function registerEnvDiff(env) {
 	});
 }
 //#endregion
+//#region src/group-sync-grants.ts
+/** Wrap a newly composed group layer for connections already syncing the app env or its branches. */
+async function syncGrantsForGroupLink(ctx, orgId, envId, envSlug, groupId) {
+	const [{ groups }, { bindings }, { branches }] = await Promise.all([
+		ctx.client.listEnvGroups(orgId, envId),
+		ctx.client.listSyncBindings(orgId),
+		ctx.client.listBranches(orgId, envId)
+	]);
+	if (groups.some((group) => group.groupId === groupId)) return void 0;
+	const targets = /* @__PURE__ */ new Set([envId, ...branches.map((branch) => branch.id)]);
+	const connectionIds = new Set(bindings.filter((binding) => targets.has(binding.environmentId)).map((b) => b.connectionId));
+	if (connectionIds.size === 0) return void 0;
+	const [{ environments }, { connections }] = await Promise.all([ctx.client.listGroupEnvs(orgId, groupId), ctx.client.listSyncConnections(orgId)]);
+	const groupEnv = environments.find((entry) => entry.slug === envSlug);
+	if (!groupEnv) fail(`create a ${envSlug} environment in this group before composing it`);
+	const dek = await getDek(ctx, orgId, groupEnv.id);
+	return Promise.all([...connectionIds].map(async (connectionId) => {
+		const connection = connections.find((entry) => entry.id === connectionId);
+		if (!connection) fail("a sync connection could not be found; refresh and retry");
+		return {
+			connectionId,
+			wrappedDek: await wrapDek(dek, connection.publicKeyJwk)
+		};
+	}));
+}
+//#endregion
 //#region src/kms.ts
 /** Collect a repeatable option into a list. */
 function collect$8(value, acc = []) {
@@ -8186,9 +8339,11 @@ function registerAppCommands(program) {
 			org: options.org,
 			group: options.group
 		});
+		const syncGrants = await syncGrantsForGroupLink(ctx, target.orgId, target.envId, target.envSlug, group.id);
 		await ctx.client.linkEnvGroup(target.orgId, target.envId, {
 			groupId: group.id,
-			position: options.position === void 0 ? void 0 : Number.parseInt(options.position, 10)
+			position: options.position === void 0 ? void 0 : Number.parseInt(options.position, 10),
+			syncGrants
 		});
 		console.error(`composed ${group.slug} into ${target.appSlug}/${target.envSlug}`);
 	});
@@ -9763,6 +9918,133 @@ function registerBranchCommands(program) {
 		console.error(`deleted branch ${app.slug}#${target.slug}`);
 	});
 }
+//#endregion
+//#region src/changes.ts
+/**
+* Change requests: the review queue in front of protected environments, and the
+* protection settings that create it.
+*
+* Reviewing here is keyless by construction — a change request carries
+* ciphertext, so the CLI can show a reviewer *what* is changing and who
+* proposed it without ever holding a DEK. `seekrit changes show` therefore
+* prints no value, and deliberately does not offer to.
+*/
+function registerChangeCommands(program) {
+	const changes = program.command("changes").description("review changes queued for protected environments");
+	changes.command("list", { isDefault: true }).alias("ls").description("list change requests awaiting review").option("--org <slug>", "organization slug (defaults to seekrit.json, or your only org)").option("--status <status>", `filter by status (${CHANGE_REQUEST_STATUSES.join(", ")})`, "open").option("--all", "every status, not just open").option("--limit <n>", "entries to show (max 200)", "50").option("--json", "print the raw API response").action(async (options) => {
+		const ctx = buildContext();
+		const ref = await resolveOrg(ctx, options.org);
+		const status = options.all ? void 0 : parseStatus(options.status);
+		const limit = Number(options.limit);
+		if (!Number.isInteger(limit) || limit < 1) fail("--limit must be a positive whole number");
+		const { changeRequests } = await ctx.client.listChangeRequests(ref.id, {
+			status,
+			limit: Math.min(limit, 200)
+		});
+		emit(options, { changeRequests }, () => {
+			printTable(changeRequests, [
+				col("id", (r) => r.id),
+				col("change", (r) => describeChange(r.kind, r.secretName, r.restoreFromVersion)),
+				col("status", (r) => r.status),
+				col("proposed by", (r) => `${r.requestedByType}:${r.requestedById}`),
+				col("when", (r) => r.createdAt)
+			], options.all ? "no change requests" : "nothing waiting for review");
+		});
+	});
+	changes.command("show <id>").description("show one change request and its reviews (never its value)").option("--org <slug>", "organization slug").option("--json", "print the raw API response").action(async (id, options) => {
+		const ctx = buildContext();
+		const ref = await resolveOrg(ctx, options.org);
+		const { changeRequest, reviews } = await ctx.client.getChangeRequest(ref.id, id);
+		emit(options, {
+			changeRequest,
+			reviews
+		}, () => {
+			printFields([
+				["id", changeRequest.id],
+				["change", describeChange(changeRequest.kind, changeRequest.secretName, changeRequest.restoreFromVersion)],
+				["environment", changeRequest.environmentId],
+				["status", changeRequest.status],
+				["base version", changeRequest.baseVersion ?? "(new secret)"],
+				["approvals needed", changeRequest.requiredApprovals],
+				["proposed by", `${changeRequest.requestedByType}:${changeRequest.requestedById}`],
+				["note", changeRequest.note ?? "-"]
+			]);
+			section("reviews");
+			printTable(reviews, [
+				col("decision", (r) => r.decision),
+				col("reviewer", (r) => r.reviewerId ?? "(removed)"),
+				col("comment", (r) => r.comment ?? "-"),
+				col("when", (r) => r.createdAt)
+			], "no reviews yet");
+		});
+	});
+	changes.command("approve <id>").description("approve a queued change (applies it once it has enough approvals)").option("--org <slug>", "organization slug").option("-m, --comment <text>", "note recorded with your approval").option("--json", "print the raw API response").action(async (id, options) => {
+		const ctx = buildContext();
+		const ref = await resolveOrg(ctx, options.org);
+		const result = await ctx.client.approveChangeRequest(ref.id, id, options.comment);
+		emit(options, result, () => {
+			if (result.status === "applied") console.error(`approved and applied${result.version ? ` as v${result.version}` : ""}`);
+			else if (result.status === "superseded") console.error(`not applied: ${result.reason ?? "the secret has changed since"}`);
+			else console.error(`approved — ${result.approvals ?? 0}/${result.required ?? "?"} approvals`);
+		});
+	});
+	changes.command("reject <id>").description("reject a queued change").option("--org <slug>", "organization slug").option("-m, --comment <text>", "note recorded with your rejection").option("--json", "print the raw API response").action(async (id, options) => {
+		const ctx = buildContext();
+		const ref = await resolveOrg(ctx, options.org);
+		emit(options, await ctx.client.rejectChangeRequest(ref.id, id, options.comment), () => console.error("rejected"));
+	});
+	changes.command("withdraw <id>").description("take your own queued change off the review queue").option("--org <slug>", "organization slug").option("--json", "print the raw API response").action(async (id, options) => {
+		const ctx = buildContext();
+		const ref = await resolveOrg(ctx, options.org);
+		emit(options, await ctx.client.withdrawChangeRequest(ref.id, id), () => console.error("withdrawn"));
+	});
+	const protection = changes.command("protection").description("require review before an environment's secrets change");
+	protection.command("show", { isDefault: true }).description("show whether an environment is protected").option("--org <slug>", "organization slug").option("--app <slug>", "application slug").option("--group <slug>", "group slug (instead of --app)").option("--env <slug>", "environment slug").option("--json", "print the raw API response").action(async (options) => {
+		const ctx = buildContext();
+		const { orgId, envId, label } = await resolveEnvTarget(ctx, options);
+		const result = await ctx.client.getEnvironmentProtection(orgId, envId);
+		emit(options, result, () => {
+			if (!result.protection) {
+				console.log(`${label}: unprotected — writes land immediately`);
+				return;
+			}
+			printFields([
+				["environment", label],
+				["approvals required", result.protection.requiredApprovals],
+				["self-approval", result.protection.allowSelfApproval ? "allowed" : "not allowed"],
+				["waiting for review", result.openChangeRequests]
+			]);
+		});
+	});
+	protection.command("on").description("require approval before secrets in this environment change").option("--org <slug>", "organization slug").option("--app <slug>", "application slug").option("--group <slug>", "group slug (instead of --app)").option("--env <slug>", "environment slug").option("--approvals <n>", "approvals a change needs", "1").option("--allow-self-approval", "let the proposer's own approval count").option("--json", "print the raw API response").action(async (options) => {
+		const ctx = buildContext();
+		const { orgId, envId, label } = await resolveEnvTarget(ctx, options);
+		const requiredApprovals = Number(options.approvals);
+		if (!Number.isInteger(requiredApprovals) || requiredApprovals < 1) fail("--approvals must be a positive whole number");
+		emit(options, await ctx.client.setEnvironmentProtection(orgId, envId, {
+			requiredApprovals,
+			allowSelfApproval: options.allowSelfApproval ?? false
+		}), () => console.error(`${label} now requires ${requiredApprovals} approval${requiredApprovals === 1 ? "" : "s"} before a secret changes`));
+	});
+	protection.command("off").description("stop requiring approval (queued changes stay queued)").option("--org <slug>", "organization slug").option("--app <slug>", "application slug").option("--group <slug>", "group slug (instead of --app)").option("--env <slug>", "environment slug").option("--json", "print the raw API response").action(async (options) => {
+		const ctx = buildContext();
+		const { orgId, envId, label } = await resolveEnvTarget(ctx, options);
+		emit(options, await ctx.client.deleteEnvironmentProtection(orgId, envId), () => console.error(`${label} no longer requires approval — writes land immediately`));
+	});
+}
+function parseStatus(raw) {
+	if (!raw) return void 0;
+	if (!CHANGE_REQUEST_STATUSES.includes(raw)) fail(`unknown status "${raw}" — one of ${CHANGE_REQUEST_STATUSES.join(", ")}`);
+	return raw;
+}
+/**
+* Report a write that was queued instead of performed. Every write path calls
+* this: a CLI that printed "set FOO" for a change nobody has approved would be
+* telling the operator the deploy is ready when it is not.
+*/
+function reportQueued(cr) {
+	console.error(`queued for review: ${describeChange(cr.kind, cr.secretName, cr.restoreFromVersion)} — needs ${cr.requiredApprovals} approval${cr.requiredApprovals === 1 ? "" : "s"} (${cr.id})`);
+}
 /** Plugin id and integration id declared by `@seekrit/openclaw-plugin`. */
 const PLUGIN_ID = "seekrit";
 const PLUGIN_INTEGRATION_ID = "seekrit";
@@ -11599,7 +11881,7 @@ function collect$4(value, acc) {
 * release-please-config.json), so the pin follows the crate without anyone
 * remembering to move it.
 */
-const PROXY_VERSION = "0.12.1";
+const PROXY_VERSION = "0.12.2";
 const BIN = "seekrit-proxy";
 /**
 * Host → Rust target triple.
@@ -11635,7 +11917,7 @@ function versionPrefix(version) {
 	return version.startsWith("v") ? version : `v${version}`;
 }
 function resolveVersion(explicit) {
-	return explicit ?? process.env.SEEKRIT_PROXY_VERSION ?? "0.12.1";
+	return explicit ?? process.env.SEEKRIT_PROXY_VERSION ?? "0.12.2";
 }
 function resolveBaseUrl(explicit) {
 	return (explicit ?? process.env.SEEKRIT_PROXY_BASE_URL ?? "https://proxy.seekrit.dev").replace(/\/+$/, "");
@@ -11793,7 +12075,7 @@ const PLUGIN_BIN = "seekrit-nomad-secrets";
 * entry in release-please-config.json), so the pin follows the crate without
 * anyone remembering to move it — the same arrangement `PROXY_VERSION` has.
 */
-const NOMAD_PLUGIN_VERSION = "0.2.0";
+const NOMAD_PLUGIN_VERSION = "0.2.1";
 /** Public artifact host. Mirrors GitHub Releases; public, no egress fees. */
 const DEFAULT_BASE_URL = "https://nomad.seekrit.dev";
 /** Where the plugin reads its node config, matching `config::DEFAULT_CONFIG_PATH`. */
@@ -11880,7 +12162,7 @@ async function fetchBytes(url) {
 * let Nomad fingerprint a half-written executable.
 */
 async function installPlugin(pluginDir, options = {}) {
-	const version = options.version ?? "0.2.0";
+	const version = options.version ?? "0.2.1";
 	const baseUrl = (options.baseUrl ?? "https://nomad.seekrit.dev").replace(/\/+$/, "");
 	const { target, exe } = detectTarget();
 	if (exe !== "") fail("Nomad secret provider plugins are not supported on Windows clients");
@@ -13585,10 +13867,10 @@ Next:
 		});
 		console.log(path);
 		const { target } = detectTarget();
-		process.stderr.write(`seekrit-proxy ${versionPrefix(options.proxyVersion ?? "0.12.1")} (${target})\n`);
+		process.stderr.write(`seekrit-proxy ${versionPrefix(options.proxyVersion ?? "0.12.2")} (${target})\n`);
 	});
 	proxy.command("where").description("show which binary `seekrit proxy run` would use, without fetching it").option("--proxy-version <version>", `version to report (default: ${PROXY_VERSION})`).option("--json", "machine-readable output").action((options) => {
-		const version = options.proxyVersion ?? process.env.SEEKRIT_PROXY_VERSION ?? "0.12.1";
+		const version = options.proxyVersion ?? process.env.SEEKRIT_PROXY_VERSION ?? "0.12.2";
 		const override = process.env.SEEKRIT_PROXY_BIN;
 		const { target, exe } = detectTarget();
 		const path = override ?? proxyBinaryPath(version, target, exe);
@@ -13647,7 +13929,7 @@ Next:
 		process.stdout.write(renderComposeSnippet(plan, {
 			service: options.service,
 			workload: options.workload,
-			image: options.image ?? `seekritdev/proxy:0.12.1`,
+			image: options.image ?? `seekritdev/proxy:0.12.2`,
 			publish: Boolean(options.publish)
 		}));
 	});
@@ -15072,6 +15354,14 @@ function parseVersion(raw) {
 * line is the whole invocation for CI and for agents. `resolveEnvTarget` fills
 * it in from the token, and still insists on it for a user session.
 */
+/**
+* Attach `--note` to a command that *writes*. In a protected environment the
+* write becomes a change request, and the note is what tells the reviewer why —
+* so it is offered on every write path, and silently ignored everywhere else.
+*/
+function withNote(cmd) {
+	return cmd.option("-m, --note <text>", "why (shown to reviewers if the change needs approval)");
+}
 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").option("--branch <slug>", "operate on a branch of --env").option("--env <slug>", "environment slug (a service token infers its own)");
 }
@@ -15102,7 +15392,7 @@ withTarget(secrets.command("get <name>").description("decrypt and print one secr
 	process.stdout.write(options.pretty ? prettyJsonOrRaw(value) : value);
 	if (process.stdout.isTTY) process.stdout.write("\n");
 });
-withTarget(secrets.command("set <name> [value]").description("encrypt and store a secret (reads stdin when value is omitted or '-')").option("--file <path>", "read the value from a file — the way to store a JSON credential or a PEM key without fighting shell quoting")).action(async (name, value, options) => {
+withNote(withTarget(secrets.command("set <name> [value]").description("encrypt and store a secret (reads stdin when value is omitted or '-')").option("--file <path>", "read the value from a file — the way to store a JSON credential or a PEM key without fighting shell quoting"))).action(async (name, value, options) => {
 	if (options.file !== void 0 && value !== void 0) fail("pass a value or --file, not both");
 	const ctx = buildContext();
 	const { orgId, envId } = await resolveEnvTarget(ctx, options);
@@ -15112,10 +15402,11 @@ withTarget(secrets.command("set <name> [value]").description("encrypt and store
 		plaintext = readFileSync(options.file, "utf8").replace(/\n$/, "");
 	} else if (value === void 0 || value === "-") plaintext = (await readStdin()).replace(/\n$/, "");
 	else plaintext = value;
-	await encryptAndSetSecret(ctx, orgId, envId, name, plaintext);
-	console.error(`${name} saved`);
+	const queued = await encryptAndSetSecret(ctx, orgId, envId, name, plaintext, options.note);
+	if (queued) reportQueued(queued);
+	else console.error(`${name} saved`);
 });
-withTarget(secrets.command("import [file]").description("bulk-import secrets from a .env file (default .env; '-' reads stdin)").option("--dry-run", "list the variable names that would be imported, without writing")).action(async (file, options) => {
+withNote(withTarget(secrets.command("import [file]").description("bulk-import secrets from a .env file (default .env; '-' reads stdin)").option("--dry-run", "list the variable names that would be imported, without writing"))).action(async (file, options) => {
 	const source = file ?? ".env";
 	let content;
 	if (source === "-") content = await readStdin();
@@ -15137,8 +15428,11 @@ withTarget(secrets.command("import [file]").description("bulk-import secrets fro
 		for (const name of names.sort()) console.error(`  ${name}\t${existing.has(name) ? "update" : "new"}`);
 		return;
 	}
-	const { created, updated } = await importSecrets(ctx, orgId, envId, entries);
-	console.error(`imported ${created.length + updated.length} secret(s) into ${label} (${created.length} new, ${updated.length} updated)`);
+	const { created, updated, queued } = await importSecrets(ctx, orgId, envId, entries, options.note);
+	if (queued.length > 0) {
+		console.error(`${queued.length} change(s) queued for review in ${label} — nothing has changed yet`);
+		for (const cr of queued) reportQueued(cr);
+	} else console.error(`imported ${created.length + updated.length} secret(s) into ${label} (${created.length} new, ${updated.length} updated)`);
 });
 withTarget(secrets.command("history <name>").description("list a secret's versions (metadata only — no values)").option("--limit <n>", `how many versions to show (max 200)`, "20").option("--json", "print the raw API response")).action(async (name, options) => {
 	const ctx = buildContext();
@@ -15154,18 +15448,20 @@ withTarget(secrets.command("history <name>").description("list a secret's versio
 		col("note", (v) => [v.version === currentVersion ? "current" : null, v.restoredFromVersion === null ? null : `restored from v${v.restoredFromVersion}`].filter(Boolean).join(", "))
 	], `no versions of ${name}`));
 });
-withTarget(secrets.command("restore <name> <version>").description("roll a secret back to an earlier version (stored as a new version)")).action(async (name, version, options) => {
+withNote(withTarget(secrets.command("restore <name> <version>").description("roll a secret back to an earlier version (stored as a new version)"))).action(async (name, version, options) => {
 	const ctx = buildContext();
 	const { orgId, envId } = await resolveEnvTarget(ctx, options);
-	const { secret, restoredFrom } = await ctx.client.restoreSecret(orgId, envId, name, parseVersion(version));
-	console.error(`${name} restored from v${restoredFrom} — now v${secret.version}`);
+	const result = await ctx.client.restoreSecret(orgId, envId, name, parseVersion(version), options.note);
+	if (result.queued) reportQueued(result.changeRequest);
+	else console.error(`${name} restored from v${result.restoredFrom} — now v${result.secret.version}`);
 });
-withTarget(secrets.command("rm <name>").description("delete a secret and its whole version history").option("-y, --yes", "skip the confirmation")).action(async (name, options) => {
+withNote(withTarget(secrets.command("rm <name>").description("delete a secret and its whole version history").option("-y, --yes", "skip the confirmation"))).action(async (name, options) => {
 	const ctx = buildContext();
 	const { orgId, envId, label } = await resolveEnvTarget(ctx, options);
 	await confirmDestructive(options.yes, `Delete ${name} from ${label}, including every earlier version? This cannot be undone.`);
-	await ctx.client.deleteSecret(orgId, envId, name);
-	console.error(`${name} deleted`);
+	const removed = await ctx.client.deleteSecret(orgId, envId, name, options.note);
+	if (removed.queued) reportQueued(removed.changeRequest);
+	else console.error(`${name} deleted`);
 });
 /**
 * Open the last-known-good cache for this request, or `undefined` when it is
@@ -15514,6 +15810,7 @@ token.command("delete <tokenId>").description("permanently delete a revoked serv
 	console.error(`${tokenId} deleted`);
 });
 registerBranchCommands(program);
+registerChangeCommands(program);
 registerPgCommands(program);
 registerMysqlCommands(program);
 registerRedisCommands(program);
@@ -15532,7 +15829,7 @@ registerKmsCommands(program);
 registerRotationCommands(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-BvXwiGRv.js");
+	const { runMcpServer } = await import("./mcp-ZYu1Q6Ft.js");
 	await runMcpServer();
 });
 registerAuditCommands(program);
@@ -15547,4 +15844,4 @@ program.parseAsync(argv).catch((err) => {
 	fail(describeError(err));
 });
 //#endregion
-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 _, kmsResolveRecipient as a, writeProjectConfig as b, fetchDecryptedVersion as c, resolveAppEnv as d, resolveBranch as f, getDek as g, resolveOrg as h, kmsResolveKey as i, generatePostgresCredential as j, signatureKeyRef as k, materializeEnv as l, resolveGroup as m, kmsCallerIdentity as n, encryptAndSetSecret as o, resolveEnvTarget as p, kmsRecoverMaterial as r, fetchDecryptedSecrets as s, ensureM2mAdminToken as t, resolveApp as u, tryBuildContext as v, parseServiceToken as w, version as x, setFailThrows as y, generateDek as z };
+export { signatureKeyRef as A, generateDek as B, createServiceToken as C, importSigningKey as D, generateSigningKeyMaterial as E, generateEncryptKeyMaterial as F, parseBranchTtl as H, kmsBlobKeyRef as I, kmsDecrypt as L, generatePostgresCredential as M, generateMysqlCredential as N, importVerifyingKey as O, generateDataKey as P, kmsEncrypt as R, version as S, parseServiceToken as T, toBase64 as V, getDek as _, kmsResolveRecipient as a, setFailThrows as b, fetchDecryptedSecrets as c, resolveApp as d, resolveAppEnv as f, resolveOrg as g, resolveGroup as h, kmsResolveKey as i, verifyMessage as j, signMessage as k, fetchDecryptedVersion as l, resolveEnvTarget as m, kmsCallerIdentity as n, syncGrantsForGroupLink as o, resolveBranch as p, kmsRecoverMaterial as r, encryptAndSetSecret as s, ensureM2mAdminToken as t, materializeEnv as u, isTokenAuth as v, isServiceToken as w, writeProjectConfig as x, tryBuildContext as y, wrapDek as z };

package/dist/{mcp-BvXwiGRv.js → mcp-ZYu1Q6Ft.js}

@@ -1,4 +1,4 @@
-import { A as verifyMessage, B as toBase64, C as isServiceToken, D as importVerifyingKey, E as importSigningKey, F as kmsBlobKeyRef, I as kmsDecrypt, L as kmsEncrypt, M as generateMysqlCredential, N as generateDataKey, O as signMessage, P as generateEncryptKeyMaterial, R as wrapDek, S as createServiceToken, T as generateSigningKeyMaterial, V as parseBranchTtl, _ as isTokenAuth, a as kmsResolveRecipient, b as writeProjectConfig, c as fetchDecryptedVersion, d as resolveAppEnv, f as resolveBranch, g as getDek, h as resolveOrg, i as kmsResolveKey, j as generatePostgresCredential, k as signatureKeyRef, l as materializeEnv, m as resolveGroup, n as kmsCallerIdentity, o as encryptAndSetSecret, p as resolveEnvTarget, r as kmsRecoverMaterial, s as fetchDecryptedSecrets, t as ensureM2mAdminToken, u as resolveApp, v as tryBuildContext, w as parseServiceToken, x as version, y as setFailThrows, z as generateDek } from "./index.js";
+import { A as signatureKeyRef, B as generateDek, C as createServiceToken, D as importSigningKey, E as generateSigningKeyMaterial, F as generateEncryptKeyMaterial, H as parseBranchTtl, I as kmsBlobKeyRef, L as kmsDecrypt, M as generatePostgresCredential, N as generateMysqlCredential, O as importVerifyingKey, P as generateDataKey, R as kmsEncrypt, S as version, T as parseServiceToken, V as toBase64, _ as getDek, a as kmsResolveRecipient, b as setFailThrows, c as fetchDecryptedSecrets, d as resolveApp, f as resolveAppEnv, g as resolveOrg, h as resolveGroup, i as kmsResolveKey, j as verifyMessage, k as signMessage, l as fetchDecryptedVersion, m as resolveEnvTarget, n as kmsCallerIdentity, o as syncGrantsForGroupLink, p as resolveBranch, r as kmsRecoverMaterial, s as encryptAndSetSecret, t as ensureM2mAdminToken, u as materializeEnv, v as isTokenAuth, w as isServiceToken, x as writeProjectConfig, y as tryBuildContext, z as wrapDek } from "./index.js";
 import { spawn } from "node:child_process";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -621,9 +621,11 @@ async function runMcpServer(options = {}) {
 			org,
 			group
 		});
+		const syncGrants = await syncGrantsForGroupLink(ctx, target.orgId, target.envId, target.envSlug, g.id);
 		return (await ctx.client.linkEnvGroup(target.orgId, target.envId, {
 			groupId: g.id,
-			position
+			position,
+			syncGrants
 		})).group;
 	});
 	tool("uncompose_group", "Remove a composed group from an application environment.", { idempotent: true }, {
@@ -645,16 +647,23 @@ async function runMcpServer(options = {}) {
 		await ctx.client.unlinkEnvGroup(target.orgId, target.envId, g.id);
 		return { ok: true };
 	});
-	tool("set_secret", "Encrypt a value locally and store it in an environment. A value may reference another secret as ${OTHER_SECRET}: the reference is stored literally and expanded whenever the secret is read, so it tracks the referenced value. Write $${OTHER_SECRET} for a literal.", { idempotent: false }, {
+	tool("set_secret", "Encrypt a value locally and store it in an environment. A value may reference another secret as ${OTHER_SECRET}: the reference is stored literally and expanded whenever the secret is read, so it tracks the referenced value. Write $${OTHER_SECRET} for a literal. If the environment requires approval the write is QUEUED, not stored: the result carries queued:true and a changeRequestId, and the secret keeps its old value until a human approves.", { idempotent: false }, {
 		...targetShape,
 		name: z.string(),
-		value: z.string()
+		value: z.string(),
+		note: z.string().optional()
 	}, async (o) => {
 		const ctx = getCtx();
 		ensureDecryptable(ctx);
 		const { orgId, envId } = await resolveEnvTarget(ctx, o);
-		await encryptAndSetSecret(ctx, orgId, envId, o.name, o.value);
-		return {
+		const queued = await encryptAndSetSecret(ctx, orgId, envId, o.name, o.value, o.note);
+		return queued ? {
+			ok: true,
+			queued: true,
+			name: o.name,
+			changeRequestId: queued.id,
+			requiredApprovals: queued.requiredApprovals
+		} : {
 			ok: true,
 			name: o.name
 		};
@@ -717,26 +726,38 @@ async function runMcpServer(options = {}) {
 	tool("restore_secret", "Roll a secret back to an earlier version. The stored ciphertext is replayed as a NEW version (history is append-only, nothing is overwritten). Keyless — no decryption happens, so this works even without a key.", { idempotent: false }, {
 		...targetShape,
 		name: z.string(),
-		version: z.number().int().positive()
+		version: z.number().int().positive(),
+		note: z.string().optional()
 	}, async (o) => {
 		const ctx = getCtx();
 		const { orgId, envId } = await resolveEnvTarget(ctx, o);
-		const { secret, restoredFrom } = await ctx.client.restoreSecret(orgId, envId, o.name, o.version);
-		return {
+		const result = await ctx.client.restoreSecret(orgId, envId, o.name, o.version, o.note);
+		return result.queued ? {
+			ok: true,
+			queued: true,
+			name: o.name,
+			changeRequestId: result.changeRequest.id
+		} : {
 			ok: true,
 			name: o.name,
-			restoredFrom,
-			version: secret.version
+			restoredFrom: result.restoredFrom,
+			version: result.secret.version
 		};
 	});
 	tool("delete_secret", "Delete a secret from an environment.", destructive, {
 		...targetShape,
-		name: z.string()
+		name: z.string(),
+		note: z.string().optional()
 	}, async (o) => {
 		const ctx = getCtx();
 		const { orgId, envId } = await resolveEnvTarget(ctx, o);
-		await ctx.client.deleteSecret(orgId, envId, o.name);
-		return {
+		const removed = await ctx.client.deleteSecret(orgId, envId, o.name, o.note);
+		return removed.queued ? {
+			ok: true,
+			queued: true,
+			name: o.name,
+			changeRequestId: removed.changeRequest.id
+		} : {
 			ok: true,
 			name: o.name
 		};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seekrit/cli",
-  "version": "1.6.5",
+  "version": "1.7.1",
   "description": "End-to-end encrypted secrets manager CLI — inject decrypted secrets into any command.",
   "type": "module",
   "publishConfig": {
@@ -24,12 +24,12 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "commander": "^15.0.0",
-    "zod": "^4.6.2"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.1",
     "tsdown": "^0.23.0",
-    "vitest": "^4.1.11",
+    "vitest": "^5.0.1",
     "@seekrit/api-client": "0.0.1",
     "@seekrit/core": "0.0.1",
     "@seekrit/crypto": "0.0.1"