envpkt 0.8.1 → 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,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 = /^(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");
@@ -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]) => {
@@ -2969,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({
@@ -2980,6 +3213,7 @@ const handleGetPacketHealth = (args) => {
 		expired: audit.expired,
 		stale: audit.stale,
 		missing: audit.missing,
+		aliases: audit.aliases,
 		secrets: secretDetails
 	}, null, 2));
 };
@@ -3009,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));
 	});
 };

package/dist/index.d.ts

@@ -44,6 +44,7 @@ declare const SecretMetaSchema: _$_sinclair_typebox0.TObject<{
   model_hint: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
   source: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
   encrypted_value: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
+  from_key: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
   required: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TBoolean>;
   tags: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TRecord<_$_sinclair_typebox0.TString, _$_sinclair_typebox0.TString>>;
 }>;
@@ -63,7 +64,8 @@ type CallbackConfig = Static<typeof CallbackConfigSchema>;
 declare const ToolsConfigSchema: _$_sinclair_typebox0.TRecord<_$_sinclair_typebox0.TString, _$_sinclair_typebox0.TUnknown>;
 type ToolsConfig = Static<typeof ToolsConfigSchema>;
 declare const EnvMetaSchema: _$_sinclair_typebox0.TObject<{
-  value: _$_sinclair_typebox0.TString;
+  value: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
+  from_key: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
   purpose: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
   comment: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
   tags: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TRecord<_$_sinclair_typebox0.TString, _$_sinclair_typebox0.TString>>;
@@ -96,11 +98,13 @@ declare const EnvpktConfigSchema: _$_sinclair_typebox0.TObject<{
     model_hint: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
     source: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
     encrypted_value: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
+    from_key: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
     required: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TBoolean>;
     tags: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TRecord<_$_sinclair_typebox0.TString, _$_sinclair_typebox0.TString>>;
   }>>>;
   env: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TRecord<_$_sinclair_typebox0.TString, _$_sinclair_typebox0.TObject<{
-    value: _$_sinclair_typebox0.TString;
+    value: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
+    from_key: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
     purpose: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
     comment: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TString>;
     tags: _$_sinclair_typebox0.TOptional<_$_sinclair_typebox0.TRecord<_$_sinclair_typebox0.TString, _$_sinclair_typebox0.TString>>;
@@ -133,7 +137,8 @@ type SecretHealth = {
   readonly purpose: Option<string>;
   readonly created: Option<string>;
   readonly expires: Option<string>;
-  readonly issues: List<string>;
+  readonly issues: List<string>; /** If this entry is an alias (from_key), the reference it points at (e.g. "secret.X") */
+  readonly alias_of: Option<string>;
 };
 type AuditResult = {
   readonly status: HealthStatus;
@@ -145,7 +150,8 @@ type AuditResult = {
   readonly stale: number;
   readonly missing: number;
   readonly missing_metadata: number;
-  readonly orphaned: number;
+  readonly orphaned: number; /** Count of entries that are aliases (from_key). Included in `secrets` but reported separately for visibility. */
+  readonly aliases: number;
   readonly identity?: Identity;
 };
 type EnvDriftStatus = "default" | "overridden" | "missing";
@@ -154,7 +160,8 @@ type EnvDriftEntry = {
   readonly defaultValue: string;
   readonly currentValue: string | undefined;
   readonly status: EnvDriftStatus;
-  readonly purpose: string | undefined;
+  readonly purpose: string | undefined; /** If this entry is an alias (from_key), the reference it points at (e.g. "env.X") */
+  readonly alias_of: Option<string>;
 };
 type EnvAuditResult = {
   readonly entries: ReadonlyArray<EnvDriftEntry>;
@@ -238,6 +245,40 @@ type CatalogError = {
   readonly _tag: "MissingSecretsList";
   readonly message: string;
 };
+type AliasTable = {
+  /** key → { type: "secret"|"env", targetType, targetKey } for every alias entry */readonly entries: ReadonlyMap<string, {
+    readonly kind: "secret" | "env";
+    readonly targetKind: "secret" | "env";
+    readonly targetKey: string;
+  }>;
+};
+type AliasError = {
+  readonly _tag: "AliasInvalidSyntax";
+  readonly key: string;
+  readonly kind: "secret" | "env";
+  readonly value: string;
+} | {
+  readonly _tag: "AliasTargetMissing";
+  readonly key: string;
+  readonly target: string;
+} | {
+  readonly _tag: "AliasSelfReference";
+  readonly key: string;
+} | {
+  readonly _tag: "AliasChained";
+  readonly key: string;
+  readonly target: string;
+} | {
+  readonly _tag: "AliasCrossType";
+  readonly key: string;
+  readonly kind: "secret" | "env";
+  readonly targetKind: "secret" | "env";
+} | {
+  readonly _tag: "AliasValueConflict";
+  readonly key: string;
+  readonly kind: "secret" | "env";
+  readonly field: string;
+};
 type BootOptions = {
   readonly configPath?: string;
   readonly profile?: string;
@@ -256,7 +297,7 @@ type BootResult = {
   readonly configPath: string;
   readonly configSource: ConfigSource;
 };
-type BootError = ConfigError | FnoxError | CatalogError | {
+type BootError = ConfigError | FnoxError | CatalogError | AliasError | {
   readonly _tag: "AuditFailed";
   readonly audit: AuditResult;
   readonly message: string;
@@ -354,6 +395,33 @@ declare const resolveSecrets: (agentMeta: Record<string, SecretMeta>, catalogMet
 /** Resolve an agent config against its catalog (if any), producing a flat self-contained config */
 declare const resolveConfig: (agentConfig: EnvpktConfig, agentConfigDir: string) => Either<CatalogError, ResolveResult>;
 //#endregion
+//#region src/core/alias.d.ts
+/**
+ * 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)
+ */
+declare const validateAliases: (config: EnvpktConfig) => Either<AliasError, AliasTable>;
+/** Does this secret entry point at another entry? */
+declare const isSecretAlias: (meta: {
+  from_key?: string;
+} | undefined) => boolean;
+/** Does this env entry point at another entry? */
+declare const isEnvAlias: (meta: {
+  from_key?: string;
+} | undefined) => boolean;
+/** Format an alias error into a human-readable message */
+declare const formatAliasError: (error: AliasError) => string;
+//#endregion
 //#region src/core/format.d.ts
 type SecretDisplay = "encrypted" | "plaintext";
 type FormatPacketOptions = {
@@ -364,7 +432,7 @@ declare const maskValue: (value: string) => string;
 declare const formatPacket: (result: ResolveResult, options?: FormatPacketOptions) => string;
 //#endregion
 //#region src/core/audit.d.ts
-declare const computeAudit: (config: EnvpktConfig, fnoxKeys?: ReadonlySet<string>, today?: Date) => AuditResult;
+declare const computeAudit: (config: EnvpktConfig, fnoxKeys?: ReadonlySet<string>, today?: Date, aliasTable?: AliasTable) => AuditResult;
 declare const computeEnvAudit: (config: EnvpktConfig, env?: Readonly<Record<string, string | undefined>>) => EnvAuditResult;
 //#endregion
 //#region src/core/patterns.d.ts
@@ -554,4 +622,4 @@ type ToolDef = {
 declare const toolDefinitions: readonly ToolDef[];
 declare const callTool: (name: string, args: Record<string, unknown>) => CallToolResult;
 //#endregion
-export { type AgentIdentity, AgentIdentitySchema, type AuditResult, type BootError, type BootOptions, type BootResult, type CallbackConfig, CallbackConfigSchema, type CatalogError, type CheckResult, type ConfidenceLevel, type ConfigError, type ConfigSource, type ConsumerType, type CredentialPattern, type DriftEntry, type DriftStatus, type EnvAuditResult, type EnvDriftEntry, type EnvDriftStatus, type EnvMeta, EnvMetaSchema, EnvpktBootError, type EnvpktConfig, EnvpktConfigSchema, type FleetAgent, type FleetHealth, type FnoxConfig, type FnoxError, type FnoxSecret, type FormatPacketOptions, type HealthStatus, type Identity, type IdentityError, IdentitySchema, type KeygenError, type KeygenResult, type LifecycleConfig, LifecycleConfigSchema, type MatchResult, type ResolveOptions, type ResolveResult, type ResolvedPath, type ScanOptions, type ScanResult, type SealError, type SecretDisplay, type SecretHealth, type SecretMeta, SecretMetaSchema, type SecretStatus, type TomlEditError, type ToolsConfig, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createServer, deriveServiceFromName, detectFnox, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatPacket, generateKeypair, generateTomlFromScan, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateConfig };
+export { type AgentIdentity, AgentIdentitySchema, type AliasError, type AliasTable, type AuditResult, type BootError, type BootOptions, type BootResult, type CallbackConfig, CallbackConfigSchema, type CatalogError, type CheckResult, type ConfidenceLevel, type ConfigError, type ConfigSource, type ConsumerType, type CredentialPattern, type DriftEntry, type DriftStatus, type EnvAuditResult, type EnvDriftEntry, type EnvDriftStatus, type EnvMeta, EnvMetaSchema, EnvpktBootError, type EnvpktConfig, EnvpktConfigSchema, type FleetAgent, type FleetHealth, type FnoxConfig, type FnoxError, type FnoxSecret, type FormatPacketOptions, type HealthStatus, type Identity, type IdentityError, IdentitySchema, type KeygenError, type KeygenResult, type LifecycleConfig, LifecycleConfigSchema, type MatchResult, type ResolveOptions, type ResolveResult, type ResolvedPath, type ScanOptions, type ScanResult, type SealError, type SecretDisplay, type SecretHealth, type SecretMeta, SecretMetaSchema, type SecretStatus, type TomlEditError, type ToolsConfig, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createServer, deriveServiceFromName, detectFnox, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };

package/dist/index.js

@@ -60,6 +60,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" });
@@ -84,7 +85,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" }))
@@ -347,6 +349,155 @@ const resolveConfig = (agentConfig, agentConfigDir) => {
 	}));
 };
 //#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 });
+};
+/** Does this secret entry point at another entry? */
+const isSecretAlias = (meta) => meta?.from_key !== void 0;
+/** Does this env entry point at another entry? */
+const isEnvAlias = (meta) => meta?.from_key !== void 0;
+/** Format an alias error into a human-readable message */
+const formatAliasError = (error) => {
+	switch (error._tag) {
+		case "AliasInvalidSyntax": return `[${error.kind}.${error.key}] from_key = "${error.value}" — expected "secret.<KEY>" or "env.<KEY>"`;
+		case "AliasTargetMissing": return `[${error.key}] from_key target "${error.target}" not found in config`;
+		case "AliasSelfReference": return `[${error.key}] from_key cannot reference itself`;
+		case "AliasChained": return `[${error.key}] from_key target "${error.target}" is itself an alias; chained aliases are not supported`;
+		case "AliasCrossType": return `[${error.kind}.${error.key}] cannot alias a ${error.targetKind} entry; same-type aliasing only (secret→secret, env→env)`;
+		case "AliasValueConflict": return `[${error.kind}.${error.key}] cannot declare both from_key and ${error.field}; an alias has no value of its own`;
+	}
+};
+//#endregion
 //#region src/core/format.ts
 const maskValue = (value) => {
 	if (value.length > 8) return `${value.slice(0, 3)}${"•".repeat(5)}${value.slice(-4)}`;
@@ -393,11 +544,20 @@ const formatPacket = (result, options) => {
 	const metaEntries = Object.entries(secretConfig);
 	const secretHeader = `secrets: ${metaEntries.length}`;
 	const secretLines = metaEntries.map(([key, meta]) => {
-		const header = `  ${key} → ${meta.service ?? key}${meta.encrypted_value ? " [sealed]" : ""}${Option(options?.secrets?.[key]).fold(() => "", (secretValue) => ` = ${(options?.secretDisplay ?? "encrypted") === "plaintext" ? secretValue : maskValue(secretValue)}`)}`;
+		const header = `  ${key} → ${meta.service ?? key}${meta.encrypted_value ? " [sealed]" : ""}${meta.from_key ? ` [alias → ${meta.from_key}]` : ""}${Option(options?.secrets?.[key]).fold(() => "", (secretValue) => ` = ${(options?.secretDisplay ?? "encrypted") === "plaintext" ? secretValue : maskValue(secretValue)}`)}`;
 		const fields = formatSecretFields(meta, "    ");
 		return fields ? `${header}\n${fields}` : header;
 	});
 	sections.push([secretHeader, ...secretLines].join("\n"));
+	const envConfig = config.env ?? {};
+	const envEntriesArr = Object.entries(envConfig);
+	if (envEntriesArr.length > 0) {
+		const envHeader = `env: ${envEntriesArr.length}`;
+		const envLines = envEntriesArr.map(([key, meta]) => {
+			return `  ${key}${meta.from_key ? ` [alias → ${meta.from_key}]` : ""}${meta.value !== void 0 ? ` = ${meta.value}` : ""}${meta.purpose ? `\n    purpose: ${meta.purpose}` : ""}`;
+		});
+		sections.push([envHeader, ...envLines].join("\n"));
+	}
 	if (config.lifecycle) {
 		const lcLines = ["lifecycle:"];
 		if (config.lifecycle.stale_warning_days !== void 0) lcLines.push(`  stale_warning_days: ${config.lifecycle.stale_warning_days}`);
@@ -456,10 +616,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;
@@ -467,9 +645,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");
@@ -477,6 +677,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,
@@ -488,6 +689,7 @@ const computeAudit = (config, fnoxKeys, today) => {
 		missing,
 		missing_metadata,
 		orphaned,
+		aliases,
 		identity: config.identity
 	};
 };
@@ -495,13 +697,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 {
@@ -1226,14 +1432,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),
@@ -1242,12 +1461,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),
@@ -1693,7 +1919,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) => {
@@ -1701,26 +1927,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;
 			});
@@ -1729,7 +1958,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);
@@ -1738,7 +1967,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);
@@ -1756,9 +1985,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,
@@ -1771,7 +2025,7 @@ const bootSafe = (options) => {
 				configSource
 			};
 		});
-	});
+	}));
 };
 /** Programmatic boot — throws EnvpktBootError on failure (intentional throwing wrapper over bootSafe) */
 const boot = (options) => bootSafe(options).fold((err) => {
@@ -1803,6 +2057,12 @@ const formatBootError = (error) => {
 		case "AgeNotFound": return `age not found: ${error.message}`;
 		case "DecryptFailed": return `Decrypt failed: ${error.message}`;
 		case "IdentityNotFound": return `Identity file not found: ${error.path}`;
+		case "AliasInvalidSyntax":
+		case "AliasTargetMissing":
+		case "AliasSelfReference":
+		case "AliasChained":
+		case "AliasCrossType":
+		case "AliasValueConflict": return formatAliasError(error);
 		default: return `Boot error: ${JSON.stringify(error)}`;
 	}
 };
@@ -2238,6 +2498,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({
@@ -2249,6 +2510,7 @@ const handleGetPacketHealth = (args) => {
 		expired: audit.expired,
 		stale: audit.stale,
 		missing: audit.missing,
+		aliases: audit.aliases,
 		secrets: secretDetails
 	}, null, 2));
 };
@@ -2278,11 +2540,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));
 	});
 };
@@ -2356,4 +2637,4 @@ const startServer = async () => {
 	await server.connect(transport);
 };
 //#endregion
-export { AgentIdentitySchema, CallbackConfigSchema, ConsumerType, EnvMetaSchema, EnvpktBootError, EnvpktConfigSchema, IdentitySchema, LifecycleConfigSchema, SecretMetaSchema, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createServer, deriveServiceFromName, detectFnox, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatPacket, generateKeypair, generateTomlFromScan, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateConfig };
+export { AgentIdentitySchema, CallbackConfigSchema, ConsumerType, EnvMetaSchema, EnvpktBootError, EnvpktConfigSchema, IdentitySchema, LifecycleConfigSchema, SecretMetaSchema, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createServer, deriveServiceFromName, detectFnox, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envpkt",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "description": "Credential lifecycle and fleet management for AI agents",
   "keywords": [
     "credentials",
@@ -20,18 +20,36 @@
   "bin": {
     "envpkt": "dist/cli.js"
   },
+  "scripts": {
+    "validate": "ts-builds validate",
+    "format": "ts-builds format",
+    "format:check": "ts-builds format:check",
+    "lint": "ts-builds lint",
+    "lint:check": "ts-builds lint:check",
+    "typecheck": "ts-builds typecheck",
+    "test": "ts-builds test",
+    "test:watch": "ts-builds test:watch",
+    "test:coverage": "ts-builds test:coverage",
+    "build": "ts-builds build",
+    "build:schema": "tsx scripts/build-schema.ts",
+    "demo": "tsx scripts/generate-demo-html.ts",
+    "dev": "ts-builds dev",
+    "docs:dev": "pnpm --dir site dev",
+    "docs:build": "pnpm --dir site build",
+    "prepublishOnly": "pnpm validate"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@sinclair/typebox": "^0.34.49",
     "commander": "^14.0.3",
-    "functype": "^0.56.0",
+    "functype": "^0.58.1",
     "functype-os": "^0.4.2",
     "smol-toml": "^1.6.1"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",
-    "ts-builds": "^2.6.3",
-    "tsdown": "^0.21.7",
+    "ts-builds": "^2.7.0",
+    "tsdown": "^0.21.9",
     "tsx": "^4.21.0"
   },
   "type": "module",
@@ -52,21 +70,5 @@
     "schemas"
   ],
   "prettier": "ts-builds/prettier",
-  "scripts": {
-    "validate": "ts-builds validate",
-    "format": "ts-builds format",
-    "format:check": "ts-builds format:check",
-    "lint": "ts-builds lint",
-    "lint:check": "ts-builds lint:check",
-    "typecheck": "ts-builds typecheck",
-    "test": "ts-builds test",
-    "test:watch": "ts-builds test:watch",
-    "test:coverage": "ts-builds test:coverage",
-    "build": "ts-builds build",
-    "build:schema": "tsx scripts/build-schema.ts",
-    "demo": "tsx scripts/generate-demo-html.ts",
-    "dev": "ts-builds dev",
-    "docs:dev": "pnpm --dir site dev",
-    "docs:build": "pnpm --dir site build"
-  }
-}
+  "packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319"
+}

package/schemas/envpkt.schema.json

@@ -151,6 +151,10 @@
               "description": "Age-encrypted secret value (armored ciphertext, safe to commit)",
               "type": "string"
             },
+            "from_key": {
+              "description": "Reference another entry (format: 'secret.<KEY>') whose resolved value this alias reuses. Mutually exclusive with encrypted_value.",
+              "type": "string"
+            },
             "required": {
               "description": "Whether this secret is required for operation",
               "type": "boolean"
@@ -175,12 +179,13 @@
         "^(.*)$": {
           "description": "Metadata for a plaintext environment default (non-secret)",
           "type": "object",
-          "required": [
-            "value"
-          ],
           "properties": {
             "value": {
-              "description": "Default value for this environment variable",
+              "description": "Default value for this environment variable. Optional when from_key is set; required otherwise.",
+              "type": "string"
+            },
+            "from_key": {
+              "description": "Reference another entry (format: 'env.<KEY>') whose resolved value this alias reuses. Mutually exclusive with value.",
               "type": "string"
             },
             "purpose": {