@selvajs/cli 4.20.0-beta.20 → 4.20.0-beta.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selvajs/cli",
-  "version": "4.20.0-beta.20",
+  "version": "4.20.0-beta.21",
   "description": "Scaffold and operate a Selva white-label deployment. `npx @selvajs/cli <dir>` to bootstrap, `selva <cmd>` to manage.",
   "license": "MIT",
   "author": "VektorNode",
@@ -46,6 +46,6 @@
   "scripts": {
     "start": "node ./bin/cli.js",
     "selva": "node ./bin/selva.js",
-    "test": "node --check ./bin/cli.js && node --check ./bin/selva.js && node --input-type=module -e \"for (const m of ['./src/cli.js','./src/prompts.js','./src/env.js','./src/paths.js','./src/secrets.js','./src/node-range.js','./src/deployment-package.js','./src/commands/create.js','./src/commands/init.js','./src/commands/doctor.js','./src/commands/pm2.js','./src/commands/migrate.js','./src/commands/keys.js']) { await import(m); }\" && node --test \"./src/__tests__/*.test.js\""
+    "test": "node --check ./bin/cli.js && node --check ./bin/selva.js && node --input-type=module -e \"for (const m of ['./src/cli.js','./src/prompts.js','./src/env.js','./src/paths.js','./src/secrets.js','./src/node-range.js','./src/deployment-package.js','./src/commands/create.js','./src/commands/init.js','./src/commands/doctor.js','./src/commands/pm2.js','./src/commands/migrate.js','./src/commands/keys.js','./src/commands/config.js','./src/env-migration.js']) { await import(m); }\" && node --test \"./src/__tests__/*.test.js\""
   }
 }

package/src/caddyfile.js

@@ -46,10 +46,10 @@ export function renderCaddyfile({ domain, acmeEmail, port = 3000 }) {
 	header @api Cache-Control "no-cache, no-store, must-revalidate"
 
 	# Must clear the app's own caps (COMPUTE_REQUEST_MAX_BYTES / BODY_SIZE_LIMIT,
-	# both 256 MB) — Caddy rejects first, so a lower value here silently caps
-	# every upload no matter what .env says.
+	# both 256 MiB) — Caddy rejects first, so a lower value here silently caps
+	# every upload no matter what .env says. Write MiB: Caddy's "mb" is 10^6 bytes.
 	request_body {
-		max_size 256mb
+		max_size 256MiB
 	}
 
 	log {

package/src/checks/config.js

@@ -11,6 +11,7 @@
 // table, so a rule changed here and not there fails CI.
 
 import { RENAMED_ENV_VARS, REPLACED_ENV_VARS } from '../env.js';
+import { keyRotationStatus } from '../generated/config.js';
 import { green, red, yellow } from './result.js';
 
 const HEX_64 = /^[0-9a-f]{64}$/i;
@@ -28,10 +29,33 @@ const VALID_DATA = ['local', 'supabase'];
 export function checkSecret(value, label) {
 	if (!value) return red(`${label} — unset`);
 	if (value === PLACEHOLDER) return red(`${label} — still the placeholder`);
-	if (!HEX_64.test(value)) return red(`${label} — not 64 hex chars`);
+	if (!HEX_64.test(value) && !isBase64Of32Bytes(value)) {
+		return red(`${label} — not 32 bytes as 64 hex chars or base64`);
+	}
 	return green(label);
 }
 
+/**
+ * SELVA_HMAC_KEY takes any string of 32+ characters (the token codec's rule),
+ * not only hex: reding a valid key would send an operator rotating it.
+ */
+export function checkHmacKey(value) {
+	const label = 'SELVA_HMAC_KEY is at least 32 characters';
+	if (!value) return red(`${label} — unset`);
+	if (value === PLACEHOLDER) return red(`${label} — still the placeholder`);
+	if (value.length < 32) return red(`${label} — only ${value.length}`);
+	return green(label);
+}
+
+// Mirrors decodeSecretKey in @selvajs/platform: only a round trip proves the
+// whole string was base64, since Buffer.from skips what it can't decode.
+function isBase64Of32Bytes(value) {
+	const buf = Buffer.from(value, 'base64');
+	return (
+		buf.length === 32 && buf.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
+	);
+}
+
 // Lowercased and defaulted the same way create-selva-providers.ts defaults them.
 export function resolveProviders(env) {
 	return {
@@ -291,6 +315,19 @@ export function checkClientAddress(env) {
 		);
 	}
 
+	// A trusted address header is only safe if every request passes through the
+	// proxy: on a public bind a direct caller sets the header itself and picks
+	// its own rate-limit bucket.
+	const host = env.HOST ?? '0.0.0.0';
+	if (!['127.0.0.1', 'localhost', '::1'].includes(host)) {
+		return yellow(
+			`ADDRESS_HEADER=${header} is trusted but HOST=${host} leaves the app reachable ` +
+				`without the proxy, so a direct caller can set the header and pick its own ` +
+				`rate-limit bucket. Set HOST=127.0.0.1 and keep port 3000 closed in the ` +
+				`firewall (ignore this only if the proxy runs on another host behind network isolation).`
+		);
+	}
+
 	return green(`ADDRESS_HEADER=${header}${depth ? ` (XFF_DEPTH=${depth})` : ''}`);
 }
 
@@ -316,3 +353,33 @@ export function checkDeprecatedEnv(env) {
 
 	return checks;
 }
+
+/** Where each root key's rotation overlap stands. Nothing while no rotation is in progress. */
+export function checkKeyRotation(env, now = Date.now()) {
+	return keyRotationStatus(env, now).flatMap(({ key, state, expires, daysLeft }) => {
+		const previous = `${key}_PREVIOUS`;
+		const target = key === 'SELVA_HMAC_KEY' ? 'hmac' : 'at-rest';
+		if (state === 'active') {
+			return [
+				green(`${previous} accepted for ${daysLeft} more days (until ${expires.slice(0, 10)})`)
+			];
+		}
+		if (state === 'expired') {
+			return [
+				yellow(
+					`${previous} passed its deadline (${expires}) and is no longer accepted. ` +
+						`Remove it: npx selva keys rotate ${target} --finish`
+				)
+			];
+		}
+		if (state === 'no-deadline') {
+			return [
+				yellow(
+					`${previous} has no deadline, so the old key is accepted for good. Set ` +
+						`${previous}_EXPIRES, or remove it: npx selva keys rotate ${target} --finish`
+				)
+			];
+		}
+		return [];
+	});
+}

package/src/cli.js

@@ -16,7 +16,8 @@ const COMMANDS = {
 	update: () => import('./commands/pm2.js').then((m) => m.runUpdate),
 	migrate: () => import('./commands/migrate.js').then((m) => m.runMigrate),
 	'setup-proxy': () => import('./commands/proxy.js').then((m) => m.runSetupProxy),
-	keys: () => import('./commands/keys.js').then((m) => keysDispatch(m))
+	keys: () => import('./commands/keys.js').then((m) => keysDispatch(m)),
+	config: () => import('./commands/config.js').then((m) => m.runConfig)
 };
 
 // `selva doctor --help` used to run the full doctor: commands own their argv,
@@ -49,9 +50,13 @@ const USAGE = {
 			'npm update @selvajs/cli + @selvajs/selva, then restart. Rolls the\ndependency tree back if the install fails.'
 	},
 	migrate: {
-		usage: 'selva migrate',
+		usage: 'selva migrate [--dry-run | --undo]',
 		blurb:
-			'Bring package.json and the deployment layout onto the current release.\nRewrites keys, never comments.'
+			'Bring package.json, the deployment layout and .env onto the current release.\nRenames old keys and proves every setting keeps its meaning before writing.',
+		flags: [
+			['--dry-run', 'Show what would change. Writes nothing.'],
+			['--undo', 'Restore the newest .env backup.']
+		]
 	},
 	'setup-proxy': {
 		usage: 'selva setup-proxy [--domain <fqdn>] [--acme-email <addr>]',
@@ -62,10 +67,20 @@ const USAGE = {
 			['--acme-email', "Address Let's Encrypt sends expiry notices to."]
 		]
 	},
+	config: {
+		usage: 'selva config <show [--all] | set KEY=VALUE | unset KEY>',
+		blurb:
+			'Show what .env sets, what is default and what is wrong; set or unset one\nkey after checking it. Edits only that line and keeps a backup.',
+		flags: [['--all', 'show: list every setting, defaults included.']]
+	},
 	keys: {
-		usage: 'selva keys rotate <hmac|at-rest>',
+		usage: 'selva keys rotate <hmac|at-rest> [--finish | --leaked]',
 		blurb:
-			'Rotate one secret in .env. Destructive and not reversible — the command\nspells out the blast radius and asks before writing.'
+			'Rotate one secret in .env. The old key stays accepted as <KEY>_PREVIOUS, so\nnothing breaks; --finish drops it later. --leaked drops it at once.',
+		flags: [
+			['--finish', 'Remove <KEY>_PREVIOUS once the overlap has passed.'],
+			['--leaked', 'Replace the key and drop the old one now. Breaks what it signed.']
+		]
 	}
 };
 
@@ -85,7 +100,7 @@ function keysDispatch(m) {
 	return async (argv) => {
 		const sub = argv[0];
 		if (sub === 'rotate') return m.runKeysRotate(argv.slice(1));
-		console.error(`Usage: selva keys rotate <hmac|at-rest>`);
+		console.error(`Usage: selva keys rotate <hmac|at-rest> [--finish | --leaked]`);
 		process.exit(1);
 	};
 }
@@ -140,7 +155,8 @@ function printHelp() {
 			'  update                  npm update @selvajs/cli + @selvajs/selva, then restart',
 			'  migrate                 Bring package.json onto the current layout',
 			'  setup-proxy             Install + configure Caddy with TLS for this deployment',
-			'  keys rotate <hmac|at-rest>   Rotate a secret in .env (destructive)',
+			'  config show|set|unset   What .env sets; change one key safely',
+			'  keys rotate <hmac|at-rest>   Rotate a secret; the old one keeps working',
 			'',
 			pc.dim('`npx selva <command> --help` explains one command.'),
 			'',

package/src/commands/config.js

@@ -0,0 +1,196 @@
+// `selva config show|set|unset`: what this deployment's .env sets, checked
+// against the manifest the runtime declares.
+
+import { copyFileSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import pc from 'picocolors';
+import { parseEnv, setEnvValues, writeEnvText } from '../env.js';
+import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
+import {
+	ALL_SETTINGS,
+	deploymentReport,
+	deploymentSnapshot,
+	diffSnapshots,
+	resolveConfig
+} from '../generated/config.js';
+import { backupPathFor, backupStamp } from './migrate.js';
+
+export const SNAPSHOT_FILE = '.selva-config-snapshot.json';
+
+/** The same report the app builds for /admin/system. */
+export const reportFor = deploymentReport;
+
+/**
+ * How `.env` differs from what the app last booted with. Non-empty means it
+ * was edited without a restart, or something (pm2's saved env, compose)
+ * overrides it.
+ */
+export function driftFromLastBoot(dir, env) {
+	const path = join(dir, SNAPSHOT_FILE);
+	if (!existsSync(path)) return null;
+	let snapshot;
+	try {
+		snapshot = JSON.parse(readFileSync(path, 'utf8'));
+	} catch {
+		return null;
+	}
+	return diffSnapshots(snapshot, deploymentSnapshot(env, snapshot.salt));
+}
+
+/** Validate one KEY=VALUE against the manifest. Returns the spec, or an error message. */
+export function checkSetting(key, value) {
+	const spec = ALL_SETTINGS.find((s) => s.key === key);
+	if (!spec) {
+		const alias = ALL_SETTINGS.find((s) => s.aliases?.includes(key));
+		return {
+			error: alias
+				? `${key} was renamed to ${alias.key}.`
+				: `${key} is not a setting Selva reads. \`selva config show --all\` lists them.`
+		};
+	}
+	// Setting a key by hand skips _PREVIOUS and breaks what it protected.
+	if (spec.class === 'secret' && spec.generated) {
+		const target = key.startsWith('SELVA_HMAC_KEY') ? 'hmac' : 'at-rest';
+		return {
+			error: `${key} is replaced with \`selva keys rotate ${target}\`, which keeps the old key working.`
+		};
+	}
+	const report = resolveConfig([spec], { [key]: value }).keys[key];
+	if (report.status !== 'ok') return { error: `${key} ${report.problem}.` };
+	return { spec };
+}
+
+function printRow(row) {
+	const value = row.display === '' ? pc.dim('—') : row.display;
+	const source =
+		row.source === 'default'
+			? pc.dim('default')
+			: row.source === 'unset'
+				? pc.dim('not set')
+				: row.source === 'alias'
+					? pc.yellow(`from ${row.alias}`)
+					: '.env';
+	const mark =
+		row.status === 'error' ? pc.red('✗') : row.status === 'invalid' ? pc.yellow('!') : ' ';
+	console.log(`${mark} ${row.key.padEnd(36)} ${String(value).padEnd(30)} ${source}`);
+	if (row.problem) console.log(`    ${pc.red(`value ${row.problem}`)}`);
+}
+
+export async function runConfig(argv) {
+	const [sub, ...rest] = argv;
+	if (sub === 'show' || sub === undefined) return runShow(rest);
+	if (sub === 'set') return runSet(rest);
+	if (sub === 'unset') return runUnset(rest);
+	console.error('Usage: selva config <show [--all] | set KEY=VALUE | unset KEY>');
+	process.exit(1);
+}
+
+function readDeploymentEnv() {
+	const dir = resolveDeploymentDir();
+	requireDeploymentDir(dir);
+	const envPath = join(dir, '.env');
+	const text = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+	return { dir, envPath, text, env: parseEnv(text) };
+}
+
+function runShow(argv) {
+	const all = argv.includes('--all');
+	const { dir, env } = readDeploymentEnv();
+	const report = reportFor(env);
+
+	console.log(pc.bold('\nThe important ones'));
+	for (const row of report.rows.filter((r) => r.summary)) printRow(row);
+
+	const rest = report.rows.filter(
+		(r) => !r.summary && (all || r.source !== 'default') && r.source !== 'unset'
+	);
+	if (rest.length > 0) {
+		console.log(pc.bold(all ? '\nEverything else' : '\nAlso set in .env'));
+		for (const row of rest) printRow(row);
+	}
+
+	if (report.unknown.length > 0) {
+		console.log(pc.bold('\nNot settings Selva reads'));
+		for (const u of report.unknown) {
+			console.log(
+				`${pc.yellow('!')} ${u.key}${u.suggestion ? pc.dim(`  did you mean ${u.suggestion}?`) : ''}`
+			);
+		}
+	}
+
+	const drift = driftFromLastBoot(dir, env);
+	if (drift && drift.length > 0) {
+		console.log(pc.bold('\nDiffers from what the app last started with'));
+		console.log(
+			pc.dim('  Restart to apply, or check whether pm2 or the environment overrides .env.')
+		);
+		for (const c of drift) {
+			const detail =
+				c.from !== undefined || c.to !== undefined ? `  ${c.from ?? '—'} → ${c.to ?? '—'}` : '';
+			console.log(`  ${c.key} ${pc.dim(c.change)}${detail}`);
+		}
+	}
+
+	const errors = report.problems.filter((p) => p.status === 'error').length;
+	console.log(
+		'\n' +
+			(errors > 0
+				? pc.red(`${errors} setting${errors === 1 ? '' : 's'} would stop the app from starting.`)
+				: pc.green('Nothing stops the app from starting.')) +
+			(all ? '' : pc.dim('  `selva config show --all` lists every setting.'))
+	);
+	if (errors > 0) process.exit(1);
+}
+
+function backUp(envPath) {
+	if (!existsSync(envPath)) return null;
+	const bak = backupPathFor(envPath, backupStamp());
+	copyFileSync(envPath, bak);
+	writeEnvText(bak, readFileSync(bak, 'utf8'));
+	return bak;
+}
+
+function runSet(argv) {
+	const arg = argv[0] ?? '';
+	const eq = arg.indexOf('=');
+	if (eq <= 0) {
+		console.error('Usage: selva config set KEY=VALUE');
+		process.exit(1);
+	}
+	const key = arg.slice(0, eq);
+	const value = arg.slice(eq + 1);
+	const { spec, error } = checkSetting(key, value);
+	if (error) {
+		console.error(pc.red(`✗ ${error}`));
+		process.exit(1);
+	}
+	const { envPath, text } = readDeploymentEnv();
+	if (spec.impact) console.log(pc.yellow(`! ${spec.impact}`));
+	const bak = backUp(envPath);
+	writeEnvText(envPath, setEnvValues(text, { [key]: value }));
+	console.log(pc.green(`✓ ${key} set.`) + (bak ? pc.dim(` Backup: ${bak}`) : ''));
+	console.log(pc.dim('Restart to apply: ') + pc.cyan('selva restart'));
+}
+
+function runUnset(argv) {
+	const key = argv[0];
+	if (!key) {
+		console.error('Usage: selva config unset KEY');
+		process.exit(1);
+	}
+	const { envPath, text, env } = readDeploymentEnv();
+	if (!(key in env)) {
+		console.log(pc.dim(`${key} is not set in .env.`));
+		return;
+	}
+	const spec = ALL_SETTINGS.find((s) => s.key === key);
+	if (spec?.required) {
+		console.error(pc.red(`✗ ${key} is required; the app would not start without it.`));
+		process.exit(1);
+	}
+	if (spec?.impact) console.log(pc.yellow(`! ${spec.impact}`));
+	const bak = backUp(envPath);
+	writeEnvText(envPath, setEnvValues(text, { [key]: undefined }));
+	console.log(pc.green(`✓ ${key} removed.`) + (bak ? pc.dim(` Backup: ${bak}`) : ''));
+	console.log(pc.dim('Restart to apply: ') + pc.cyan('selva restart'));
+}

package/src/commands/doctor.js

@@ -8,7 +8,6 @@
 import {
 	existsSync,
 	readFileSync,
-	writeFileSync,
 	copyFileSync,
 	readdirSync,
 	accessSync,
@@ -20,7 +19,13 @@ import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import { readEnvFile, parseEnv, countEnvCommentLines, stripEnvComments } from '../env.js';
+import {
+	readEnvFile,
+	parseEnv,
+	countEnvCommentLines,
+	stripEnvComments,
+	writeEnvText
+} from '../env.js';
 import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 import { satisfiesNodeRange } from '../node-range.js';
 import { green, yellow, red, fixable } from '../checks/result.js';
@@ -32,6 +37,8 @@ import {
 	checkDeprecatedEnv,
 	checkEnvDocumentation,
 	checkHeaderNames,
+	checkHmacKey,
+	checkKeyRotation,
 	checkOrigin,
 	checkProviders,
 	checkSecret,
@@ -55,8 +62,9 @@ export async function runDoctor(argv = []) {
 	checks.push(checkLayoutDrift(dir));
 	checks.push(checkMigrationLeftovers(dir));
 	checks.push(checkAgedBackups(dir));
-	checks.push(checkSecret(env.SELVA_HMAC_KEY, 'SELVA_HMAC_KEY is a 32-byte hex string'));
-	checks.push(checkSecret(env.SELVA_AT_REST_KEY, 'SELVA_AT_REST_KEY is a 32-byte hex string'));
+	checks.push(checkHmacKey(env.SELVA_HMAC_KEY));
+	checks.push(checkSecret(env.SELVA_AT_REST_KEY, 'SELVA_AT_REST_KEY is a 32-byte key'));
+	checks.push(...checkKeyRotation(env));
 
 	const providers = resolveProviders(env);
 	checks.push(...checkProviders(providers));
@@ -460,7 +468,7 @@ function checkEnvDocs(dir) {
 				if (drift) return red(`refused to strip .env — ${drift}`);
 
 				copyFileSync(envPath, envPath + '.bak');
-				writeFileSync(envPath, strippedText, 'utf8');
+				writeEnvText(envPath, strippedText);
 				return green(`stripped ${removed} comment lines from .env (backup: .env.bak)`);
 			} catch (err) {
 				return red(`could not rewrite .env: ${err instanceof Error ? err.message : err}`);

package/src/commands/init.js

@@ -2,11 +2,12 @@
 // the current .env as prompt defaults and never touches package.json or runs
 // npm install.
 
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { collectConfig } from '../prompts.js';
-import { readEnvFile, writeEnvFile } from '../env.js';
+import { parseEnv, seededTemplateDefaults, setEnvValues, writeEnvText } from '../env.js';
 import { generateKey } from '../secrets.js';
 import { readEnvTemplate, requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 
@@ -15,7 +16,8 @@ export async function runInit() {
 	requireDeploymentDir(dir);
 
 	const envPath = join(dir, '.env');
-	const current = readEnvFile(envPath);
+	const text = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+	const current = parseEnv(text);
 	const values = await collectConfig({ defaults: current, mode: 'init' });
 
 	// Never regenerate an existing key: rotating SELVA_HMAC_KEY or
@@ -42,11 +44,17 @@ export async function runInit() {
 		p.log.warn('SELVA_AT_REST_KEY was missing — generated a fresh one.');
 	}
 
-	// A values-only rewrite drops anything it isn't handed, and the prompts cover
-	// only the vars they ask about — every tuned knob the operator set by hand
-	// (BODY_SIZE_LIMIT, COMPUTE_*, LOG_LEVEL, …) lives outside that set. Carry
-	// the existing file forward and let the prompt answers win on top.
-	writeEnvFile(envPath, readEnvTemplate(dir), { ...current, ...values });
+	// Line-level: keys the prompts don't cover, and the operator's comments, stay as they are.
+	// A prompt answered blank means unset, as it did when the file was re-rendered.
+	const updates = Object.fromEntries(
+		Object.entries(values).map(([k, v]) => [k, v === '' ? undefined : v])
+	);
+	// A template default missing from .env (BODY_SIZE_LIMIT: unset, every upload
+	// 413s at adapter-node's 512 KB) is filled in; one the operator set is kept.
+	for (const [k, v] of Object.entries(seededTemplateDefaults(readEnvTemplate(dir)))) {
+		if (current[k] === undefined && !(k in updates)) updates[k] = v;
+	}
+	writeEnvText(envPath, setEnvValues(text, updates));
 
 	p.outro(
 		[

package/src/commands/keys.js

@@ -1,67 +1,146 @@
-// Rotate SELVA_HMAC_KEY or SELVA_AT_REST_KEY; requires explicit confirm (blast radius in TARGETS).
+// `selva keys rotate <hmac|at-rest> [--finish | --leaked]`.
+//
+// A routine rotation keeps the old key as <KEY>_PREVIOUS, which the app still
+// accepts, so nothing breaks. `--finish` drops the previous key once its
+// overlap has passed. `--leaked` replaces the key and drops the old one at
+// once: that is the destructive path, for a key that must stop working now.
 
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import { readEnvFile, writeEnvFile } from '../env.js';
+import { parseEnv, setEnvValues, writeEnvText } from '../env.js';
+import { resolveProviders } from '../checks/config.js';
 import { generateKey } from '../secrets.js';
-import { readEnvTemplate, requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
+import { PREVIOUS_KEY_DAYS } from '../generated/config.js';
+import { requireDeploymentDir, resolveDeploymentDir } from '../paths.js';
 
 const TARGETS = {
 	hmac: {
 		envVar: 'SELVA_HMAC_KEY',
-		warning: [
-			'This will:',
-			pc.red('  • log every signed-in user out (existing session cookies stop verifying)'),
-			pc.red('  • invalidate every share link and pending invite')
-		].join('\n')
+		leakedBlastRadius: hmacBlastRadius,
+		finishNote:
+			'The app stops accepting the previous key on its own at SELVA_HMAC_KEY_PREVIOUS_EXPIRES; ' +
+			'finishing ends it now. Either way this stops working: MCP clients registered before the ' +
+			'rotation (they register again), and share links, invites and API tokens stored under the ' +
+			'previous key before tokens were hashed without one. Sessions it signed last 8 hours at most.'
 	},
 	'at-rest': {
 		envVar: 'SELVA_AT_REST_KEY',
-		warning: [
-			'This will:',
-			pc.red('  • make the encrypted Rhino.Compute API key undecryptable'),
-			pc.red('  • require re-entering the API key at /admin/compute'),
-			pc.dim('    (other data is plaintext on disk — only the compute API key is encrypted)')
-		].join('\n')
+		leakedBlastRadius: atRestBlastRadius,
+		finishNote:
+			'The app re-seals stored API keys under the new key at boot, and stops accepting the previous ' +
+			'key at SELVA_AT_REST_KEY_PREVIOUS_EXPIRES. Check that /admin/system shows none left on the ' +
+			'previous key before finishing, or they become unreadable.'
 	}
 };
 
+/** What dropping the old SELVA_HMAC_KEY at once invalidates on this deployment's providers. */
+export function hmacBlastRadius(env) {
+	const { auth } = resolveProviders(env);
+	const lines = [];
+	// Only the local provider signs sessions with it: Supabase sessions are
+	// Supabase JWTs, and under header auth the proxy owns the session.
+	if (auth === 'local') lines.push('log every signed-in user out');
+	lines.push(
+		'invalidate share links, invites and API tokens created before stored tokens were hashed without a key',
+		'disconnect every MCP client (each has to register and sign in again)',
+		'fail live solve-event streams of solves already running'
+	);
+	return lines;
+}
+
+export function atRestBlastRadius() {
+	return [
+		'make the stored Rhino.Compute API keys unreadable',
+		'require re-entering each API key at /admin/compute'
+	];
+}
+
+/** The .env change for each mode, as `setEnvValues` updates. */
+export function rotationUpdates(env, envVar, mode, fresh = generateKey(), now = Date.now()) {
+	const previousVar = `${envVar}_PREVIOUS`;
+	const expiresVar = `${previousVar}_EXPIRES`;
+	if (mode === 'finish') return { [previousVar]: undefined, [expiresVar]: undefined };
+	if (mode === 'leaked')
+		return { [envVar]: fresh, [previousVar]: undefined, [expiresVar]: undefined };
+	const expires = new Date(now + PREVIOUS_KEY_DAYS * 86_400_000).toISOString();
+	return { [envVar]: fresh, [previousVar]: env[envVar], [expiresVar]: expires };
+}
+
+function backupsHolding(dir, value) {
+	if (!value) return [];
+	return readdirSync(dir)
+		.filter((f) => f.startsWith('.env.') && f.endsWith('.bak'))
+		.filter((f) => readFileSync(join(dir, f), 'utf8').includes(value));
+}
+
 export async function runKeysRotate(argv) {
 	const target = argv[0];
+	const mode = argv.includes('--finish')
+		? 'finish'
+		: argv.includes('--leaked')
+			? 'leaked'
+			: 'rotate';
 	if (!target || !(target in TARGETS)) {
-		console.error(`Usage: selva keys rotate <hmac|at-rest>`);
+		console.error('Usage: selva keys rotate <hmac|at-rest> [--finish | --leaked]');
 		process.exit(1);
 	}
 
 	const dir = resolveDeploymentDir();
 	requireDeploymentDir(dir);
 
-	const { envVar, warning } = TARGETS[target];
+	const { envVar, leakedBlastRadius, finishNote } = TARGETS[target];
+	const previousVar = `${envVar}_PREVIOUS`;
 	const envPath = join(dir, '.env');
-	const current = readEnvFile(envPath);
+	const text = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+	const env = parseEnv(text);
 
-	p.intro(pc.bgYellow(pc.black(` rotate ${envVar} `)));
-	p.note(warning, 'Blast radius');
+	p.intro(pc.bgYellow(pc.black(` ${mode === 'rotate' ? 'rotate' : mode} ${envVar} `)));
+
+	if (mode === 'rotate') {
+		if (env[previousVar]) {
+			p.cancel(
+				`${previousVar} is still set from the last rotation. Run \`selva keys rotate ${target} --finish\` first.`
+			);
+			process.exit(1);
+		}
+		p.note(
+			`The current key moves to ${previousVar}, which the app keeps accepting for ${PREVIOUS_KEY_DAYS} days.\nNothing stops working now. After that it is refused on its own; \`selva keys rotate ${target} --finish\`\nremoves it from .env.`,
+			'Safe rotation'
+		);
+	} else if (mode === 'finish') {
+		if (!env[previousVar]) {
+			p.outro(pc.dim(`${previousVar} is not set: nothing to finish.`));
+			return;
+		}
+		p.note(finishNote, 'Before you finish');
+	} else {
+		p.note(
+			['This will:', ...leakedBlastRadius(env).map((l) => pc.red(`  • ${l}`))].join('\n'),
+			'Blast radius'
+		);
+	}
 
-	const confirmed = await p.confirm({
-		message: `Rotate ${envVar}?`,
-		initialValue: false
-	});
+	const confirmed = await p.confirm({ message: 'Continue?', initialValue: mode === 'rotate' });
 	if (p.isCancel(confirmed) || !confirmed) {
 		p.cancel('Cancelled.');
 		return;
 	}
 
-	const fresh = generateKey();
-	current[envVar] = fresh;
+	writeEnvText(envPath, setEnvValues(text, rotationUpdates(env, envVar, mode)));
 
-	writeEnvFile(envPath, readEnvTemplate(dir), current);
-
-	p.outro(
-		[
-			pc.green(`${envVar} rotated.`),
-			pc.dim('Restart the app to apply: ') + pc.cyan('selva restart')
-		].join('\n')
-	);
+	const lines = [pc.green(mode === 'finish' ? `${previousVar} removed.` : `${envVar} rotated.`)];
+	if (mode !== 'rotate') {
+		const stale = backupsHolding(dir, mode === 'finish' ? env[previousVar] : env[envVar]);
+		if (stale.length > 0) {
+			lines.push(
+				pc.yellow(
+					`These backups still hold the old key: ${stale.join(', ')}. Delete them if it leaked.`
+				)
+			);
+		}
+	}
+	lines.push(pc.dim('Restart the app to apply: ') + pc.cyan('selva restart'));
+	p.outro(lines.join('\n'));
 }