envpkt 0.11.2 → 0.11.4

package/dist/cli.js

@@ -27,20 +27,26 @@ const classifySecret = (key, meta, fnoxKeys, staleWarningDays, requireExpiration
 	const issues = [];
 	const created = Option(meta.created).flatMap(parseDate);
 	const expires = Option(meta.expires).flatMap(parseDate);
+	const lastRotated = Option(meta.last_rotated_at).flatMap(parseDate);
 	const rotationUrl = Option(meta.rotation_url);
 	const purpose = Option(meta.purpose);
 	const service = Option(meta.service);
 	const daysRemaining = expires.map((exp) => daysBetween(today, exp));
-	const daysSinceCreated = created.map((c) => daysBetween(c, today));
+	const staleFromRotation = lastRotated.isSome();
+	const daysSinceRotation = (staleFromRotation ? lastRotated : created).map((d) => daysBetween(d, today));
 	const isExpired = daysRemaining.fold(() => false, (d) => d < 0);
 	const isExpiringSoon = daysRemaining.fold(() => false, (d) => d >= 0 && d <= WARN_BEFORE_DAYS);
-	const isStale = daysSinceCreated.fold(() => false, (d) => d > staleWarningDays);
+	const isStale = daysSinceRotation.fold(() => false, (d) => d > staleWarningDays);
 	const hasSealed = !!meta.encrypted_value;
 	const isMissing = fnoxKeys.size > 0 && !fnoxKeys.has(key) && !hasSealed;
 	const isMissingMetadata = requireExpiration && expires.isNone() || requireService && service.isNone();
 	if (isExpired) issues.push("Secret has expired");
 	if (isExpiringSoon) issues.push(`Expires in ${daysRemaining.fold(() => "?", (d) => String(d))} days`);
-	if (isStale) issues.push("Secret is stale (no rotation detected)");
+	if (isStale) {
+		const since = daysSinceRotation.fold(() => "?", (d) => String(d));
+		const label = staleFromRotation ? "last rotated" : "created";
+		issues.push(`Secret is stale (${label} ${since} days ago)`);
+	}
 	if (isMissing) issues.push("Key not found in fnox");
 	if (isMissingMetadata) {
 		if (requireExpiration && expires.isNone()) issues.push("Missing required expiration date");
@@ -55,6 +61,7 @@ const classifySecret = (key, meta, fnoxKeys, staleWarningDays, requireExpiration
 		purpose,
 		created: Option(meta.created),
 		expires: Option(meta.expires),
+		last_rotated_at: Option(meta.last_rotated_at),
 		issues: List(issues),
 		alias_of: Option(void 0)
 	};
@@ -73,6 +80,7 @@ const classifyAlias = (key, meta, targetHealth, targetRef) => ({
 	purpose: Option(meta.purpose).fold(() => targetHealth.purpose, (v) => Option(v)),
 	created: targetHealth.created,
 	expires: targetHealth.expires,
+	last_rotated_at: targetHealth.last_rotated_at,
 	issues: List([]),
 	alias_of: Option(targetRef)
 });
@@ -106,6 +114,7 @@ const computeAudit = (config, fnoxKeys, today, aliasTable) => {
 			purpose: Option(meta.purpose),
 			created: Option(meta.created),
 			expires: Option(meta.expires),
+			last_rotated_at: Option(meta.last_rotated_at),
 			issues: List(["Alias target not resolvable"]),
 			alias_of: Option(targetRef)
 		}), (health) => classifyAlias(key, meta, health, targetRef));
@@ -205,6 +214,10 @@ const SecretMetaSchema = Type.Object({
 		format: "date",
 		description: "Date the secret was provisioned (YYYY-MM-DD)"
 	})),
+	last_rotated_at: Type.Optional(Type.String({
+		format: "date",
+		description: "Date the secret value was most recently rotated (YYYY-MM-DD). Used by audit for staleness."
+	})),
 	rotates: Type.Optional(Type.String({ description: "Rotation schedule (e.g. '90d', 'quarterly')" })),
 	rate_limit: Type.Optional(Type.String({ description: "Rate limit or quota info (e.g. '1000/min')" })),
 	model_hint: Type.Optional(Type.String({ description: "Suggested model or tier for this credential" })),
@@ -765,9 +778,13 @@ const runAuditOnConfig = (config, options) => {
 		...afterStatus,
 		secrets: afterStatus.secrets.filter((s) => s.days_remaining.fold(() => false, (d) => d >= 0 && d <= expiring))
 	}));
-	if (options.format === "json") console.log(formatAuditJson(filtered));
-	else if (options.format === "minimal") console.log(formatAuditMinimal(filtered));
-	else console.log(formatAudit(filtered));
+	const sorted = options.sort ? {
+		...filtered,
+		secrets: filtered.secrets.sortBy((s) => s.key)
+	} : filtered;
+	if (options.format === "json") console.log(formatAuditJson(sorted));
+	else if (options.format === "minimal") console.log(formatAuditMinimal(sorted));
+	else console.log(formatAudit(sorted));
 	if (options.all) if (options.format === "json") console.log(formatEnvAuditJson(config));
 	else formatEnvAuditTable(config);
 	const code = options.strict ? exitCodeForAudit(audit) : audit.status === "critical" ? 2 : 0;
@@ -2347,6 +2364,145 @@ const updateSectionFields = (raw, sectionHeader, updates) => {
 * Ensures proper spacing (double newline before the block).
 */
 const appendSection = (raw, block) => `${raw.trimEnd()}\n\n${block}`;
+const ENV_HEADER_RE = /^\[env\.(.+)\]\s*$/;
+const SECRET_HEADER_RE = /^\[secret\.(.+)\]\s*$/;
+const ANY_HEADER_RE = /^\[.+\]\s*$/;
+/**
+* Find the end (exclusive) of a section starting at `start`, respecting
+* multiline `"""..."""` values so the scanner does not mistake content inside
+* a multiline string for a section header.
+*/
+const findSectionEnd = (lines, start) => {
+	const initial = {
+		end: lines.length,
+		inMultiline: false,
+		done: false
+	};
+	return List(lines.slice(start + 1)).zipWithIndex().foldLeft(initial)((state, entry) => scanSectionBoundary(state, entry[0], start + 1 + entry[1])).end;
+};
+/**
+* Walking backwards from `headerIdx`, return the index of the first line of the
+* "doc block" that should travel with this section. A doc block is a contiguous
+* run of `#`-comment lines *immediately* above the header (no blank line
+* between). A blank line acts as a paragraph break and stops the walk — so
+* `# Some heading\n\n[secret.X]` does NOT attach the heading to `[secret.X]`.
+*/
+const findPreambleStart = (lines, headerIdx) => {
+	const stopOffset = [...lines.slice(0, headerIdx)].reverse().findIndex((l) => !l.trim().startsWith("#"));
+	return stopOffset === -1 ? 0 : headerIdx - stopOffset;
+};
+const classifyHeader = (line, idx) => {
+	if (!ANY_HEADER_RE.test(line)) return Option.none();
+	const envMatch = line.match(ENV_HEADER_RE);
+	if (envMatch) return Option({
+		idx,
+		kind: "env",
+		key: envMatch[1]
+	});
+	const secretMatch = line.match(SECRET_HEADER_RE);
+	if (secretMatch) return Option({
+		idx,
+		kind: "secret",
+		key: secretMatch[1]
+	});
+	return Option({
+		idx,
+		kind: "other",
+		key: ""
+	});
+};
+const scanHeader = (state, line, idx) => {
+	if (state.inMultiline) return line.includes(MULTILINE_OPEN) ? {
+		...state,
+		inMultiline: false
+	} : state;
+	if (line.includes(MULTILINE_OPEN)) return (line.slice(line.indexOf("=") + 1).trim().match(/* @__PURE__ */ new RegExp("\"\"\"", "g")) ?? []).length === 1 ? {
+		...state,
+		inMultiline: true
+	} : state;
+	return classifyHeader(line, idx).fold(() => state, (header) => ({
+		...state,
+		headers: [...state.headers, header]
+	}));
+};
+const partitionSections = (raw) => {
+	const lines = raw.split("\n");
+	const { headers } = List(lines).zipWithIndex().foldLeft({
+		headers: [],
+		inMultiline: false
+	})((state, entry) => scanHeader(state, entry[0], entry[1]));
+	const envSecretHeaders = headers.filter((h) => h.kind === "env" || h.kind === "secret");
+	const trueBodyRange = (headerIdx) => {
+		const naiveEnd = findSectionEnd(lines, headerIdx);
+		const lastContent = lines.slice(headerIdx, naiveEnd).findLastIndex((l) => {
+			const t = l.trim();
+			return t !== "" && !t.startsWith("#");
+		});
+		return {
+			start: headerIdx,
+			end: lastContent === -1 ? headerIdx + 1 : headerIdx + lastContent + 1
+		};
+	};
+	const sections = envSecretHeaders.map((h) => {
+		const headerIdx = h.idx;
+		const preambleStart = findPreambleStart(lines, headerIdx);
+		const body = lines.slice(headerIdx, trueBodyRange(headerIdx).end);
+		const preamble = lines.slice(preambleStart, headerIdx);
+		return {
+			kind: h.kind,
+			key: h.key,
+			body,
+			preamble
+		};
+	});
+	const claimedRanges = envSecretHeaders.map((h) => {
+		const headerIdx = h.idx;
+		return {
+			start: findPreambleStart(lines, headerIdx),
+			end: trueBodyRange(headerIdx).end
+		};
+	});
+	const isClaimed = (idx) => claimedRanges.some((r) => idx >= r.start && idx < r.end);
+	return {
+		preambleLines: lines.map((l, idx) => isClaimed(idx) ? null : l).filter((l) => l !== null),
+		envSections: sections.filter((s) => s.kind === "env"),
+		secretSections: sections.filter((s) => s.kind === "secret")
+	};
+};
+const emitSection = (s) => {
+	return `${s.preamble.length > 0 ? `${s.preamble.join("\n")}\n` : ""}${s.body.join("\n")}`;
+};
+/**
+* Reformat a TOML config with `[env.*]` and `[secret.*]` sections grouped and
+* alphabetized. Top-level content (version key, `[identity]`, `[lifecycle]`,
+* `[callbacks]`, `[tools]`, etc.) stays in its original position. Comment
+* doc-blocks immediately above a section header travel with that section.
+*
+* Pure — no I/O. Returns the raw input unchanged when there is no env or
+* secret content to reorder.
+*/
+const sortConfigToml = (raw) => {
+	const { preambleLines, envSections, secretSections } = partitionSections(raw);
+	if (envSections.length === 0 && secretSections.length === 0) return raw;
+	const sortedEnv = [...envSections].sort((a, b) => a.key.localeCompare(b.key));
+	const sortedSecret = [...secretSections].sort((a, b) => a.key.localeCompare(b.key));
+	const trimTrailing = (xs) => {
+		const lastNonBlank = xs.findLastIndex((l) => l.trim() !== "");
+		return lastNonBlank === -1 ? [] : xs.slice(0, lastNonBlank + 1);
+	};
+	const collapseBlanks = (xs) => xs.reduce((acc, line) => {
+		const isBlank = line.trim() === "";
+		const prevBlank = acc.length > 0 && acc[acc.length - 1].trim() === "";
+		if (isBlank && prevBlank) return acc;
+		return [...acc, line];
+	}, []);
+	const preambleTrimmed = collapseBlanks(trimTrailing(preambleLines));
+	const parts = [];
+	if (preambleTrimmed.length > 0) parts.push(preambleTrimmed.join("\n"));
+	if (sortedEnv.length > 0) parts.push(sortedEnv.map(emitSection).join("\n\n"));
+	if (sortedSecret.length > 0) parts.push(sortedSecret.map(emitSection).join("\n\n"));
+	return `${parts.join("\n\n")}\n`;
+};
 //#endregion
 //#region src/core/validate.ts
 /**
@@ -2987,6 +3143,7 @@ const printSecretMeta = (meta, indent) => {
 		console.log(`${indent}${DIM}tags:${RESET} ${tagStr}`);
 	}
 };
+const sortedIfRequested = (entries, sort) => sort ? [...entries].sort((a, b) => a[0].localeCompare(b[0])) : entries;
 const printConfig = (config, path, resolveResult, opts) => {
 	console.log(`${BOLD}envpkt.toml${RESET} ${DIM}(${path})${RESET}`);
 	if (resolveResult?.catalogPath) console.log(`${DIM}Catalog: ${CYAN}${resolveResult.catalogPath}${RESET}`);
@@ -3004,7 +3161,7 @@ const printConfig = (config, path, resolveResult, opts) => {
 	}
 	const secretEntries = config.secret ?? {};
 	console.log(`${BOLD}Secrets:${RESET} ${Object.keys(secretEntries).length}`);
-	Object.entries(secretEntries).forEach(([key, meta]) => {
+	sortedIfRequested(Object.entries(secretEntries), opts?.sort).forEach(([key, meta]) => {
 		const valueSuffix = Option(opts?.secrets?.[key]).fold(() => "", (secretValue) => ` = ${YELLOW}${(opts?.secretDisplay ?? "encrypted") === "plaintext" ? secretValue : maskValue(secretValue)}${RESET}`);
 		const sealedTag = meta.encrypted_value ? ` ${CYAN}[sealed]${RESET}` : "";
 		console.log(`  ${BOLD}${key}${RESET} → ${meta.service ?? key}${sealedTag}${valueSuffix}`);
@@ -3015,7 +3172,7 @@ const printConfig = (config, path, resolveResult, opts) => {
 	if (envKeys.length > 0) {
 		console.log("");
 		console.log(`${BOLD}Environment Defaults:${RESET} ${envKeys.length}`);
-		Object.entries(envEntries).forEach(([key, entry]) => {
+		sortedIfRequested(Object.entries(envEntries), opts?.sort).forEach(([key, entry]) => {
 			console.log(`  ${BOLD}${key}${RESET} = ${GREEN}"${entry.value}"${RESET}`);
 			if (entry.purpose) console.log(`    ${DIM}purpose:${RESET} ${entry.purpose}`);
 			if (entry.comment) console.log(`    ${DIM}comment:${RESET} ${DIM}${entry.comment}${RESET}`);
@@ -3079,7 +3236,10 @@ const runInspect = (options) => {
 						secretDisplay: options.plaintext ? "plaintext" : "encrypted"
 					};
 				})() : void 0;
-				printConfig(showConfig, path, showResolved ? resolveResult : void 0, printOpts);
+				printConfig(showConfig, path, showResolved ? resolveResult : void 0, {
+					...printOpts ?? {},
+					sort: options.sort
+				});
 			});
 		});
 	});
@@ -3544,9 +3704,13 @@ const META_SECTION_RE = /^\[secret\.(.+)\]\s*$/;
 const ENCRYPTED_VALUE_RE = /^encrypted_value\s*=/;
 const NEW_SECTION_RE = /^\[/;
 const MULTILINE_DELIM = "\"\"\"";
-/** Write sealed values back into the TOML file, preserving structure. */
-const writeSealedToml = (configPath, sealedMeta) => {
-	const lines = readFileSync(configPath, "utf-8").split("\n");
+/**
+* In-memory transform: inject sealed encrypted_value blocks into raw TOML,
+* replacing existing encrypted_value lines (single or multiline) or appending
+* a new block at the end of the section. Pure — no I/O.
+*/
+const applySealedToml = (raw, sealedMeta) => {
+	const lines = raw.split("\n");
 	const getSeal = (key) => Option(sealedMeta[key]?.encrypted_value);
 	const isPending = (state, key) => !getSeal(key).isEmpty && !state.consumedKeys.has(key);
 	const sealLinesFor = (key) => getSeal(key).fold(() => [], (v) => [
@@ -3628,7 +3792,11 @@ const writeSealedToml = (configPath, sealedMeta) => {
 		consumedKeys: Set$1.empty(),
 		skipUntil: -1
 	};
-	const finalContent = flushPending(List(lines).zipWithIndex().foldLeft(initial)((state, entry) => step(state, entry[0], entry[1]))).output.join("\n");
+	return flushPending(List(lines).zipWithIndex().foldLeft(initial)((state, entry) => step(state, entry[0], entry[1]))).output.join("\n");
+};
+/** Write sealed values back into the TOML file, preserving structure. */
+const writeSealedToml = (configPath, sealedMeta) => {
+	const finalContent = applySealedToml(readFileSync(configPath, "utf-8"), sealedMeta);
 	validateOrExit(finalContent);
 	writeFileSync(configPath, finalContent);
 };
@@ -4005,6 +4173,98 @@ const runSecretAlias = (name, options) => {
 		});
 	});
 };
+const readNewValue = async (key) => {
+	if (!process.stdin.isTTY) {
+		const chunks = [];
+		return new Promise((resolveP, rejectP) => {
+			process.stdin.on("data", (c) => chunks.push(Buffer.from(c)));
+			process.stdin.on("end", () => resolveP(Buffer.concat(chunks).toString("utf-8").replace(/\r?\n$/, "")));
+			process.stdin.on("error", rejectP);
+		});
+	}
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	return new Promise((resolveP) => {
+		rl.question(`Enter new value for ${key}: `, (answer) => {
+			rl.close();
+			resolveP(answer);
+		});
+	});
+};
+const runSecretRotate = async (name, options) => {
+	const { configPath, source } = resolveConfigPath(options.config).fold((err) => {
+		console.error(formatError(err));
+		process.exit(2);
+		return {
+			configPath: "",
+			source: "flag"
+		};
+	}, ({ path, source: s }) => ({
+		configPath: path,
+		source: s
+	}));
+	const sourceMsg = formatConfigSource(configPath, source);
+	if (sourceMsg) console.error(sourceMsg);
+	const config = loadConfig(configPath).fold((err) => {
+		console.error(formatError(err));
+		process.exit(2);
+	}, (c) => c);
+	const meta = config.secret?.[name];
+	if (!meta) {
+		console.error(`${RED}Error:${RESET} Secret "${name}" not found in ${configPath}`);
+		process.exit(1);
+	}
+	if (meta.from_key) {
+		console.error(`${RED}Error:${RESET} "${name}" is an alias (from_key = "${meta.from_key}"). Rotate the target secret instead.`);
+		process.exit(1);
+	}
+	const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+	const wasSealed = !!meta.encrypted_value;
+	const raw = readFileSync(configPath, "utf-8");
+	if (!wasSealed) {
+		updateSectionFields(raw, `[secret.${name}]`, { last_rotated_at: `"${today}"` }).fold((err) => {
+			console.error(`${RED}Error:${RESET} ${err._tag}: ${err.section}`);
+			process.exit(2);
+		}, (result) => {
+			if (options.dryRun) {
+				console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
+				console.log(result);
+				return;
+			}
+			writeIfValid(configPath, result, `${GREEN}✓${RESET} Stamped ${BOLD}last_rotated_at${RESET} on ${BOLD}${name}${RESET} (unsealed — no ciphertext to update)`);
+		});
+		return;
+	}
+	if (!config.identity?.recipient) {
+		console.error(`${RED}Error:${RESET} identity.recipient is required to rotate a sealed secret`);
+		console.error(`${DIM}Run ${CYAN}envpkt keygen${DIM} to configure one.${RESET}`);
+		process.exit(2);
+	}
+	const { recipient } = config.identity;
+	const value = await readNewValue(name);
+	if (value === "") {
+		console.error(`${YELLOW}Cancelled:${RESET} no value provided — ${BOLD}${name}${RESET} was not rotated.`);
+		process.exit(1);
+	}
+	const ciphertext = ageEncrypt(value, recipient).fold((err) => {
+		console.error(`${RED}Error:${RESET} Encryption failed: ${err.message}`);
+		process.exit(2);
+		return "";
+	}, (ct) => ct);
+	updateSectionFields(applySealedToml(raw, { [name]: { encrypted_value: ciphertext } }), `[secret.${name}]`, { last_rotated_at: `"${today}"` }).fold((err) => {
+		console.error(`${RED}Error:${RESET} ${err._tag}: ${err.section}`);
+		process.exit(2);
+	}, (result) => {
+		if (options.dryRun) {
+			console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
+			console.log(result);
+			return;
+		}
+		writeIfValid(configPath, result, `${GREEN}✓${RESET} Rotated ${BOLD}${name}${RESET} (resealed + stamped ${CYAN}${today}${RESET})`);
+	});
+};
 const addSecretFlags = (cmd) => cmd.option("--service <service>", "Service this secret authenticates to").option("--purpose <purpose>", "Why this secret exists").option("--comment <comment>", "Free-form annotation").option("--expires <date>", "Expiration date (YYYY-MM-DD)").option("--capabilities <caps>", "Comma-separated capabilities (e.g. read,write)").option("--rotates <schedule>", "Rotation schedule (e.g. 90d, quarterly)").option("--rate-limit <limit>", "Rate limit info (e.g. 1000/min)").option("--model-hint <hint>", "Suggested model or tier").option("--source <source>", "Where the value originates (e.g. vault, ci)").option("--rotation-url <url>", "URL for secret rotation procedure").option("--tags <tags>", "Comma-separated key=value tags (e.g. env=prod,team=payments)");
 const registerSecretCommands = (program) => {
 	const secret = program.command("secret").description("Manage secret entries in envpkt.toml");
@@ -4020,6 +4280,9 @@ const registerSecretCommands = (program) => {
 	secret.command("rename").description("Rename a secret entry, preserving all metadata").argument("<old>", "Current secret name").argument("<new>", "New secret name").option("-c, --config <path>", "Path to envpkt.toml").option("--dry-run", "Preview the result without writing").action((oldName, newName, options) => {
 		runSecretRename(oldName, newName, options);
 	});
+	secret.command("rotate").description("Rotate a secret's value (sealed: reseal + stamp; unsealed: stamp only)").argument("<name>", "Secret name to rotate").option("-c, --config <path>", "Path to envpkt.toml").option("--dry-run", "Preview the result without writing").action(async (name, options) => {
+		await runSecretRotate(name, options);
+	});
 	secret.command("alias").description("Create an alias entry that reuses another secret's resolved value").argument("<name>", "Alias name (becomes the env var key)").requiredOption("--from <ref>", "Target reference — must be \"secret.<KEY>\"").option("-c, --config <path>", "Path to envpkt.toml").option("--purpose <purpose>", "Why this alias exists (local metadata)").option("--comment <comment>", "Free-form annotation").option("--tags <tags>", "Comma-separated key=value tags (e.g. env=prod,team=payments)").option("--force", "Overwrite the entry if <name> already exists").option("--dry-run", "Preview the TOML block without writing").action((name, options) => {
 		runSecretAlias(name, options);
 	});
@@ -4066,6 +4329,45 @@ const runShellHook = (shell) => {
 	}
 };
 //#endregion
+//#region src/cli/commands/sort.ts
+const SECTION_HEADER_RE = /^\[(env|secret)\.(.+)\]\s*$/;
+const countSections = (raw) => raw.split("\n").reduce((acc, line) => {
+	const m = SECTION_HEADER_RE.exec(line);
+	if (!m) return acc;
+	return m[1] === "env" ? {
+		...acc,
+		env: acc.env + 1
+	} : {
+		...acc,
+		secret: acc.secret + 1
+	};
+}, {
+	env: 0,
+	secret: 0
+});
+const runSort = (options) => {
+	resolveConfigPath(options.config).fold((err) => {
+		console.error(formatError(err));
+		process.exit(2);
+	}, ({ path: configPath, source }) => {
+		const sourceMsg = formatConfigSource(configPath, source);
+		if (sourceMsg) console.error(sourceMsg);
+		const raw = readFileSync(configPath, "utf-8");
+		const sorted = sortConfigToml(raw);
+		const counts = countSections(sorted);
+		if (sorted === raw) {
+			console.log(`${GREEN}✓${RESET} ${BOLD}Already sorted${RESET} — ${counts.env} env, ${counts.secret} secret`);
+			return;
+		}
+		if (options.dryRun) {
+			console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
+			console.log(sorted);
+			return;
+		}
+		writeIfValid(configPath, sorted, `${GREEN}✓${RESET} Sorted ${BOLD}${counts.env}${RESET} env and ${BOLD}${counts.secret}${RESET} secret entries in ${CYAN}${configPath}${RESET}`);
+	});
+};
+//#endregion
 //#region src/cli/commands/upgrade.ts
 const getCurrentVersion = () => Try(() => execFileSync("npm", [
 	"list",
@@ -4322,7 +4624,7 @@ program.command("init").description("Initialize a new envpkt.toml in the current
 program.command("keygen").description("Generate an age keypair for sealing secrets — run this before `seal` if you don't have a key yet").option("-c, --config <path>", "Path to envpkt.toml (updates identity.recipient if found)").option("-o, --output <path>", "Output path for identity file (default: ~/.envpkt/<project>-key.txt)").option("--global", "Write key to the shared default path (~/.envpkt/age-key.txt) instead of a project-specific one").action((options) => {
 	runKeygen(options);
 });
-program.command("audit").description("Audit credential health from envpkt.toml (use --strict in CI pipelines to gate deploys)").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json | minimal", "table").option("--expiring <days>", "Show secrets expiring within N days", parseInt).option("--status <status>", "Filter by status: healthy | expiring_soon | expired | stale | missing").option("--strict", "Exit non-zero on any non-healthy secret").option("--all", "Show both secrets and env defaults").option("--env-only", "Show only env defaults (drift detection)").option("--sealed", "Show only secrets with encrypted_value").option("--external", "Show only secrets without encrypted_value").action((options) => {
+program.command("audit").description("Audit credential health from envpkt.toml (use --strict in CI pipelines to gate deploys)").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json | minimal", "table").option("--expiring <days>", "Show secrets expiring within N days", parseInt).option("--status <status>", "Filter by status: healthy | expiring_soon | expired | stale | missing").option("--strict", "Exit non-zero on any non-healthy secret").option("--all", "Show both secrets and env defaults").option("--env-only", "Show only env defaults (drift detection)").option("--sealed", "Show only secrets with encrypted_value").option("--external", "Show only secrets without encrypted_value").option("--sort", "Sort secrets alphabetically within each status bucket (no file mutation)").action((options) => {
 	runAudit(options);
 });
 program.command("fleet").description("Scan directory tree for envpkt.toml files and aggregate health (use in CI for fleet-wide monitoring)").option("-d, --dir <path>", "Root directory to scan", ".").option("--depth <n>", "Max directory depth", parseInt).option("--format <format>", "Output format: table | json", "table").option("--status <status>", "Filter agents by health status").action((options) => {
@@ -4331,7 +4633,7 @@ program.command("fleet").description("Scan directory tree for envpkt.toml files
 program.command("validate").description("Verify envpkt.toml integrity — runs TOML syntax, schema, catalog, alias, and sealed-block structural checks").option("-c, --config <path>", "Path to envpkt.toml").option("--json", "Output structured JSON instead of human-readable text").action((options) => {
 	runValidate(options);
 });
-program.command("inspect").description("Display structured view of envpkt.toml").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json", "table").option("--resolved", "Show resolved view (catalog merged)").option("--secrets", "Show secret values from environment (masked by default)").option("--plaintext", "Show secret values in plaintext (requires --secrets)").action((options) => {
+program.command("inspect").description("Display structured view of envpkt.toml").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json", "table").option("--resolved", "Show resolved view (catalog merged)").option("--secrets", "Show secret values from environment (masked by default)").option("--plaintext", "Show secret values in plaintext (requires --secrets)").option("--sort", "Display secrets and env entries in alphabetical order (no file mutation)").action((options) => {
 	runInspect(options);
 });
 program.command("exec").description("Run pre-flight audit then execute a command with injected secrets (sealed → fnox → env cascade)").argument("<command...>", "Command to execute").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("--skip-audit", "Skip the pre-flight audit (alias: --no-check)").option("--no-check", "Skip the pre-flight audit").option("--warn-only", "Warn on critical audit but do not abort").option("--strict", "Abort on any non-healthy secret").action((args, options) => {
@@ -4348,6 +4650,9 @@ program.command("mcp").description("Start the envpkt MCP server (stdio transport
 });
 registerSecretCommands(program);
 registerEnvCommands(program);
+program.command("sort").description("Group [env.*] and [secret.*] sections and alphabetize within each region").option("-c, --config <path>", "Path to envpkt.toml").option("--dry-run", "Preview the result without writing").action((options) => {
+	runSort(options);
+});
 program.command("upgrade").description("Upgrade envpkt to the latest version (npm install -g envpkt@latest)").action(() => {
 	runUpgrade();
 });

package/dist/index.d.ts

@@ -40,6 +40,7 @@ declare const SecretMetaSchema: import("@sinclair/typebox").TObject<{
   comment: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
   capabilities: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
   created: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+  last_rotated_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
   rotates: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
   rate_limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
   model_hint: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -94,6 +95,7 @@ declare const EnvpktConfigSchema: import("@sinclair/typebox").TObject<{
     comment: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     capabilities: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     created: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    last_rotated_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     rotates: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     rate_limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     model_hint: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -138,6 +140,7 @@ type SecretHealth = {
   readonly purpose: Option<string>;
   readonly created: Option<string>;
   readonly expires: Option<string>;
+  readonly last_rotated_at: Option<string>;
   readonly issues: List<string>; /** If this entry is an alias (from_key), the reference it points at (e.g. "secret.X") */
   readonly alias_of: Option<string>;
 };

package/dist/index.js

@@ -56,6 +56,10 @@ const SecretMetaSchema = Type.Object({
 		format: "date",
 		description: "Date the secret was provisioned (YYYY-MM-DD)"
 	})),
+	last_rotated_at: Type.Optional(Type.String({
+		format: "date",
+		description: "Date the secret value was most recently rotated (YYYY-MM-DD). Used by audit for staleness."
+	})),
 	rotates: Type.Optional(Type.String({ description: "Rotation schedule (e.g. '90d', 'quarterly')" })),
 	rate_limit: Type.Optional(Type.String({ description: "Rate limit or quota info (e.g. '1000/min')" })),
 	model_hint: Type.Optional(Type.String({ description: "Suggested model or tier for this credential" })),
@@ -565,20 +569,26 @@ const classifySecret = (key, meta, fnoxKeys, staleWarningDays, requireExpiration
 	const issues = [];
 	const created = Option(meta.created).flatMap(parseDate);
 	const expires = Option(meta.expires).flatMap(parseDate);
+	const lastRotated = Option(meta.last_rotated_at).flatMap(parseDate);
 	const rotationUrl = Option(meta.rotation_url);
 	const purpose = Option(meta.purpose);
 	const service = Option(meta.service);
 	const daysRemaining = expires.map((exp) => daysBetween(today, exp));
-	const daysSinceCreated = created.map((c) => daysBetween(c, today));
+	const staleFromRotation = lastRotated.isSome();
+	const daysSinceRotation = (staleFromRotation ? lastRotated : created).map((d) => daysBetween(d, today));
 	const isExpired = daysRemaining.fold(() => false, (d) => d < 0);
 	const isExpiringSoon = daysRemaining.fold(() => false, (d) => d >= 0 && d <= WARN_BEFORE_DAYS);
-	const isStale = daysSinceCreated.fold(() => false, (d) => d > staleWarningDays);
+	const isStale = daysSinceRotation.fold(() => false, (d) => d > staleWarningDays);
 	const hasSealed = !!meta.encrypted_value;
 	const isMissing = fnoxKeys.size > 0 && !fnoxKeys.has(key) && !hasSealed;
 	const isMissingMetadata = requireExpiration && expires.isNone() || requireService && service.isNone();
 	if (isExpired) issues.push("Secret has expired");
 	if (isExpiringSoon) issues.push(`Expires in ${daysRemaining.fold(() => "?", (d) => String(d))} days`);
-	if (isStale) issues.push("Secret is stale (no rotation detected)");
+	if (isStale) {
+		const since = daysSinceRotation.fold(() => "?", (d) => String(d));
+		const label = staleFromRotation ? "last rotated" : "created";
+		issues.push(`Secret is stale (${label} ${since} days ago)`);
+	}
 	if (isMissing) issues.push("Key not found in fnox");
 	if (isMissingMetadata) {
 		if (requireExpiration && expires.isNone()) issues.push("Missing required expiration date");
@@ -593,6 +603,7 @@ const classifySecret = (key, meta, fnoxKeys, staleWarningDays, requireExpiration
 		purpose,
 		created: Option(meta.created),
 		expires: Option(meta.expires),
+		last_rotated_at: Option(meta.last_rotated_at),
 		issues: List(issues),
 		alias_of: Option(void 0)
 	};
@@ -611,6 +622,7 @@ const classifyAlias = (key, meta, targetHealth, targetRef) => ({
 	purpose: Option(meta.purpose).fold(() => targetHealth.purpose, (v) => Option(v)),
 	created: targetHealth.created,
 	expires: targetHealth.expires,
+	last_rotated_at: targetHealth.last_rotated_at,
 	issues: List([]),
 	alias_of: Option(targetRef)
 });
@@ -644,6 +656,7 @@ const computeAudit = (config, fnoxKeys, today, aliasTable) => {
 			purpose: Option(meta.purpose),
 			created: Option(meta.created),
 			expires: Option(meta.expires),
+			last_rotated_at: Option(meta.last_rotated_at),
 			issues: List(["Alias target not resolvable"]),
 			alias_of: Option(targetRef)
 		}), (health) => classifyAlias(key, meta, health, targetRef));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envpkt",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Credential lifecycle and fleet management for AI agents",
   "keywords": [
     "credentials",

package/schemas/envpkt.schema.json

@@ -131,6 +131,11 @@
               "description": "Date the secret was provisioned (YYYY-MM-DD)",
               "type": "string"
             },
+            "last_rotated_at": {
+              "format": "date",
+              "description": "Date the secret value was most recently rotated (YYYY-MM-DD). Used by audit for staleness.",
+              "type": "string"
+            },
             "rotates": {
               "description": "Rotation schedule (e.g. '90d', 'quarterly')",
               "type": "string"