@seekrit/mcp 0.5.0 → 0.6.1

package/dist/index.js

@@ -8,6 +8,1138 @@ import { homedir } from "node:os";
 import { dirname, join, parse } from "node:path";
 import { createInterface } from "node:readline";
 import { Writable } from "node:stream";
+/** All catalog keys as a runtime array (for iteration / zod enums). */
+const ENTITLEMENT_KEYS = Object.keys({
+	"feature.kms": {
+		kind: "feature",
+		label: "Managed keys (KMS)",
+		description: "Client-side managed keys for application-layer encryption and signing.",
+		default: true
+	},
+	"feature.leases": {
+		kind: "feature",
+		label: "Temporary access",
+		description: "Vault-style short-lived database and cloud credentials.",
+		default: true
+	},
+	"feature.log_sink": {
+		kind: "feature",
+		label: "Audit log export (SIEM)",
+		description: "Stream the audit log to an external OTLP collector.",
+		default: true
+	},
+	"feature.proxy": {
+		kind: "feature",
+		label: "Agent egress proxy",
+		description: "Substitute secrets into outbound requests for untrusted workloads.",
+		default: true
+	},
+	"feature.sso": {
+		kind: "feature",
+		label: "SSO / SAML",
+		description: "Single sign-on beyond the built-in providers.",
+		default: true
+	},
+	"feature.sync": {
+		kind: "feature",
+		label: "Third-party sync",
+		description: "Push environment secrets to external platforms like Vercel.",
+		default: true
+	},
+	"apps.max": {
+		kind: "limit",
+		label: "Applications",
+		description: "Maximum applications in the organization.",
+		default: null
+	},
+	"envs.per_app.max": {
+		kind: "limit",
+		label: "Environments per application",
+		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",
+		description: "Maximum secrets in a single environment.",
+		default: null
+	},
+	"groups.max": {
+		kind: "limit",
+		label: "Groups",
+		description: "Maximum reusable secret groups in the organization.",
+		default: null
+	},
+	"tokens.max": {
+		kind: "limit",
+		label: "Service tokens",
+		description: "Maximum active service tokens in the organization.",
+		default: null
+	},
+	"kms.keys.max": {
+		kind: "limit",
+		label: "Managed keys",
+		description: "Maximum managed KMS keys in the organization.",
+		default: null
+	},
+	"lease.targets.max": {
+		kind: "limit",
+		label: "Lease targets",
+		description: "Maximum registered temporary-access targets.",
+		default: null
+	},
+	"sync.connections.max": {
+		kind: "limit",
+		label: "Sync connections",
+		description: "Maximum registered third-party sync destinations.",
+		default: null
+	},
+	members: {
+		kind: "metered",
+		label: "Members",
+		description: "Users in the organization. Included in the plan, then billed per seat.",
+		default: null,
+		metric: "member_count"
+	},
+	"resolves.monthly": {
+		kind: "metered",
+		label: "Monthly resolves",
+		description: "Secret resolutions per month. Included in the plan, then billed per unit.",
+		default: null,
+		metric: "monthly_resolves"
+	}
+});
+//#endregion
+//#region ../../packages/core/src/plans.ts
+const PLAN_FAMILIES = {
+	free: {
+		id: "free",
+		name: "Free",
+		description: "Get started with the essentials.",
+		current: 1,
+		hidden: false
+	},
+	team: {
+		id: "team",
+		name: "Team",
+		description: "For small teams collaborating on secrets.",
+		current: 1,
+		hidden: false
+	},
+	pro: {
+		id: "pro",
+		name: "Pro",
+		description: "For teams running secrets in production.",
+		current: 1,
+		hidden: true
+	},
+	enterprise: {
+		id: "enterprise",
+		name: "Enterprise",
+		description: "Unlimited scale with advanced governance.",
+		current: 1,
+		hidden: false
+	}
+};
+const PLAN_FAMILY_IDS = Object.keys(PLAN_FAMILIES);
+PLAN_FAMILY_IDS.filter((family) => !PLAN_FAMILIES[family].hidden);
+//#endregion
+//#region ../../packages/core/src/billing.ts
+/**
+* Lifecycle states a subscription can be in. Mirrors the biller's own states
+* (Stripe) but is provider-neutral so a different biller could map onto it.
+*/
+const SUBSCRIPTION_STATUSES = [
+	"trialing",
+	"active",
+	"past_due",
+	"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/dotenv.ts
+/**
+* Apply double-quote escapes in a single left-to-right pass.
+*
+* A pass per escape (`\n` → newline, then `\\` → `\`, …) is wrong: in `\\n` the
+* first pass matches the trailing `\n` and yields a real newline, corrupting
+* every literal backslash-n a JSON credential is made of. Scanning once means a
+* backslash consumes the character after it and can never be re-read.
+*/
+function unescapeDoubleQuoted(text) {
+	let out = "";
+	for (let i = 0; i < text.length; i++) {
+		if (text[i] !== "\\" || i === text.length - 1) {
+			out += text[i];
+			continue;
+		}
+		const next = text[++i];
+		if (next === "n") out += "\n";
+		else if (next === "r") out += "\r";
+		else if (next === "t") out += "	";
+		else if (next === "\"" || next === "\\") out += next;
+		else out += `\\${next}`;
+	}
+	return out;
+}
+/**
+* Find the index of the quote that closes a value opened at `start`.
+*
+* Inside double quotes a `\"` is an escaped quote, not the terminator (and a
+* `\\` immediately before the quote *is* a terminator, since the backslash is
+* itself escaped) — so the scan tracks escapes rather than searching for the
+* next bare quote. Single quotes have no escapes: the next one closes. Returns
+* -1 when the value is never closed.
+*/
+function findClosingQuote(content, start, quote) {
+	for (let i = start; i < content.length; i++) {
+		if (quote === "\"" && content[i] === "\\") {
+			i++;
+			continue;
+		}
+		if (content[i] === quote) return i;
+	}
+	return -1;
+}
+/**
+* Parse `.env` text into variables. Later assignments win, matching the
+* object-assignment semantics every `.env` reader has.
+*/
+function parseDotenv(content) {
+	const out = {};
+	let cursor = 0;
+	while (cursor < content.length) {
+		const newline = content.indexOf("\n", cursor);
+		const lineEnd = newline === -1 ? content.length : newline;
+		const lineStart = cursor;
+		const trimmedEnd = lineEnd > lineStart && content[lineEnd - 1] === "\r" ? lineEnd - 1 : lineEnd;
+		cursor = lineEnd + 1;
+		let i = skipSpace(content, lineStart, trimmedEnd);
+		if (i === trimmedEnd || content[i] === "#") continue;
+		if (content.startsWith("export ", i)) i = skipSpace(content, i + 7, trimmedEnd);
+		const eq = content.indexOf("=", i);
+		if (eq === -1 || eq >= trimmedEnd) continue;
+		const key = content.slice(i, eq).trim();
+		if (!key) continue;
+		const valueStart = skipSpace(content, eq + 1, trimmedEnd);
+		const quote = content[valueStart];
+		if (valueStart === trimmedEnd || quote !== "\"" && quote !== "'") {
+			const rest = content.slice(valueStart, trimmedEnd).trimEnd();
+			const comment = rest.indexOf(" #");
+			out[key] = comment === -1 ? rest : rest.slice(0, comment).trimEnd();
+			continue;
+		}
+		const close = findClosingQuote(content, valueStart + 1, quote);
+		const valueEnd = close === -1 ? content.length : close;
+		const value = content.slice(valueStart + 1, valueEnd);
+		out[key] = quote === "\"" ? unescapeDoubleQuoted(value) : value;
+		if (valueEnd >= cursor) {
+			const after = content.indexOf("\n", valueEnd);
+			cursor = after === -1 ? content.length : after + 1;
+		}
+	}
+	return out;
+}
+/** First index at or after `from` (and before `end`) that isn't a space or tab. */
+function skipSpace(content, from, end) {
+	let i = from;
+	while (i < end && (content[i] === " " || content[i] === "	")) i++;
+	return i;
+}
+//#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",
+	"ssh",
+	"redis",
+	"aws",
+	"gcp",
+	"mongodb"
+]);
+const executorModeSchema = z.enum(["in_do", "remote"]);
+/**
+* A Postgres role name we are willing to create. Deliberately strict — this
+* value is interpolated into a SQL template, so it must be a bare identifier
+* with no way to break out of quoting (no quotes, whitespace, or semicolons).
+*/
+const postgresRoleNameSchema = z.string().regex(/^[a-z_][a-z0-9_]{2,62}$/, "must be 3–63 chars, lowercase letters/digits/underscore, starting with a letter or underscore");
+/**
+* A SCRAM-SHA-256 verifier string as produced by @seekrit/crypto. Validated so
+* it, too, is safe to interpolate into a quoted SQL literal (the alphabet is
+* base64 + the fixed structural characters, none of which is a single quote).
+*/
+const scramVerifierSchema = z.string().regex(/^SCRAM-SHA-256\$\d{3,}:[A-Za-z0-9+/=]+\$[A-Za-z0-9+/=]+:[A-Za-z0-9+/=]+$/, "must be a SCRAM-SHA-256 verifier");
+/**
+* An SSH login principal (a Unix-style username the certificate authorizes).
+* Bounded and restricted to a safe charset — principals are SSH-wire-encoded,
+* not shell-interpolated, so this is sanity/DoS hardening, not an injection gate.
+*/
+const sshPrincipalSchema = z.string().regex(/^[A-Za-z0-9._-]{1,64}$/, "must be 1–64 chars of letters, digits, dot, dash, underscore");
+/** An `ssh-ed25519 <base64> [comment]` public key line (deep-validated on sign). */
+const sshPublicKeySchema = z.string().max(2048).regex(/^ssh-ed25519 [A-Za-z0-9+/=]+( .*)?$/, "must be an ssh-ed25519 public key");
+/** An SSH certificate extension name, e.g. `permit-pty`. */
+const sshExtensionSchema = z.string().regex(/^[a-z0-9-]{1,64}$/);
+/**
+* A MySQL/MariaDB user name we are willing to create. Interpolated into a
+* quoted SQL literal (`'{{name}}'@'%'`), so it is kept strict — plain
+* alphanumerics/underscore, no quotes/whitespace/semicolons to break out.
+*/
+const mysqlUserNameSchema = z.string().regex(/^[A-Za-z0-9_]{3,32}$/, "must be 3–32 chars, letters/digits/underscore");
+/**
+* A `mysql_native_password` authentication string — `*` followed by 40 upper
+* hex chars (`UPPER(HEX(SHA1(SHA1(password))))`), as produced by
+* @seekrit/crypto `mysqlNativePasswordVerifier`. Stored verbatim by
+* `CREATE USER … IDENTIFIED WITH mysql_native_password AS '<str>'`, and its
+* alphabet contains no single quote, so it is safe in a quoted SQL literal.
+*/
+const mysqlNativeVerifierSchema = z.string().regex(/^\*[0-9A-F]{40}$/, "must be a mysql_native_password hash (*<40 hex>)");
+/**
+* A Redis ACL user name we are willing to create. Interpolated into a Redis
+* command line as a bare token (`ACL SETUSER <name> …`), so it is kept strict —
+* plain alphanumerics/underscore, no whitespace to split the arg or ACL rule
+* characters (`~ + @ # & %`) that could be read as a permission.
+*/
+const redisUserNameSchema = z.string().regex(/^[A-Za-z0-9_]{3,32}$/, "must be 3–32 chars, letters/digits/underscore");
+/**
+* A Redis password verifier — the lowercase-hex SHA-256 of the password, as
+* produced by @seekrit/crypto `redisSha256Verifier`. `ACL SETUSER … on #<hex>`
+* stores this digest verbatim, and it cannot authenticate: Redis `AUTH` hashes
+* the *plaintext* it receives with SHA-256 and compares, so the stored digest
+* is preimage-resistant (the password is high-entropy and machine-generated).
+* The alphabet is bare hex, so it is a safe bare command token.
+*/
+const redisSha256VerifierSchema = z.string().regex(/^[0-9a-f]{64}$/, "must be a lowercase-hex SHA-256 digest (64 chars)");
+/**
+* An IAM role ARN the broker is allowed to assume. Bounded and structurally
+* validated: `arn:<partition>:iam::<account>:role/<path-and-name>`. Partition
+* covers commercial (`aws`), GovCloud (`aws-us-gov`), and China (`aws-cn`).
+*/
+const awsRoleArnSchema = z.string().regex(/^arn:aws(?:-us-gov|-cn)?:iam::\d{12}:role\/[\w+=,.@/-]{1,512}$/, "must be an IAM role ARN (arn:aws:iam::<account>:role/<name>)");
+/** An AWS region id, e.g. `us-east-1`, `eu-west-2`, `us-gov-west-1`. */
+const awsRegionSchema = z.string().regex(/^[a-z]{2}(?:-[a-z]+)+-\d$/, "must be an AWS region id (e.g. us-east-1)");
+/**
+* An STS external id — the shared string a role's trust policy can require so a
+* confused-deputy can't assume it. AWS allows a broad charset; we keep to the
+* documented safe set and bound the length.
+*/
+const awsExternalIdSchema = z.string().regex(/^[\w+=,.@:/-]{2,1224}$/, "must be a valid STS external id");
+z.string().regex(/^[\w+=,.@-]{2,64}$/, "must be 2–64 chars of [A-Za-z0-9_+=,.@-]");
+/**
+* A GCP service-account email the broker is allowed to impersonate (or that
+* appears in a delegation chain). Structurally validated and bounded: it is
+* interpolated into the IAM Credentials API URL path, so the charset excludes
+* anything that could break out of a path segment. Covers user-managed
+* (`name@<project>.iam.gserviceaccount.com`) and Google-managed
+* (`<project-number>-compute@developer.gserviceaccount.com`) forms.
+*/
+const gcpServiceAccountEmailSchema = z.string().max(256).regex(/^[a-z0-9-]+@[a-z0-9.-]+\.gserviceaccount\.com$/, "must be a service-account email (…@….gserviceaccount.com)");
+/**
+* An OAuth 2.0 scope granted to the minted access token, e.g.
+* `https://www.googleapis.com/auth/cloud-platform`. Bounded and whitespace-free
+* (scopes are space-delimited); passed to the IAM Credentials API in a JSON body
+* array, not a URL, so this is sanity/DoS hardening rather than an injection gate.
+*/
+const gcpOauthScopeSchema = z.string().min(1).max(256).regex(/^\S+$/, "must be a single OAuth scope with no whitespace");
+/**
+* The consumer's ephemeral P-256 public key (JWK-serialized) that a tier-2
+* credential is wrapped to before it is returned. Validated structurally here;
+* the executor imports it defensively before wrapping. Bounded so a giant blob
+* can't be pushed through the control plane.
+*/
+const p256PublicKeyJwkSchema = z.string().max(2048).refine((s) => {
+	try {
+		const jwk = JSON.parse(s);
+		return jwk.kty === "EC" && jwk.crv === "P-256" && !!jwk.x && !!jwk.y;
+	} catch {
+		return false;
+	}
+}, "must be a JWK-serialized P-256 public key");
+z.string().regex(/^[A-Za-z0-9_-]{1,64}$/, "must be 1–64 chars of [A-Za-z0-9_-]");
+/**
+* A MongoDB database name — the db a preset role is granted on, or the
+* authentication database a leased user is created in. MongoDB forbids
+* `/\. "$*<>:|?` and the empty string in db names; we keep to a safe subset.
+*/
+const mongoDatabaseNameSchema = z.string().regex(/^[A-Za-z0-9_-]{1,63}$/, "must be 1–63 chars of [A-Za-z0-9_-]");
+/**
+* A single MongoDB role grant `{ role, db }` for a `custom` target — e.g.
+* `{ role: "readWrite", db: "app" }` or a user-defined role. Admin-supplied
+* trusted input, set once at registration; still bounded structurally.
+*/
+const mongoRoleSchema = z.object({
+	role: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/, "must be a role name"),
+	db: mongoDatabaseNameSchema
+});
+const postgresAccessLevelSchema = z.enum([
+	"readonly",
+	"readwrite",
+	"custom"
+]);
+const mysqlAccessLevelSchema = z.enum([
+	"readonly",
+	"readwrite",
+	"custom"
+]);
+const redisAccessLevelSchema = z.enum([
+	"readonly",
+	"readwrite",
+	"custom"
+]);
+const mongoAccessLevelSchema = z.enum([
+	"readonly",
+	"readwrite",
+	"custom"
+]);
+const connectionSchema = z.object({
+	host: z.string().min(1),
+	port: z.number().int().min(1).max(65535),
+	database: z.string().min(1)
+});
+/** A `{{name}}`/`{{verifier}}`/`{{valid_until}}` templated SQL statement. */
+const statementSchema = z.string().min(1).max(4e3);
+/** A bare SQL identifier (schema name) — no quotes/whitespace/semicolons. */
+const identifierSchema = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,62}$/, "must be an identifier");
+const postgresTargetConfigSchema = z.object({
+	provider: z.literal("postgres"),
+	executor: executorModeSchema,
+	accessLevel: postgresAccessLevelSchema.optional(),
+	schema: identifierSchema.optional(),
+	connection: connectionSchema,
+	provisionerUrl: z.url().optional(),
+	createStatements: z.array(statementSchema).max(16).optional(),
+	revokeStatements: z.array(statementSchema).max(16).optional()
+});
+/** A MySQL account host part (`'name'@'<host>'`) — no quotes/whitespace. */
+const mysqlHostSchema = z.string().regex(/^[A-Za-z0-9_.%:-]{1,255}$/, "must be a host pattern");
+const mysqlTargetConfigSchema = z.object({
+	provider: z.literal("mysql"),
+	executor: executorModeSchema,
+	accessLevel: mysqlAccessLevelSchema.optional(),
+	connection: connectionSchema,
+	userHost: mysqlHostSchema.optional(),
+	provisionerUrl: z.url().optional(),
+	createStatements: z.array(statementSchema).max(16).optional(),
+	revokeStatements: z.array(statementSchema).max(16).optional()
+});
+const redisConnectionSchema = z.object({
+	host: z.string().min(1),
+	port: z.number().int().min(1).max(65535),
+	/** Redis logical database index (the `/<n>` in a connection URL). */
+	db: z.number().int().min(0).max(15).optional()
+});
+const redisTargetConfigSchema = z.object({
+	provider: z.literal("redis"),
+	executor: executorModeSchema,
+	accessLevel: redisAccessLevelSchema.optional(),
+	connection: redisConnectionSchema,
+	provisionerUrl: z.url().optional(),
+	createStatements: z.array(statementSchema).max(16).optional(),
+	revokeStatements: z.array(statementSchema).max(16).optional()
+});
+const sshTargetConfigSchema = z.object({
+	provider: z.literal("ssh"),
+	executor: z.literal("in_do"),
+	caPublicKey: sshPublicKeySchema,
+	allowedPrincipals: z.array(sshPrincipalSchema).max(64).optional(),
+	extensions: z.array(sshExtensionSchema).max(16).optional(),
+	maxTtlSeconds: z.number().int().min(60).max(3600 * 24 * 7).optional(),
+	connection: z.object({
+		host: z.string().min(1).optional(),
+		user: sshPrincipalSchema.optional()
+	}).optional()
+});
+const AWS_MAX_TTL_SECONDS = 3600 * 12;
+const awsTargetConfigSchema = z.object({
+	provider: z.literal("aws"),
+	executor: z.literal("in_do"),
+	roleArn: awsRoleArnSchema,
+	region: awsRegionSchema,
+	externalId: awsExternalIdSchema.optional(),
+	sessionPolicy: z.string().min(1).max(4e3).optional(),
+	maxTtlSeconds: z.number().int().min(900).max(AWS_MAX_TTL_SECONDS).optional()
+});
+const GCP_MAX_TTL_SECONDS = 3600 * 12;
+const gcpTargetConfigSchema = z.object({
+	provider: z.literal("gcp"),
+	executor: z.literal("in_do"),
+	serviceAccount: gcpServiceAccountEmailSchema,
+	scopes: z.array(gcpOauthScopeSchema).min(1).max(32).optional(),
+	delegates: z.array(gcpServiceAccountEmailSchema).max(8).optional(),
+	maxTtlSeconds: z.number().int().min(60).max(GCP_MAX_TTL_SECONDS).optional()
+});
+const mongoTargetConfigSchema = z.object({
+	provider: z.literal("mongodb"),
+	executor: z.literal("in_do"),
+	accessLevel: mongoAccessLevelSchema.optional(),
+	connection: connectionSchema,
+	authSource: mongoDatabaseNameSchema.optional(),
+	roles: z.array(mongoRoleSchema).min(1).max(32).optional(),
+	tls: z.boolean().optional(),
+	maxTtlSeconds: z.number().int().min(60).max(3600 * 24 * 7).optional()
+});
+const leaseTargetConfigSchema = z.discriminatedUnion("provider", [
+	postgresTargetConfigSchema,
+	mysqlTargetConfigSchema,
+	redisTargetConfigSchema,
+	sshTargetConfigSchema,
+	awsTargetConfigSchema,
+	gcpTargetConfigSchema,
+	mongoTargetConfigSchema
+]);
+z.object({
+	name: z.string().trim().min(1).max(128),
+	config: leaseTargetConfigSchema,
+	/**
+	* The admin/provisioning credential (e.g. a Postgres connection string),
+	* encrypted client-side to the broker's public key (a `wd1.` wrap). The
+	* control plane stores only this ciphertext — it never sees the plaintext.
+	*/
+	wrappedAdminSecret: z.string().min(1)
+});
+/** Requested lease lifetime, shared by all providers. */
+const ttlSecondsSchema = z.number().int().min(60).max(3600 * 24 * 7);
+/**
+* Client → API: mint a Postgres lease. The client generates the password and
+* its SCRAM verifier locally and sends only the verifier — the plaintext
+* password never leaves the requesting machine.
+*/
+const mintPostgresLeaseSchema = z.object({
+	provider: z.literal("postgres"),
+	targetId: z.string().min(1),
+	roleName: postgresRoleNameSchema,
+	verifier: scramVerifierSchema,
+	ttlSeconds: ttlSecondsSchema
+});
+/**
+* Client → API: mint a MySQL/MariaDB lease. The client generates the password
+* and its `mysql_native_password` hash locally and sends only the hash — the
+* plaintext password never leaves the requesting machine.
+*/
+const mintMysqlLeaseSchema = z.object({
+	provider: z.literal("mysql"),
+	targetId: z.string().min(1),
+	roleName: mysqlUserNameSchema,
+	verifier: mysqlNativeVerifierSchema,
+	ttlSeconds: ttlSecondsSchema
+});
+/**
+* Client → API: mint a Redis lease. The client generates the password and its
+* SHA-256 hex digest locally and sends only the digest — the plaintext password
+* never leaves the requesting machine.
+*/
+const mintRedisLeaseSchema = z.object({
+	provider: z.literal("redis"),
+	targetId: z.string().min(1),
+	roleName: redisUserNameSchema,
+	verifier: redisSha256VerifierSchema,
+	ttlSeconds: ttlSecondsSchema
+});
+/**
+* Client → API: mint an SSH lease. The client generates an ephemeral keypair
+* locally and sends only the public key; the signed certificate comes back in
+* the response. The private key never leaves the requesting machine.
+*/
+const mintSshLeaseSchema = z.object({
+	provider: z.literal("ssh"),
+	targetId: z.string().min(1),
+	publicKey: sshPublicKeySchema,
+	principals: z.array(sshPrincipalSchema).min(1).max(32),
+	ttlSeconds: ttlSecondsSchema
+});
+/**
+* Client → API: mint an AWS lease. The client generates an ephemeral P-256
+* keypair locally and sends only the public key; STS mints the credential and
+* the broker returns it wrapped to that key. The private key never leaves the
+* requesting machine, so the plaintext credential is only decryptable there.
+*
+* TTL bounds are STS's own `DurationSeconds` limits (15 min – 12 h), not the
+* generic lease bounds — STS rejects anything below 900 seconds.
+*/
+const mintAwsLeaseSchema = z.object({
+	provider: z.literal("aws"),
+	targetId: z.string().min(1),
+	recipientPublicKey: p256PublicKeyJwkSchema,
+	ttlSeconds: z.number().int().min(900).max(AWS_MAX_TTL_SECONDS)
+});
+/**
+* Client → API: mint a GCP lease. Like AWS (tier 2): the client generates an
+* ephemeral P-256 keypair locally and sends only the public key; the IAM
+* Credentials API mints the access token and the broker returns it wrapped to
+* that key. The private key never leaves the requesting machine, so the plaintext
+* token is only decryptable there.
+*
+* TTL bounds are GCP's `generateAccessToken` limits (1 min – 12 h); tokens over
+* 1 h require the credential-lifetime-extension org policy.
+*/
+const mintGcpLeaseSchema = z.object({
+	provider: z.literal("gcp"),
+	targetId: z.string().min(1),
+	recipientPublicKey: p256PublicKeyJwkSchema,
+	ttlSeconds: z.number().int().min(60).max(GCP_MAX_TTL_SECONDS)
+});
+/**
+* Client → API: mint a MongoDB lease. Like AWS (tier 2), the client generates
+* an ephemeral P-256 keypair locally and sends only the public key; the broker
+* generates the password, runs `createUser`, and returns the credential wrapped
+* to that key. The private key never leaves the requesting machine, so the
+* plaintext credential is only decryptable there.
+*/
+const mintMongoLeaseSchema = z.object({
+	provider: z.literal("mongodb"),
+	targetId: z.string().min(1),
+	recipientPublicKey: p256PublicKeyJwkSchema,
+	ttlSeconds: ttlSecondsSchema
+});
+z.discriminatedUnion("provider", [
+	mintPostgresLeaseSchema,
+	mintMysqlLeaseSchema,
+	mintRedisLeaseSchema,
+	mintSshLeaseSchema,
+	mintAwsLeaseSchema,
+	mintGcpLeaseSchema,
+	mintMongoLeaseSchema
+]);
+//#endregion
+//#region ../../packages/core/src/types.ts
+/**
+* Transactional notification emails seekrit can send. Each id is one
+* user-facing on/off toggle (see `NOTIFICATION_TYPE_META`). These carry only
+* audit-grade metadata — never secret material — and every one is opt-out
+* (defaults on). Kept as a const array so the API, api-client, and dashboard
+* share a single source of truth (mirrors `AUDIT_ACTIONS`).
+*/
+const NOTIFICATION_TYPES = [
+	"token_created",
+	"token_revoked",
+	"env_access_granted",
+	"env_access_revoked",
+	"resolve_denied",
+	"org_welcome",
+	"token_expiring",
+	"lease_expired",
+	"sync_failed"
+];
+//#endregion
+//#region ../../packages/core/src/schemas.ts
+/** URL-safe identifier segment: `my-app`, `production`, … */
+const slugSchema = z.string().min(1).max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "must be lowercase alphanumeric with hyphens");
+const nameSchema = z.string().trim().min(1).max(128);
+/** An email address, normalized to trimmed lowercase before validation. */
+const emailSchema = z.string().trim().toLowerCase().pipe(z.email().max(320));
+/** Env-var style secret name: FOO, DATABASE_URL, apiKey2 … */
+const secretNameSchema = z.string().min(1).max(256).regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "must be a valid environment variable name");
+z.enum([
+	"owner",
+	"admin",
+	"member"
+]);
+/** Role a person may be invited at — never `owner` (ownership isn't invitable). */
+const inviteRoleSchema = z.enum(["admin", "member"]);
+const principalTypeSchema = z.enum(["user", "service_token"]);
+/** Org-level capability a service token can hold (never `owner`). */
+const serviceTokenRoleSchema = z.enum(["admin", "member"]);
+z.object({
+	name: nameSchema,
+	slug: slugSchema
+});
+z.object({
+	name: nameSchema,
+	slug: slugSchema
+});
+z.object({ name: nameSchema });
+z.object({ name: nameSchema });
+z.object({ name: nameSchema });
+z.object({ required: z.boolean() });
+z.object({
+	email: emailSchema,
+	role: inviteRoleSchema.default("member")
+});
+z.object({
+	name: nameSchema,
+	slug: slugSchema
+});
+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()
+});
+z.object({
+	name: nameSchema,
+	slug: slugSchema,
+	/** Environment DEK wrapped to the creator's public key — created client-side. */
+	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. */
+ciphertext: z.string().min(1).max(65536) });
+z.object({ version: z.number().int().positive() });
+z.object({ limit: z.coerce.number().int().min(1).max(200).default(50) });
+z.object({
+	publicKeyJwk: z.string().min(1),
+	/**
+	* Private key encrypted with a passphrase-derived KEK; opaque to the
+	* server. Self-contained blob (embeds KDF salt + iterations).
+	*/
+	encryptedPrivateKey: z.string().min(1)
+});
+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]+$/),
+	/** SHA-256 hash (base64url) of the full token string. */
+	tokenHash: z.string().min(1),
+	publicKeyJwk: z.string().min(1),
+	/**
+	* Org-level capability. Defaults to `member` (a runtime credential); pass
+	* `admin` to mint a headless provisioning token. Only an admin caller may
+	* create an `admin` token, so capability cannot escalate itself.
+	*/
+	role: serviceTokenRoleSchema.default("member"),
+	/**
+	* The application environment this token is bound to (org + app + env).
+	* Optional so org-admin tokens can exist, but required for runtime tokens
+	* that resolve secrets via `GET /v1/resolve`.
+	*/
+	environmentId: z.string().min(1).nullish(),
+	expiresAt: z.iso.datetime().nullish()
+});
+const kmsKeyPurposeSchema = z.enum(["encrypt", "sign"]);
+const kmsKeySpecSchema = z.enum(["aes-256-gcm", "ecdsa-p256"]);
+/** A wrapped key grant supplied by the client (server never sees plaintext material). */
+const kmsGrantInputSchema = z.object({
+	principalType: principalTypeSchema,
+	principalId: z.string().min(1),
+	/** Key material wrapped to the principal's public key (`wd1.` blob). */
+	wrappedKey: z.string().min(1)
+});
+z.object({
+	name: nameSchema,
+	purpose: kmsKeyPurposeSchema,
+	spec: kmsKeySpecSchema,
+	applicationId: z.string().min(1).nullish(),
+	groupId: z.string().min(1).nullish(),
+	/** ECDSA P-256 public key (JWK) for `sign` keys; omit for `encrypt` keys. */
+	publicKeyJwk: z.string().min(1).nullish(),
+	grants: z.array(kmsGrantInputSchema).min(1)
+}).refine((v) => !(v.applicationId && v.groupId), {
+	message: "a key may be scoped to an application or a group, not both",
+	path: ["groupId"]
+}).refine((v) => v.purpose === "sign" === (v.spec === "ecdsa-p256"), {
+	message: "sign keys require spec ecdsa-p256; encrypt keys require aes-256-gcm",
+	path: ["spec"]
+}).refine((v) => v.purpose === "sign" === (v.publicKeyJwk != null), {
+	message: "sign keys require a publicKeyJwk; encrypt keys must omit it",
+	path: ["publicKeyJwk"]
+});
+z.object({
+	principalType: principalTypeSchema,
+	principalId: z.string().min(1),
+	/** Current-version key material wrapped to the principal's public key. */
+	wrappedKey: z.string().min(1)
+});
+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),
+	headers: z.record(z.string().min(1).max(256), z.string().max(4096)).optional(),
+	enabled: z.boolean().default(true)
+});
+const planFamilySchema = z.enum(PLAN_FAMILY_IDS);
+const subscriptionStatusSchema = z.enum(SUBSCRIPTION_STATUSES);
+z.enum(ENTITLEMENT_KEYS);
+/** An entitlement value: boolean (features), number or null/unlimited (limits, metered). */
+const entitlementValueSchema = z.union([
+	z.boolean(),
+	z.number(),
+	z.null()
+]);
+z.object({
+	family: planFamilySchema,
+	version: z.number().int().positive().optional(),
+	status: subscriptionStatusSchema.default("active")
+});
+z.object({
+	value: entitlementValueSchema,
+	note: z.string().max(500).nullish(),
+	expiresAt: z.iso.datetime().nullish()
+});
+z.object({ family: planFamilySchema });
+z.object({
+	sessionId: z.string().regex(/^skc_[0-9A-Za-z]+$/),
+	/** SHA-256 hash (base64url) of the full session token string. */
+	tokenHash: z.string().min(1).max(128),
+	/** Display-only, e.g. `miles@studio.local`. */
+	deviceLabel: z.string().trim().min(1).max(120),
+	/** Display-only, e.g. `cli/0.4.2`. */
+	client: z.string().trim().max(60).optional()
+});
+z.object({ code: z.string().trim().min(1).max(32) });
+z.object({
+	cursor: z.string().optional(),
+	limit: z.coerce.number().int().min(1).max(200).default(50),
+	action: z.string().optional(),
+	resourceType: z.string().optional()
+});
+z.enum(["vercel"]);
+/**
+* Vercel account scope. The API token itself is never here — it is wrapped to
+* the connection's public key and stored as ciphertext.
+*
+* `teamId` is required for tokens scoped to a Vercel Team; personal-account
+* tokens omit it. Vercel rejects team-owned project calls that lack it with a
+* bare 403, so we pass it through as `?teamId=` on every request.
+*/
+const vercelConnectionConfigSchema = z.object({
+	provider: z.literal("vercel"),
+	/** Vercel Team id (`team_…`). Omit for a personal account. */
+	teamId: z.string().trim().min(1).max(128).optional()
+});
+const syncConnectionConfigSchema = z.discriminatedUnion("provider", [vercelConnectionConfigSchema]);
+const vercelDestinationSchema = z.object({
+	provider: z.literal("vercel"),
+	/** Vercel project id (`prj_…`) or project name. */
+	projectId: z.string().trim().min(1).max(128),
+	/** Which deployment targets receive these values. At least one. */
+	targets: z.array(z.enum([
+		"production",
+		"preview",
+		"development"
+	])).min(1),
+	/**
+	* Restrict `preview` writes to one git branch. Vercel only honors this when
+	* `targets` includes `preview`; ignored otherwise.
+	*/
+	gitBranch: z.string().trim().min(1).max(255).optional()
+});
+const syncDestinationSchema = z.discriminatedUnion("provider", [vercelDestinationSchema]);
+/**
+* How seekrit secret names become destination key names. Applied in order:
+* explicit `rename` (wins outright), then `prefix`/`suffix`, then `case`.
+*/
+const nameTransformSchema = z.object({
+	prefix: z.string().max(64).regex(/^[A-Za-z0-9_]*$/, "must be alphanumeric or underscore").optional(),
+	suffix: z.string().max(64).regex(/^[A-Za-z0-9_]*$/, "must be alphanumeric or underscore").optional(),
+	case: z.enum([
+		"preserve",
+		"upper",
+		"lower"
+	]).optional(),
+	/** Exact per-secret overrides, seekrit name → destination name. */
+	rename: z.record(secretNameSchema, secretNameSchema).optional()
+});
+z.object({
+	/**
+	* The id the client already fetched a public key for. Connections are a
+	* two-step dance — mint the key, wrap the credential to it, then create the
+	* row — so the id has to be chosen before the row exists. Omit it and the
+	* server generates one (only useful when there is no credential to wrap yet).
+	*/
+	id: z.string().regex(/^syc_[A-Za-z0-9]{24}$/, "must be a connection id from the public-key call").optional(),
+	name: z.string().trim().min(1).max(128),
+	config: syncConnectionConfigSchema,
+	/**
+	* The destination's API credential (a Vercel token), encrypted client-side to
+	* the connection's public key (a `wd1.` wrap). The control plane stores only
+	* this ciphertext; it is unwrapped transiently inside the sync engine DO.
+	*/
+	wrappedCredential: z.string().min(1)
+});
+z.object({ destination: syncDestinationSchema });
+const globListSchema = z.array(z.string().trim().min(1).max(256)).max(100);
+z.object({
+	connectionId: z.string().min(1),
+	environmentId: z.string().min(1),
+	destination: syncDestinationSchema,
+	nameTransform: nameTransformSchema.optional(),
+	include: globListSchema.optional(),
+	exclude: globListSchema.optional(),
+	onDelete: z.enum(["delete", "retain"]).default("delete"),
+	mode: z.enum(["auto", "manual"]).default("auto"),
+	wrappedDeks: z.array(z.object({
+		environmentId: z.string().min(1),
+		wrappedDek: z.string().min(1)
+	})).min(1),
+	acknowledgedDecryption: z.literal(true)
+});
+z.object({
+	destination: syncDestinationSchema.optional(),
+	nameTransform: nameTransformSchema.nullable().optional(),
+	include: globListSchema.nullable().optional(),
+	exclude: globListSchema.nullable().optional(),
+	onDelete: z.enum(["delete", "retain"]).optional(),
+	mode: z.enum(["auto", "manual"]).optional(),
+	enabled: z.boolean().optional()
+});
+//#endregion
 //#region ../../packages/crypto/src/encoding.ts
 const CHUNK = 32768;
 /** Base64url (no padding) — portable across browsers, Workers, and Node. */
@@ -619,7 +1751,7 @@ function signatureKeyRef(signature) {
 const TOKEN_PREFIX = "skt";
 const TOKEN_ID_LENGTH = 22;
 const ID_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
-function randomTokenId() {
+function randomTokenId(prefix = TOKEN_PREFIX) {
 	let out = "";
 	while (out.length < TOKEN_ID_LENGTH) {
 		const bytes = crypto.getRandomValues(new Uint8Array(TOKEN_ID_LENGTH - out.length));
@@ -628,7 +1760,7 @@ function randomTokenId() {
 			if (out.length === TOKEN_ID_LENGTH) break;
 		}
 	}
-	return `${TOKEN_PREFIX}_${out}`;
+	return `${prefix}_${out}`;
 }
 async function hashToken(token) {
 	const digest = await crypto.subtle.digest("SHA-256", utf8Encode(token));
@@ -664,7 +1796,7 @@ function isServiceToken(value) {
 }
 //#endregion
 //#region ../cli/package.json
-var version$1 = "0.23.0";
+var version$1 = "0.32.0";
 const PROJECT_FILE = "seekrit.json";
 function globalConfigPath() {
 	return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "seekrit", "config.json");
@@ -674,6 +1806,10 @@ function readGlobalConfig() {
 	if (!existsSync(path)) return {};
 	return JSON.parse(readFileSync(path, "utf8"));
 }
+/**
+* Merge into the saved config. A key set to `undefined` is *removed* (JSON
+* drops it), which is how the login paths clear a credential they replace.
+*/
 function writeGlobalConfig(update) {
 	const path = globalConfigPath();
 	const merged = {
@@ -771,6 +1907,32 @@ var SeekritClient = class {
 	getMyNotificationPrefs() {
 		return this.request("GET", "/v1/me/notifications");
 	}
+	/**
+	* Devices this user has authorized. `currentSessionId` is set when the caller
+	* *is* a CLI session, so it can label (or revoke) itself.
+	*/
+	listCliSessions() {
+		return this.request("GET", "/v1/me/cli-sessions");
+	}
+	/** Sign a device out. Its token stops authenticating immediately. */
+	revokeCliSession(sessionId) {
+		return this.request("DELETE", `/v1/me/cli-sessions/${sessionId}`);
+	}
+	/** What a pending login request is asking for — for the approval screen. */
+	getCliLoginRequest(code) {
+		return this.request("GET", `/v1/cli-login/${encodeURIComponent(code)}`);
+	}
+	/**
+	* Authorize a device. Requires a browser session; members with a second
+	* factor must have re-entered it just now, else this rejects with
+	* `mfa_required` (recoverable — prompt for a code and retry).
+	*/
+	approveCliLogin(code) {
+		return this.request("POST", `/v1/cli-login/${encodeURIComponent(code)}/approve`);
+	}
+	denyCliLogin(code) {
+		return this.request("POST", `/v1/cli-login/${encodeURIComponent(code)}/deny`);
+	}
 	setMyNotificationPrefs(input) {
 		return this.request("PUT", "/v1/me/notifications", input);
 	}
@@ -838,6 +2000,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`);
 	}
@@ -873,6 +2057,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}`);
@@ -886,6 +2071,19 @@ var SeekritClient = class {
 	deleteSecret(orgId, envId, name) {
 		return this.request("DELETE", `/v1/orgs/${orgId}/envs/${envId}/secrets/${name}`);
 	}
+	/** A secret's append-only history, newest version first. */
+	listSecretVersions(orgId, envId, name, query = {}) {
+		const qs = query.limit === void 0 ? "" : `?limit=${query.limit}`;
+		return this.request("GET", `/v1/orgs/${orgId}/envs/${envId}/secrets/${name}/versions${qs}`);
+	}
+	/**
+	* Roll a secret back to an earlier version. Keyless — the server copies the
+	* ciphertext it already stores, so this appends a new version rather than
+	* rewinding, and needs no DEK on the caller's side.
+	*/
+	restoreSecret(orgId, envId, name, version) {
+		return this.request("POST", `/v1/orgs/${orgId}/envs/${envId}/secrets/${name}/restore`, { version });
+	}
 	/** The calling principal's wrapped DEK for this environment. */
 	getMyEnvKey(orgId, envId) {
 		return this.request("GET", `/v1/orgs/${orgId}/envs/${envId}/key`);
@@ -1012,6 +2210,54 @@ var SeekritClient = class {
 	deleteLeaseTarget(orgId, targetId) {
 		return this.request("DELETE", `/v1/orgs/${orgId}/leases/targets/${targetId}`);
 	}
+	listSyncConnections(orgId) {
+		return this.request("GET", `/v1/orgs/${orgId}/sync/connections`);
+	}
+	/**
+	* Mint (or re-read) the keypair for a connection id, *before* the connection
+	* exists. Wrap the destination credential and every environment DEK to this
+	* key, then pass the same id to {@link createSyncConnection}.
+	*/
+	getSyncConnectionKey(orgId, connectionId) {
+		return this.request("GET", `/v1/orgs/${orgId}/sync/connections/${connectionId}/public-key`);
+	}
+	createSyncConnection(orgId, input) {
+		return this.request("POST", `/v1/orgs/${orgId}/sync/connections`, input);
+	}
+	/** Test the stored credential against a destination. Never throws on a bad token. */
+	verifySyncConnection(orgId, connectionId, destination) {
+		return this.request("POST", `/v1/orgs/${orgId}/sync/connections/${connectionId}/verify`, { destination });
+	}
+	/** Deletes the connection, its bindings, its key grants, and its keypair. */
+	deleteSyncConnection(orgId, connectionId) {
+		return this.request("DELETE", `/v1/orgs/${orgId}/sync/connections/${connectionId}`);
+	}
+	listSyncBindings(orgId) {
+		return this.request("GET", `/v1/orgs/${orgId}/sync/bindings`);
+	}
+	/**
+	* Enable sync for one environment. `wrappedDeks` must cover the target
+	* environment *and* every group environment it composes, each wrapped to the
+	* connection's public key — the API cannot compute these, which is what keeps
+	* enabling sync a key-holder operation.
+	*/
+	createSyncBinding(orgId, input) {
+		return this.request("POST", `/v1/orgs/${orgId}/sync/bindings`, input);
+	}
+	updateSyncBinding(orgId, bindingId, input) {
+		return this.request("PATCH", `/v1/orgs/${orgId}/sync/bindings/${bindingId}`, input);
+	}
+	deleteSyncBinding(orgId, bindingId) {
+		return this.request("DELETE", `/v1/orgs/${orgId}/sync/bindings/${bindingId}`);
+	}
+	/** Push now, synchronously. */
+	runSyncBinding(orgId, bindingId) {
+		return this.request("POST", `/v1/orgs/${orgId}/sync/bindings/${bindingId}/run`);
+	}
+	listSyncRuns(orgId, bindingId) {
+		const qs = bindingId ? `?bindingId=${encodeURIComponent(bindingId)}` : "";
+		return this.request("GET", `/v1/orgs/${orgId}/sync/runs${qs}`);
+	}
 	listLeases(orgId) {
 		return this.request("GET", `/v1/orgs/${orgId}/leases`);
 	}
@@ -1132,7 +2378,7 @@ function tryBuildContext(dotenvVars = {}) {
 	const config = readGlobalConfig();
 	const fromEnv = (key) => process.env[key] ?? dotenvVars[key];
 	const apiUrl = fromEnv("SEEKRIT_API_URL") ?? config.apiUrl ?? "https://api.seekrit.dev";
-	const token = fromEnv("SEEKRIT_TOKEN") ?? config.token;
+	const token = fromEnv("SEEKRIT_TOKEN") ?? config.token ?? config.sessionToken;
 	const devUser = fromEnv("SEEKRIT_DEV_USER") ?? config.devUser;
 	let auth;
 	if (token) auth = {
@@ -1150,7 +2396,8 @@ function tryBuildContext(dotenvVars = {}) {
 			auth,
 			client: CLI_CLIENT
 		}),
-		auth
+		auth,
+		apiUrl
 	};
 }
 function isTokenAuth(ctx) {
@@ -1197,12 +2444,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}`);
@@ -1215,34 +2464,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,
@@ -1344,12 +2618,16 @@ function readM2mCreds(dotenvVars = {}) {
 		clientSecret
 	};
 }
-/** True when a service/dev credential is already configured explicitly. */
+/**
+* True when a service/session/dev credential is already configured explicitly.
+* A browser-authorized session counts: a human who ran `seekrit login` must not
+* be silently swapped onto a machine identity.
+*/
 function hasExplicitCredential(dotenvVars) {
 	const fromEnv = (key) => process.env[key] ?? dotenvVars[key];
 	if (fromEnv("SEEKRIT_TOKEN") || fromEnv("SEEKRIT_DEV_USER")) return true;
 	const config = readGlobalConfig();
-	return Boolean(config.token || config.devUser);
+	return Boolean(config.token || config.sessionToken || config.devUser);
 }
 /** Mint a fresh org-scoped admin token using M2M credentials (keyless). */
 async function mintAdminToken(apiUrl, creds) {
@@ -1399,43 +2677,70 @@ async function ensureM2mAdminToken(dotenvVars = {}) {
 	return token;
 }
 //#endregion
-//#region ../cli/src/dotenv.ts
+//#region ../cli/src/cache.ts
+/** Render an age for a log line, rounded to its largest whole unit. */
+function humanize(ms) {
+	const secs = Math.floor(ms / 1e3);
+	if (secs < 60) return `${secs}s`;
+	if (secs < 3600) return `${Math.floor(secs / 60)}m`;
+	if (secs < 86400) return `${Math.floor(secs / 3600)}h`;
+	return `${Math.floor(secs / 86400)}d`;
+}
 /**
-* 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.
+* Whether a failed resolve means the API was *unreachable* (the cache may stand
+* in) rather than *refusing us* (it must not). A refusal is an answer, and
+* revocation is supposed to take effect the moment it arrives.
 */
-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;
+function mayFallBack(err) {
+	if (err instanceof SeekritApiError) return err.status >= 500 || err.status === 429;
+	return true;
 }
-//#endregion
-//#region ../cli/src/secrets.ts
-/** Fetch + decrypt every secret in a single environment. */
-async function fetchDecryptedSecrets(ctx, orgId, envId) {
+/**
+* Fetch + decrypt every secret in a single environment.
+*
+* `${OTHER_SECRET}` references are expanded (see `@seekrit/core`'s
+* `interpolate`) unless `raw` is set. Only this environment's own secrets are in
+* scope here — a reference to a secret inherited from a composed group is left
+* literal, because the group layers aren't fetched. `materializeEnv` is the
+* fully-layered view.
+*/
+async function fetchDecryptedSecrets(ctx, orgId, envId, opts = {}) {
 	const [dek, { secrets }] = await Promise.all([getDek(ctx, orgId, envId), ctx.client.listSecrets(orgId, envId)]);
 	const entries = await Promise.all(secrets.map(async (secret) => [secret.name, await decryptSecret(dek, secret.ciphertext, secretAad(envId, secret.name))]));
-	return Object.fromEntries(entries);
+	return interpolateValues(Object.fromEntries(entries), !opts.raw).values;
+}
+/**
+* Expand `${OTHER_SECRET}` references in a merged variable set. A cycle becomes
+* the CLI's standard fatal exit — it is a config bug with no correct value to
+* emit. Pass `enabled: false` (`--no-interpolate`) to hand the set back as-is.
+*/
+function interpolateValues(values, enabled = true) {
+	if (!enabled) return {
+		values,
+		interpolated: [],
+		unresolvedRefs: []
+	};
+	try {
+		const { values: expandedValues, expanded, unresolved } = interpolateSecrets(values);
+		return {
+			values: expandedValues,
+			interpolated: expanded,
+			unresolvedRefs: unresolved
+		};
+	} catch (err) {
+		return fail(err instanceof Error ? err.message : String(err));
+	}
+}
+/**
+* Decrypt one historical version of a secret. Ciphertext is bound to
+* `(envId, name)` as AAD and neither changes across versions, so an old blob
+* opens with the environment's current data key — no special handling needed.
+*/
+async function fetchDecryptedVersion(ctx, orgId, envId, name, version) {
+	const [dek, { versions }] = await Promise.all([getDek(ctx, orgId, envId), ctx.client.listSecretVersions(orgId, envId, name, { limit: 200 })]);
+	const row = versions.find((v) => v.version === version);
+	if (!row) fail(`${name} has no version ${version} in its ${versions.length} newest versions`);
+	return decryptSecret(dek, row.ciphertext, secretAad(envId, name));
 }
 async function encryptAndSetSecret(ctx, orgId, envId, name, value) {
 	const ciphertext = await encryptSecret(await getDek(ctx, orgId, envId), value, secretAad(envId, name));
@@ -1447,34 +2752,82 @@ async function encryptAndSetSecret(ctx, orgId, envId, name, value) {
 * 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;
 	}
-	const { scope, layers } = await ctx.client.resolve(query);
+	const { scope, layers } = await resolveWithCache(ctx, query, opts.cache);
 	const privateKey = await getPrivateKey(ctx);
 	const values = {};
 	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
 	};
 }
 /**
+* Resolve, going through the last-known-good cache when one is configured.
+*
+* Always live first: the cache exists for when the call cannot land, not to
+* save a round trip, so a recovered network is picked up on the very next
+* invocation. A *refused* resolve (401/403/…) drops the entry rather than
+* falling back to it — otherwise revoking a token would keep working offline
+* until the entry aged out.
+*/
+async function resolveWithCache(ctx, query, cache) {
+	if (!cache) return ctx.client.resolve(query);
+	try {
+		const response = await ctx.client.resolve(query);
+		try {
+			cache.write(JSON.stringify(response));
+		} catch (err) {
+			warn(`could not update the cache: ${errorMessage(err)}`);
+		}
+		return response;
+	} catch (err) {
+		if (!mayFallBack(err)) {
+			cache.invalidate();
+			throw err;
+		}
+		const found = cache.read();
+		if (found.kind === "hit") {
+			warn(`${errorMessage(err)} — using cached secrets fetched ${humanize(found.ageMs)} ago`);
+			return JSON.parse(found.body);
+		}
+		if (found.kind === "expired") warn(`cached secrets are ${humanize(found.ageMs)} old, past --cache-max-age`);
+		else if (found.kind === "unusable") warn(`ignoring the cached secrets: ${found.reason}`);
+		throw err;
+	}
+}
+function warn(text) {
+	process.stderr.write(`seekrit: ${text}\n`);
+}
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/**
 * Overlay `.env` files onto an existing value/provenance set (later files win).
 * Missing files are skipped. Returns the files that were actually loaded. Used
 * both by {@link materializeEnv} and by `seekrit run`'s degraded path, where
@@ -1516,6 +2869,16 @@ function errText(err) {
 		isError: true
 	};
 }
+/** Read-only and safe to repeat — every list/inspect tool. */
+const ro = {
+	readOnly: true,
+	idempotent: true
+};
+/** Removes or overwrites something; repeating it lands in the same state. */
+const destructive = {
+	destructive: true,
+	idempotent: true
+};
 /**
 * Short primer surfaced as the MCP server `instructions`. Most clients show
 * this to the model on connect, so it has to orient an agent that lands here
@@ -1563,6 +2926,8 @@ function getStartedText() {
 		"## 3. Store secrets",
 		"- `set_secret` — encrypts a value locally and stores the ciphertext.",
 		"- `list_secrets` — confirm names + versions (never returns values).",
+		"- `list_secret_versions` + `restore_secret` — undo a bad write by rolling",
+		"  back to an earlier version (keyless, and history is append-only).",
 		"",
 		"## 4. Use secrets without exposing them",
 		"- `run_command -- <cmd>` — inject secrets into a subprocess; prefer this.",
@@ -1647,6 +3012,7 @@ async function materializeFor(ctx, o) {
 	if (!isTokenAuth(ctx)) envId = (await resolveAppEnv(ctx, o)).envId;
 	return materializeEnv(ctx, {
 		envId,
+		branch: o.branch,
 		with: o.with,
 		envFiles: o.envFile ?? [".env"]
 	});
@@ -1681,10 +3047,17 @@ async function runMcpServer(options = {}) {
 		version: options.version ?? version$1
 	}, { instructions: serverInstructions() });
 	/** Register a tool whose handler returns data (serialized) or throws (→ isError). */
-	const tool = (name, description, shape, handler) => {
+	const tool = (name, description, hints, shape, handler) => {
 		server.registerTool(name, {
 			description,
-			inputSchema: shape
+			inputSchema: shape,
+			annotations: {
+				title: name,
+				readOnlyHint: hints.readOnly ?? false,
+				destructiveHint: hints.destructive ?? false,
+				idempotentHint: hints.idempotent ?? false,
+				openWorldHint: true
+			}
 		}, (async (args) => {
 			try {
 				return jsonText(await handler(args));
@@ -1702,7 +3075,7 @@ async function runMcpServer(options = {}) {
 			openWorldHint: false
 		}
 	}, async () => jsonText(getStartedText()));
-	tool("whoami", "Show the authenticated identity, its role, and accessible orgs.", {}, async () => {
+	tool("whoami", "Show the authenticated identity, its role, and accessible orgs.", ro, {}, async () => {
 		const ctx = getCtx();
 		if (isTokenAuth(ctx) && ctx.auth.type === "bearer") {
 			const { tokenId } = await parseServiceToken(ctx.auth.token);
@@ -1723,13 +3096,13 @@ async function runMcpServer(options = {}) {
 			...await ctx.client.me()
 		};
 	});
-	tool("list_orgs", "List organizations the caller can access.", {}, async () => (await getCtx().client.listOrgs()).orgs);
-	tool("list_apps", "List applications in an organization.", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_orgs", "List organizations the caller can access.", ro, {}, async () => (await getCtx().client.listOrgs()).orgs);
+	tool("list_apps", "List applications in an organization.", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listApps(orgRef.id)).apps;
 	});
-	tool("list_envs", "List environments of an application.", {
+	tool("list_envs", "List environments of an application.", ro, {
 		org: z.string().optional(),
 		app: z.string()
 	}, async ({ org, app }) => {
@@ -1740,12 +3113,30 @@ async function runMcpServer(options = {}) {
 		if (!appRow) throw new Error(`no app "${app}" in ${orgRef.slug}`);
 		return (await ctx.client.listEnvs(orgRef.id, appRow.id)).environments;
 	});
-	tool("list_groups", "List shared groups (reusable secret bags) in an organization.", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_branches", "List ephemeral branch configs in an application (optionally just one environment's).", ro, {
+		org: z.string().optional(),
+		app: z.string(),
+		env: z.string().optional()
+	}, async ({ org, app, env }) => {
+		const ctx = getCtx();
+		const appRef = await resolveApp(ctx, {
+			org,
+			app
+		});
+		if (!env) return (await ctx.client.listAppBranches(appRef.orgId, appRef.id)).branches;
+		const parent = await resolveAppEnv(ctx, {
+			org,
+			app,
+			env
+		});
+		return (await ctx.client.listBranches(parent.orgId, parent.envId)).branches;
+	});
+	tool("list_groups", "List shared groups (reusable secret bags) in an organization.", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listGroups(orgRef.id)).groups;
 	});
-	tool("list_group_envs", "List a group's environments (per-slug value sets).", {
+	tool("list_group_envs", "List a group's environments (per-slug value sets).", ro, {
 		org: z.string().optional(),
 		group: z.string()
 	}, async ({ org, group }) => {
@@ -1756,7 +3147,7 @@ async function runMcpServer(options = {}) {
 		});
 		return (await ctx.client.listGroupEnvs(g.orgId, g.id)).environments;
 	});
-	tool("list_env_groups", "List the groups composed into an application environment (precedence order).", {
+	tool("list_env_groups", "List the groups composed into an application environment (precedence order).", ro, {
 		org: z.string().optional(),
 		app: z.string(),
 		env: z.string()
@@ -1769,17 +3160,17 @@ async function runMcpServer(options = {}) {
 		});
 		return (await ctx.client.listEnvGroups(target.orgId, target.envId)).groups;
 	});
-	tool("list_members", "List organization members and their public keys (for granting access).", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_members", "List organization members and their public keys (for granting access).", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listMembers(orgRef.id)).members;
 	});
-	tool("kms_list_keys", "List managed KMS keys the caller can see (metadata only).", { org: z.string().optional() }, async ({ org }) => {
+	tool("kms_list_keys", "List managed KMS keys the caller can see (metadata only).", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listKmsKeys(orgRef.id)).keys;
 	});
-	tool("kms_create_key", "Create an org-scoped managed key. Material is generated locally and wrapped to each grantee (self plus any listed users/tokens); the server never sees it. Use the CLI for app/group-scoped keys.", {
+	tool("kms_create_key", "Create an org-scoped managed key. Material is generated locally and wrapped to each grantee (self plus any listed users/tokens); the server never sees it. Use the CLI for app/group-scoped keys.", { idempotent: false }, {
 		org: z.string().optional(),
 		name: z.string(),
 		purpose: z.enum(["encrypt", "sign"]),
@@ -1820,7 +3211,7 @@ async function runMcpServer(options = {}) {
 		});
 		return key;
 	});
-	tool("kms_grant", "Grant a principal (user email or token id) use of a key's current version.", {
+	tool("kms_grant", "Grant a principal (user email or token id) use of a key's current version.", { idempotent: true }, {
 		org: z.string().optional(),
 		key: z.string(),
 		user: z.string().optional(),
@@ -1845,7 +3236,7 @@ async function runMcpServer(options = {}) {
 			key: k.name
 		};
 	});
-	tool("kms_encrypt", "Encrypt a value under a managed encrypt key; returns a ce1 ciphertext blob. `context` (if given) is bound as AAD and must be supplied identically to decrypt.", {
+	tool("kms_encrypt", "Encrypt a value under a managed encrypt key; returns a ce1 ciphertext blob. `context` (if given) is bound as AAD and must be supplied identically to decrypt.", { readOnly: true }, {
 		org: z.string().optional(),
 		key: z.string(),
 		plaintext: z.string(),
@@ -1862,7 +3253,7 @@ async function runMcpServer(options = {}) {
 			version: currentVersion
 		}, plaintext, context ?? "") };
 	});
-	tool("kms_decrypt", "Decrypt a ce1 blob. Supply the same `context` used to encrypt.", {
+	tool("kms_decrypt", "Decrypt a ce1 blob. Supply the same `context` used to encrypt.", ro, {
 		org: z.string().optional(),
 		key: z.string(),
 		ciphertext: z.string(),
@@ -1876,7 +3267,7 @@ async function runMcpServer(options = {}) {
 		const { material } = await kmsRecoverMaterial(ctx, orgRef.id, k.id, ref.version);
 		return { plaintext: await kmsDecrypt(material, ciphertext, context ?? "") };
 	});
-	tool("kms_generate_data_key", "Generate a data key under a managed encrypt key (envelope encryption). Returns the plaintext key (base64) and its wrapped form to store.", {
+	tool("kms_generate_data_key", "Generate a data key under a managed encrypt key (envelope encryption). Returns the plaintext key (base64) and its wrapped form to store.", { readOnly: true }, {
 		org: z.string().optional(),
 		key: z.string()
 	}, async ({ org, key }) => {
@@ -1895,7 +3286,7 @@ async function runMcpServer(options = {}) {
 			wrapped: dk.wrapped
 		};
 	});
-	tool("kms_sign", "Sign a message with a managed signing key; returns an sg1 signature blob.", {
+	tool("kms_sign", "Sign a message with a managed signing key; returns an sg1 signature blob.", { readOnly: true }, {
 		org: z.string().optional(),
 		key: z.string(),
 		message: z.string()
@@ -1911,7 +3302,7 @@ async function runMcpServer(options = {}) {
 			version: currentVersion
 		}, message) };
 	});
-	tool("kms_verify", "Verify an sg1 signature over a message using a signing key's published public key (no grant needed).", {
+	tool("kms_verify", "Verify an sg1 signature over a message using a signing key's published public key (no grant needed).", ro, {
 		org: z.string().optional(),
 		key: z.string(),
 		signature: z.string(),
@@ -1926,7 +3317,7 @@ async function runMcpServer(options = {}) {
 		if (!pub) throw new Error(`no published public key for version ${ref.version}`);
 		return { valid: await verifyMessage(await importVerifyingKey(pub), signature, message) };
 	});
-	tool("list_secrets", "List secret names + versions in an environment (never values).", targetShape, async (o) => {
+	tool("list_secrets", "List secret names + versions in an environment (never values).", ro, targetShape, async (o) => {
 		const ctx = getCtx();
 		const { orgId, envId } = await resolveTargetEnv(ctx, o);
 		const { secrets } = await ctx.client.listSecrets(orgId, envId);
@@ -1936,12 +3327,12 @@ async function runMcpServer(options = {}) {
 			updatedAt: s.updatedAt
 		}));
 	});
-	tool("list_tokens", "List an organization's service tokens (never the secret token strings).", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_tokens", "List an organization's service tokens (never the secret token strings).", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listTokens(orgRef.id)).tokens;
 	});
-	tool("audit", "Read the organization's audit trail (most recent first).", {
+	tool("audit", "Read the organization's audit trail (most recent first).", ro, {
 		org: z.string().optional(),
 		limit: z.number().int().min(1).max(200).optional(),
 		action: z.string().optional().describe("filter by action, e.g. secret.updated")
@@ -1953,14 +3344,14 @@ async function runMcpServer(options = {}) {
 			action
 		})).entries;
 	});
-	tool("create_org", "Create an organization. Requires a user session — service tokens cannot own a Stytch org.", {
+	tool("create_org", "Create an organization. Requires a user session — service tokens cannot own a Stytch org.", { idempotent: false }, {
 		name: z.string(),
 		slug: z.string()
 	}, async ({ name, slug }) => (await getCtx().client.createOrg({
 		name,
 		slug
 	})).org);
-	tool("create_app", "Create an application in an organization.", {
+	tool("create_app", "Create an application in an organization.", { idempotent: false }, {
 		org: z.string().optional(),
 		name: z.string(),
 		slug: z.string()
@@ -1972,7 +3363,7 @@ async function runMcpServer(options = {}) {
 			slug
 		})).app;
 	});
-	tool("create_group", "Create a shared group (reusable secret bag) in an organization.", {
+	tool("create_group", "Create a shared group (reusable secret bag) in an organization.", { idempotent: false }, {
 		org: z.string().optional(),
 		name: z.string(),
 		slug: z.string()
@@ -1984,7 +3375,7 @@ async function runMcpServer(options = {}) {
 			slug
 		})).group;
 	});
-	tool("create_env", "Create an application environment. Generates the data key locally and grants it to the caller.", {
+	tool("create_env", "Create an application environment. Generates the data key locally and grants it to the caller.", { idempotent: false }, {
 		org: z.string().optional(),
 		app: z.string(),
 		name: z.string(),
@@ -2002,7 +3393,56 @@ async function runMcpServer(options = {}) {
 			wrappedDek
 		})).environment;
 	});
-	tool("create_group_env", "Create a group environment. Generates the data key locally and grants it to the caller.", {
+	tool("create_branch", "Fork an environment into an ephemeral branch (a per-PR / preview config). The branch inherits the parent's secrets by layering at read time — nothing is copied or re-encrypted — and holds only the values you override on it. Generates the branch's data key locally, grants it to the caller, and shares it with the parent's other readers.", { idempotent: false }, {
+		org: z.string().optional(),
+		app: z.string(),
+		from: z.string().describe("the environment to branch"),
+		slug: z.string().describe("the branch name, e.g. pr-142"),
+		ttl: z.string().optional().describe("lifetime: 12h, 7d, 2w, … or `never` (default 7d)")
+	}, async ({ org, app, from, slug, ttl }) => {
+		const ctx = getCtx();
+		const parent = await resolveAppEnv(ctx, {
+			org,
+			app,
+			env: from
+		});
+		const parsedTtl = parseBranchTtl(ttl ?? "7d");
+		if (parsedTtl === null) throw new Error(`invalid ttl "${ttl}" (try 12h, 7d, 2w, or never)`);
+		const me = await kmsCallerIdentity(ctx);
+		const dek = generateDek();
+		const wrappedDek = await wrapDek(dek, me.publicKeyJwk);
+		const grants = [];
+		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)
+			});
+		}
+		return (await ctx.client.createBranch(parent.orgId, parent.envId, {
+			slug,
+			ttlSeconds: Number.isFinite(parsedTtl) ? parsedTtl : null,
+			wrappedDek,
+			grants
+		})).branch;
+	});
+	tool("delete_branch", "Tear down a branch config and every value it overrode. The parent environment is untouched.", destructive, {
+		org: z.string().optional(),
+		app: z.string(),
+		branch: z.string()
+	}, async ({ org, app, branch }) => {
+		const ctx = getCtx();
+		const appRef = await resolveApp(ctx, {
+			org,
+			app
+		});
+		const target = await resolveBranch(ctx, appRef, branch);
+		await ctx.client.deleteBranch(appRef.orgId, target.id);
+		return { deleted: target.slug };
+	});
+	tool("create_group_env", "Create a group environment. Generates the data key locally and grants it to the caller.", { idempotent: false }, {
 		org: z.string().optional(),
 		group: z.string(),
 		name: z.string(),
@@ -2020,7 +3460,7 @@ async function runMcpServer(options = {}) {
 			wrappedDek
 		})).environment;
 	});
-	tool("compose_group", "Compose a group into an application environment (higher position wins on name clashes).", {
+	tool("compose_group", "Compose a group into an application environment (higher position wins on name clashes).", { idempotent: true }, {
 		org: z.string().optional(),
 		app: z.string(),
 		env: z.string(),
@@ -2042,7 +3482,7 @@ async function runMcpServer(options = {}) {
 			position
 		})).group;
 	});
-	tool("uncompose_group", "Remove a composed group from an application environment.", {
+	tool("uncompose_group", "Remove a composed group from an application environment.", { idempotent: true }, {
 		org: z.string().optional(),
 		app: z.string(),
 		env: z.string(),
@@ -2061,7 +3501,7 @@ async function runMcpServer(options = {}) {
 		await ctx.client.unlinkEnvGroup(target.orgId, target.envId, g.id);
 		return { ok: true };
 	});
-	tool("set_secret", "Encrypt a value locally and store it in an environment.", {
+	tool("set_secret", "Encrypt a value locally and store it in an environment. A value may reference another secret as ${OTHER_SECRET}: the reference is stored literally and expanded whenever the secret is read, so it tracks the referenced value. Write $${OTHER_SECRET} for a literal.", { idempotent: false }, {
 		...targetShape,
 		name: z.string(),
 		value: z.string()
@@ -2075,10 +3515,12 @@ async function runMcpServer(options = {}) {
 			name: o.name
 		};
 	});
-	tool("get_secret", "Return one secret. By default only reports presence + version; pass reveal:true to decrypt the plaintext into this response (avoid unless the value is actually needed — prefer run_command).", {
+	tool("get_secret", "Return one secret. By default only reports presence + version; pass reveal:true to decrypt the plaintext into this response (avoid unless the value is actually needed — prefer run_command). A revealed current value has its ${OTHER_SECRET} references expanded against this environment's own secrets; pass raw:true for the stored text instead. Pass `version` to read an earlier version instead of the current one (always as stored, never expanded).", ro, {
 		...targetShape,
 		name: z.string(),
-		reveal: z.boolean().optional()
+		reveal: z.boolean().optional(),
+		raw: z.boolean().optional().describe("skip ${OTHER_SECRET} expansion (with reveal)"),
+		version: z.number().int().positive().optional().describe("an earlier version from list_secret_versions (default: current)")
 	}, async (o) => {
 		const ctx = getCtx();
 		const { orgId, envId } = await resolveTargetEnv(ctx, o);
@@ -2088,12 +3530,21 @@ async function runMcpServer(options = {}) {
 			if (!row) throw new Error(`no secret named ${o.name}`);
 			return {
 				name: row.name,
-				version: row.version,
+				version: o.version ?? row.version,
 				revealed: false
 			};
 		}
 		ensureDecryptable(ctx);
-		const values = await fetchDecryptedSecrets(ctx, orgId, envId);
+		if (o.version !== void 0) {
+			const value = await fetchDecryptedVersion(ctx, orgId, envId, o.name, o.version);
+			return {
+				name: o.name,
+				version: o.version,
+				value,
+				revealed: true
+			};
+		}
+		const values = await fetchDecryptedSecrets(ctx, orgId, envId, { raw: o.raw });
 		if (!(o.name in values)) throw new Error(`no secret named ${o.name}`);
 		return {
 			name: o.name,
@@ -2101,7 +3552,40 @@ async function runMcpServer(options = {}) {
 			revealed: true
 		};
 	});
-	tool("delete_secret", "Delete a secret from an environment.", {
+	tool("list_secret_versions", "List a secret's version history: who wrote each version, when, and which ones were restores. Never returns values — pair it with restore_secret to roll back, or get_secret(version, reveal:true) to inspect one.", ro, {
+		...targetShape,
+		name: z.string(),
+		limit: z.number().int().min(1).max(200).optional().describe("default 20")
+	}, async (o) => {
+		const ctx = getCtx();
+		const { orgId, envId } = await resolveTargetEnv(ctx, o);
+		const { versions, currentVersion } = await ctx.client.listSecretVersions(orgId, envId, o.name, { limit: o.limit ?? 20 });
+		return {
+			currentVersion,
+			versions: versions.map((v) => ({
+				version: v.version,
+				createdAt: v.createdAt,
+				createdBy: `${v.createdByType}:${v.createdById}`,
+				restoredFromVersion: v.restoredFromVersion
+			}))
+		};
+	});
+	tool("restore_secret", "Roll a secret back to an earlier version. The stored ciphertext is replayed as a NEW version (history is append-only, nothing is overwritten). Keyless — no decryption happens, so this works even without a key.", { idempotent: false }, {
+		...targetShape,
+		name: z.string(),
+		version: z.number().int().positive()
+	}, async (o) => {
+		const ctx = getCtx();
+		const { orgId, envId } = await resolveTargetEnv(ctx, o);
+		const { secret, restoredFrom } = await ctx.client.restoreSecret(orgId, envId, o.name, o.version);
+		return {
+			ok: true,
+			name: o.name,
+			restoredFrom,
+			version: secret.version
+		};
+	});
+	tool("delete_secret", "Delete a secret from an environment.", destructive, {
 		...targetShape,
 		name: z.string()
 	}, async (o) => {
@@ -2114,11 +3598,15 @@ async function runMcpServer(options = {}) {
 		};
 	});
 	tool("run_command", "Run a command with the resolved secrets injected as environment variables, and return its exit code + captured output. Secret VALUES are never returned — this is the preferred way to use secrets. process env > .env > app env > groups.", {
+		destructive: true,
+		idempotent: false
+	}, {
 		command: z.string().describe("executable to run"),
 		args: z.array(z.string()).optional(),
 		org: z.string().optional(),
 		app: z.string().optional(),
 		env: z.string().optional().describe("environment slug (token auth infers this)"),
+		branch: z.string().optional().describe("read an ephemeral branch of that environment"),
 		with: z.record(z.string(), z.string()).optional().describe("group=env slice overrides"),
 		envFile: z.array(z.string()).optional().describe(".env files to overlay (default [.env])"),
 		cwd: z.string().optional()
@@ -2135,11 +3623,12 @@ async function runMcpServer(options = {}) {
 			injectedVarCount: Object.keys(values).length
 		};
 	});
-	tool("export_env", "Write the resolved secrets to a dotenv file on disk and return the variable names written (never the values). Use to materialize a .env for local tooling.", {
+	tool("export_env", "Write the resolved secrets to a dotenv file on disk and return the variable names written (never the values). Use to materialize a .env for local tooling.", destructive, {
 		file: z.string().describe("path to write, e.g. .env"),
 		org: z.string().optional(),
 		app: z.string().optional(),
 		env: z.string().optional(),
+		branch: z.string().optional().describe("read an ephemeral branch of that environment"),
 		with: z.record(z.string(), z.string()).optional()
 	}, async (o) => {
 		const ctx = getCtx();
@@ -2153,7 +3642,7 @@ async function runMcpServer(options = {}) {
 			names: Object.keys(values).sort()
 		};
 	});
-	tool("create_token", "Mint a service token, printed once. Runtime tokens bind to one app environment (auto-granted its keys, so a command/agent can decrypt it). Pass admin:true for an org-scoped provisioning token (create apps/groups/envs, grant, mint tokens) — admin tokens need no env binding.", {
+	tool("create_token", "Mint a service token, printed once. Runtime tokens bind to one app environment (auto-granted its keys, so a command/agent can decrypt it). Pass admin:true for an org-scoped provisioning token (create apps/groups/envs, grant, mint tokens) — admin tokens need no env binding.", { idempotent: false }, {
 		name: z.string().describe("display name, e.g. ci-deploy or agent-session"),
 		org: z.string().optional(),
 		app: z.string().optional().describe("bind to this app (runtime tokens)"),
@@ -2204,7 +3693,7 @@ async function runMcpServer(options = {}) {
 			note: "save this now — the secret token string is not stored and cannot be retrieved"
 		};
 	});
-	tool("revoke_token", "Revoke a service token by id.", {
+	tool("revoke_token", "Revoke a service token by id.", destructive, {
 		org: z.string().optional(),
 		tokenId: z.string()
 	}, async ({ org, tokenId }) => {
@@ -2216,7 +3705,7 @@ async function runMcpServer(options = {}) {
 			tokenId
 		};
 	});
-	tool("grant_env", "Grant a member (by email) or service token (by id) access to an environment's data key. Re-wraps the DEK to the grantee — the caller must already hold the key.", {
+	tool("grant_env", "Grant a member (by email) or service token (by id) access to an environment's data key. Re-wraps the DEK to the grantee — the caller must already hold the key.", { idempotent: true }, {
 		...targetShape,
 		user: z.string().optional().describe("org member email"),
 		token: z.string().optional().describe("service token id (skt_…)")
@@ -2261,12 +3750,12 @@ async function runMcpServer(options = {}) {
 			principalId
 		};
 	});
-	tool("list_pg_targets", "List registered Postgres provisioning targets for temporary credentials.", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_pg_targets", "List registered Postgres provisioning targets for temporary credentials.", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listLeaseTargets(orgRef.id)).targets;
 	});
-	tool("create_pg_lease", "Mint a short-lived Postgres credential against a target and return a ready-to-use connection URL. The password is generated on THIS machine and only its SCRAM verifier is sent to the API — the plaintext never reaches seekrit or Postgres at rest. The role auto-expires; revoke early with revoke_pg_lease.", {
+	tool("create_pg_lease", "Mint a short-lived Postgres credential against a target and return a ready-to-use connection URL. The password is generated on THIS machine and only its SCRAM verifier is sent to the API — the plaintext never reaches seekrit or Postgres at rest. The role auto-expires; revoke early with revoke_pg_lease.", { idempotent: false }, {
 		org: z.string().optional(),
 		target: z.string().describe("target id or name"),
 		role: z.string().optional().describe("role name to create (default: random tmp_ name)"),
@@ -2295,12 +3784,12 @@ async function runMcpServer(options = {}) {
 			note: "short-lived credential; it auto-expires and the plaintext is not stored anywhere"
 		};
 	});
-	tool("list_pg_leases", "List Postgres leases (the ledger — never secret material).", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_pg_leases", "List Postgres leases (the ledger — never secret material).", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listLeases(orgRef.id)).leases;
 	});
-	tool("revoke_pg_lease", "Revoke a Postgres lease now (drops the role immediately).", {
+	tool("revoke_pg_lease", "Revoke a Postgres lease now (drops the role immediately).", destructive, {
 		org: z.string().optional(),
 		leaseId: z.string()
 	}, async ({ org, leaseId }) => {
@@ -2312,12 +3801,12 @@ async function runMcpServer(options = {}) {
 			leaseId
 		};
 	});
-	tool("list_mysql_targets", "List registered MySQL/MariaDB provisioning targets for temporary credentials.", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_mysql_targets", "List registered MySQL/MariaDB provisioning targets for temporary credentials.", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listLeaseTargets(orgRef.id)).targets.filter((t) => t.provider === "mysql");
 	});
-	tool("create_mysql_lease", "Mint a short-lived MySQL/MariaDB credential against a target and return a ready-to-use connection URL. The password is generated on THIS machine and only its mysql_native_password hash is sent to the API — the plaintext never reaches seekrit or MySQL at rest. The user auto-expires; revoke early with revoke_mysql_lease.", {
+	tool("create_mysql_lease", "Mint a short-lived MySQL/MariaDB credential against a target and return a ready-to-use connection URL. The password is generated on THIS machine and only its mysql_native_password hash is sent to the API — the plaintext never reaches seekrit or MySQL at rest. The user auto-expires; revoke early with revoke_mysql_lease.", { idempotent: false }, {
 		org: z.string().optional(),
 		target: z.string().describe("target id or name"),
 		user: z.string().optional().describe("user name to create (default: random tmp_ name)"),
@@ -2347,12 +3836,12 @@ async function runMcpServer(options = {}) {
 			note: "short-lived credential; it auto-expires and the plaintext is not stored anywhere"
 		};
 	});
-	tool("list_mysql_leases", "List MySQL/MariaDB leases (the ledger — never secret material).", { org: z.string().optional() }, async ({ org }) => {
+	tool("list_mysql_leases", "List MySQL/MariaDB leases (the ledger — never secret material).", ro, { org: z.string().optional() }, async ({ org }) => {
 		const ctx = getCtx();
 		const orgRef = await resolveOrg(ctx, org);
 		return (await ctx.client.listLeases(orgRef.id)).leases.filter((l) => l.provider === "mysql");
 	});
-	tool("revoke_mysql_lease", "Revoke a MySQL/MariaDB lease now (drops the user immediately).", {
+	tool("revoke_mysql_lease", "Revoke a MySQL/MariaDB lease now (drops the user immediately).", destructive, {
 		org: z.string().optional(),
 		leaseId: z.string()
 	}, async ({ org, leaseId }) => {
@@ -2364,7 +3853,7 @@ async function runMcpServer(options = {}) {
 			leaseId
 		};
 	});
-	tool("configure_project", "Link a directory to an org/app by writing seekrit.json (like `seekrit init`). The environment is chosen by the service token at runtime.", {
+	tool("configure_project", "Link a directory to an org/app by writing seekrit.json (like `seekrit init`). The environment is chosen by the service token at runtime.", destructive, {
 		org: z.string(),
 		app: z.string(),
 		dir: z.string().optional()
@@ -2389,7 +3878,7 @@ async function runMcpServer(options = {}) {
 /**
 * `@seekrit/mcp` — a standalone, `npx`-able entrypoint for seekrit's MCP server.
 *
-* This is a thin wrapper: the server itself (all 27 tools, the crypto plane of
+* This is a thin wrapper: the server itself (every tool, the crypto plane of
 * the two-server design) lives in `@seekrit/cli` and is shared with the
 * `seekrit mcp` subcommand — this package just publishes it as its own binary so
 * an agent can run it with zero prior install:
@@ -2402,7 +3891,7 @@ async function runMcpServer(options = {}) {
 * `seekrit mcp`. tsdown bundles the shared server source in at build time, so the
 * published package is self-contained and needs no `@seekrit/cli` install.
 */
-runMcpServer({ version: "0.5.0" }).catch((err) => {
+runMcpServer({ version: "0.6.1" }).catch((err) => {
 	const message = err instanceof Error ? err.message : String(err);
 	process.stderr.write(`seekrit-mcp: fatal: ${message}\n`);
 	process.exit(1);