envpkt 0.8.1 → 0.10.1

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,6 +870,140 @@ 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$2 = /^(secret|env)\.(.+)$/;
+const parseRef = (raw) => {
+	const match = ALIAS_REF_RE$2.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");
@@ -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]) => {
@@ -2303,6 +2535,77 @@ const runEnvRm = (name, options) => {
 		});
 	});
 };
+const ALIAS_REF_RE$1 = /^(secret|env)\.(.+)$/;
+const buildEnvAliasBlock = (name, options) => {
+	const lines = [`[env.${name}]`, `from_key = "${options.from}"`];
+	if (options.purpose) lines.push(`purpose = "${options.purpose}"`);
+	if (options.comment) lines.push(`comment = "${options.comment}"`);
+	if (options.tags) {
+		const pairs = options.tags.split(",").map((pair) => {
+			const [k, v] = pair.split("=").map((s) => s.trim());
+			return `${k} = "${v}"`;
+		});
+		lines.push(`tags = { ${pairs.join(", ")} }`);
+	}
+	return `${lines.join("\n")}\n`;
+};
+const runEnvAlias = (name, options) => {
+	const match = ALIAS_REF_RE$1.exec(options.from);
+	if (!match) {
+		console.error(`${RED}Error:${RESET} --from "${options.from}" must be formatted as "secret.<KEY>" or "env.<KEY>"`);
+		process.exit(1);
+	}
+	const [, targetKind, targetKey] = match;
+	if (targetKind !== "env") {
+		console.error(`${RED}Error:${RESET} env alias must point at another env entry — got "${options.from}". Use \`envpkt secret alias\` for secret→secret aliases.`);
+		process.exit(1);
+	}
+	resolveConfigPath(options.config).fold((err) => {
+		console.error(formatError(err));
+		process.exit(2);
+	}, ({ path: configPath, source }) => {
+		const sourceMsg = formatConfigSource(configPath, source);
+		if (sourceMsg) console.error(sourceMsg);
+		loadConfig(configPath).fold((err) => {
+			console.error(formatError(err));
+			process.exit(2);
+		}, (config) => {
+			const envEntries = config.env ?? {};
+			if (name === targetKey) {
+				console.error(`${RED}Error:${RESET} alias "${name}" cannot reference itself`);
+				process.exit(1);
+			}
+			const target = envEntries[targetKey];
+			if (!target) {
+				console.error(`${RED}Error:${RESET} alias target "${options.from}" not found in ${configPath}. Add the target env entry first.`);
+				process.exit(1);
+			}
+			if (target.from_key !== void 0) {
+				console.error(`${RED}Error:${RESET} alias target "${options.from}" is itself an alias. Chained aliases are not supported — point at the canonical entry instead.`);
+				process.exit(1);
+			}
+			const existing = envEntries[name];
+			if (existing) {
+				if (!options.force) {
+					console.error(`${YELLOW}Warning:${RESET} env entry "${name}" already exists in ${configPath} (${existing.from_key ? `currently alias → ${existing.from_key}` : "currently a regular entry"}).`);
+					console.error(`  Pass ${BOLD}--force${RESET} to overwrite, or use a different name.`);
+					process.exit(1);
+				}
+				console.error(`${YELLOW}Warning:${RESET} overwriting existing env entry "${name}" (${existing.from_key ? `was alias → ${existing.from_key}` : "was a regular entry"})`);
+			}
+			const block = buildEnvAliasBlock(name, options);
+			if (options.dryRun) {
+				console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
+				if (existing) console.log(`${DIM}# (would replace existing [env.${name}] block)${RESET}\n`);
+				console.log(block);
+				return;
+			}
+			const raw = readFileSync(configPath, "utf-8");
+			writeFileSync(configPath, appendSection(existing ? removeSection(raw, `[env.${name}]`).fold(() => raw, (r) => r) : raw, block), "utf-8");
+			console.log(`${GREEN}✓${RESET} Aliased ${BOLD}${name}${RESET} → ${BOLD}${options.from}${RESET} in ${CYAN}${configPath}${RESET}`);
+		});
+	});
+};
 const runEnvRename = (oldName, newName, options) => {
 	withConfig$1(Option(options.config), (configPath, raw) => {
 		renameSection(raw, `[env.${oldName}]`, `[env.${newName}]`).fold((err) => {
@@ -2342,6 +2645,9 @@ const registerEnvCommands = (program) => {
 	env.command("rename").description("Rename an env entry, preserving all fields").argument("<old>", "Current env variable name").argument("<new>", "New env variable name").option("-c, --config <path>", "Path to envpkt.toml").option("--dry-run", "Preview the result without writing").action((oldName, newName, options) => {
 		runEnvRename(oldName, newName, options);
 	});
+	env.command("alias").description("Create an alias entry that reuses another env entry's resolved value").argument("<name>", "Alias name (becomes the env var key)").requiredOption("--from <ref>", "Target reference — must be \"env.<KEY>\"").option("-c, --config <path>", "Path to envpkt.toml").option("--purpose <purpose>", "Why this alias exists (local metadata)").option("--comment <comment>", "Free-form annotation").option("--tags <tags>", "Comma-separated key=value tags (e.g. env=prod,team=payments)").option("--force", "Overwrite the entry if <name> already exists").option("--dry-run", "Preview the TOML block without writing").action((name, options) => {
+		runEnvAlias(name, options);
+	});
 };
 //#endregion
 //#region src/cli/commands/exec.ts
@@ -2969,6 +3275,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({
@@ -2980,6 +3287,7 @@ const handleGetPacketHealth = (args) => {
 		expired: audit.expired,
 		stale: audit.stale,
 		missing: audit.missing,
+		aliases: audit.aliases,
 		secrets: secretDetails
 	}, null, 2));
 };
@@ -3009,11 +3317,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));
 	});
 };
@@ -3546,6 +3873,77 @@ const runSecretRename = (oldName, newName, options) => {
 		});
 	});
 };
+const ALIAS_REF_RE = /^(secret|env)\.(.+)$/;
+const buildSecretAliasBlock = (name, options) => {
+	const lines = [`[secret.${name}]`, `from_key = "${options.from}"`];
+	if (options.purpose) lines.push(`purpose = "${options.purpose}"`);
+	if (options.comment) lines.push(`comment = "${options.comment}"`);
+	if (options.tags) {
+		const pairs = options.tags.split(",").map((pair) => {
+			const [k, v] = pair.split("=").map((s) => s.trim());
+			return `${k} = "${v}"`;
+		});
+		lines.push(`tags = { ${pairs.join(", ")} }`);
+	}
+	return `${lines.join("\n")}\n`;
+};
+const runSecretAlias = (name, options) => {
+	const match = ALIAS_REF_RE.exec(options.from);
+	if (!match) {
+		console.error(`${RED}Error:${RESET} --from "${options.from}" must be formatted as "secret.<KEY>" or "env.<KEY>"`);
+		process.exit(1);
+	}
+	const [, targetKind, targetKey] = match;
+	if (targetKind !== "secret") {
+		console.error(`${RED}Error:${RESET} secret alias must point at another secret — got "${options.from}". Use \`envpkt env alias\` for env→env aliases.`);
+		process.exit(1);
+	}
+	resolveConfigPath(options.config).fold((err) => {
+		console.error(formatError(err));
+		process.exit(2);
+	}, ({ path: configPath, source }) => {
+		const sourceMsg = formatConfigSource(configPath, source);
+		if (sourceMsg) console.error(sourceMsg);
+		loadConfig(configPath).fold((err) => {
+			console.error(formatError(err));
+			process.exit(2);
+		}, (config) => {
+			const secrets = config.secret ?? {};
+			if (name === targetKey) {
+				console.error(`${RED}Error:${RESET} alias "${name}" cannot reference itself`);
+				process.exit(1);
+			}
+			const target = secrets[targetKey];
+			if (!target) {
+				console.error(`${RED}Error:${RESET} alias target "${options.from}" not found in ${configPath}. Add the target secret first.`);
+				process.exit(1);
+			}
+			if (target.from_key !== void 0) {
+				console.error(`${RED}Error:${RESET} alias target "${options.from}" is itself an alias. Chained aliases are not supported — point at the canonical entry instead.`);
+				process.exit(1);
+			}
+			const existing = secrets[name];
+			if (existing) {
+				if (!options.force) {
+					console.error(`${YELLOW}Warning:${RESET} secret "${name}" already exists in ${configPath} (${existing.from_key ? `currently alias → ${existing.from_key}` : "currently a regular entry"}).`);
+					console.error(`  Pass ${BOLD}--force${RESET} to overwrite, or use a different name.`);
+					process.exit(1);
+				}
+				console.error(`${YELLOW}Warning:${RESET} overwriting existing entry "${name}" (${existing.from_key ? `was alias → ${existing.from_key}` : "was a regular entry"})`);
+			}
+			const block = buildSecretAliasBlock(name, options);
+			if (options.dryRun) {
+				console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
+				if (existing) console.log(`${DIM}# (would replace existing [secret.${name}] block)${RESET}\n`);
+				console.log(block);
+				return;
+			}
+			const raw = readFileSync(configPath, "utf-8");
+			writeFileSync(configPath, appendSection(existing ? removeSection(raw, `[secret.${name}]`).fold(() => raw, (r) => r) : raw, block), "utf-8");
+			console.log(`${GREEN}✓${RESET} Aliased ${BOLD}${name}${RESET} → ${BOLD}${options.from}${RESET} in ${CYAN}${configPath}${RESET}`);
+		});
+	});
+};
 const addSecretFlags = (cmd) => cmd.option("--service <service>", "Service this secret authenticates to").option("--purpose <purpose>", "Why this secret exists").option("--comment <comment>", "Free-form annotation").option("--expires <date>", "Expiration date (YYYY-MM-DD)").option("--capabilities <caps>", "Comma-separated capabilities (e.g. read,write)").option("--rotates <schedule>", "Rotation schedule (e.g. 90d, quarterly)").option("--rate-limit <limit>", "Rate limit info (e.g. 1000/min)").option("--model-hint <hint>", "Suggested model or tier").option("--source <source>", "Where the value originates (e.g. vault, ci)").option("--rotation-url <url>", "URL for secret rotation procedure").option("--tags <tags>", "Comma-separated key=value tags (e.g. env=prod,team=payments)");
 const registerSecretCommands = (program) => {
 	const secret = program.command("secret").description("Manage secret entries in envpkt.toml");
@@ -3561,6 +3959,9 @@ const registerSecretCommands = (program) => {
 	secret.command("rename").description("Rename a secret entry, preserving all metadata").argument("<old>", "Current secret name").argument("<new>", "New secret name").option("-c, --config <path>", "Path to envpkt.toml").option("--dry-run", "Preview the result without writing").action((oldName, newName, options) => {
 		runSecretRename(oldName, newName, options);
 	});
+	secret.command("alias").description("Create an alias entry that reuses another secret's resolved value").argument("<name>", "Alias name (becomes the env var key)").requiredOption("--from <ref>", "Target reference — must be \"secret.<KEY>\"").option("-c, --config <path>", "Path to envpkt.toml").option("--purpose <purpose>", "Why this alias exists (local metadata)").option("--comment <comment>", "Free-form annotation").option("--tags <tags>", "Comma-separated key=value tags (e.g. env=prod,team=payments)").option("--force", "Overwrite the entry if <name> already exists").option("--dry-run", "Preview the TOML block without writing").action((name, options) => {
+		runSecretAlias(name, options);
+	});
 };
 //#endregion
 //#region src/cli/commands/shell-hook.ts