envpkt 0.8.0 → 0.9.1

package/README.md

@@ -141,6 +141,29 @@ value = "info"
 purpose = "Application log verbosity"
 ```
 
+### Aliases
+
+When a consumer hardcodes a different env var name than the one you govern
+canonically, use `from_key` to expose the same value under a second name —
+without duplicating the secret:
+
+```toml
+[secret.API_KEY]
+service      = "stripe"
+expires      = "2027-01-15"
+rotation_url = "https://dashboard.stripe.com/apikeys"
+
+# Same governed value, under a legacy name some consumer expects
+[secret.STRIPE_SECRET_KEY]
+from_key = "secret.API_KEY"
+```
+
+Both names are injected at boot, both appear in audit output, and expiration
+tracking lives on the target — an alias is healthy iff its target is. Same
+pattern works for `[env.*]`. Cross-type aliasing (secret → env) is rejected
+at load time. See [TOML Schema → Aliases](https://envpkt.dev/reference/toml-schema/#aliases)
+for the full rules.
+
 See [`examples/`](./examples/) for more configurations.
 
 ## Sealed Packets
@@ -150,21 +173,22 @@ Sealed packets embed age-encrypted secret values directly in `envpkt.toml`. This
 ### Setup
 
 ```bash
-# Generate an age keypair
-age-keygen -o identity.txt
-# public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+# Generate an age keypair — writes to ~/.envpkt/<project>-key.txt and updates envpkt.toml
+envpkt keygen
 ```
 
-Add the public key to your config and the identity file to `.gitignore`:
+This writes `[identity]` with `name`, `recipient`, and `key_file` to your `envpkt.toml`. Add the key file to `.gitignore`:
 
 ```toml
 [identity]
 name = "my-agent"
 recipient = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"
-key_file = "identity.txt"
+key_file = "~/.envpkt/my-agent-key.txt"
 ```
 
-The `key_file` path supports `~` expansion and environment variables (`$VAR`, `${VAR}`), so you can use paths like `~/keys/identity.txt` or `$KEYS_DIR/identity.txt`. Relative paths are resolved from the config file's directory. When omitted, envpkt falls back to `ENVPKT_AGE_KEY_FILE` env var, then `~/.envpkt/age-key.txt`.
+`envpkt keygen` defaults to a **project-specific path** (`~/.envpkt/<project>-key.txt`), so separate projects never collide. For multi-environment projects (e.g. `prod.envpkt.toml` + `dev.envpkt.toml`), each config gets its own key automatically. Pass `--global` to use the shared `~/.envpkt/age-key.txt` path instead.
+
+The `key_file` path supports `~` expansion and environment variables (`$VAR`, `${VAR}`). Relative paths are resolved from the config file's directory. When omitted, envpkt falls back to `ENVPKT_AGE_KEY_FILE` env var, then `~/.envpkt/age-key.txt` — but it's best to set `key_file` explicitly so the config tells you which key it needs.
 
 ### Seal
 

package/dist/cli.js

@@ -54,10 +54,28 @@ const classifySecret = (key, meta, fnoxKeys, staleWarningDays, requireExpiration
 		purpose,
 		created: Option(meta.created),
 		expires: Option(meta.expires),
-		issues: List(issues)
+		issues: List(issues),
+		alias_of: Option(void 0)
 	};
 };
-const computeAudit = (config, fnoxKeys, today) => {
+/**
+* Build a SecretHealth row for an alias entry. Status is inherited from the
+* target; metadata (purpose, tags) comes from the alias entry itself where
+* set, otherwise falls through to the target so operators see context.
+*/
+const classifyAlias = (key, meta, targetHealth, targetRef) => ({
+	key,
+	service: targetHealth.service,
+	status: targetHealth.status,
+	days_remaining: targetHealth.days_remaining,
+	rotation_url: targetHealth.rotation_url,
+	purpose: meta.purpose !== void 0 ? Option(meta.purpose) : targetHealth.purpose,
+	created: targetHealth.created,
+	expires: targetHealth.expires,
+	issues: List([]),
+	alias_of: Option(targetRef)
+});
+const computeAudit = (config, fnoxKeys, today, aliasTable) => {
 	const now = today ?? /* @__PURE__ */ new Date();
 	const lifecycle = config.lifecycle ?? {};
 	const staleWarningDays = lifecycle.stale_warning_days ?? 90;
@@ -65,9 +83,31 @@ const computeAudit = (config, fnoxKeys, today) => {
 	const requireService = lifecycle.require_service ?? false;
 	const keys = fnoxKeys ?? /* @__PURE__ */ new Set();
 	const secretEntries = config.secret ?? {};
-	const metaKeys = new Set(Object.keys(secretEntries));
-	const secrets = List(Object.entries(secretEntries).map(([key, meta]) => classifySecret(key, meta, keys, staleWarningDays, requireExpiration, requireService, now)));
-	const orphaned = keys.size > 0 ? [...metaKeys].filter((k) => !keys.has(k)).length : 0;
+	const nonAliasEntries = Object.entries(secretEntries).filter(([, meta]) => meta.from_key === void 0);
+	const aliasEntries = Object.entries(secretEntries).filter(([, meta]) => meta.from_key !== void 0);
+	const nonAliasMetaKeys = new Set(nonAliasEntries.map(([k]) => k));
+	const nonAliasHealth = nonAliasEntries.map(([key, meta]) => classifySecret(key, meta, keys, staleWarningDays, requireExpiration, requireService, now));
+	const healthByKey = new Map(nonAliasHealth.map((h) => [h.key, h]));
+	const aliasHealth = aliasEntries.map(([key, meta]) => {
+		const targetKey = (aliasTable?.entries.get(`secret.${key}`))?.targetKey;
+		const targetHealth = targetKey !== void 0 ? healthByKey.get(targetKey) : void 0;
+		const targetRef = meta.from_key ?? (targetKey !== void 0 ? `secret.${targetKey}` : "");
+		if (!targetHealth) return {
+			key,
+			service: Option(meta.service),
+			status: "missing",
+			days_remaining: Option(void 0),
+			rotation_url: Option(meta.rotation_url),
+			purpose: Option(meta.purpose),
+			created: Option(meta.created),
+			expires: Option(meta.expires),
+			issues: List(["Alias target not resolvable"]),
+			alias_of: Option(targetRef)
+		};
+		return classifyAlias(key, meta, targetHealth, targetRef);
+	});
+	const secrets = List([...nonAliasHealth, ...aliasHealth]);
+	const orphaned = keys.size > 0 ? [...nonAliasMetaKeys].filter((k) => !keys.has(k)).length : 0;
 	const total = secrets.size;
 	const expired = secrets.count((s) => s.status === "expired");
 	const missing = secrets.count((s) => s.status === "missing");
@@ -75,6 +115,7 @@ const computeAudit = (config, fnoxKeys, today) => {
 	const expiring_soon = secrets.count((s) => s.status === "expiring_soon");
 	const stale = secrets.count((s) => s.status === "stale");
 	const healthy = secrets.count((s) => s.status === "healthy");
+	const aliases = aliasHealth.length;
 	return {
 		status: Cond.of().when(expired > 0 || missing > 0, "critical").elseWhen(expiring_soon > 0 || stale > 0 || missing_metadata > 0, "degraded").else("healthy"),
 		secrets,
@@ -86,6 +127,7 @@ const computeAudit = (config, fnoxKeys, today) => {
 		missing,
 		missing_metadata,
 		orphaned,
+		aliases,
 		identity: config.identity
 	};
 };
@@ -93,13 +135,17 @@ const computeEnvAudit = (config, env = process.env) => {
 	const envEntries = config.env ?? {};
 	const entries = Object.entries(envEntries).map(([key, entry]) => {
 		const currentValue = env[key];
-		const status = Cond.of().when(currentValue === void 0, "missing").elseWhen(currentValue !== entry.value, "overridden").else("default");
+		const effectiveDefault = entry.from_key !== void 0 ? (() => {
+			const targetKey = /^env\.(.+)$/.exec(entry.from_key)?.[1];
+			return (targetKey !== void 0 ? envEntries[targetKey] : void 0)?.value ?? "";
+		})() : entry.value ?? "";
 		return {
 			key,
-			defaultValue: entry.value,
+			defaultValue: effectiveDefault,
 			currentValue,
-			status,
-			purpose: entry.purpose
+			status: Cond.of().when(currentValue === void 0, "missing").elseWhen(currentValue !== effectiveDefault, "overridden").else("default"),
+			purpose: entry.purpose,
+			alias_of: Option(entry.from_key)
 		};
 	});
 	return {
@@ -158,6 +204,7 @@ const SecretMetaSchema = Type.Object({
 	model_hint: Type.Optional(Type.String({ description: "Suggested model or tier for this credential" })),
 	source: Type.Optional(Type.String({ description: "Where the secret value originates (e.g. 'vault', 'ci')" })),
 	encrypted_value: Type.Optional(Type.String({ description: "Age-encrypted secret value (armored ciphertext, safe to commit)" })),
+	from_key: Type.Optional(Type.String({ description: "Reference another entry (format: 'secret.<KEY>') whose resolved value this alias reuses. Mutually exclusive with encrypted_value." })),
 	required: Type.Optional(Type.Boolean({ description: "Whether this secret is required for operation" })),
 	tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Key-value tags for grouping and filtering" }))
 }, { description: "Metadata about a single secret" });
@@ -182,7 +229,8 @@ const CallbackConfigSchema = Type.Object({
 }, { description: "Automation callbacks for lifecycle events" });
 const ToolsConfigSchema = Type.Record(Type.String(), Type.Unknown(), { description: "Tool integration configuration — open namespace for third-party extensions" });
 const EnvMetaSchema = Type.Object({
-	value: Type.String({ description: "Default value for this environment variable" }),
+	value: Type.Optional(Type.String({ description: "Default value for this environment variable. Optional when from_key is set; required otherwise." })),
+	from_key: Type.Optional(Type.String({ description: "Reference another entry (format: 'env.<KEY>') whose resolved value this alias reuses. Mutually exclusive with value." })),
 	purpose: Type.Optional(Type.String({ description: "Why this env var exists" })),
 	comment: Type.Optional(Type.String({ description: "Free-form annotation or note" })),
 	tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Key-value tags for grouping and filtering" }))
@@ -822,17 +870,151 @@ const readFnoxConfig = (path) => Try(() => readFileSync(path, "utf-8")).fold((er
 /** Extract the set of secret key names from a parsed fnox config */
 const extractFnoxKeys = (config) => new Set(Object.keys(config.secrets));
 //#endregion
+//#region src/core/alias.ts
+const ALIAS_REF_RE = /^(secret|env)\.(.+)$/;
+const parseRef = (raw) => {
+	const match = ALIAS_REF_RE.exec(raw);
+	if (!match) return Option(void 0);
+	const kind = match[1];
+	const key = match[2];
+	if (!key) return Option(void 0);
+	return Option({
+		kind,
+		key
+	});
+};
+const validateOneSecret = (key, meta, secretEntries) => {
+	if (meta.from_key === void 0) return Right(Option(void 0));
+	const ref = meta.from_key;
+	if (meta.encrypted_value !== void 0) return Left({
+		_tag: "AliasValueConflict",
+		key,
+		kind: "secret",
+		field: "encrypted_value"
+	});
+	return parseRef(ref).fold(() => Left({
+		_tag: "AliasInvalidSyntax",
+		key,
+		kind: "secret",
+		value: ref
+	}), (parsed) => {
+		if (parsed.kind !== "secret") return Left({
+			_tag: "AliasCrossType",
+			key,
+			kind: "secret",
+			targetKind: parsed.kind
+		});
+		if (parsed.key === key) return Left({
+			_tag: "AliasSelfReference",
+			key: `secret.${key}`
+		});
+		return Option(secretEntries[parsed.key]).fold(() => Left({
+			_tag: "AliasTargetMissing",
+			key: `secret.${key}`,
+			target: ref
+		}), (target) => {
+			if (target.from_key !== void 0) return Left({
+				_tag: "AliasChained",
+				key: `secret.${key}`,
+				target: ref
+			});
+			return Right(Option({
+				kind: "secret",
+				targetKind: "secret",
+				targetKey: parsed.key
+			}));
+		});
+	});
+};
+const validateOneEnv = (key, meta, envEntries) => {
+	if (meta.from_key === void 0) return Right(Option(void 0));
+	const ref = meta.from_key;
+	if (meta.value !== void 0) return Left({
+		_tag: "AliasValueConflict",
+		key,
+		kind: "env",
+		field: "value"
+	});
+	return parseRef(ref).fold(() => Left({
+		_tag: "AliasInvalidSyntax",
+		key,
+		kind: "env",
+		value: ref
+	}), (parsed) => {
+		if (parsed.kind !== "env") return Left({
+			_tag: "AliasCrossType",
+			key,
+			kind: "env",
+			targetKind: parsed.kind
+		});
+		if (parsed.key === key) return Left({
+			_tag: "AliasSelfReference",
+			key: `env.${key}`
+		});
+		return Option(envEntries[parsed.key]).fold(() => Left({
+			_tag: "AliasTargetMissing",
+			key: `env.${key}`,
+			target: ref
+		}), (target) => {
+			if (target.from_key !== void 0) return Left({
+				_tag: "AliasChained",
+				key: `env.${key}`,
+				target: ref
+			});
+			return Right(Option({
+				kind: "env",
+				targetKind: "env",
+				targetKey: parsed.key
+			}));
+		});
+	});
+};
+/**
+* Validate all `from_key` references in a resolved config. Produces an
+* AliasTable mapping each alias to its target, or an AliasError describing
+* the first failure.
+*
+* Rules:
+* - Ref must be "secret.<KEY>" or "env.<KEY>"
+* - Target must exist in the same resolved config
+* - Target must be the same type (secret→secret, env→env only)
+* - Target must not itself be a from_key entry (single hop only)
+* - Self-reference is rejected
+* - An alias entry cannot also carry a value field (encrypted_value for
+*   secrets, value for env)
+*/
+const validateAliases = (config) => {
+	const secretEntries = config.secret ?? {};
+	const envEntries = config.env ?? {};
+	const entries = /* @__PURE__ */ new Map();
+	const secretResults = Object.entries(secretEntries).map(([key, meta]) => [key, validateOneSecret(key, meta, secretEntries)]);
+	for (const [key, result] of secretResults) {
+		const outcome = result.fold((err) => err, (opt) => opt.orUndefined());
+		if (outcome === void 0) continue;
+		if ("_tag" in outcome) return Left(outcome);
+		entries.set(`secret.${key}`, outcome);
+	}
+	const envResults = Object.entries(envEntries).map(([key, meta]) => [key, validateOneEnv(key, meta, envEntries)]);
+	for (const [key, result] of envResults) {
+		const outcome = result.fold((err) => err, (opt) => opt.orUndefined());
+		if (outcome === void 0) continue;
+		if ("_tag" in outcome) return Left(outcome);
+		entries.set(`env.${key}`, outcome);
+	}
+	return Right({ entries });
+};
+//#endregion
 //#region src/core/keygen.ts
 /** Resolve the age identity file path: ENVPKT_AGE_KEY_FILE env var > ~/.envpkt/age-key.txt */
 const resolveKeyPath = () => process.env["ENVPKT_AGE_KEY_FILE"] ?? join(homedir(), ".envpkt", "age-key.txt");
-/** Generate an age keypair and write to disk */
+/** 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"
 	});
 	const outputPath = options?.outputPath ?? resolveKeyPath();
-	if (existsSync(outputPath) && !options?.force) return Left({
+	if (existsSync(outputPath)) return Left({
 		_tag: "KeyExists",
 		path: outputPath
 	});
@@ -1089,7 +1271,7 @@ const looksLikeSecret = (value) => {
 };
 const checkEnvMisclassification = (config) => {
 	const envEntries = config.env ?? {};
-	return Object.entries(envEntries).filter(([, entry]) => looksLikeSecret(entry.value)).map(([key]) => `[env.${key}] value looks like a secret — consider moving to [secret.${key}]`);
+	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) => {
@@ -1097,26 +1279,29 @@ const bootSafe = (options) => {
 	const inject = opts.inject !== false;
 	const failOnExpired = opts.failOnExpired !== false;
 	const warnOnly = opts.warnOnly ?? false;
-	return resolveAndLoad(opts).flatMap(({ config, configPath, configDir, configSource }) => {
+	return resolveAndLoad(opts).flatMap(({ config, configPath, configDir, configSource }) => validateAliases(config).fold((err) => Left(err), (aliasTable) => {
 		const secretEntries = config.secret ?? {};
-		const metaKeys = Object.keys(secretEntries);
-		const hasSealedValues = metaKeys.some((k) => !!secretEntries[k].encrypted_value);
+		const envEntries = config.env ?? {};
+		const nonAliasSecretEntries = Object.fromEntries(Object.entries(secretEntries).filter(([, meta]) => meta.from_key === void 0));
+		const aliasSecretKeys = Object.keys(secretEntries).filter((k) => secretEntries[k].from_key !== void 0);
+		const nonAliasEnvEntries = Object.entries(envEntries).filter(([, meta]) => meta.from_key === void 0);
+		const aliasEnvKeys = Object.keys(envEntries).filter((k) => envEntries[k].from_key !== void 0);
+		const nonAliasMetaKeys = Object.keys(nonAliasSecretEntries);
+		const hasSealedValues = nonAliasMetaKeys.some((k) => !!nonAliasSecretEntries[k].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 audit = computeAudit(config, detectFnoxKeys(configDir));
+		const audit = computeAudit(config, detectFnoxKeys(configDir), void 0, aliasTable);
 		return checkExpiration(audit, failOnExpired, warnOnly).map((warnings) => {
 			const secrets = {};
 			const injected = [];
 			const skipped = [];
 			warnings.push(...checkEnvMisclassification(config));
-			const envEntries = config.env ?? {};
-			const envEntriesArr = Object.entries(envEntries);
-			const envDefaults = Object.fromEntries(envEntriesArr.flatMap(([key, entry]) => Option(process.env[key]).fold(() => [[key, entry.value]], () => [])));
-			const overridden = envEntriesArr.flatMap(([key]) => Option(process.env[key]).fold(() => [], () => [key]));
+			const envDefaults = Object.fromEntries(nonAliasEnvEntries.flatMap(([key, entry]) => Option(process.env[key]).fold(() => entry.value !== void 0 ? [[key, entry.value]] : [], () => [])));
+			const overridden = nonAliasEnvEntries.flatMap(([key]) => Option(process.env[key]).fold(() => [], () => [key]));
 			if (inject) Object.entries(envDefaults).forEach(([key, value]) => {
 				process.env[key] = value;
 			});
@@ -1125,7 +1310,7 @@ const bootSafe = (options) => {
 			if (hasSealedValues) identityFilePath.fold(() => {
 				warnings.push("Sealed values found but no identity file available for decryption");
 			}, (idPath) => {
-				unsealSecrets(secretEntries, idPath).fold((err) => {
+				unsealSecrets(nonAliasSecretEntries, idPath).fold((err) => {
 					warnings.push(`Sealed value decryption failed: ${err.message}`);
 				}, (unsealed) => {
 					const unsealedEntries = Object.entries(unsealed);
@@ -1134,7 +1319,7 @@ const bootSafe = (options) => {
 					unsealedEntries.map(([key]) => key).forEach((key) => sealedKeys.add(key));
 				});
 			});
-			const remainingKeys = metaKeys.filter((k) => !sealedKeys.has(k));
+			const remainingKeys = nonAliasMetaKeys.filter((k) => !sealedKeys.has(k));
 			if (remainingKeys.length > 0) if (fnoxAvailable()) fnoxExport(opts.profile, identityKey.orUndefined()).fold((err) => {
 				warnings.push(`fnox export failed: ${err.message}`);
 				skipped.push(...remainingKeys);
@@ -1152,9 +1337,34 @@ const bootSafe = (options) => {
 				else warnings.push("fnox not available — unsealed secrets could not be resolved");
 				skipped.push(...remainingKeys);
 			}
-			if (inject) Object.entries(secrets).forEach(([key, value]) => {
-				process.env[key] = value;
+			aliasSecretKeys.forEach((aliasKey) => {
+				const entry = aliasTable.entries.get(`secret.${aliasKey}`);
+				if (!entry) return;
+				const targetValue = secrets[entry.targetKey];
+				if (targetValue !== void 0) {
+					secrets[aliasKey] = targetValue;
+					injected.push(aliasKey);
+				} else skipped.push(aliasKey);
+			});
+			aliasEnvKeys.forEach((aliasKey) => {
+				const entry = aliasTable.entries.get(`env.${aliasKey}`);
+				if (!entry) return;
+				if (process.env[aliasKey] !== void 0) {
+					overridden.push(aliasKey);
+					return;
+				}
+				const targetEntry = envEntries[entry.targetKey];
+				if (targetEntry?.value === void 0) return;
+				envDefaults[aliasKey] = process.env[entry.targetKey] ?? targetEntry.value;
 			});
+			if (inject) {
+				Object.entries(envDefaults).forEach(([key, value]) => {
+					process.env[key] ??= value;
+				});
+				Object.entries(secrets).forEach(([key, value]) => {
+					process.env[key] = value;
+				});
+			}
 			return {
 				audit,
 				injected,
@@ -1167,7 +1377,7 @@ const bootSafe = (options) => {
 				configSource
 			};
 		});
-	});
+	}));
 };
 //#endregion
 //#region src/core/patterns.ts
@@ -1883,14 +2093,27 @@ const envScan = (env, options) => {
 		low_confidence
 	};
 };
+const parseAliasRef = (raw, expectedKind) => {
+	const match = /^(secret|env)\.(.+)$/.exec(raw);
+	if (!match) return void 0;
+	if (match[1] !== expectedKind) return void 0;
+	return match[2];
+};
 /** Bidirectional drift detection between config and live environment */
 const envCheck = (config, env) => {
 	const secretEntries = config.secret ?? {};
 	const metaKeys = Object.keys(secretEntries);
 	const trackedSet = new Set(metaKeys);
+	const isSecretPresent = (key) => {
+		if (env[key] !== void 0 && env[key] !== "") return true;
+		const meta = secretEntries[key];
+		if (meta?.from_key === void 0) return false;
+		const targetKey = parseAliasRef(meta.from_key, "secret");
+		return targetKey !== void 0 && env[targetKey] !== void 0 && env[targetKey] !== "";
+	};
 	const secretDriftEntries = metaKeys.map((key) => {
 		const meta = secretEntries[key];
-		const present = env[key] !== void 0 && env[key] !== "";
+		const present = isSecretPresent(key);
 		return {
 			envVar: key,
 			service: Option(meta.service),
@@ -1899,12 +2122,19 @@ const envCheck = (config, env) => {
 		};
 	});
 	const envDefaults = config.env ?? {};
+	const isEnvPresent = (key) => {
+		if (env[key] !== void 0 && env[key] !== "") return true;
+		const meta = envDefaults[key];
+		if (meta?.from_key === void 0) return false;
+		const targetKey = parseAliasRef(meta.from_key, "env");
+		return targetKey !== void 0 && env[targetKey] !== void 0 && env[targetKey] !== "";
+	};
 	const envDefaultEntries = Object.keys(envDefaults).filter((key) => {
 		if (trackedSet.has(key)) return false;
 		trackedSet.add(key);
 		return true;
 	}).map((key) => {
-		const present = env[key] !== void 0 && env[key] !== "";
+		const present = isEnvPresent(key);
 		return {
 			envVar: key,
 			service: Option(void 0),
@@ -2193,7 +2423,9 @@ const runEnvExport = (options) => {
 		if (boot.overridden.length > 0) loadConfig(boot.configPath).fold(() => {}, (config) => {
 			const envEntries = config.env ?? {};
 			boot.overridden.forEach((key) => {
-				if (key in envEntries) console.log(`export ${key}='${shellEscape(envEntries[key].value)}'`);
+				if (!(key in envEntries)) return;
+				const value = envEntries[key].value ?? process.env[key] ?? "";
+				console.log(`export ${key}='${shellEscape(value)}'`);
 			});
 		});
 		Object.entries(boot.secrets).forEach(([key, value]) => {
@@ -2738,15 +2970,26 @@ const tildeShorten = (p) => {
 };
 /** Derive a default identity name from the config path's parent directory */
 const deriveIdentityName = (configPath) => basename(dirname(resolve(configPath)));
+/**
+* Derive a project-specific key path from the config path.
+* - `envpkt.toml` → `~/.envpkt/<dir>-key.txt`
+* - `prod.envpkt.toml` → `~/.envpkt/<dir>-prod-key.txt`
+* - `foo.envpkt.toml` → `~/.envpkt/<dir>-foo-key.txt`
+*/
+const deriveKeyPath = (configPath) => {
+	const abs = resolve(configPath);
+	const dir = basename(dirname(abs));
+	const stem = basename(abs).replace(/\.envpkt\.toml$/, "").replace(/\.toml$/, "");
+	const name = stem === "envpkt" || stem === "" ? dir : `${dir}-${stem}`;
+	return join(homedir(), ".envpkt", `${name}-key.txt`);
+};
 const runKeygen = (options) => {
-	const outputPath = options.output ?? resolveKeyPath();
-	generateKeypair({
-		force: options.force,
-		outputPath
-	}).fold((err) => {
+	const configPath = resolve(options.config ?? join(process.cwd(), "envpkt.toml"));
+	generateKeypair({ outputPath: options.output ?? (options.global ? resolveKeyPath() : deriveKeyPath(configPath)) }).fold((err) => {
 		if (err._tag === "KeyExists") {
 			console.error(`${YELLOW}Warning:${RESET} Identity file already exists: ${CYAN}${err.path}${RESET}`);
-			console.error(`${DIM}Use --force to overwrite.${RESET}`);
+			console.error(`${DIM}To replace it: remove the file first, then re-run keygen.${RESET}`);
+			console.error(`${DIM}To use a different path: pass -o <path>.${RESET}`);
 			process.exit(1);
 		}
 		console.error(formatError(err));
@@ -2755,7 +2998,6 @@ const runKeygen = (options) => {
 		console.log(`${GREEN}Generated${RESET} age identity: ${CYAN}${identityPath}${RESET}`);
 		console.log(`${BOLD}Recipient:${RESET} ${recipient}`);
 		console.log("");
-		const configPath = resolve(options.config ?? join(process.cwd(), "envpkt.toml"));
 		if (existsSync(configPath)) {
 			const name = deriveIdentityName(configPath);
 			const keyFile = tildeShorten(identityPath);
@@ -2959,6 +3201,7 @@ const handleGetPacketHealth = (args) => {
 		status: s.status,
 		days_remaining: s.days_remaining.fold(() => null, (d) => d),
 		rotation_url: s.rotation_url.fold(() => null, (u) => u),
+		alias_of: s.alias_of.fold(() => null, (a) => a),
 		issues: s.issues.toArray()
 	}));
 	return textResult(JSON.stringify({
@@ -2970,6 +3213,7 @@ const handleGetPacketHealth = (args) => {
 		expired: audit.expired,
 		stale: audit.stale,
 		missing: audit.missing,
+		aliases: audit.aliases,
 		secrets: secretDetails
 	}, null, 2));
 };
@@ -2999,11 +3243,30 @@ const handleGetSecretMeta = (args) => {
 	const loaded = loadConfigForTool(configPathArg(args));
 	if (!loaded.ok) return loaded.result;
 	const { config } = loaded;
-	return Option((config.secret ?? {})[key]).fold(() => errorResult(`Secret not found: ${key}`), (meta) => {
-		const { encrypted_value: _, ...safeMeta } = meta;
+	const secretEntries = config.secret ?? {};
+	return Option(secretEntries[key]).fold(() => errorResult(`Secret not found: ${key}`), (meta) => {
+		const { encrypted_value: _, from_key: fromKey, ...rest } = meta;
+		if (fromKey !== void 0) {
+			const targetKey = /^secret\.(.+)$/.exec(fromKey)?.[1];
+			const target = targetKey !== void 0 ? secretEntries[targetKey] : void 0;
+			if (target) {
+				const { encrypted_value: __, from_key: ___, ...targetRest } = target;
+				return textResult(JSON.stringify({
+					key,
+					...targetRest,
+					...rest,
+					alias_of: fromKey
+				}, null, 2));
+			}
+			return textResult(JSON.stringify({
+				key,
+				...rest,
+				alias_of: fromKey
+			}, null, 2));
+		}
 		return textResult(JSON.stringify({
 			key,
-			...safeMeta
+			...rest
 		}, null, 2));
 	});
 };
@@ -3661,7 +3924,7 @@ 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("--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("--force", "Overwrite existing identity file").option("-o, --output <path>", "Output path for identity file (default: ~/.envpkt/age-key.txt)").action((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("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) => {