envpkt 0.4.2 → 0.5.0

package/dist/cli.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { Cond, Left, List, Option, Right, Try } from "functype";
-import { homedir } from "node:os";
 import { TypeCompiler } from "@sinclair/typebox/compiler";
+import { Env, Fs, Path } from "functype-os";
 import { TomlDate, parse, stringify } from "smol-toml";
 import { FormatRegistry, Type } from "@sinclair/typebox";
 import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -219,11 +220,11 @@ const normalizeDates = (obj) => {
 	if (obj !== null && typeof obj === "object") return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, normalizeDates(v)]));
 	return obj;
 };
-/** Expand ~ and $ENV_VAR / ${ENV_VAR} in a path string */
+/** Expand ~ and $ENV_VAR / ${ENV_VAR} in a path string (silent — unresolved vars become "") */
 const expandPath = (p) => {
-	return (p.startsWith("~/") || p === "~" ? join(homedir(), p.slice(1)) : p).replace(/\$\{(\w+)\}|\$(\w+)/g, (_, braced, bare) => {
+	return Path.expandTilde(p).replace(/\$\{(\w+)\}|\$(\w+)/g, (_, braced, bare) => {
 		const name = braced ?? bare ?? "";
-		return process.env[name] ?? "";
+		return Env.getOrDefault(name, "");
 	});
 };
 /**
@@ -232,16 +233,16 @@ const expandPath = (p) => {
 * Non-glob paths return a single-element array if they exist.
 */
 const expandGlobPath = (expanded) => {
-	if (!expanded.includes("*")) return existsSync(expanded) ? [expanded] : [];
+	if (!expanded.includes("*")) return Fs.existsSync(expanded) ? [expanded] : [];
 	const segments = expanded.split("/");
 	const globIdx = segments.findIndex((s) => s.includes("*"));
 	if (globIdx < 0) return [];
 	const parentDir = segments.slice(0, globIdx).join("/");
 	const globSegment = segments[globIdx];
 	const suffix = segments.slice(globIdx + 1).join("/");
-	if (!existsSync(parentDir)) return [];
+	if (!Fs.existsSync(parentDir)) return [];
 	const prefix = globSegment.replace(/\*.*$/, "");
-	return readdirSync(parentDir).filter((entry) => entry.startsWith(prefix)).map((entry) => join(parentDir, entry, suffix)).filter((p) => existsSync(p));
+	return Fs.readdirSync(parentDir).fold(() => [], (entries) => entries.filter((entry) => entry.startsWith(prefix)).map((entry) => join(parentDir, entry, suffix)).filter((p) => Fs.existsSync(p)).toArray());
 };
 /** Ordered candidate paths for config discovery beyond CWD */
 const CONFIG_SEARCH_PATHS = [
@@ -267,11 +268,11 @@ const CONFIG_SEARCH_PATHS = [
 /** Discover config by checking CWD, then ENVPKT_SEARCH_PATH, then built-in candidate paths */
 const discoverConfig = (cwd) => {
 	const cwdCandidate = join(cwd ?? process.cwd(), CONFIG_FILENAME$2);
-	if (existsSync(cwdCandidate)) return Option({
+	if (Fs.existsSync(cwdCandidate)) return Option({
 		path: cwdCandidate,
 		source: "cwd"
 	});
-	const customPaths = process.env.ENVPKT_SEARCH_PATH?.split(":").filter(Boolean) ?? [];
+	const customPaths = Env.get("ENVPKT_SEARCH_PATH").fold(() => [], (v) => v.split(":").filter(Boolean));
 	for (const template of [...customPaths, ...CONFIG_SEARCH_PATHS]) {
 		const expanded = expandPath(template);
 		if (!expanded || expanded.startsWith("/.envpkt")) continue;
@@ -285,14 +286,14 @@ const discoverConfig = (cwd) => {
 };
 /** Read a config file, returning Either<ConfigError, string> */
 const readConfigFile = (path) => {
-	if (!existsSync(path)) return Left({
+	if (!Fs.existsSync(path)) return Left({
 		_tag: "FileNotFound",
 		path
 	});
-	return Try(() => readFileSync(path, "utf-8")).fold((err) => Left({
+	return Fs.readFileSync(path, "utf-8").mapLeft((err) => ({
 		_tag: "ReadError",
-		message: String(err)
-	}), (content) => Right(content));
+		message: err.message
+	}));
 };
 /** Ensure required fields have defaults for valid configs (e.g. agent configs with catalog may omit secret) */
 const applyDefaults = (data) => {
@@ -332,19 +333,19 @@ const resolveConfigPath = (flagPath, envVar, cwd) => {
 			path: resolved,
 			source: "flag"
 		};
-		return existsSync(resolved) ? Right(result) : Left({
+		return Fs.existsSync(resolved) ? Right(result) : Left({
 			_tag: "FileNotFound",
 			path: resolved
 		});
 	}
-	const envPath = envVar ?? process.env[ENV_VAR_CONFIG];
+	const envPath = envVar ?? Env.get(ENV_VAR_CONFIG).fold(() => void 0, (v) => v);
 	if (envPath) {
 		const resolved = resolve(envPath);
 		const result = {
 			path: resolved,
 			source: "env"
 		};
-		return existsSync(resolved) ? Right(result) : Left({
+		return Fs.existsSync(resolved) ? Right(result) : Left({
 			_tag: "FileNotFound",
 			path: resolved
 		});
@@ -542,6 +543,10 @@ const formatError = (error) => {
 		case "CatalogLoadError": return `${RED}Error:${RESET} Catalog load error: ${error.message}`;
 		case "SecretNotInCatalog": return `${RED}Error:${RESET} Secret "${error.key}" not found in catalog: ${error.path}`;
 		case "MissingSecretsList": return `${RED}Error:${RESET} ${error.message}`;
+		case "KeygenFailed": return `${RED}Error:${RESET} Keygen failed: ${error.message}`;
+		case "KeyExists": return `${YELLOW}Warning:${RESET} Identity file already exists: ${error.path}\n${DIM}Use --force to overwrite.${RESET}`;
+		case "WriteError": return `${RED}Error:${RESET} Write failed: ${error.message}`;
+		case "ConfigUpdateError": return `${RED}Error:${RESET} Config update failed: ${error.message}`;
 		default: return `${RED}Error:${RESET} ${error.message ?? tag}`;
 	}
 };
@@ -1812,6 +1817,12 @@ created = "${todayIso$1()}"
 
 //#endregion
 //#region src/cli/commands/env.ts
+const printPostWriteGuidance = () => {
+	console.log(`\n${DIM}Note: Secret values are NOT stored — only metadata.${RESET}`);
+	console.log(`${BOLD}Next steps:${RESET}`);
+	console.log(`  ${DIM}1.${RESET} envpkt keygen          ${DIM}# generate age key (if no recipient configured)${RESET}`);
+	console.log(`  ${DIM}2.${RESET} envpkt seal            ${DIM}# encrypt secret values into envpkt.toml${RESET}`);
+};
 const runEnvScan = (options) => {
 	const scan = envScan(process.env, { includeUnknown: options.includeUnknown });
 	if (scan.discovered.size === 0) {
@@ -1841,6 +1852,7 @@ const runEnvScan = (options) => {
 				process.exit(1);
 			}, () => {
 				console.log(`\n${GREEN}✓${RESET} Appended ${BOLD}${newEntries.length}${RESET} new entry/entries to ${CYAN}${configPath}${RESET}`);
+				printPostWriteGuidance();
 			});
 		} else {
 			const header = `#:schema https://raw.githubusercontent.com/jordanburke/envpkt/main/schemas/envpkt.schema.json\n\nversion = 1\n\n[lifecycle]\nstale_warning_days = 90\n\n`;
@@ -1849,6 +1861,7 @@ const runEnvScan = (options) => {
 				process.exit(1);
 			}, () => {
 				console.log(`\n${GREEN}✓${RESET} Created ${CYAN}${configPath}${RESET} with ${BOLD}${scan.discovered.size}${RESET} credential(s)`);
+				printPostWriteGuidance();
 			});
 		}
 	}
@@ -2271,6 +2284,143 @@ const runInspect = (options) => {
 	});
 };
 
+//#endregion
+//#region src/core/keygen.ts
+/** Resolve the age identity file path: ENVPKT_AGE_KEY_FILE env var > ~/.envpkt/age-key.txt */
+const resolveKeyPath = () => process.env["ENVPKT_AGE_KEY_FILE"] ?? join(homedir(), ".envpkt", "age-key.txt");
+/** Generate an age keypair and write to disk */
+const generateKeypair = (options) => {
+	if (!ageAvailable()) return Left({
+		_tag: "AgeNotFound",
+		message: "age-keygen CLI not found on PATH. Install age: https://github.com/FiloSottile/age"
+	});
+	const outputPath = options?.outputPath ?? resolveKeyPath();
+	if (existsSync(outputPath) && !options?.force) return Left({
+		_tag: "KeyExists",
+		path: outputPath
+	});
+	return Try(() => execFileSync("age-keygen", [], {
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf-8"
+	})).fold((err) => Left({
+		_tag: "KeygenFailed",
+		message: `age-keygen failed: ${err}`
+	}), (output) => {
+		const recipientLine = output.split("\n").find((l) => l.startsWith("# public key:"));
+		if (!recipientLine) return Left({
+			_tag: "KeygenFailed",
+			message: "Could not parse public key from age-keygen output"
+		});
+		const recipient = recipientLine.replace("# public key: ", "").trim();
+		const dir = dirname(outputPath);
+		const mkdirFailed = Try(() => {
+			if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+		}).fold((err) => ({
+			_tag: "WriteError",
+			message: `Failed to create directory ${dir}: ${err}`
+		}), () => void 0);
+		if (mkdirFailed) return Left(mkdirFailed);
+		return Try(() => {
+			writeFileSync(outputPath, output, { mode: 384 });
+			chmodSync(outputPath, 384);
+		}).fold((err) => Left({
+			_tag: "WriteError",
+			message: `Failed to write identity file: ${err}`
+		}), () => Right({
+			recipient,
+			identityPath: outputPath,
+			configUpdated: false
+		}));
+	});
+};
+/** Update agent.recipient in an envpkt.toml file, preserving structure */
+const updateConfigRecipient = (configPath, recipient) => {
+	return Try(() => readFileSync(configPath, "utf-8")).fold((err) => Left({
+		_tag: "ConfigUpdateError",
+		message: `Failed to read config: ${err}`
+	}), (raw) => {
+		const lines = raw.split("\n");
+		const output = [];
+		let inAgentSection = false;
+		let recipientUpdated = false;
+		let hasAgentSection = false;
+		for (const line of lines) {
+			if (/^\[agent\]\s*$/.test(line)) {
+				inAgentSection = true;
+				hasAgentSection = true;
+				output.push(line);
+				continue;
+			}
+			if (/^\[/.test(line) && !/^\[agent\]\s*$/.test(line)) {
+				if (inAgentSection && !recipientUpdated) {
+					output.push(`recipient = "${recipient}"`);
+					recipientUpdated = true;
+				}
+				inAgentSection = false;
+				output.push(line);
+				continue;
+			}
+			if (inAgentSection && /^recipient\s*=/.test(line)) {
+				output.push(`recipient = "${recipient}"`);
+				recipientUpdated = true;
+				continue;
+			}
+			output.push(line);
+		}
+		if (inAgentSection && !recipientUpdated) output.push(`recipient = "${recipient}"`);
+		if (!hasAgentSection) {
+			output.push("");
+			output.push("[agent]");
+			output.push(`recipient = "${recipient}"`);
+		}
+		return Try(() => writeFileSync(configPath, output.join("\n"))).fold((err) => Left({
+			_tag: "ConfigUpdateError",
+			message: `Failed to write config: ${err}`
+		}), () => Right(true));
+	});
+};
+
+//#endregion
+//#region src/cli/commands/keygen.ts
+const runKeygen = (options) => {
+	const outputPath = options.output ?? resolveKeyPath();
+	generateKeypair({
+		force: options.force,
+		outputPath
+	}).fold((err) => {
+		if (err._tag === "KeyExists") {
+			console.error(`${YELLOW}Warning:${RESET} Identity file already exists: ${CYAN}${err.path}${RESET}`);
+			console.error(`${DIM}Use --force to overwrite.${RESET}`);
+			process.exit(1);
+		}
+		console.error(formatError(err));
+		process.exit(2);
+	}, ({ recipient, identityPath }) => {
+		console.log(`${GREEN}Generated${RESET} age identity: ${CYAN}${identityPath}${RESET}`);
+		console.log(`${BOLD}Recipient:${RESET} ${recipient}`);
+		console.log("");
+		const configPath = resolve(options.config ?? join(process.cwd(), "envpkt.toml"));
+		if (existsSync(configPath)) updateConfigRecipient(configPath, recipient).fold((err) => {
+			console.error(`${YELLOW}Warning:${RESET} Could not update config: ${"message" in err ? err.message : err._tag}`);
+			console.log(`${DIM}Manually add to your envpkt.toml:${RESET}`);
+			console.log(`  [agent]`);
+			console.log(`  recipient = "${recipient}"`);
+		}, () => {
+			console.log(`${GREEN}Updated${RESET} ${CYAN}${configPath}${RESET} with agent.recipient`);
+		});
+		else {
+			console.log(`${BOLD}Next steps:${RESET}`);
+			console.log(`  ${DIM}1.${RESET} envpkt init          ${DIM}# create envpkt.toml${RESET}`);
+			console.log(`  ${DIM}2.${RESET} envpkt env scan --write  ${DIM}# discover credentials${RESET}`);
+			console.log(`  ${DIM}3.${RESET} envpkt seal           ${DIM}# encrypt secret values${RESET}`);
+		}
+	});
+};
+
 //#endregion
 //#region src/mcp/resources.ts
 const loadConfigSafe = () => {
@@ -2747,7 +2897,11 @@ const runSeal = async (options) => {
 	}, (c) => c);
 	if (!config.agent?.recipient) {
 		console.error(`${RED}Error:${RESET} agent.recipient is required for sealing (age public key)`);
-		console.error(`${DIM}Add [agent] section with recipient = "age1..." to your envpkt.toml${RESET}`);
+		console.error("");
+		console.error(`${BOLD}Quick fix:${RESET} run ${CYAN}envpkt keygen${RESET} to generate a key and auto-configure recipient`);
+		console.error(`${DIM}Or manually add to your envpkt.toml:${RESET}`);
+		console.error(`${DIM}  [agent]${RESET}`);
+		console.error(`${DIM}  recipient = "age1..."${RESET}`);
 		process.exit(2);
 	}
 	const { recipient } = config.agent;
@@ -2844,7 +2998,7 @@ const runShellHook = (shell) => {
 //#endregion
 //#region src/cli/index.ts
 const program = new Command();
-program.name("envpkt").description("Credential lifecycle and fleet management for AI agents\n\n  Developer workflow:  env scan → catalog → cloud-synced folder → eval $(envpkt env export)\n  Agent / CI workflow: catalog → audit --strict → seal → exec --strict → fleet").version((() => {
+program.name("envpkt").description("Credential lifecycle and fleet management for AI agents\n\n  Developer workflow:  env scan → keygen → seal → eval $(envpkt env export)\n  Agent / CI workflow: catalog → audit --strict → seal → exec --strict → fleet").version((() => {
 	const findPkgJson = (dir) => {
 		if (existsSync(join(dir, "package.json"))) return join(dir, "package.json");
 		const parent = dirname(dir);
@@ -2856,6 +3010,9 @@ program.name("envpkt").description("Credential lifecycle and fleet management fo
 program.command("init").description("Initialize a new envpkt.toml in the current directory").option("--from-fnox [path]", "Scaffold from fnox.toml (optionally specify path)").option("--catalog <path>", "Path to shared secret catalog").option("--agent", "Include [agent] section").option("--name <name>", "Agent name (requires --agent)").option("--capabilities <caps>", "Comma-separated capabilities (requires --agent)").option("--expires <date>", "Agent credential expiration YYYY-MM-DD (requires --agent)").option("--force", "Overwrite existing envpkt.toml").action((options) => {
 	runInit(process.cwd(), options);
 });
+program.command("keygen").description("Generate an age keypair for sealing secrets — run this before `seal` if you don't have a key yet").option("-c, --config <path>", "Path to envpkt.toml (updates agent.recipient if found)").option("--force", "Overwrite existing identity file").option("-o, --output <path>", "Output path for identity file (default: ~/.envpkt/age-key.txt)").action((options) => {
+	runKeygen(options);
+});
 program.command("audit").description("Audit credential health from envpkt.toml (use --strict in CI pipelines to gate deploys)").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json | minimal", "table").option("--expiring <days>", "Show secrets expiring within N days", parseInt).option("--status <status>", "Filter by status: healthy | expiring_soon | expired | stale | missing").option("--strict", "Exit non-zero on any non-healthy secret").option("--all", "Show both secrets and env defaults").option("--env-only", "Show only env defaults (drift detection)").option("--sealed", "Show only secrets with encrypted_value").option("--external", "Show only secrets without encrypted_value").action((options) => {
 	runAudit(options);
 });

package/dist/index.d.ts

@@ -272,6 +272,27 @@ type SealError = {
   readonly _tag: "NoRecipient";
   readonly message: string;
 };
+type KeygenError = {
+  readonly _tag: "AgeNotFound";
+  readonly message: string;
+} | {
+  readonly _tag: "KeygenFailed";
+  readonly message: string;
+} | {
+  readonly _tag: "KeyExists";
+  readonly path: string;
+} | {
+  readonly _tag: "WriteError";
+  readonly message: string;
+} | {
+  readonly _tag: "ConfigUpdateError";
+  readonly message: string;
+};
+type KeygenResult = {
+  readonly recipient: string;
+  readonly identityPath: string;
+  readonly configUpdated: boolean;
+};
 //#endregion
 //#region src/core/config.d.ts
 /** Find envpkt.toml in the given directory */
@@ -406,6 +427,19 @@ declare const sealSecrets: (meta: Readonly<Record<string, SecretMeta>>, values:
 /** Unseal secrets: decrypt encrypted_value for each meta entry that has one */
 declare const unsealSecrets: (meta: Readonly<Record<string, SecretMeta>>, identityPath: string) => Either<SealError, Record<string, string>>;
 //#endregion
+//#region src/core/keygen.d.ts
+/** Resolve the age identity file path: ENVPKT_AGE_KEY_FILE env var > ~/.envpkt/age-key.txt */
+declare const resolveKeyPath: () => string;
+/** Resolve an inline age key from ENVPKT_AGE_KEY env var (for CI) */
+declare const resolveInlineKey: () => Option<string>;
+/** Generate an age keypair and write to disk */
+declare const generateKeypair: (options?: {
+  readonly force?: boolean;
+  readonly outputPath?: string;
+}) => Either<KeygenError, KeygenResult>;
+/** Update agent.recipient in an envpkt.toml file, preserving structure */
+declare const updateConfigRecipient: (configPath: string, recipient: string) => Either<KeygenError, true>;
+//#endregion
 //#region src/core/resolve-values.d.ts
 /** Resolve plaintext values for the given keys via cascade: fnox → env → interactive prompt */
 declare const resolveValues: (keys: ReadonlyArray<string>, profile?: string, agentKey?: string) => Promise<Record<string, string>>;
@@ -467,4 +501,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 IdentityError, 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 ToolsConfig, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createServer, deriveServiceFromName, detectFnox, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatPacket, generateTomlFromScan, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, readConfigFile, readFnoxConfig, readResource, resolveConfig, resolveConfigPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, validateConfig };
+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 IdentityError, 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 ToolsConfig, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, 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, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigRecipient, validateConfig };

package/dist/index.js

@@ -1,11 +1,12 @@
 import { FormatRegistry, Type } from "@sinclair/typebox";
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { TypeCompiler } from "@sinclair/typebox/compiler";
-import { Cond, Left, List, Option, Right, Try } from "functype";
+import { Cond, Left, List, None, Option, Right, Some, Try } from "functype";
+import { Env, Fs, Path } from "functype-os";
 import { TomlDate, parse } from "smol-toml";
 import { execFileSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { createInterface } from "node:readline";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -117,17 +118,17 @@ const normalizeDates = (obj) => {
 	if (obj !== null && typeof obj === "object") return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, normalizeDates(v)]));
 	return obj;
 };
-/** Expand ~ and $ENV_VAR / ${ENV_VAR} in a path string */
+/** Expand ~ and $ENV_VAR / ${ENV_VAR} in a path string (silent — unresolved vars become "") */
 const expandPath = (p) => {
-	return (p.startsWith("~/") || p === "~" ? join(homedir(), p.slice(1)) : p).replace(/\$\{(\w+)\}|\$(\w+)/g, (_, braced, bare) => {
+	return Path.expandTilde(p).replace(/\$\{(\w+)\}|\$(\w+)/g, (_, braced, bare) => {
 		const name = braced ?? bare ?? "";
-		return process.env[name] ?? "";
+		return Env.getOrDefault(name, "");
 	});
 };
 /** Find envpkt.toml in the given directory */
 const findConfigPath = (dir) => {
 	const candidate = join(dir, CONFIG_FILENAME$1);
-	return existsSync(candidate) ? Option(candidate) : Option(void 0);
+	return Fs.existsSync(candidate) ? Option(candidate) : Option(void 0);
 };
 /**
 * Expand a path template that may contain a single `*` glob segment.
@@ -135,16 +136,16 @@ const findConfigPath = (dir) => {
 * Non-glob paths return a single-element array if they exist.
 */
 const expandGlobPath = (expanded) => {
-	if (!expanded.includes("*")) return existsSync(expanded) ? [expanded] : [];
+	if (!expanded.includes("*")) return Fs.existsSync(expanded) ? [expanded] : [];
 	const segments = expanded.split("/");
 	const globIdx = segments.findIndex((s) => s.includes("*"));
 	if (globIdx < 0) return [];
 	const parentDir = segments.slice(0, globIdx).join("/");
 	const globSegment = segments[globIdx];
 	const suffix = segments.slice(globIdx + 1).join("/");
-	if (!existsSync(parentDir)) return [];
+	if (!Fs.existsSync(parentDir)) return [];
 	const prefix = globSegment.replace(/\*.*$/, "");
-	return readdirSync(parentDir).filter((entry) => entry.startsWith(prefix)).map((entry) => join(parentDir, entry, suffix)).filter((p) => existsSync(p));
+	return Fs.readdirSync(parentDir).fold(() => [], (entries) => entries.filter((entry) => entry.startsWith(prefix)).map((entry) => join(parentDir, entry, suffix)).filter((p) => Fs.existsSync(p)).toArray());
 };
 /** Ordered candidate paths for config discovery beyond CWD */
 const CONFIG_SEARCH_PATHS = [
@@ -170,11 +171,11 @@ const CONFIG_SEARCH_PATHS = [
 /** Discover config by checking CWD, then ENVPKT_SEARCH_PATH, then built-in candidate paths */
 const discoverConfig = (cwd) => {
 	const cwdCandidate = join(cwd ?? process.cwd(), CONFIG_FILENAME$1);
-	if (existsSync(cwdCandidate)) return Option({
+	if (Fs.existsSync(cwdCandidate)) return Option({
 		path: cwdCandidate,
 		source: "cwd"
 	});
-	const customPaths = process.env.ENVPKT_SEARCH_PATH?.split(":").filter(Boolean) ?? [];
+	const customPaths = Env.get("ENVPKT_SEARCH_PATH").fold(() => [], (v) => v.split(":").filter(Boolean));
 	for (const template of [...customPaths, ...CONFIG_SEARCH_PATHS]) {
 		const expanded = expandPath(template);
 		if (!expanded || expanded.startsWith("/.envpkt")) continue;
@@ -188,14 +189,14 @@ const discoverConfig = (cwd) => {
 };
 /** Read a config file, returning Either<ConfigError, string> */
 const readConfigFile = (path) => {
-	if (!existsSync(path)) return Left({
+	if (!Fs.existsSync(path)) return Left({
 		_tag: "FileNotFound",
 		path
 	});
-	return Try(() => readFileSync(path, "utf-8")).fold((err) => Left({
+	return Fs.readFileSync(path, "utf-8").mapLeft((err) => ({
 		_tag: "ReadError",
-		message: String(err)
-	}), (content) => Right(content));
+		message: err.message
+	}));
 };
 /** Ensure required fields have defaults for valid configs (e.g. agent configs with catalog may omit secret) */
 const applyDefaults = (data) => {
@@ -244,19 +245,19 @@ const resolveConfigPath = (flagPath, envVar, cwd) => {
 			path: resolved,
 			source: "flag"
 		};
-		return existsSync(resolved) ? Right(result) : Left({
+		return Fs.existsSync(resolved) ? Right(result) : Left({
 			_tag: "FileNotFound",
 			path: resolved
 		});
 	}
-	const envPath = envVar ?? process.env[ENV_VAR_CONFIG];
+	const envPath = envVar ?? Env.get(ENV_VAR_CONFIG).fold(() => void 0, (v) => v);
 	if (envPath) {
 		const resolved = resolve(envPath);
 		const result = {
 			path: resolved,
 			source: "env"
 		};
-		return existsSync(resolved) ? Right(result) : Left({
+		return Fs.existsSync(resolved) ? Right(result) : Left({
 			_tag: "FileNotFound",
 			path: resolved
 		});
@@ -1666,6 +1667,111 @@ const formatBootError = (error) => {
 	}
 };
 
+//#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");
+/** Resolve an inline age key from ENVPKT_AGE_KEY env var (for CI) */
+const resolveInlineKey = () => {
+	const key = process.env["ENVPKT_AGE_KEY"];
+	return key ? Some(key) : None();
+};
+/** Generate an age keypair and write to disk */
+const generateKeypair = (options) => {
+	if (!ageAvailable()) return Left({
+		_tag: "AgeNotFound",
+		message: "age-keygen CLI not found on PATH. Install age: https://github.com/FiloSottile/age"
+	});
+	const outputPath = options?.outputPath ?? resolveKeyPath();
+	if (existsSync(outputPath) && !options?.force) return Left({
+		_tag: "KeyExists",
+		path: outputPath
+	});
+	return Try(() => execFileSync("age-keygen", [], {
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf-8"
+	})).fold((err) => Left({
+		_tag: "KeygenFailed",
+		message: `age-keygen failed: ${err}`
+	}), (output) => {
+		const recipientLine = output.split("\n").find((l) => l.startsWith("# public key:"));
+		if (!recipientLine) return Left({
+			_tag: "KeygenFailed",
+			message: "Could not parse public key from age-keygen output"
+		});
+		const recipient = recipientLine.replace("# public key: ", "").trim();
+		const dir = dirname(outputPath);
+		const mkdirFailed = Try(() => {
+			if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+		}).fold((err) => ({
+			_tag: "WriteError",
+			message: `Failed to create directory ${dir}: ${err}`
+		}), () => void 0);
+		if (mkdirFailed) return Left(mkdirFailed);
+		return Try(() => {
+			writeFileSync(outputPath, output, { mode: 384 });
+			chmodSync(outputPath, 384);
+		}).fold((err) => Left({
+			_tag: "WriteError",
+			message: `Failed to write identity file: ${err}`
+		}), () => Right({
+			recipient,
+			identityPath: outputPath,
+			configUpdated: false
+		}));
+	});
+};
+/** Update agent.recipient in an envpkt.toml file, preserving structure */
+const updateConfigRecipient = (configPath, recipient) => {
+	return Try(() => readFileSync(configPath, "utf-8")).fold((err) => Left({
+		_tag: "ConfigUpdateError",
+		message: `Failed to read config: ${err}`
+	}), (raw) => {
+		const lines = raw.split("\n");
+		const output = [];
+		let inAgentSection = false;
+		let recipientUpdated = false;
+		let hasAgentSection = false;
+		for (const line of lines) {
+			if (/^\[agent\]\s*$/.test(line)) {
+				inAgentSection = true;
+				hasAgentSection = true;
+				output.push(line);
+				continue;
+			}
+			if (/^\[/.test(line) && !/^\[agent\]\s*$/.test(line)) {
+				if (inAgentSection && !recipientUpdated) {
+					output.push(`recipient = "${recipient}"`);
+					recipientUpdated = true;
+				}
+				inAgentSection = false;
+				output.push(line);
+				continue;
+			}
+			if (inAgentSection && /^recipient\s*=/.test(line)) {
+				output.push(`recipient = "${recipient}"`);
+				recipientUpdated = true;
+				continue;
+			}
+			output.push(line);
+		}
+		if (inAgentSection && !recipientUpdated) output.push(`recipient = "${recipient}"`);
+		if (!hasAgentSection) {
+			output.push("");
+			output.push("[agent]");
+			output.push(`recipient = "${recipient}"`);
+		}
+		return Try(() => writeFileSync(configPath, output.join("\n"))).fold((err) => Left({
+			_tag: "ConfigUpdateError",
+			message: `Failed to write config: ${err}`
+		}), () => Right(true));
+	});
+};
+
 //#endregion
 //#region src/core/resolve-values.ts
 /** Resolve plaintext values for the given keys via cascade: fnox → env → interactive prompt */
@@ -2088,4 +2194,4 @@ const startServer = async () => {
 };
 
 //#endregion
-export { AgentIdentitySchema, CallbackConfigSchema, ConsumerType, EnvMetaSchema, EnvpktBootError, EnvpktConfigSchema, LifecycleConfigSchema, SecretMetaSchema, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createServer, deriveServiceFromName, detectFnox, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatPacket, generateTomlFromScan, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, readConfigFile, readFnoxConfig, readResource, resolveConfig, resolveConfigPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, validateConfig };
+export { AgentIdentitySchema, CallbackConfigSchema, ConsumerType, EnvMetaSchema, EnvpktBootError, EnvpktConfigSchema, LifecycleConfigSchema, SecretMetaSchema, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, 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, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigRecipient, validateConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envpkt",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Credential lifecycle and fleet management for AI agents",
   "keywords": [
     "credentials",
@@ -42,7 +42,8 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@sinclair/typebox": "^0.34.48",
     "commander": "^14.0.3",
-    "functype": "^0.48.0",
+    "functype": "^0.49.0",
+    "functype-os": "^0.2.0",
     "smol-toml": "^1.6.0"
   },
   "devDependencies": {