@seekrit/cli 0.17.2 → 0.18.0

package/dist/index.js

@@ -682,7 +682,13 @@ z.object({
 	name: nameSchema,
 	slug: slugSchema,
 	/** Environment DEK wrapped to the creator's public key — created client-side. */
-	wrappedDek: z.string().min(1)
+	wrappedDek: z.string().min(1),
+	/**
+	* When the org has recovery enabled, the same DEK additionally wrapped to the
+	* org recovery public key, so the environment is recovery-protected from
+	* creation. Omitted when recovery is off (backfilled later by `recovery sync`).
+	*/
+	recoveryWrappedDek: z.string().min(1).nullish()
 });
 z.object({ 
 /** Opaque versioned ciphertext blob from @seekrit/crypto. */
@@ -758,6 +764,55 @@ z.object({
 	publicKeyJwk: z.string().min(1).nullish(),
 	grants: z.array(kmsGrantInputSchema).min(1)
 });
+/**
+* One custodian's wrapped Shamir share of the org recovery private key. The
+* client generates the recovery keypair, splits the private half M-of-N, and
+* wraps each share to a custodian's public key — the server stores only the
+* opaque `wrappedShare` and can reconstruct nothing.
+*/
+const recoveryShareInputSchema = z.object({
+	principalType: principalTypeSchema,
+	principalId: z.string().min(1),
+	/** Shamir x-coordinate carried by the share (1..255). */
+	shareIndex: z.number().int().min(1).max(255),
+	/** The recovery-key share wrapped to the custodian's public key (`wd1.`). */
+	wrappedShare: z.string().min(1)
+});
+/** An environment DEK additionally wrapped to the org recovery public key. */
+const recoveryEnvGrantSchema = z.object({
+	environmentId: z.string().min(1),
+	/** The environment's DEK wrapped to the recovery public key (`wd1.`). */
+	wrappedDek: z.string().min(1)
+});
+z.object({
+	recoveryPublicKeyJwk: z.string().min(1),
+	threshold: z.number().int().min(1).max(255),
+	shares: z.array(recoveryShareInputSchema).min(1).max(255),
+	grants: z.array(recoveryEnvGrantSchema).default([])
+}).refine((v) => v.threshold <= v.shares.length, {
+	message: "threshold cannot exceed the number of custodians",
+	path: ["threshold"]
+}).refine((v) => new Set(v.shares.map((s) => `${s.principalType}:${s.principalId}`)).size === v.shares.length, {
+	message: "custodians must be distinct",
+	path: ["shares"]
+});
+z.object({ grants: z.array(recoveryEnvGrantSchema).min(1).max(500) });
+z.object({
+	targetPublicKeyJwk: z.string().min(1),
+	targetType: principalTypeSchema.nullish(),
+	targetId: z.string().min(1).nullish(),
+	reason: z.string().max(500).nullish()
+});
+z.object({
+	shareIndex: z.number().int().min(1).max(255),
+	/** The custodian's share re-wrapped to the target public key (`wd1.`). */
+	contributedShare: z.string().min(1)
+});
+z.object({
+	principalType: principalTypeSchema,
+	principalId: z.string().min(1),
+	grants: z.array(recoveryEnvGrantSchema).min(1).max(500)
+});
 z.object({ prefs: z.partialRecord(z.enum(NOTIFICATION_TYPES), z.boolean()) });
 z.object({
 	endpoint: z.url().max(2048),
@@ -1343,6 +1398,191 @@ async function decryptPrivateKey(passphrase, blob) {
 	}
 }
 //#endregion
+//#region ../../packages/crypto/src/shamir.ts
+/**
+* Shamir's Secret Sharing over GF(2^8) — the same field AES uses, with the
+* reduction polynomial x^8 + x^4 + x^3 + x + 1 (0x11b). Splits a byte string
+* into `shares` shares such that any `threshold` of them reconstruct the secret
+* exactly and any fewer reveal nothing about it.
+*
+* This is the one hand-rolled primitive behind org recovery (P0-1): the org
+* recovery private key is split into shares, each wrapped to a designated
+* custodian's public key, so a quorum — never seekrit, never any single
+* custodian below the threshold — can reconstruct it. See recovery.ts for the
+* composition with key wrapping.
+*
+* Each secret byte gets its own degree-(threshold-1) polynomial whose constant
+* term is that byte; a share is that polynomial family evaluated at one distinct
+* nonzero x-coordinate. Reconstruction is Lagrange interpolation back to x = 0.
+*
+* Share wire format: a Uint8Array whose first byte is the share's distinct
+* nonzero x-coordinate and whose remaining bytes are the evaluations p_j(x) for
+* each secret byte j. Self-describing, so combineSecret() needs no external
+* index — the x-coordinate survives being wrapped/unwrapped/re-wrapped intact.
+*/
+/** Russian-peasant multiply in GF(2^8) (mod 0x11b) — used only to seed tables. */
+function peasantMul(a, b) {
+	let product = 0;
+	let x = a;
+	let y = b;
+	for (let i = 0; i < 8; i++) {
+		if (y & 1) product ^= x;
+		const carry = x & 128;
+		x = x << 1 & 255;
+		if (carry) x ^= 27;
+		y >>= 1;
+	}
+	return product;
+}
+const EXP = /* @__PURE__ */ new Uint8Array(512);
+const LOG = /* @__PURE__ */ new Uint8Array(256);
+{
+	let a = 1;
+	for (let i = 0; i < 255; i++) {
+		EXP[i] = a;
+		LOG[a] = i;
+		a = peasantMul(a, 3);
+	}
+	for (let i = 255; i < 512; i++) EXP[i] = EXP[i - 255];
+}
+/** Multiply in GF(2^8) via the log/exp tables. */
+function mul(a, b) {
+	if (a === 0 || b === 0) return 0;
+	return EXP[LOG[a] + LOG[b]];
+}
+/** Divide in GF(2^8) (a / b). Caller guarantees b !== 0. */
+function div(a, b) {
+	if (a === 0) return 0;
+	return EXP[LOG[a] + 255 - LOG[b]];
+}
+/** Evaluate a polynomial (coeffs low-degree-first) at x, via Horner's rule. */
+function evalPoly(coeffs, x) {
+	let result = 0;
+	for (let i = coeffs.length - 1; i >= 0; i--) result = mul(result, x) ^ coeffs[i];
+	return result;
+}
+/**
+* Split `secret` into `shares` shares, any `threshold` of which reconstruct it.
+* x-coordinates are 1..shares, so shares must be in 1..255 and threshold in
+* 1..shares. threshold = shares means every share is needed; threshold = 1 is
+* the degenerate case where each share equals the secret (the "single recovery
+* admin" configuration).
+*/
+function splitSecret(secret, threshold, shares) {
+	if (secret.length < 1) throw new SeekritCryptoError("MALFORMED_BLOB", "cannot split an empty secret");
+	if (!Number.isInteger(threshold) || !Number.isInteger(shares) || threshold < 1 || shares < threshold || shares > 255) throw new SeekritCryptoError("MALFORMED_BLOB", `invalid Shamir parameters: need 1 <= threshold (${threshold}) <= shares (${shares}) <= 255`);
+	const out = [];
+	for (let s = 0; s < shares; s++) {
+		const share = new Uint8Array(1 + secret.length);
+		share[0] = s + 1;
+		out.push(share);
+	}
+	const randomCoeffs = threshold > 1 ? crypto.getRandomValues(new Uint8Array(secret.length * (threshold - 1))) : /* @__PURE__ */ new Uint8Array(0);
+	const coeffs = new Uint8Array(threshold);
+	for (let j = 0; j < secret.length; j++) {
+		coeffs[0] = secret[j];
+		for (let k = 1; k < threshold; k++) coeffs[k] = randomCoeffs[j * (threshold - 1) + (k - 1)];
+		for (const share of out) share[1 + j] = evalPoly(coeffs, share[0]);
+	}
+	return out;
+}
+/**
+* Reconstruct a secret from shares in the {@link splitSecret} wire format.
+* Supplying at least `threshold` valid shares returns the original secret;
+* fewer returns a plausible-but-wrong value (that is the security property —
+* downstream key use is what actually verifies the result). Shares must be the
+* same length and carry distinct nonzero x-coordinates.
+*/
+function combineSecret(shares) {
+	if (shares.length < 1) throw new SeekritCryptoError("MALFORMED_BLOB", "need at least one share to combine");
+	const width = shares[0].length;
+	if (width < 2) throw new SeekritCryptoError("MALFORMED_BLOB", "share is too short to carry a secret");
+	const xs = new Uint8Array(shares.length);
+	for (let i = 0; i < shares.length; i++) {
+		const share = shares[i];
+		if (share.length !== width) throw new SeekritCryptoError("MALFORMED_BLOB", "shares have mismatched lengths");
+		const x = share[0];
+		if (x === 0) throw new SeekritCryptoError("MALFORMED_BLOB", "share has an invalid zero x-coordinate");
+		for (let p = 0; p < i; p++) if (xs[p] === x) throw new SeekritCryptoError("MALFORMED_BLOB", "shares have duplicate x-coordinates");
+		xs[i] = x;
+	}
+	const basis = new Uint8Array(shares.length);
+	for (let i = 0; i < shares.length; i++) {
+		const xi = xs[i];
+		let num = 1;
+		let den = 1;
+		for (let m = 0; m < shares.length; m++) {
+			if (m === i) continue;
+			const xm = xs[m];
+			num = mul(num, xm);
+			den = mul(den, xi ^ xm);
+		}
+		basis[i] = div(num, den);
+	}
+	const secret = new Uint8Array(width - 1);
+	for (let j = 0; j < secret.length; j++) {
+		let acc = 0;
+		for (let i = 0; i < shares.length; i++) acc ^= mul(shares[i][1 + j], basis[i]);
+		secret[j] = acc;
+	}
+	return secret;
+}
+//#endregion
+//#region ../../packages/crypto/src/recovery.ts
+/** Generate a fresh org recovery keypair (P-256, same as any principal). */
+function generateRecoveryKey() {
+	return generateKeyPair();
+}
+/**
+* Split a recovery private key into one wrapped share per custodian, such that
+* any `threshold` custodians can reconstruct it. The share count is the number
+* of custodians.
+*/
+async function splitRecoveryKey(privateKeyJwk, threshold, custodians) {
+	if (custodians.length < 1) throw new SeekritCryptoError("MALFORMED_BLOB", "recovery needs at least one custodian");
+	const shares = splitSecret(utf8Encode(privateKeyJwk), threshold, custodians.length);
+	return Promise.all(custodians.map(async (custodian, i) => {
+		const share = shares[i];
+		return {
+			principalType: custodian.principalType,
+			principalId: custodian.principalId,
+			shareIndex: share[0],
+			wrappedShare: await wrapDek(share, custodian.publicKeyJwk)
+		};
+	}));
+}
+/**
+* Unwrap a single recovery share with the holder's private key, returning the
+* raw share bytes. Used by a custodian to unlock their own share, and by a
+* recovery target to unlock a share re-wrapped to them — both are plain
+* {@link unwrapDek}, since a share is just wrapped bytes.
+*/
+function unwrapRecoveryShare(wrappedShare, privateKey) {
+	return unwrapDek(wrappedShare, privateKey);
+}
+/**
+* Re-wrap an already-unwrapped share to a recovery target's public key. This is
+* the custodian's contribution during a recovery ceremony: the server collects
+* a quorum of shares all wrapped to the target, none of which it can read.
+*/
+function rewrapRecoveryShare(shareBytes, targetPublicKeyJwk) {
+	return wrapDek(shareBytes, targetPublicKeyJwk);
+}
+/**
+* Combine a quorum of unwrapped shares back into the recovery private key,
+* imported and ready to unwrap DEK recovery grants. Fewer than the threshold, or
+* shares from different recovery keys, yield garbage that fails to import or
+* decrypt — surfaced as DECRYPT_FAILED, never a silent wrong key.
+*/
+async function combineRecoveryShares(shareBytes) {
+	const privateKeyJwk = utf8Decode(combineSecret(shareBytes));
+	try {
+		return await importPrivateKey(privateKeyJwk);
+	} catch {
+		throw new SeekritCryptoError("DECRYPT_FAILED", "recovery reconstruction failed: wrong, insufficient, or mismatched shares");
+	}
+}
+//#endregion
 //#region ../../packages/crypto/src/redis.ts
 /**
 * Client-side construction of a Redis (6+) ACL password verifier, for minting
@@ -1721,7 +1961,7 @@ function isServiceToken(value) {
 }
 //#endregion
 //#region package.json
-var version = "0.17.2";
+var version = "0.18.0";
 //#endregion
 //#region ../../packages/api-client/src/index.ts
 var SeekritApiError = class extends Error {
@@ -1896,6 +2136,53 @@ var SeekritClient = class {
 	revokeEnvKey(orgId, envId, grantId) {
 		return this.request("DELETE", `/v1/orgs/${orgId}/envs/${envId}/keys/${grantId}`);
 	}
+	/** Org recovery status: threshold, custodians, and environment coverage. */
+	getRecovery(orgId) {
+		return this.request("GET", `/v1/orgs/${orgId}/recovery`);
+	}
+	/** Enable recovery with the recovery public key, custodian shares, and grants. */
+	configureRecovery(orgId, input) {
+		return this.request("POST", `/v1/orgs/${orgId}/recovery`, input);
+	}
+	/** Rotate the recovery key: new keypair, custodian set, and env re-wraps. */
+	rotateRecovery(orgId, input) {
+		return this.request("POST", `/v1/orgs/${orgId}/recovery/rotate`, input);
+	}
+	disableRecovery(orgId) {
+		return this.request("DELETE", `/v1/orgs/${orgId}/recovery`);
+	}
+	/** The calling principal's own wrapped recovery share (custodian only). */
+	getMyRecoveryShare(orgId) {
+		return this.request("GET", `/v1/orgs/${orgId}/recovery/share`);
+	}
+	/** Every environment DEK wrapped to the org recovery key (admin only). */
+	getRecoveryEnvKeys(orgId) {
+		return this.request("GET", `/v1/orgs/${orgId}/recovery/env-keys`);
+	}
+	/** Backfill recovery grants for environments the caller can decrypt. */
+	uploadRecoveryGrants(orgId, input) {
+		return this.request("POST", `/v1/orgs/${orgId}/recovery/grants`, input);
+	}
+	listRecoveryRequests(orgId) {
+		return this.request("GET", `/v1/orgs/${orgId}/recovery/requests`);
+	}
+	createRecoveryRequest(orgId, input) {
+		return this.request("POST", `/v1/orgs/${orgId}/recovery/requests`, input);
+	}
+	getRecoveryRequest(orgId, requestId) {
+		return this.request("GET", `/v1/orgs/${orgId}/recovery/requests/${requestId}`);
+	}
+	/** A custodian contributes their share, re-wrapped to the request target. */
+	contributeRecoveryShare(orgId, requestId, input) {
+		return this.request("POST", `/v1/orgs/${orgId}/recovery/requests/${requestId}/shares`, input);
+	}
+	/** The target finalizes recovery, re-granting itself the recovered DEKs. */
+	completeRecoveryRequest(orgId, requestId, input) {
+		return this.request("POST", `/v1/orgs/${orgId}/recovery/requests/${requestId}/complete`, input);
+	}
+	cancelRecoveryRequest(orgId, requestId) {
+		return this.request("POST", `/v1/orgs/${orgId}/recovery/requests/${requestId}/cancel`);
+	}
 	listTokens(orgId) {
 		return this.request("GET", `/v1/orgs/${orgId}/tokens`);
 	}
@@ -2586,7 +2873,7 @@ function registerGcpCommands(program) {
 //#endregion
 //#region src/kms.ts
 /** Collect a repeatable option into a list. */
-function collect$5(value, acc = []) {
+function collect$6(value, acc = []) {
 	acc.push(value);
 	return acc;
 }
@@ -2654,7 +2941,7 @@ async function kmsRecoverMaterial(ctx, orgId, keyId, version) {
 }
 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$5, []).option("--grant-token <tokenId>", "also grant a service token (repeatable)", collect$5, []).action(async (options) => {
+	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();
@@ -2888,7 +3175,7 @@ function parseTtlSeconds$4(input) {
 	}[m[2] || "s"] ?? 1);
 }
 /** Collect a repeatable option into an array. */
-function collect$4(value, previous) {
+function collect$5(value, previous) {
 	return [...previous, value];
 }
 /** Parse `readWrite@app` → { role, db } for a custom target. */
@@ -2913,7 +3200,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$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) => {
+	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) => {
 		const ctx = buildContext();
 		const org = await resolveOrg(ctx, options.org);
 		const adminUri = resolveAdminUri(options.uri);
@@ -3073,7 +3360,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$3, []).option("--revoke-statement <sql>", "custom REVOKE template (repeatable)", collect$3, []).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$4, []).option("--revoke-statement <sql>", "custom REVOKE template (repeatable)", collect$4, []).action(async (options) => {
 		const ctx = buildContext();
 		const org = await resolveOrg(ctx, options.org);
 		const executor = options.executor === "remote" ? "remote" : "in_do";
@@ -3174,7 +3461,7 @@ function registerMysqlCommands(program) {
 	});
 }
 /** Collect a repeatable option into an array. */
-function collect$3(value, acc) {
+function collect$4(value, acc) {
 	acc.push(value);
 	return acc;
 }
@@ -3211,7 +3498,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$2, []).option("--revoke-statement <sql>", "custom REVOKE template (repeatable)", collect$2, []).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$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";
@@ -3325,11 +3612,209 @@ function registerPgCommands(program) {
 	});
 }
 /** Collect a repeatable option into an array. */
-function collect$2(value, acc) {
+function collect$3(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
@@ -3792,11 +4277,14 @@ env.command("create").description("create an application environment (generates
 	if (!appRow) fail(`no app "${options.app}" in ${orgRef.slug}`);
 	const { user } = await ctx.client.me();
 	if (!user.publicKeyJwk) fail("run `seekrit keys setup` first");
-	const wrappedDek = await wrapDek(generateDek(), user.publicKeyJwk);
+	const dek = generateDek();
+	const wrappedDek = await wrapDek(dek, user.publicKeyJwk);
+	const recoveryWrappedDek = await recoveryWrapForNewEnv(ctx, orgRef.id, dek);
 	const created = await ctx.client.createEnv(orgRef.id, appRow.id, {
 		name: options.name,
 		slug: options.slug,
-		wrappedDek
+		wrappedDek,
+		recoveryWrappedDek
 	});
 	console.error(`created environment ${created.environment.slug} (${created.environment.id})`);
 });
@@ -3848,11 +4336,14 @@ group.command("env").description("manage a group’s environments (per-slug valu
 	});
 	const { user } = await ctx.client.me();
 	if (!user.publicKeyJwk) fail("run `seekrit keys setup` first");
-	const wrappedDek = await wrapDek(generateDek(), user.publicKeyJwk);
+	const dek = generateDek();
+	const wrappedDek = await wrapDek(dek, user.publicKeyJwk);
+	const recoveryWrappedDek = await recoveryWrapForNewEnv(ctx, groupRef.orgId, dek);
 	const created = await ctx.client.createGroupEnv(groupRef.orgId, groupRef.id, {
 		name: options.name,
 		slug: options.slug,
-		wrappedDek
+		wrappedDek,
+		recoveryWrappedDek
 	});
 	console.error(`created ${groupRef.slug}@${created.environment.slug} (${created.environment.id})`);
 });
@@ -4096,6 +4587,7 @@ registerAwsCommands(program);
 registerGcpCommands(program);
 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-CVhEQDfd.js");
 	await runMcpServer();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seekrit/cli",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "End-to-end encrypted secrets manager CLI — inject decrypted secrets into any command.",
   "type": "module",
   "publishConfig": {