envpkt 0.17.0 → 0.18.0

package/dist/cli.js

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
-import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { $, Cond, Do, Either, Left, List, Map as Map$1, None, Option, Right, Set as Set$1, Some, Try } from "functype";
+import { $, Cond, Do, Either, Left, List, Map as Map$1, None, Option, Right, Set as Set$1, Some, Try, tryCatch, tryCatchAsync } from "functype";
 import { TypeCompiler } from "@sinclair/typebox/compiler";
 import { Env, Fs, Path, Platform } from "functype-os";
 import { TomlDate, parse, stringify } from "smol-toml";
 import { FormatRegistry, Type } from "@sinclair/typebox";
-import { execFileSync } from "node:child_process";
-import { homedir, tmpdir } from "node:os";
+import { Decrypter, Encrypter, armor, generateX25519Identity, identityToRecipient } from "age-encryption";
+import { homedir } from "node:os";
 import { directSilentLogger } from "functype-log/direct";
+import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -586,33 +588,109 @@ const resolveConfig = (agentConfig, agentConfigDir) => {
 	}));
 };
 //#endregion
-//#region src/fnox/identity.ts
-/** Check if the age CLI is available on PATH */
-const ageAvailable = () => Try(() => {
-	execFileSync("age", ["--version"], { stdio: "pipe" });
-	return true;
-}).fold(() => false, (v) => v);
-/** The age CLI version string (e.g. "v1.2.0"), or None if age isn't on PATH. */
-const ageVersion = () => Try(() => execFileSync("age", ["--version"], {
-	stdio: [
-		"pipe",
-		"pipe",
-		"pipe"
-	],
-	encoding: "utf-8"
-}).trim()).toOption();
-/** Platform-aware instructions for installing the age CLI. */
-const ageInstallHint = () => {
-	return `Install age:\n    ${{
-		darwin: "brew install age",
-		linux: "apt install age   (or: apk add age · dnf install age · nix-env -iA nixpkgs.age)",
-		win32: "scoop install age   (or: winget install FiloSottile.age)"
-	}[process.platform] ?? "see the install guide"}\n    https://github.com/FiloSottile/age#installation`;
+//#region src/core/age.ts
+/**
+* In-process age encryption via typage (`age-encryption`). This is the only module that imports
+* it. Ciphertext is age's ASCII armor, interoperable with the `age` CLI in both directions.
+*/
+/** Encrypt `plaintext` to an age recipient (`age1…`), returning armored text without a trailing newline. */
+const encryptArmored = (plaintext, recipient) => tryCatchAsync(async () => {
+	const encrypter = new Encrypter();
+	encrypter.addRecipient(recipient);
+	return armor.encode(await encrypter.encrypt(plaintext)).trim();
+}, (err) => ({
+	_tag: "EncryptFailed",
+	key: "",
+	message: `age encrypt failed: ${String(err)}`
+}));
+const decryptFailed = (message) => ({
+	_tag: "DecryptFailed",
+	key: "",
+	message: `age decrypt failed: ${message}`
+});
+/** Mask any age secret key in an error message. typage's bech32 errors quote the key they rejected. */
+const redactKeys = (message) => message.replace(/AGE-SECRET-KEY-[0-9A-Z-]+/gi, "AGE-SECRET-KEY-…");
+/** Add each identity to a fresh Decrypter. A malformed key fails with its position, never its text. */
+const toDecrypter = (identities) => identities.reduce((acc, identity, i) => acc.flatMap((decrypter) => tryCatch(() => {
+	decrypter.addIdentity(identity);
+	return decrypter;
+}, () => decryptFailed(`identity ${i + 1} is not a valid age secret key`))), Right(new Decrypter()));
+const utf8 = new TextDecoder("utf-8", { ignoreBOM: true });
+/**
+* Decrypt armored age ciphertext with any of `identities` (`AGE-SECRET-KEY-…`). The plaintext is
+* returned as-is: byte for byte when it is valid UTF-8.
+*/
+const decryptArmored = (armored, identities) => {
+	if (identities.length === 0) return Promise.resolve(Left(decryptFailed("no identity provided")));
+	return toDecrypter(identities).fold((err) => Promise.resolve(Left(err)), (decrypter) => tryCatchAsync(async () => utf8.decode(await decrypter.decrypt(armor.decode(armored))), (err) => decryptFailed(redactKeys(String(err)))));
 };
+/** Generate an X25519 age keypair: the secret identity and its public recipient. */
+const generateAgeKeypair = () => tryCatchAsync(async () => {
+	const identity = await generateX25519Identity();
+	return {
+		identity,
+		recipient: await identityToRecipient(identity)
+	};
+}, (err) => ({
+	_tag: "KeygenFailed",
+	message: `age keygen failed: ${String(err)}`
+}));
+/** The installed `age-encryption` version, for `envpkt doctor`. Its `exports` hide package.json, so read it beside the entry point. */
+const ageEncryptionVersion = () => Try(() => {
+	const entry = createRequire(import.meta.url).resolve("age-encryption");
+	return JSON.parse(readFileSync(join(dirname(entry), "..", "package.json"), "utf-8")).version;
+}).toOption();
+const SECRET_KEY_PREFIX = "AGE-SECRET-KEY-";
+/** Classify a non-key line, so the error can name what it is without echoing its content. */
+const unsupportedLine = (line, lineNumber) => {
+	if (line.startsWith("-----BEGIN AGE ENCRYPTED FILE-----") || line.startsWith("age-encryption.org/")) return { _tag: "PassphraseProtectedIdentity" };
+	if (line.startsWith("AGE-PLUGIN-")) return {
+		_tag: "UnsupportedIdentity",
+		kind: "plugin",
+		line: lineNumber
+	};
+	if (line.startsWith("-----BEGIN") || line.startsWith("ssh-")) return {
+		_tag: "UnsupportedIdentity",
+		kind: "ssh",
+		line: lineNumber
+	};
+	return {
+		_tag: "UnsupportedIdentity",
+		kind: "unknown",
+		line: lineNumber
+	};
+};
+/**
+* Read every `AGE-SECRET-KEY-…` line from an age identity file, as the `age` CLI does. Blank lines
+* and `#` comments are skipped. Any other line — a plugin or SSH key, or a passphrase-protected
+* (age-encrypted) key file — is an error, since in-process decryption can't use it.
+*/
+const parseIdentityFile = (content) => {
+	const significant = content.split("\n").map((line, i) => ({
+		text: line.trim(),
+		number: i + 1
+	})).filter(({ text }) => text !== "" && !text.startsWith("#"));
+	const firstUnsupported = significant.find(({ text }) => !text.startsWith(SECRET_KEY_PREFIX));
+	if (firstUnsupported) return Left(unsupportedLine(firstUnsupported.text, firstUnsupported.number));
+	if (significant.length === 0) return Left({ _tag: "NoIdentityKey" });
+	return Right(significant.map(({ text }) => text));
+};
+//#endregion
+//#region src/fnox/identity.ts
+/** The `source` name for the inline key in identity errors. */
+const INLINE_KEY_SOURCE = "ENVPKT_AGE_KEY";
+/**
+* Read the age secret keys (`AGE-SECRET-KEY-…`) from identity text, such as a key file's content
+* or the inline `ENVPKT_AGE_KEY`. `source` names it in errors.
+*/
+const parseIdentityKeys = (content, source) => parseIdentityFile(content).mapLeft((err) => ({
+	...err,
+	source
+}));
 /**
-* Extract the secret key from an age identity file (plain or encrypted).
-* - Plain identity files (from `age-keygen`) contain `AGE-SECRET-KEY-*` lines directly
-* - Encrypted identity files need `age --decrypt` to unwrap
+* Read every secret key from a plain age identity file (as written by `envpkt keygen` or
+* `age-keygen`). A missing or unreadable file, and passphrase-protected, plugin and SSH key files,
+* are rejected with a typed error.
 */
 const unwrapAgentKey = (identityPath) => {
 	if (!existsSync(identityPath)) return Left({
@@ -620,27 +698,34 @@ const unwrapAgentKey = (identityPath) => {
 		path: identityPath
 	});
 	return Try(() => readFileSync(identityPath, "utf-8")).fold((err) => Left({
-		_tag: "DecryptFailed",
-		message: `Failed to read identity file: ${err}`
-	}), (content) => {
-		const secretKeyLine = content.split("\n").find((l) => l.startsWith("AGE-SECRET-KEY-"));
-		if (secretKeyLine) return Right(secretKeyLine.trim());
-		if (!ageAvailable()) return Left({
-			_tag: "AgeNotFound",
-			message: "age CLI not found on PATH"
-		});
-		return Try(() => execFileSync("age", ["--decrypt", identityPath], {
-			stdio: [
-				"pipe",
-				"pipe",
-				"pipe"
-			],
-			encoding: "utf-8"
-		})).fold((err) => Left({
-			_tag: "DecryptFailed",
-			message: `age decrypt failed: ${err}`
-		}), (output) => Right(output.trim()));
-	});
+		_tag: "IdentityUnreadable",
+		path: identityPath,
+		message: err.message
+	}), (content) => parseIdentityKeys(content, identityPath));
+};
+const IDENTITY_ERROR_TAGS = new Set(Object.keys({
+	IdentityNotFound: true,
+	IdentityUnreadable: true,
+	NoIdentityKey: true,
+	PassphraseProtectedIdentity: true,
+	UnsupportedIdentity: true
+}));
+/** True when `err` is about the age key itself rather than the config. */
+const isIdentityError = (err) => IDENTITY_ERROR_TAGS.has(err._tag);
+const UNSUPPORTED_KIND = {
+	plugin: "an age plugin key",
+	ssh: "an SSH key",
+	unknown: "not an age secret key"
+};
+/** Explain an identity error. Never includes key material. */
+const describeIdentityError = (err) => {
+	switch (err._tag) {
+		case "IdentityNotFound": return `Identity file not found: ${err.path}`;
+		case "IdentityUnreadable": return `Can't read key file ${err.path}: ${err.message}`;
+		case "NoIdentityKey": return `${err.source} has no age secret key (AGE-SECRET-KEY-…)`;
+		case "PassphraseProtectedIdentity": return err.source === "ENVPKT_AGE_KEY" ? `${INLINE_KEY_SOURCE} holds a passphrase-protected key, which envpkt can't read. Set it to the plain key file's content (its AGE-SECRET-KEY-… line).` : `${err.source} is a passphrase-protected key file, which envpkt can't read. Unwrap it once with \`age -d -o <plain-key-file> ${err.source}\` and point envpkt at the plain file.`;
+		case "UnsupportedIdentity": return `${err.source} line ${err.line} is ${UNSUPPORTED_KIND[err.kind]}; envpkt reads plain age secret keys (AGE-SECRET-KEY-…) only`;
+	}
 };
 //#endregion
 //#region src/cli/output.ts
@@ -747,7 +832,10 @@ const formatError = (error) => {
 		case "ParseError": return `${RED}Error:${RESET} Failed to parse TOML: ${error.message}`;
 		case "ValidationError": return `${RED}Error:${RESET} Config validation failed:\n${String(error.errors)}`;
 		case "ReadError": return `${RED}Error:${RESET} Could not read file: ${error.message}`;
-		case "AgeNotFound": return `${RED}Error:${RESET} age is required for this operation but was not found on PATH.\n${DIM}${ageInstallHint()}${RESET}`;
+		case "IdentityUnreadable":
+		case "NoIdentityKey":
+		case "PassphraseProtectedIdentity":
+		case "UnsupportedIdentity": return `${RED}Error:${RESET} ${describeIdentityError(error)}`;
 		case "DecryptFailed": return `${RED}Error:${RESET} Decrypt failed: ${error.message}`;
 		case "IdentityNotFound": return `${RED}Error:${RESET} Identity file not found: ${error.path}`;
 		case "SealKeyUnavailable": {
@@ -1160,54 +1248,32 @@ const resolveInlineKey = () => {
 	const key = process.env["ENVPKT_AGE_KEY"];
 	return key ? Some(key) : None();
 };
-/** Generate an age keypair and write to disk. Refuses to overwrite if the file already exists. */
-const generateKeypair = (options) => {
-	if (!ageAvailable()) return Left({
-		_tag: "AgeNotFound",
-		message: "age-keygen CLI not found on PATH. Install age: https://github.com/FiloSottile/age"
+/** The identity file `age-keygen` writes: creation time, public key, secret key. */
+const identityFileContent = (identity, recipient) => `# created: ${(/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z")}\n# public key: ${recipient}\n${identity}\n`;
+/** Write the identity file (0600), creating its directory if needed. Never overwrites a file. */
+const writeIdentityFile = (outputPath, content) => Try(() => {
+	mkdirSync(dirname(outputPath), { recursive: true });
+	writeFileSync(outputPath, content, {
+		mode: 384,
+		flag: "wx"
 	});
+	chmodSync(outputPath, 384);
+}).fold((err) => Left({
+	_tag: "WriteError",
+	message: `Failed to write identity file: ${err}`
+}), () => Right(void 0));
+/** Generate an age keypair and write to disk. Refuses to overwrite if the file already exists. */
+const generateKeypair = async (options) => {
 	const outputPath = options?.outputPath ?? resolveKeyPath();
 	if (existsSync(outputPath)) return Left({
 		_tag: "KeyExists",
 		path: outputPath
 	});
-	return Try(() => execFileSync("age-keygen", [], {
-		stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		],
-		encoding: "utf-8"
-	})).fold((err) => Left({
-		_tag: "KeygenFailed",
-		message: `age-keygen failed: ${err}`
-	}), (output) => {
-		const recipientLine = output.split("\n").find((l) => l.startsWith("# public key:"));
-		if (!recipientLine) return Left({
-			_tag: "KeygenFailed",
-			message: "Could not parse public key from age-keygen output"
-		});
-		const recipient = recipientLine.replace("# public key: ", "").trim();
-		const dir = dirname(outputPath);
-		const mkdirFailed = Try(() => {
-			if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-		}).fold((err) => ({
-			_tag: "WriteError",
-			message: `Failed to create directory ${dir}: ${err}`
-		}), () => void 0);
-		if (mkdirFailed) return Left(mkdirFailed);
-		return Try(() => {
-			writeFileSync(outputPath, output, { mode: 384 });
-			chmodSync(outputPath, 384);
-		}).fold((err) => Left({
-			_tag: "WriteError",
-			message: `Failed to write identity file: ${err}`
-		}), () => Right({
-			recipient,
-			identityPath: outputPath,
-			configUpdated: false
-		}));
-	});
+	return (await generateAgeKeypair()).flatMap(({ identity, recipient }) => writeIdentityFile(outputPath, identityFileContent(identity, recipient)).map(() => ({
+		recipient,
+		identityPath: outputPath,
+		configUpdated: false
+	})));
 };
 /** Update identity fields (recipient, key_file, name) in an envpkt.toml file, preserving structure */
 const updateConfigIdentity = (configPath, options) => {
@@ -1288,94 +1354,36 @@ const updateConfigIdentity = (configPath, options) => {
 };
 //#endregion
 //#region src/core/seal.ts
-/** Encrypt a plaintext string using age with the given recipient public key (armored output) */
-const ageEncrypt = (plaintext, recipient) => {
-	if (!ageAvailable()) return Left({
-		_tag: "AgeNotFound",
-		message: "age CLI not found on PATH"
-	});
-	return Try(() => execFileSync("age", [
-		"--encrypt",
-		"--recipient",
-		recipient,
-		"--armor"
-	], {
-		input: plaintext,
-		stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		],
-		encoding: "utf-8"
-	})).fold((err) => Left({
-		_tag: "EncryptFailed",
-		key: "",
-		message: `age encrypt failed: ${err}`
-	}), (output) => Right(output.trim()));
-};
-/** Decrypt an age-armored ciphertext using the given identity file. The plaintext is returned as-is, untrimmed. */
-const ageDecrypt = (ciphertext, identityPath) => {
-	if (!ageAvailable()) return Left({
-		_tag: "AgeNotFound",
-		message: "age CLI not found on PATH"
-	});
-	return Try(() => execFileSync("age", [
-		"--decrypt",
-		"--identity",
-		identityPath
-	], {
-		input: ciphertext,
-		stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		],
-		encoding: "utf-8"
-	})).fold((err) => Left({
-		_tag: "DecryptFailed",
-		key: "",
-		message: `age decrypt failed: ${err}`
-	}), (output) => Right(output));
-};
+/** Encrypt a plaintext string to an age recipient public key (armored output) */
+const ageEncrypt = (plaintext, recipient) => encryptArmored(plaintext, recipient);
+/**
+* Decrypt an age-armored ciphertext with any of the given secret keys (`AGE-SECRET-KEY-…`, as
+* returned by `unwrapAgentKey`). The plaintext is returned as-is, untrimmed.
+*/
+const ageDecrypt = (ciphertext, identities) => decryptArmored(ciphertext, identities);
 /** Seal multiple secrets: encrypt each value with the recipient key and set encrypted_value on meta */
-const sealSecrets = (meta, values, recipient) => {
-	if (!ageAvailable()) return Left({
-		_tag: "AgeNotFound",
-		message: "age CLI not found on PATH"
-	});
-	return Object.entries(meta).reduce((acc, [key, secretMeta]) => acc.flatMap((result) => {
+const sealSecrets = async (meta, values, recipient) => {
+	return (await Either.traverseAsync(Object.entries(meta), async ([key, secretMeta]) => {
 		const value = values[key];
-		if (value === void 0) return Right({
-			...result,
-			[key]: secretMeta
-		});
-		return ageEncrypt(value, recipient).mapLeft((err) => ({
+		if (value === void 0) return Right([key, secretMeta]);
+		return (await ageEncrypt(value, recipient)).mapLeft((err) => ({
 			_tag: "EncryptFailed",
 			key,
 			message: err.message
-		})).map((ciphertext) => ({
-			...result,
-			[key]: {
-				...secretMeta,
-				encrypted_value: ciphertext
-			}
-		}));
-	}), Right({}));
-};
-/** Unseal secrets: decrypt encrypted_value for each meta entry that has one */
-const unsealSecrets = (meta, identityPath) => {
-	if (!ageAvailable()) return Left({
-		_tag: "AgeNotFound",
-		message: "age CLI not found on PATH"
-	});
-	return Object.entries(meta).filter(([, secretMeta]) => secretMeta.encrypted_value !== void 0 && secretMeta.encrypted_value !== "").reduce((acc, [key, secretMeta]) => acc.flatMap((result) => ageDecrypt(secretMeta.encrypted_value, identityPath).mapLeft((err) => ({
+		})).map((ciphertext) => [key, {
+			...secretMeta,
+			encrypted_value: ciphertext
+		}]);
+	})).map((entries) => Object.fromEntries(entries));
+};
+/** Unseal secrets: decrypt encrypted_value for each meta entry that has one, with any of `identities` */
+const unsealSecrets = async (meta, identities) => {
+	const sealedEntries = Object.entries(meta).filter(([, secretMeta]) => secretMeta.encrypted_value !== void 0 && secretMeta.encrypted_value !== "");
+	return (await Either.traverseAsync(sealedEntries, async ([key, secretMeta]) => (await ageDecrypt(secretMeta.encrypted_value, identities)).mapLeft((err) => ({
 		_tag: "DecryptFailed",
 		key,
 		message: err.message
-	})).map((plaintext) => ({
-		...result,
-		[key]: plaintext
-	}))), Right({}));
+	})).map((plaintext) => [key, plaintext]))).map((entries) => Object.fromEntries(entries));
 };
 //#endregion
 //#region src/core/boot.ts
@@ -1395,51 +1403,27 @@ const resolveIdentityFilePath = (config, configDir, useDefaultFallback) => {
 	const defaultPath = resolveKeyPath();
 	return existsSync(defaultPath) ? Option(defaultPath) : Option(void 0);
 };
-const noop = () => {};
-/** Write an inline age key to a private temp file so the `age` CLI (file-based) can use it. */
-const materializeInlineKey = (key) => {
-	const dir = mkdtempSync(join(tmpdir(), "envpkt-age-"));
-	const keyPath = join(dir, "age-key.txt");
-	writeFileSync(keyPath, key.endsWith("\n") ? key : `${key}\n`);
-	chmodSync(keyPath, 384);
-	return {
-		path: keyPath,
-		dispose: () => rmSync(dir, {
-			recursive: true,
-			force: true
-		})
-	};
-};
+const keysFrom = (keys) => keys.map((k) => Option(k));
 /**
-* Resolve an age identity for unsealing sealed packets. Precedence:
+* Resolve the age secret keys for unsealing sealed packets. Precedence:
 *   config.identity.key_file > ENVPKT_AGE_KEY_FILE > ENVPKT_AGE_KEY (inline) > ~/.envpkt/age-key.txt
 * The inline key (CI secret) ranks above the homedir default so an explicit
-* env var beats a stray local key. Inline keys are written to a 0600 temp file
-* the caller must dispose().
+* env var beats a stray local key. It is parsed in memory and never written to disk.
 */
 const resolveSealIdentity = (config, configDir) => {
 	if (config.identity?.key_file) {
 		const keyFilePath = resolve(configDir, expandPath(config.identity.key_file));
-		if (existsSync(keyFilePath)) return Option({
-			path: keyFilePath,
-			dispose: noop
-		});
+		if (existsSync(keyFilePath)) return keysFrom(unwrapAgentKey(keyFilePath));
 	}
 	const envFile = process.env["ENVPKT_AGE_KEY_FILE"];
-	if (envFile && existsSync(envFile)) return Option({
-		path: envFile,
-		dispose: noop
-	});
+	if (envFile && existsSync(envFile)) return keysFrom(unwrapAgentKey(envFile));
 	const inlineKey = resolveInlineKey().orUndefined();
-	if (inlineKey) return Option(materializeInlineKey(inlineKey));
+	if (inlineKey) return keysFrom(parseIdentityKeys(inlineKey, INLINE_KEY_SOURCE));
 	if (!config.identity?.key_file) {
 		const defaultPath = join(homedir(), ".envpkt", "age-key.txt");
-		if (existsSync(defaultPath)) return Option({
-			path: defaultPath,
-			dispose: noop
-		});
+		if (existsSync(defaultPath)) return keysFrom(unwrapAgentKey(defaultPath));
 	}
-	return Option(void 0);
+	return Right(Option(void 0));
 };
 /** Describe the seal-identity precedence chain with per-entry status, for a clear no-key error. */
 const describeSealKeySearch = (config, configDir) => {
@@ -1457,7 +1441,7 @@ const describeSealKeySearch = (config, configDir) => {
 	];
 };
 const resolveIdentityKey = (config, configDir) => {
-	return resolveIdentityFilePath(config, configDir, false).fold(() => Right(Option(void 0)), (path) => unwrapAgentKey(path).fold((err) => Left(err), (key) => Right(Option(key))));
+	return resolveIdentityFilePath(config, configDir, false).fold(() => Right(Option(void 0)), (path) => unwrapAgentKey(path).fold((err) => Left(err), (keys) => Right(Option(keys[0]))));
 };
 const detectFnoxKeys = (configDir) => detectFnox(configDir).fold(() => /* @__PURE__ */ new Set(), (fnoxPath) => readFnoxConfig(fnoxPath).fold(() => /* @__PURE__ */ new Set(), (fnoxConfig) => extractFnoxKeys(fnoxConfig)));
 const checkExpiration = (audit, failOnExpired, warnOnly) => {
@@ -1470,6 +1454,19 @@ const checkExpiration = (audit, failOnExpired, warnOnly) => {
 	if (audit.expired > 0 && warnOnly) warnings.push(`${audit.expired} secret(s) have expired (warn-only mode)`);
 	return Right(warnings);
 };
+/**
+* Sealed values are declared, so a usable key is required. No key anywhere → SealKeyUnavailable;
+* a key that can't be used (an unreadable file, or a passphrase-protected, plugin or SSH key) → its
+* IdentityError. Either way
+* boot refuses rather than inject empty values — even under warnOnly, which governs soft issues
+* like expiry, not an absent key.
+*/
+const requireSealKeys = (config, configDir, entries) => resolveSealIdentity(config, configDir).flatMap((keys) => keys.fold(() => Left({
+	_tag: "SealKeyUnavailable",
+	sealedKeys: Object.keys(entries).filter((k) => !!entries[k]?.encrypted_value),
+	searched: describeSealKeySearch(config, configDir),
+	configuredKeyFile: config.identity?.key_file ? resolve(configDir, expandPath(config.identity.key_file)) : void 0
+}), (k) => Right(k)));
 const SECRET_PATTERNS = [
 	/^sk-/,
 	/^ghp_/,
@@ -1488,171 +1485,162 @@ const checkEnvMisclassification = (config) => {
 	const envEntries = config.env ?? {};
 	return Object.entries(envEntries).filter(([, entry]) => entry.value !== void 0 && looksLikeSecret(entry.value)).map(([key]) => `[env.${key}] value looks like a secret — consider moving to [secret.${key}]`);
 };
-/** Programmatic boot — returns Either<BootError, BootResult> */
-const bootSafe = (options) => {
+/** Programmatic boot — resolves to Either<BootError, BootResult> */
+const bootSafe = async (options) => {
 	const opts = options ?? {};
 	const inject = opts.inject !== false;
 	const failOnExpired = opts.failOnExpired !== false;
 	const warnOnly = opts.warnOnly ?? false;
 	const log = (opts.logger ?? directSilentLogger).withContext({ component: "envpkt.boot" });
-	return resolveAndLoad(opts).flatMap(({ config, configPath, configDir, configSource }) => validateAliases(config).fold((err) => {
+	const loaded = resolveAndLoad(opts);
+	if (loaded.isLeft()) return Left(loaded.value);
+	const { config, configPath, configDir, configSource } = loaded.value;
+	const aliases = validateAliases(config);
+	if (aliases.isLeft()) {
+		const err = aliases.value;
 		log.warn("alias.validate.failed", {
 			tag: err._tag,
 			key: "key" in err ? err.key : void 0
 		});
 		return Left(err);
-	}, (aliasTable) => {
-		log.debug("alias.validate.success", { aliases: aliasTable.entries.size });
-		const secretEntries = config.secret ?? {};
-		const envEntries = config.env ?? {};
-		const namer = makeEnvNamer(config);
-		const secretEnv = (key) => namer(key, secretEntries[key]?.namespace);
-		const envEnv = (key) => namer(key, envEntries[key]?.namespace);
-		const envNames = {
-			...Object.fromEntries(Object.keys(envEntries).map((k) => [k, envEnv(k)])),
-			...Object.fromEntries(Object.keys(secretEntries).map((k) => [k, secretEnv(k)]))
-		};
-		const nonAliasSecretEntries = Object.fromEntries(Object.entries(secretEntries).filter(([, meta]) => meta.from_key === void 0));
-		const aliasSecretKeys = Object.entries(secretEntries).filter(([, meta]) => meta.from_key !== void 0).map(([k]) => k);
-		const nonAliasEnvEntries = Object.entries(envEntries).filter(([, meta]) => meta.from_key === void 0);
-		const aliasEnvKeys = Object.entries(envEntries).filter(([, meta]) => meta.from_key !== void 0).map(([k]) => k);
-		const nonAliasMetaKeys = Object.keys(nonAliasSecretEntries);
-		const hasSealedValues = Object.values(nonAliasSecretEntries).some((meta) => !!meta.encrypted_value);
-		const identityKeyResult = resolveIdentityKey(config, configDir);
-		const identityKey = identityKeyResult.fold(() => Option(void 0), (k) => k);
-		if (identityKeyResult.isLeft() && !hasSealedValues) return identityKeyResult.fold((err) => Left(err), () => Left({
-			_tag: "ReadError",
-			message: "unexpected"
-		}));
-		const fnoxKeys = detectFnoxKeys(configDir);
-		const audit = computeAudit(config, fnoxKeys, void 0, aliasTable);
-		const sealIdentity = hasSealedValues ? resolveSealIdentity(config, configDir) : Option(void 0);
-		if (hasSealedValues && sealIdentity.isEmpty) return Left({
-			_tag: "SealKeyUnavailable",
-			sealedKeys: nonAliasMetaKeys.filter((k) => !!nonAliasSecretEntries[k]?.encrypted_value),
-			searched: describeSealKeySearch(config, configDir),
-			configuredKeyFile: config.identity?.key_file ? resolve(configDir, expandPath(config.identity.key_file)) : void 0
+	}
+	const aliasTable = aliases.value;
+	log.debug("alias.validate.success", { aliases: aliasTable.entries.size });
+	const secretEntries = config.secret ?? {};
+	const envEntries = config.env ?? {};
+	const namer = makeEnvNamer(config);
+	const secretEnv = (key) => namer(key, secretEntries[key]?.namespace);
+	const envEnv = (key) => namer(key, envEntries[key]?.namespace);
+	const envNames = {
+		...Object.fromEntries(Object.keys(envEntries).map((k) => [k, envEnv(k)])),
+		...Object.fromEntries(Object.keys(secretEntries).map((k) => [k, secretEnv(k)]))
+	};
+	const nonAliasSecretEntries = Object.fromEntries(Object.entries(secretEntries).filter(([, meta]) => meta.from_key === void 0));
+	const aliasSecretKeys = Object.entries(secretEntries).filter(([, meta]) => meta.from_key !== void 0).map(([k]) => k);
+	const nonAliasEnvEntries = Object.entries(envEntries).filter(([, meta]) => meta.from_key === void 0);
+	const aliasEnvKeys = Object.entries(envEntries).filter(([, meta]) => meta.from_key !== void 0).map(([k]) => k);
+	const nonAliasMetaKeys = Object.keys(nonAliasSecretEntries);
+	const hasSealedValues = Object.values(nonAliasSecretEntries).some((meta) => !!meta.encrypted_value);
+	const identityKeyResult = resolveIdentityKey(config, configDir);
+	const identityKey = identityKeyResult.fold(() => Option(void 0), (k) => k);
+	if (identityKeyResult.isLeft() && !hasSealedValues) return Left(identityKeyResult.value);
+	const fnoxKeys = detectFnoxKeys(configDir);
+	const audit = computeAudit(config, fnoxKeys, void 0, aliasTable);
+	const sealKeys = hasSealedValues ? requireSealKeys(config, configDir, nonAliasSecretEntries) : Right([]);
+	if (sealKeys.isLeft()) return Left(sealKeys.value);
+	const unsealKeys = sealKeys.value;
+	const expiration = checkExpiration(audit, failOnExpired, warnOnly);
+	if (expiration.isLeft()) return Left(expiration.value);
+	const warnings = expiration.value;
+	const secrets = {};
+	const injected = [];
+	const skipped = [];
+	warnings.push(...checkEnvMisclassification(config));
+	const nsSeparator = config.namespace?.separator;
+	if (nsSeparator !== void 0 && !isShellSafeSeparator(nsSeparator)) warnings.push(`[namespace] separator "${nsSeparator}" is not shell-safe — injected names won't be usable via shell $VAR/export. Use '_' or '__'.`);
+	const envDefaults = Object.fromEntries(nonAliasEnvEntries.flatMap(([key, entry]) => Option(process.env[envEnv(key)]).fold(() => Option(entry.value).fold(() => [], (v) => [[key, v]]), () => [])));
+	const overridden = nonAliasEnvEntries.flatMap(([key]) => Option(process.env[envEnv(key)]).fold(() => [], () => [key]));
+	if (inject) Object.entries(envDefaults).forEach(([key, value]) => {
+		process.env[envEnv(key)] = value;
+	});
+	const sealedKeys = /* @__PURE__ */ new Set();
+	if (hasSealedValues) (await unsealSecrets(nonAliasSecretEntries, unsealKeys)).fold((err) => {
+		log.warn("phase.sealed.decrypt_failed", { message: err.message });
+		warnings.push(`Sealed value decryption failed: ${err.message}`);
+	}, (unsealed) => {
+		const unsealedEntries = Object.entries(unsealed);
+		Object.assign(secrets, unsealed);
+		injected.push(...unsealedEntries.map(([key]) => key));
+		unsealedEntries.forEach(([key]) => {
+			sealedKeys.add(key);
+			log.debug("phase.sealed.resolved", { key });
 		});
-		return checkExpiration(audit, failOnExpired, warnOnly).map((warnings) => {
-			const secrets = {};
-			const injected = [];
-			const skipped = [];
-			warnings.push(...checkEnvMisclassification(config));
-			const nsSeparator = config.namespace?.separator;
-			if (nsSeparator !== void 0 && !isShellSafeSeparator(nsSeparator)) warnings.push(`[namespace] separator "${nsSeparator}" is not shell-safe — injected names won't be usable via shell $VAR/export. Use '_' or '__'.`);
-			const envDefaults = Object.fromEntries(nonAliasEnvEntries.flatMap(([key, entry]) => Option(process.env[envEnv(key)]).fold(() => Option(entry.value).fold(() => [], (v) => [[key, v]]), () => [])));
-			const overridden = nonAliasEnvEntries.flatMap(([key]) => Option(process.env[envEnv(key)]).fold(() => [], () => [key]));
-			if (inject) Object.entries(envDefaults).forEach(([key, value]) => {
-				process.env[envEnv(key)] = value;
-			});
-			const sealedKeys = /* @__PURE__ */ new Set();
-			if (hasSealedValues) sealIdentity.fold(() => {
-				log.warn("phase.sealed.no_identity_file", { sealed_keys: nonAliasMetaKeys.filter((k) => !!nonAliasSecretEntries[k]?.encrypted_value).length });
-			}, ({ path: idPath, dispose }) => {
-				try {
-					unsealSecrets(nonAliasSecretEntries, idPath).fold((err) => {
-						log.warn("phase.sealed.decrypt_failed", { message: err.message });
-						warnings.push(`Sealed value decryption failed: ${err.message}`);
-					}, (unsealed) => {
-						const unsealedEntries = Object.entries(unsealed);
-						Object.assign(secrets, unsealed);
-						injected.push(...unsealedEntries.map(([key]) => key));
-						unsealedEntries.forEach(([key]) => {
-							sealedKeys.add(key);
-							log.debug("phase.sealed.resolved", { key });
-						});
-					});
-				} finally {
-					dispose();
-				}
+	});
+	const remainingKeys = nonAliasMetaKeys.filter((k) => !sealedKeys.has(k));
+	if (remainingKeys.length > 0) {
+		if (fnoxAvailable()) fnoxExport(opts.profile, identityKey.orUndefined()).fold((err) => {
+			log.warn("phase.fnox.export_failed", {
+				message: err.message,
+				skipped: remainingKeys.length
 			});
-			const remainingKeys = nonAliasMetaKeys.filter((k) => !sealedKeys.has(k));
-			if (remainingKeys.length > 0) {
-				if (fnoxAvailable()) fnoxExport(opts.profile, identityKey.orUndefined()).fold((err) => {
-					log.warn("phase.fnox.export_failed", {
-						message: err.message,
-						skipped: remainingKeys.length
-					});
-					warnings.push(`fnox export failed: ${err.message}`);
-					skipped.push(...remainingKeys);
-				}, (exported) => {
-					const found = remainingKeys.filter((key) => key in exported);
-					const notFound = remainingKeys.filter((key) => !(key in exported));
-					found.forEach((key) => {
-						secrets[key] = exported[key];
-						log.debug("phase.fnox.resolved", {
-							key,
-							profile: opts.profile
-						});
-					});
-					notFound.forEach((key) => {
-						log.debug("phase.fnox.not_in_export", {
-							key,
-							profile: opts.profile
-						});
-					});
-					injected.push(...found);
-					skipped.push(...notFound);
+			warnings.push(`fnox export failed: ${err.message}`);
+			skipped.push(...remainingKeys);
+		}, (exported) => {
+			const found = remainingKeys.filter((key) => key in exported);
+			const notFound = remainingKeys.filter((key) => !(key in exported));
+			found.forEach((key) => {
+				secrets[key] = exported[key];
+				log.debug("phase.fnox.resolved", {
+					key,
+					profile: opts.profile
 				});
-				else {
-					log.debug("phase.fnox.unavailable", { skipped: remainingKeys.length });
-					if (!hasSealedValues) warnings.push("fnox not available — no secrets injected");
-					else warnings.push("fnox not available — unsealed secrets could not be resolved");
-					skipped.push(...remainingKeys);
-				}
-			}
-			aliasSecretKeys.forEach((aliasKey) => {
-				const entry = aliasTable.entries.get(`secret.${aliasKey}`);
-				if (!entry) return;
-				Option(secrets[entry.targetKey]).fold(() => {
-					skipped.push(aliasKey);
-					log.debug("phase.alias.target_unresolved", {
-						alias: aliasKey,
-						target: entry.targetKey
-					});
-				}, (targetValue) => {
-					secrets[aliasKey] = targetValue;
-					injected.push(aliasKey);
-					log.debug("phase.alias.copied", {
-						alias: aliasKey,
-						target: entry.targetKey
-					});
+			});
+			notFound.forEach((key) => {
+				log.debug("phase.fnox.not_in_export", {
+					key,
+					profile: opts.profile
 				});
 			});
-			aliasEnvKeys.forEach((aliasKey) => {
-				const entry = aliasTable.entries.get(`env.${aliasKey}`);
-				if (!entry) return;
-				if (process.env[envEnv(aliasKey)] !== void 0) {
-					overridden.push(aliasKey);
-					return;
-				}
-				const targetEntry = envEntries[entry.targetKey];
-				if (targetEntry?.value === void 0) return;
-				const resolvedTarget = process.env[envEnv(entry.targetKey)] ?? targetEntry.value;
-				envDefaults[aliasKey] = resolvedTarget;
+			injected.push(...found);
+			skipped.push(...notFound);
+		});
+		else {
+			log.debug("phase.fnox.unavailable", { skipped: remainingKeys.length });
+			if (!hasSealedValues) warnings.push("fnox not available — no secrets injected");
+			else warnings.push("fnox not available — unsealed secrets could not be resolved");
+			skipped.push(...remainingKeys);
+		}
+	}
+	aliasSecretKeys.forEach((aliasKey) => {
+		const entry = aliasTable.entries.get(`secret.${aliasKey}`);
+		if (!entry) return;
+		Option(secrets[entry.targetKey]).fold(() => {
+			skipped.push(aliasKey);
+			log.debug("phase.alias.target_unresolved", {
+				alias: aliasKey,
+				target: entry.targetKey
+			});
+		}, (targetValue) => {
+			secrets[aliasKey] = targetValue;
+			injected.push(aliasKey);
+			log.debug("phase.alias.copied", {
+				alias: aliasKey,
+				target: entry.targetKey
 			});
-			if (inject) {
-				Object.entries(envDefaults).forEach(([key, value]) => {
-					process.env[envEnv(key)] ??= value;
-				});
-				Object.entries(secrets).forEach(([key, value]) => {
-					process.env[secretEnv(key)] = value;
-				});
-			}
-			return {
-				audit,
-				injected,
-				skipped,
-				secrets,
-				warnings,
-				envDefaults,
-				overridden,
-				envNames,
-				configPath,
-				configSource
-			};
 		});
-	}));
+	});
+	aliasEnvKeys.forEach((aliasKey) => {
+		const entry = aliasTable.entries.get(`env.${aliasKey}`);
+		if (!entry) return;
+		if (process.env[envEnv(aliasKey)] !== void 0) {
+			overridden.push(aliasKey);
+			return;
+		}
+		const targetEntry = envEntries[entry.targetKey];
+		if (targetEntry?.value === void 0) return;
+		const resolvedTarget = process.env[envEnv(entry.targetKey)] ?? targetEntry.value;
+		envDefaults[aliasKey] = resolvedTarget;
+	});
+	if (inject) {
+		Object.entries(envDefaults).forEach(([key, value]) => {
+			process.env[envEnv(key)] ??= value;
+		});
+		Object.entries(secrets).forEach(([key, value]) => {
+			process.env[secretEnv(key)] = value;
+		});
+	}
+	return Right({
+		audit,
+		injected,
+		skipped,
+		secrets,
+		warnings,
+		envDefaults,
+		overridden,
+		envNames,
+		configPath,
+		configSource
+	});
 };
 //#endregion
 //#region src/core/copy.ts
@@ -2216,7 +2204,7 @@ const todayIso$2 = () => (/* @__PURE__ */ new Date()).toISOString().split("T")[0
 * value are copied as metadata only (with a warning) — there's nothing to reseal.
 * Overwriting an existing destination entry keeps its `created`; a new entry gets today.
 */
-const sealedSecretBlock = (key, destName, srcConfig, srcPath, destConfig) => {
+const sealedSecretBlock = async (key, destName, srcConfig, srcPath, destConfig) => {
 	const meta = srcConfig.secret[key];
 	const created = destConfig.secret?.[destName]?.created ?? todayIso$2();
 	if (meta.encrypted_value === void 0 || meta.encrypted_value === "") {
@@ -2226,26 +2214,23 @@ const sealedSecretBlock = (key, destName, srcConfig, srcPath, destConfig) => {
 			encryptedValue: Option.none()
 		}));
 	}
-	const identity = resolveSealIdentity(srcConfig, dirname(srcPath)).fold(() => {
+	const keys = orExit(resolveSealIdentity(srcConfig, dirname(srcPath)), (err) => `${RED}Error:${RESET} cannot unseal "${key}" from source — ${describeIdentityError(err)}`, 2).fold(() => {
 		console.error(`${RED}Error:${RESET} cannot unseal "${key}" from source — no age key found.`);
 		describeSealKeySearch(srcConfig, dirname(srcPath)).forEach((line) => console.error(`${DIM}  ${line}${RESET}`));
 		return process.exit(2);
-	}, (id) => id);
+	}, (k) => k);
 	const recipient = destConfig.identity?.recipient;
 	if (recipient === void 0) {
-		identity.dispose();
 		console.error(`${RED}Error:${RESET} destination needs identity.recipient to reseal "${destName}".`);
 		console.error(`${DIM}  Run ${CYAN}envpkt keygen${DIM} in the destination, or add an [identity] recipient.${RESET}`);
 		return process.exit(1);
 	}
-	const unsealed = unsealSecrets({ [key]: meta }, identity.path);
-	identity.dispose();
-	const plaintext = orExit(unsealed, (err) => `${RED}Error:${RESET} decrypt failed for "${key}": ${err.message}`, 2)[key];
+	const plaintext = orExit(await unsealSecrets({ [key]: meta }, keys), (err) => `${RED}Error:${RESET} decrypt failed for "${key}": ${err.message}`, 2)[key];
 	if (plaintext === void 0) {
 		console.error(`${RED}Error:${RESET} "${key}" produced no plaintext on unseal.`);
 		return process.exit(2);
 	}
-	const cipher = orExit(ageEncrypt(plaintext, recipient), (err) => `${RED}Error:${RESET} reseal failed for "${destName}": ${err.message}`, 2);
+	const cipher = orExit(await ageEncrypt(plaintext, recipient), (err) => `${RED}Error:${RESET} reseal failed for "${destName}": ${err.message}`, 2);
 	return serializeSecretBlock(destName, copyableSecretMeta(meta, {
 		created,
 		encryptedValue: Option(cipher)
@@ -2266,7 +2251,7 @@ const writeBlock = (destPath, header, block, overwrite, dryRun, successMsg) => {
 * (secret vs env) is detected from where the key lives in the source. `--from`/`--to`
 * default to the resolved config for the current directory.
 */
-const runCopy = (key, options) => {
+const runCopy = async (key, options) => {
 	const src = orExit(resolveConfigPath(options.from), formatError, 2);
 	const dest = orExit(resolveConfigPath(options.to), formatError, 2);
 	const srcConfig = orExit(loadConfig(src.path), formatError, 2);
@@ -2293,7 +2278,7 @@ const runCopy = (key, options) => {
 		console.error(`${RED}Error:${RESET} ${kindWord} "${destName}" already exists in ${dest.path}. Use --force to overwrite.`);
 		process.exit(1);
 	}
-	const block = inSecret ? sealedSecretBlock(key, destName, srcConfig, src.path, destConfig) : serializeEnvBlock(destName, srcConfig.env[key]);
+	const block = inSecret ? await sealedSecretBlock(key, destName, srcConfig, src.path, destConfig) : serializeEnvBlock(destName, srcConfig.env[key]);
 	const renamed = destName !== key ? ` → ${BOLD}${destName}${RESET}` : "";
 	const successMsg = `${GREEN}✓${RESET} Copied ${kindWord} ${BOLD}${key}${RESET}${renamed} to ${CYAN}${dest.path}${RESET}`;
 	writeBlock(dest.path, `[${kindWord}.${destName}]`, block, existsInDest, options.dryRun === true, successMsg);
@@ -2388,15 +2373,16 @@ const ok = (label, detail) => console.log(`  ${GREEN}✓${RESET} ${label}  ${DIM
 const warn = (label, detail) => console.log(`  ${YELLOW}—${RESET} ${label}  ${detail}`);
 const bad = (label, detail) => console.log(`  ${RED}✗${RESET} ${label}  ${detail}`);
 /** Print the resolution/key check, returning whether it passed. */
-const reportResolution = (configPath) => bootSafe({
+const reportResolution = async (configPath) => (await bootSafe({
 	configPath,
 	inject: false,
 	warnOnly: true
-}).fold((err) => {
+})).fold((err) => {
 	if (err._tag === "SealKeyUnavailable") {
 		bad("key   ", `${err.sealedKeys.length} sealed secret(s) but no decryption key`);
 		err.searched.forEach((line) => console.log(`${DIM}        ${line}${RESET}`));
-	} else bad("config", `${err._tag}`);
+	} else if (isIdentityError(err)) bad("key   ", describeIdentityError(err));
+	else bad("config", `${err._tag}`);
 	return false;
 }, (boot) => {
 	const resolved = Object.keys(boot.secrets).length;
@@ -2406,30 +2392,23 @@ const reportResolution = (configPath) => bootSafe({
 	return true;
 });
 /**
-* One-shot environment check: is age installed, is a config resolvable, and do its sealed
-* secrets decrypt with an available key? Read-only; exits non-zero if any check fails.
+* One-shot environment check: is a config resolvable, and do its sealed secrets decrypt with an
+* available key? Also reports the built-in age version. Read-only; exits non-zero if a check fails.
 */
-const runDoctor = (options) => {
+const runDoctor = async (options) => {
 	console.log(`${BOLD}envpkt doctor${RESET}\n`);
-	const ageOk = ageVersion().fold(() => {
-		bad("age   ", "not found on PATH");
-		console.log(`${DIM}        ${ageInstallHint().split("\n").join("\n        ")}${RESET}`);
-		return false;
-	}, (version) => {
-		ok("age   ", version);
-		return true;
-	});
-	const resolveOk = resolveConfigPath(options.config).fold(() => {
+	ok("age   ", `built in (age-encryption ${ageEncryptionVersion().orElse("version unknown")})`);
+	const resolveOk = await resolveConfigPath(options.config).fold(() => {
 		warn("config", "no envpkt.toml found for this directory");
-		return true;
+		return Promise.resolve(true);
 	}, ({ path }) => {
 		ok("config", path);
 		return reportResolution(path);
 	});
 	console.log("");
-	if (ageOk && resolveOk) console.log(`${GREEN}✓ no issues${RESET}`);
+	if (resolveOk) console.log(`${GREEN}✓ no issues${RESET}`);
 	else {
-		console.log(`${RED}✗ ${[!ageOk, !resolveOk].filter(Boolean).length} issue(s) found${RESET} ${CYAN}(see above)${RESET}`);
+		console.log(`${RED}✗ issue found${RESET} ${CYAN}(see above)${RESET}`);
 		process.exit(1);
 	}
 };
@@ -3388,8 +3367,8 @@ const emitWarnings = (boot) => {
 		console.error(`${YELLOW}Warning:${RESET} ${warning}`);
 	});
 };
-const runEnvExport = (options) => {
-	resolveForEmit(options).fold((err) => {
+const runEnvExport = async (options) => {
+	(await resolveForEmit(options)).fold((err) => {
 		console.error(formatError(err));
 		process.exit(2);
 	}, (boot) => {
@@ -3404,8 +3383,8 @@ const runEnvExport = (options) => {
 		if (options.track) console.log(`_ENVPKT_INJECTED='${emit.map((e) => e.name).join(" ")}'`);
 	});
 };
-const runEnvGithub = (options) => {
-	resolveForEmit(options).fold((err) => {
+const runEnvGithub = async (options) => {
+	(await resolveForEmit(options)).fold((err) => {
 		console.error(formatError(err));
 		process.exit(2);
 	}, (boot) => {
@@ -3426,8 +3405,8 @@ const runEnvGithub = (options) => {
 	});
 };
 const buildDotenvHeader = (configPath) => `# Generated by envpkt — regenerate with: envpkt env dotenv\n# Source: ${configPath}. Do not edit by hand.`;
-const runEnvDotenv = (options) => {
-	resolveForEmit(options).fold((err) => {
+const runEnvDotenv = async (options) => {
+	(await resolveForEmit(options)).fold((err) => {
 		console.error(formatError(err));
 		process.exit(2);
 	}, (boot) => {
@@ -3648,14 +3627,14 @@ const registerEnvCommands = (program) => {
 	env.command("check").description("Bidirectional drift detection between envpkt.toml and live environment").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json", "table").option("--strict", "Exit non-zero on any drift").action((options) => {
 		runEnvCheck(options);
 	});
-	env.command("export").description("Output export statements for eval-ing secrets into the current shell. Usage: eval \"$(envpkt env export)\"").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("--skip-audit", "Skip the pre-flight audit").option("--track", "Emit prior-value snapshots + an _ENVPKT_INJECTED list (for the shell hook to restore on cd)").action((options) => {
-		runEnvExport(options);
+	env.command("export").description("Output export statements for eval-ing secrets into the current shell. Usage: eval \"$(envpkt env export)\"").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("--skip-audit", "Skip the pre-flight audit").option("--track", "Emit prior-value snapshots + an _ENVPKT_INJECTED list (for the shell hook to restore on cd)").action(async (options) => {
+		await runEnvExport(options);
 	});
-	env.command("github").description("Inject resolved secrets into $GITHUB_ENV for GitHub Actions, masking secret values in the log (::add-mask::)").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("--strict", "Exit non-zero if the pre-flight audit is not healthy").action((options) => {
-		runEnvGithub(options);
+	env.command("github").description("Inject resolved secrets into $GITHUB_ENV for GitHub Actions, masking secret values in the log (::add-mask::)").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("--strict", "Exit non-zero if the pre-flight audit is not healthy").action(async (options) => {
+		await runEnvGithub(options);
 	});
-	env.command("dotenv").description("Output resolved credentials in .env format (for Wrangler, Docker --env-file, Vite, etc.)").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("-o, --output <file>", "Write to a file instead of stdout").option("--no-secrets", "Omit secret values (emit KEY= with a note) — values are included by default").action((options) => {
-		runEnvDotenv(options);
+	env.command("dotenv").description("Output resolved credentials in .env format (for Wrangler, Docker --env-file, Vite, etc.)").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("-o, --output <file>", "Write to a file instead of stdout").option("--no-secrets", "Omit secret values (emit KEY= with a note) — values are included by default").action(async (options) => {
+		await runEnvDotenv(options);
 	});
 	env.command("add").description("Add a new environment default entry to envpkt.toml").argument("<name>", "Environment variable name").argument("<value>", "Default value").option("-c, --config <path>", "Path to envpkt.toml").option("--purpose <purpose>", "Why this env var exists").option("--comment <comment>", "Free-form annotation").option("--tags <tags>", "Comma-separated key=value tags (e.g. env=prod,team=payments)").option("--dry-run", "Preview the TOML block without writing").action((name, value, options) => {
 		runEnvAdd(name, value, options);
@@ -3675,20 +3654,20 @@ const registerEnvCommands = (program) => {
 };
 //#endregion
 //#region src/cli/commands/exec.ts
-const runExec = (args, options) => {
+const runExec = async (args, options) => {
 	if (args.length === 0) {
 		console.error(`${RED}Error:${RESET} No command specified`);
 		process.exit(2);
 		return;
 	}
 	const skipAudit = options.skipAudit ?? options.check === false;
-	const boot = bootSafe({
+	const boot = (await bootSafe({
 		inject: false,
 		configPath: options.config,
 		profile: options.profile,
 		failOnExpired: false,
 		warnOnly: true
-	}).fold((err) => {
+	})).fold((err) => {
 		console.error(formatError(err));
 		process.exit(2);
 	}, (b) => b);
@@ -3808,13 +3787,13 @@ const SERVER_ENV = "CLAUDE_CODE_MCP_SERVER_NAME";
 * JSON object. stdout carries the JSON and nothing else; every diagnostic goes to stderr,
 * because Claude parses stdout verbatim.
 */
-const runHeaders = (serverArg, options) => {
+const runHeaders = async (serverArg, options) => {
 	const server = serverArg ?? process.env[SERVER_ENV];
 	if (!server) {
 		console.error(`${RED}Error:${RESET} No MCP server named. Pass [server] or set ${SERVER_ENV}.`);
 		process.exit(2);
 	}
-	resolveForEmit(options).fold((err) => {
+	(await resolveForEmit(options)).fold((err) => {
 		console.error(`MCP server "${server}":\n${formatError(err)}`);
 		process.exit(2);
 	}, (boot) => {
@@ -4034,52 +4013,46 @@ const printConfig = (config, path, resolveResult, opts) => {
 		});
 	}
 };
-const runInspect = (options) => {
-	resolveConfigPath(options.config).fold((err) => {
-		console.error(formatError(err));
-		process.exit(2);
-	}, ({ path, source }) => {
-		const sourceMsg = formatConfigSource(path, source);
-		if (sourceMsg) console.error(sourceMsg);
-		loadConfig(path).fold((err) => {
-			console.error(formatError(err));
-			process.exit(2);
-		}, (config) => {
-			const configDir = dirname(path);
-			resolveConfig(config, configDir).fold((err) => {
-				console.error(formatError(err));
-				process.exit(2);
-			}, (resolveResult) => {
-				const showResolved = options.resolved ?? !!resolveResult.catalogPath;
-				const showConfig = showResolved ? resolveResult.config : config;
-				if (options.format === "json") {
-					console.log(JSON.stringify(showConfig, null, 2));
-					return;
-				}
-				const showSecrets = showConfig.secret ?? {};
-				const printOpts = options.secrets ? (() => {
-					const sealedEntries = Object.fromEntries(Object.entries(showSecrets).filter(([, meta]) => meta.encrypted_value));
-					return {
-						secrets: Object.keys(sealedEntries).length > 0 ? (() => {
-							const identityPath = showConfig.identity?.key_file ? resolve(configDir, expandPath(showConfig.identity.key_file)) : (() => {
-								const defaultPath = resolveKeyPath();
-								return existsSync(defaultPath) ? defaultPath : void 0;
-							})();
-							if (!identityPath) return {};
-							return unsealSecrets(sealedEntries, identityPath).fold((err) => {
-								console.error(`${YELLOW}Warning:${RESET} Could not decrypt sealed secrets: ${err.message}`);
-								return {};
-							}, (d) => d);
-						})() : {},
-						secretDisplay: options.plaintext ? "plaintext" : "encrypted"
-					};
-				})() : void 0;
-				printConfig(showConfig, path, showResolved ? resolveResult : void 0, {
-					...printOpts ?? {},
-					sort: options.sort
-				});
-			});
-		});
+/** Print a formatted error and exit 2. */
+const exitWithError = (err) => {
+	console.error(formatError(err));
+	return process.exit(2);
+};
+/** Decrypt sealed values for `--secrets`. A failure is a warning: inspect still prints the rest. */
+const decryptForDisplay = async (config, configDir) => {
+	const sealedEntries = Object.fromEntries(Object.entries(config.secret ?? {}).filter(([, meta]) => meta.encrypted_value));
+	if (Object.keys(sealedEntries).length === 0) return {};
+	const identityPath = config.identity?.key_file ? resolve(configDir, expandPath(config.identity.key_file)) : (() => {
+		const defaultPath = resolveKeyPath();
+		return existsSync(defaultPath) ? defaultPath : void 0;
+	})();
+	if (!identityPath) return {};
+	const warnUndecrypted = (message) => {
+		console.error(`${YELLOW}Warning:${RESET} Could not decrypt sealed secrets: ${message}`);
+		return {};
+	};
+	return unwrapAgentKey(identityPath).fold((err) => Promise.resolve(warnUndecrypted(describeIdentityError(err))), async (keys) => (await unsealSecrets(sealedEntries, keys)).fold((err) => warnUndecrypted(err.message), (d) => d));
+};
+const runInspect = async (options) => {
+	const { path, source } = resolveConfigPath(options.config).fold(exitWithError, (r) => r);
+	const sourceMsg = formatConfigSource(path, source);
+	if (sourceMsg) console.error(sourceMsg);
+	const config = loadConfig(path).fold(exitWithError, (c) => c);
+	const configDir = dirname(path);
+	const resolveResult = resolveConfig(config, configDir).fold(exitWithError, (r) => r);
+	const showResolved = options.resolved ?? !!resolveResult.catalogPath;
+	const showConfig = showResolved ? resolveResult.config : config;
+	if (options.format === "json") {
+		console.log(JSON.stringify(showConfig, null, 2));
+		return;
+	}
+	const secretOpts = options.secrets ? {
+		secrets: await decryptForDisplay(showConfig, configDir),
+		secretDisplay: options.plaintext ? "plaintext" : "encrypted"
+	} : {};
+	printConfig(showConfig, path, showResolved ? resolveResult : void 0, {
+		...secretOpts,
+		sort: options.sort
 	});
 };
 //#endregion
@@ -4091,6 +4064,19 @@ const tildeShorten = (p) => {
 };
 /** Derive a default identity name from the config path's parent directory */
 const deriveIdentityName = (configPath) => basename(dirname(resolve(configPath)));
+/** Keep the config's identity.name if it has one; otherwise derive one */
+const identityName = (configPath) => loadConfig(configPath).toOption().flatMap((config) => Option(config.identity?.name)).orElse(deriveIdentityName(configPath));
+/**
+* The key_file value to write. boot resolves key_file against the config's directory, so a key
+* inside that directory is written relative to it; any other key is written as an absolute path,
+* shortened to ~ under $HOME.
+*/
+const keyFileFor = (configPath, identityPath) => {
+	const realPath = (p) => Try(() => realpathSync(p)).orElse(resolve(p));
+	const abs = realPath(identityPath);
+	const rel = relative(realPath(dirname(configPath)), abs);
+	return rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel) ? tildeShorten(abs) : rel;
+};
 /**
 * Derive a project-specific key path from the config path.
 * - `envpkt.toml` → `~/.envpkt/<dir>-key.txt`
@@ -4104,10 +4090,10 @@ const deriveKeyPath = (configPath) => {
 	const name = stem === "envpkt" || stem === "" ? dir : `${dir}-${stem}`;
 	return join(homedir(), ".envpkt", `${name}-key.txt`);
 };
-const runKeygen = (options) => {
+const runKeygen = async (options) => {
 	const configPath = resolve(options.config ?? join(process.cwd(), "envpkt.toml"));
 	const outputPath = options.output ?? (options.global ? resolveKeyPath() : deriveKeyPath(configPath));
-	generateKeypair({ outputPath }).fold((err) => {
+	(await generateKeypair({ outputPath })).fold((err) => {
 		if (err._tag === "KeyExists") {
 			console.error(`${YELLOW}Warning:${RESET} Identity file already exists: ${CYAN}${err.path}${RESET}`);
 			console.error(`${DIM}To replace it: remove the file first, then re-run keygen.${RESET}`);
@@ -4121,8 +4107,8 @@ const runKeygen = (options) => {
 		console.log(`${BOLD}Recipient:${RESET} ${recipient}`);
 		console.log("");
 		if (existsSync(configPath)) {
-			const name = deriveIdentityName(configPath);
-			const keyFile = tildeShorten(identityPath);
+			const name = identityName(configPath);
+			const keyFile = keyFileFor(configPath, identityPath);
 			updateConfigIdentity(configPath, {
 				recipient,
 				name,
@@ -4760,10 +4746,9 @@ const runSeal = async (options) => {
 	const identityKey = Option(config.identity.key_file).flatMap((keyFile) => {
 		const identityPath = resolve(configDir, expandPath(keyFile));
 		return unwrapAgentKey(identityPath).fold((err) => {
-			const msg = err._tag === "IdentityNotFound" ? `not found: ${err.path}` : err.message;
-			console.error(`${YELLOW}Warning:${RESET} Could not unwrap agent key: ${msg}`);
+			console.error(`${YELLOW}Warning:${RESET} Could not unwrap agent key: ${describeIdentityError(err)}`);
 			return Option.none();
-		}, (k) => Option(k));
+		}, (keys) => Option(keys[0]));
 	});
 	const editKeys = options.edit ? options.edit.split(",").map((k) => k.trim()).filter((k) => k.length > 0) : [];
 	if (options.stdin && editKeys.length === 0) {
@@ -4806,7 +4791,7 @@ const runSeal = async (options) => {
 			console.error(`${RED}Error:${RESET} No values provided`);
 			process.exit(2);
 		}
-		sealSecrets(secretEntries, values, recipient).fold((err) => {
+		(await sealSecrets(secretEntries, values, recipient)).fold((err) => {
 			console.error(`${RED}Error:${RESET} Seal failed: ${err.message}`);
 			process.exit(2);
 		}, (sealedMeta) => {
@@ -4853,8 +4838,13 @@ const runSeal = async (options) => {
 				console.error(`${DIM}  3. ~/.envpkt/age-key.txt${RESET}`);
 				process.exit(2);
 			}
+			const keys = unwrapAgentKey(identityPath).fold((err) => {
+				console.error(`${RED}Error:${RESET} ${describeIdentityError(err)}`);
+				process.exit(2);
+				return [];
+			}, (k) => k);
 			const sealedEntries = Object.fromEntries(alreadySealed.map((k) => [k, allSecretEntries[k]]));
-			const decrypted = unsealSecrets(sealedEntries, identityPath).fold((err) => {
+			const decrypted = (await unsealSecrets(sealedEntries, keys)).fold((err) => {
 				console.error(`${RED}Error:${RESET} Failed to decrypt existing secrets: ${err.message}`);
 				process.exit(2);
 				return {};
@@ -4877,7 +4867,7 @@ const runSeal = async (options) => {
 		const skippedKeys = metaKeys.filter((k) => !(k in values));
 		console.log(`${YELLOW}Skipped${RESET} ${skipped} key(s) with no value: ${skippedKeys.join(", ")}`);
 	}
-	sealSecrets(secretEntries, values, recipient).fold((err) => {
+	(await sealSecrets(secretEntries, values, recipient)).fold((err) => {
 		console.error(`${RED}Error:${RESET} Seal failed: ${err.message}`);
 		process.exit(2);
 	}, (sealedMeta) => {
@@ -5213,7 +5203,7 @@ const runSecretRotate = async (name, options) => {
 		console.error(`${YELLOW}Cancelled:${RESET} no value provided — ${BOLD}${name}${RESET} was not rotated.`);
 		process.exit(1);
 	}
-	const ciphertext = ageEncrypt(value, recipient).fold((err) => {
+	const ciphertext = (await ageEncrypt(value, recipient)).fold((err) => {
 		console.error(`${RED}Error:${RESET} Encryption failed: ${err.message}`);
 		process.exit(2);
 		return "";
@@ -5677,8 +5667,8 @@ program.name("envpkt").description("Credential lifecycle and fleet management fo
 program.command("init").description("Initialize a new envpkt.toml in the current directory").option("--from-fnox [path]", "Scaffold from fnox.toml (optionally specify path)").option("--catalog <path>", "Path to shared secret catalog").option("--identity", "Include [identity] section").option("--name <name>", "Identity name (requires --identity)").option("--capabilities <caps>", "Comma-separated capabilities (requires --identity)").option("--expires <date>", "Credential expiration YYYY-MM-DD (requires --identity)").option("--scope <scope>", "Top-level scope: \"shell\" (secrets load ambiently) or \"exec\" (only via envpkt exec)").option("--global", "Scaffold a global/ambient package (implies scope = \"shell\")").option("--force", "Overwrite existing envpkt.toml").action((options) => {
 	runInit(process.cwd(), options);
 });
-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("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(async (options) => {
+	await 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 | missing_metadata | external").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("--unsealed", "Show only secrets without encrypted_value (resolved at runtime or external)").option("--sort", "Sort secrets alphabetically within each status bucket (no file mutation)").action((options) => {
 	runAudit(options);
@@ -5689,14 +5679,14 @@ 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, MCP header, 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)").option("--sort", "Display secrets and env entries in alphabetical order (no file mutation)").action((options) => {
-	runInspect(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(async (options) => {
+	await 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) => {
-	runExec(args, 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(async (args, options) => {
+	await runExec(args, options);
 });
-program.command("headers").description("Print HTTP headers for an MCP server as JSON — for Claude Code's headersHelper in .mcp.json").argument("[server]", "MCP server name (default: $CLAUDE_CODE_MCP_SERVER_NAME)").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").action((server, options) => {
-	runHeaders(server, options);
+program.command("headers").description("Print HTTP headers for an MCP server as JSON — for Claude Code's headersHelper in .mcp.json").argument("[server]", "MCP server name (default: $CLAUDE_CODE_MCP_SERVER_NAME)").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").action(async (server, options) => {
+	await runHeaders(server, options);
 });
 program.command("resolve").description("Resolve catalog references and output a flat, self-contained config").option("-c, --config <path>", "Path to envpkt.toml").option("-o, --output <path>", "Write resolved config to file (default: stdout)").option("--format <format>", "Output format: toml | json", "toml").option("--dry-run", "Show what would be resolved without writing").action((options) => {
 	runResolve(options);
@@ -5715,14 +5705,14 @@ program.command("sort").description("Group [env.*] and [secret.*] sections and a
 program.command("upgrade").description("Upgrade envpkt to the latest version (npm install -g envpkt@latest)").action(() => {
 	runUpgrade();
 });
-program.command("copy").description("Copy a secret or env entry from one config to another (auto unseal → reseal for secrets)").argument("<key>", "The secret or env key to copy").option("--from <path>", "Source config path (default: resolved config for this directory)").option("--to <path>", "Destination config path (default: resolved config for this directory)").option("--as <newKey>", "Copy under a different key name in the destination").option("--force", "Overwrite the entry if it already exists in the destination").option("--dry-run", "Preview the change without writing").action((key, options) => {
-	runCopy(key, options);
+program.command("copy").description("Copy a secret or env entry from one config to another (auto unseal → reseal for secrets)").argument("<key>", "The secret or env key to copy").option("--from <path>", "Source config path (default: resolved config for this directory)").option("--to <path>", "Destination config path (default: resolved config for this directory)").option("--as <newKey>", "Copy under a different key name in the destination").option("--force", "Overwrite the entry if it already exists in the destination").option("--dry-run", "Preview the change without writing").action(async (key, options) => {
+	await runCopy(key, options);
 });
 program.command("diff").description("Compare two envpkt.toml configs by their secret/env entries (keys + metadata)").argument("<a>", "First config path").argument("<b>", "Second config path").option("--format <format>", "Output format: text | json", "text").option("--exit-code", "Exit non-zero when the configs differ (for CI drift gates)").action((a, b, options) => {
 	runDiff(a, b, options);
 });
-program.command("doctor").description("Check that age is installed and that the resolved config's sealed secrets can be decrypted").option("-c, --config <path>", "Path to envpkt.toml").action((options) => {
-	runDoctor(options);
+program.command("doctor").description("Check that the config resolves, a usable age key is found, and its sealed secrets decrypt").option("-c, --config <path>", "Path to envpkt.toml").action(async (options) => {
+	await runDoctor(options);
 });
 program.command("config-path").description("Print the envpkt.toml path resolved for the current directory (empty if none). Resolve-only — no decryption.").option("-c, --config <path>", "Path to envpkt.toml").action((options) => {
 	runConfigPath(options);
@@ -5730,6 +5720,6 @@ program.command("config-path").description("Print the envpkt.toml path resolved
 program.command("shell-hook").description("Output a shell hook that loads a project's credentials on cd and restores them on leave").argument("<shell>", "Shell type: zsh | bash").option("--no-audit", "Omit the credential-health audit line from the emitted hook").action((shell, options) => {
 	runShellHook(shell, options);
 });
-program.parse();
+await program.parseAsync();
 //#endregion
 export {};