envpkt 0.5.0 → 0.6.0

package/README.md

@@ -97,7 +97,7 @@ And a more complete one:
 
 version = 1
 
-[agent]
+[identity]
 name = "billing-service"
 consumer = "agent"
 description = "Payment processing agent"
@@ -158,13 +158,13 @@ age-keygen -o identity.txt
 Add the public key to your config and the identity file to `.gitignore`:
 
 ```toml
-[agent]
+[identity]
 name = "my-agent"
 recipient = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"
-identity = "identity.txt"
+key_file = "identity.txt"
 ```
 
-The `identity` 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.
+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`.
 
 ### Seal
 
@@ -233,7 +233,7 @@ expires = "2026-11-01"
 version = 1
 catalog = "../../infra/envpkt.toml"
 
-[agent]
+[identity]
 name = "data-pipeline"
 consumer = "agent"
 secrets = ["DATABASE_URL", "REDIS_URL"]
@@ -255,7 +255,7 @@ This produces a self-contained config with catalog metadata merged in and agent
 
 - Each field in the agent's `[secret.KEY]` override **replaces** the catalog field (shallow merge)
 - Omitted fields keep the catalog value
-- `agent.secrets` is the source of truth for which keys the agent needs
+- `identity.secrets` is the source of truth for which keys the agent needs
 
 ## How envpkt Compares
 
@@ -267,7 +267,7 @@ The agentic credential space is splitting into approaches. Here's where envpkt f
 | **What agents see**         | Structured metadata (capabilities, constraints, expiration) | Raw secret values           | Nothing (proxy handles it) | Nothing (autofill handles it) | Raw secret values    |
 | **MCP server**              | Yes                                                         | Yes                         | No                         | No                            | Yes                  |
 | **Encryption at rest**      | age sealed packets                                          | Git-crypt                   | N/A (proxy model)          | Vault encryption              | Vault encryption     |
-| **Per-agent scoping**       | Yes (agent.secrets, capabilities)                           | Yes (policies)              | Yes (proxy rules)          | No                            | Yes (policies)       |
+| **Per-agent scoping**       | Yes (identity.secrets, capabilities)                        | Yes (policies)              | Yes (proxy rules)          | No                            | Yes (policies)       |
 | **Fleet health monitoring** | Yes (fleet scan, aggregated audit)                          | No                          | No                         | No                            | No                   |
 | **Credential metadata**     | Rich (purpose, capabilities, rotation, lifecycle)           | Minimal                     | Minimal                    | Minimal                       | Moderate             |
 | **Adoption path**           | Scan existing env vars, add metadata incrementally          | New secret storage workflow | Proxy configuration        | Browser extension             | API integration      |
@@ -285,9 +285,9 @@ Generate an `envpkt.toml` template in the current directory.
 ```bash
 envpkt init                                    # Basic template
 envpkt init --from-fnox                        # Scaffold from fnox.toml
-envpkt init --agent --name "my-agent"          # Include agent identity
+envpkt init --identity --name "my-agent"        # Include identity section
 envpkt init --catalog "../infra/envpkt.toml"   # Reference a shared catalog
-envpkt init --agent --name "bot" --capabilities "read,write" --expires "2027-01-01"
+envpkt init --identity --name "bot" --capabilities "read,write" --expires "2027-01-01"
 ```
 
 ### `envpkt audit`
@@ -354,13 +354,13 @@ envpkt seal -c path/to/envpkt.toml     # Specify config path
 envpkt seal --profile staging          # Use a specific fnox profile for value resolution
 ```
 
-Requires `agent.recipient` (age public key) in your config. Values are resolved via cascade:
+Requires `identity.recipient` (age public key) in your config. Values are resolved via cascade:
 
 1. **fnox** (if available)
 2. **Environment variables** (e.g. `OPENAI_API_KEY` in your shell)
 3. **Interactive prompt** (asks you to paste each value)
 
-After sealing, each secret gets an `encrypted_value` field. At boot time, `envpkt exec` or `boot()` automatically decrypts sealed values using the `agent.identity` file.
+After sealing, each secret gets an `encrypted_value` field. At boot time, `envpkt exec` or `boot()` automatically decrypts sealed values using the `identity.key_file` path (or the default `~/.envpkt/age-key.txt`).
 
 See [`examples/sealed-agent.toml`](./examples/sealed-agent.toml) for a complete example.
 
@@ -645,12 +645,12 @@ Each `[secret.<KEY>]` section describes a secret:
 | **Sealed**      | `encrypted_value`                               | Age-encrypted secret value (safe to commit) |
 | **Enforcement** | `required`, `tags`                              | Filtering, grouping, and policy             |
 
-### Agent Identity
+### Identity
 
-The optional `[agent]` section identifies the AI agent:
+The optional `[identity]` section identifies the consumer of these credentials:
 
 ```toml
-[agent]
+[identity]
 name = "data-pipeline-agent"
 consumer = "agent"                     # agent | service | developer | ci
 description = "ETL pipeline processor"

package/dist/cli.js

@@ -87,7 +87,7 @@ const computeAudit = (config, fnoxKeys, today) => {
 		missing,
 		missing_metadata,
 		orphaned,
-		agent: config.agent
+		identity: config.identity
 	};
 };
 const computeEnvAudit = (config, env = process.env) => {
@@ -125,20 +125,20 @@ const ConsumerType = Type.Union([
 	Type.Literal("developer"),
 	Type.Literal("ci")
 ], { description: "Classification of the agent's consumer type" });
-const AgentIdentitySchema = Type.Object({
-	name: Type.String({ description: "Agent display name" }),
+const IdentitySchema = Type.Object({
+	name: Type.String({ description: "Display name" }),
 	consumer: Type.Optional(ConsumerType),
-	description: Type.Optional(Type.String({ description: "Agent description or role" })),
-	capabilities: Type.Optional(Type.Array(Type.String(), { description: "List of capabilities this agent provides" })),
+	description: Type.Optional(Type.String({ description: "Description or role" })),
+	capabilities: Type.Optional(Type.Array(Type.String(), { description: "List of capabilities this identity provides" })),
 	expires: Type.Optional(Type.String({
 		format: "date",
-		description: "Agent credential expiration date (YYYY-MM-DD)"
+		description: "Credential expiration date (YYYY-MM-DD)"
 	})),
-	services: Type.Optional(Type.Array(Type.String(), { description: "Service dependencies for this agent" })),
-	identity: Type.Optional(Type.String({ description: "Path to encrypted agent key file (relative to config directory)" })),
-	recipient: Type.Optional(Type.String({ description: "Agent's age public key for encryption" })),
-	secrets: Type.Optional(Type.Array(Type.String(), { description: "Secret keys this agent needs from the catalog" }))
-}, { description: "Identity and capabilities of the AI agent using this envpkt" });
+	services: Type.Optional(Type.Array(Type.String(), { description: "Service dependencies" })),
+	key_file: Type.Optional(Type.String({ description: "Path to age identity file (relative to config directory)" })),
+	recipient: Type.Optional(Type.String({ description: "Age public key for encryption" })),
+	secrets: Type.Optional(Type.Array(Type.String(), { description: "Secret keys needed from the catalog" }))
+}, { description: "Identity and capabilities of the principal using this envpkt" });
 const SecretMetaSchema = Type.Object({
 	service: Type.Optional(Type.String({ description: "Service or system this secret authenticates to" })),
 	expires: Type.Optional(Type.String({
@@ -196,7 +196,7 @@ const EnvpktConfigSchema = Type.Object({
 		default: 1
 	}),
 	catalog: Type.Optional(Type.String({ description: "Path to shared secret catalog (relative to this config file)" })),
-	agent: Type.Optional(AgentIdentitySchema),
+	identity: Type.Optional(IdentitySchema),
 	secret: Type.Optional(Type.Record(Type.String(), SecretMetaSchema, { description: "Per-secret metadata keyed by secret name" })),
 	env: Type.Optional(Type.Record(Type.String(), EnvMetaSchema, { description: "Plaintext environment defaults keyed by variable name" })),
 	lifecycle: Type.Optional(LifecycleConfigSchema),
@@ -399,12 +399,12 @@ const resolveConfig = (agentConfig, agentConfigDir) => {
 		overridden: [],
 		warnings: []
 	});
-	if (!agentConfig.agent?.secrets || agentConfig.agent.secrets.length === 0) return Left({
+	if (!agentConfig.identity?.secrets || agentConfig.identity.secrets.length === 0) return Left({
 		_tag: "MissingSecretsList",
-		message: "Config has 'catalog' but agent.secrets is missing — declare which catalog secrets this agent needs"
+		message: "Config has 'catalog' but identity.secrets is missing — declare which catalog secrets this agent needs"
 	});
 	const catalogPath = resolve(agentConfigDir, agentConfig.catalog);
-	const agentSecrets = agentConfig.agent.secrets;
+	const agentSecrets = agentConfig.identity.secrets;
 	const agentSecretEntries = agentConfig.secret ?? {};
 	return loadCatalog(catalogPath).flatMap((catalogConfig) => resolveSecrets(agentSecretEntries, catalogConfig.secret ?? {}, agentSecrets, catalogPath).map((resolvedMeta) => {
 		const merged = [];
@@ -415,16 +415,16 @@ const resolveConfig = (agentConfig, agentConfigDir) => {
 			if (agentSecretEntries[key]) overridden.push(key);
 		}
 		const { catalog: _catalog, ...agentWithoutCatalog } = agentConfig;
-		const agentIdentity = agentConfig.agent ? (() => {
-			const { secrets: _secrets, ...rest } = agentConfig.agent;
+		const identityData = agentConfig.identity ? (() => {
+			const { secrets: _secrets, ...rest } = agentConfig.identity;
 			return rest;
 		})() : void 0;
 		return {
 			config: {
 				...agentWithoutCatalog,
-				agent: agentIdentity ? {
-					...agentIdentity,
-					name: agentIdentity.name
+				identity: identityData ? {
+					...identityData,
+					name: identityData.name
 				} : void 0,
 				secret: resolvedMeta
 			},
@@ -521,9 +521,9 @@ const formatFleetJson = (fleet) => JSON.stringify({
 	expiring_soon: fleet.expiring_soon,
 	agents: fleet.agents.map((a) => ({
 		path: a.path,
-		name: a.agent?.name ?? null,
-		consumer: a.agent?.consumer ?? null,
-		description: a.agent?.description ?? null,
+		name: a.identity?.name ?? null,
+		consumer: a.identity?.consumer ?? null,
+		description: a.identity?.description ?? null,
 		status: a.audit.status,
 		secrets: a.audit.total
 	})).toArray()
@@ -820,6 +820,106 @@ 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/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 identity.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 inIdentitySection = false;
+		let recipientUpdated = false;
+		let hasIdentitySection = false;
+		for (const line of lines) {
+			if (/^\[identity\]\s*$/.test(line)) {
+				inIdentitySection = true;
+				hasIdentitySection = true;
+				output.push(line);
+				continue;
+			}
+			if (/^\[/.test(line) && !/^\[identity\]\s*$/.test(line)) {
+				if (inIdentitySection && !recipientUpdated) {
+					output.push(`recipient = "${recipient}"`);
+					recipientUpdated = true;
+				}
+				inIdentitySection = false;
+				output.push(line);
+				continue;
+			}
+			if (inIdentitySection && /^recipient\s*=/.test(line)) {
+				output.push(`recipient = "${recipient}"`);
+				recipientUpdated = true;
+				continue;
+			}
+			output.push(line);
+		}
+		if (inIdentitySection && !recipientUpdated) output.push(`recipient = "${recipient}"`);
+		if (!hasIdentitySection) {
+			output.push("");
+			output.push("[identity]");
+			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/seal.ts
 /** Encrypt a plaintext string using age with the given recipient public key (armored output) */
@@ -931,9 +1031,17 @@ const resolveAndLoad = (opts) => resolveConfigPath(opts.configPath).fold((err) =
 		configSource
 	}));
 }));
-const resolveAgentKey = (config, configDir) => {
-	if (!config.agent?.identity) return Right(void 0);
-	return unwrapAgentKey(resolve(configDir, expandPath(config.agent.identity))).fold((err) => Left(err), (key) => Right(key));
+/** Resolve identity file path with explicit fallback control */
+const resolveIdentityFilePath = (config, configDir, useDefaultFallback) => {
+	if (config.identity?.key_file) return resolve(configDir, expandPath(config.identity.key_file));
+	if (!useDefaultFallback) return void 0;
+	const defaultPath = resolveKeyPath();
+	return existsSync(defaultPath) ? defaultPath : void 0;
+};
+const resolveIdentityKey = (config, configDir) => {
+	const identityPath = resolveIdentityFilePath(config, configDir, false);
+	if (!identityPath) return Right(void 0);
+	return unwrapAgentKey(identityPath).fold((err) => Left(err), (key) => Right(key));
 };
 const detectFnoxKeys = (configDir) => detectFnox(configDir).fold(() => /* @__PURE__ */ new Set(), (fnoxPath) => readFnoxConfig(fnoxPath).fold(() => /* @__PURE__ */ new Set(), (fnoxConfig) => extractFnoxKeys(fnoxConfig)));
 const checkExpiration = (audit, failOnExpired, warnOnly) => {
@@ -976,10 +1084,10 @@ const bootSafe = (options) => {
 		const secretEntries = config.secret ?? {};
 		const metaKeys = Object.keys(secretEntries);
 		const hasSealedValues = metaKeys.some((k) => !!secretEntries[k]?.encrypted_value);
-		const agentKeyResult = resolveAgentKey(config, configDir);
-		const agentKey = agentKeyResult.fold(() => void 0, (k) => k);
-		const agentKeyError = agentKeyResult.fold((err) => err, () => void 0);
-		if (agentKeyError && !hasSealedValues) return Left(agentKeyError);
+		const identityKeyResult = resolveIdentityKey(config, configDir);
+		const identityKey = identityKeyResult.fold(() => void 0, (k) => k);
+		const identityKeyError = identityKeyResult.fold((err) => err, () => void 0);
+		if (identityKeyError && !hasSealedValues) return Left(identityKeyError);
 		const audit = computeAudit(config, detectFnoxKeys(configDir));
 		return checkExpiration(audit, failOnExpired, warnOnly).map((warnings) => {
 			const secrets = {};
@@ -994,7 +1102,8 @@ const bootSafe = (options) => {
 				if (inject) process.env[key] = entry.value;
 			} else overridden.push(key);
 			const sealedKeys = /* @__PURE__ */ new Set();
-			if (hasSealedValues && config.agent?.identity) unsealSecrets(secretEntries, resolve(configDir, expandPath(config.agent.identity))).fold((err) => {
+			const identityFilePath = resolveIdentityFilePath(config, configDir, true);
+			if (hasSealedValues && identityFilePath) unsealSecrets(secretEntries, identityFilePath).fold((err) => {
 				warnings.push(`Sealed value decryption failed: ${err.message}`);
 			}, (unsealed) => {
 				for (const [key, value] of Object.entries(unsealed)) {
@@ -1004,7 +1113,7 @@ const bootSafe = (options) => {
 				}
 			});
 			const remainingKeys = metaKeys.filter((k) => !sealedKeys.has(k));
-			if (remainingKeys.length > 0) if (fnoxAvailable()) fnoxExport(opts.profile, agentKey).fold((err) => {
+			if (remainingKeys.length > 0) if (fnoxAvailable()) fnoxExport(opts.profile, identityKey).fold((err) => {
 				warnings.push(`fnox export failed: ${err.message}`);
 				for (const key of remainingKeys) skipped.push(key);
 			}, (exported) => {
@@ -2005,7 +2114,7 @@ const scanFleet = (rootDir, options) => {
 		const audit = computeAudit(config);
 		agents.push({
 			path: configPath,
-			agent: config.agent,
+			identity: config.identity,
 			min_expiry_days: audit.secrets.toArray().reduce((min, s) => s.days_remaining.fold(() => min, (d) => min === void 0 ? d : Math.min(min, d)), void 0),
 			audit
 		});
@@ -2050,7 +2159,7 @@ const runFleet = (options) => {
 	if (fleet.expiring_soon > 0) console.log(`  ${YELLOW}${fleet.expiring_soon}${RESET} expiring soon`);
 	console.log("");
 	for (const agent of agents) {
-		const name = agent.agent?.name ? BOLD + agent.agent.name + RESET : DIM + agent.path + RESET;
+		const name = agent.identity?.name ? BOLD + agent.identity.name + RESET : DIM + agent.path + RESET;
 		const icon = statusIcon(agent.audit.status);
 		console.log(`  ${icon} ${name} ${DIM}(${agent.audit.total} secrets)${RESET}`);
 	}
@@ -2073,8 +2182,8 @@ created = "${todayIso()}"
 # tags = {}
 `;
 };
-const generateAgentSection = (name, capabilities, expires) => {
-	return `[agent]
+const generateIdentitySection = (name, capabilities, expires) => {
+	return `[identity]
 name = "${name}"
 # consumer = "agent"         # agent | service | developer | ci${capabilities ? `\ncapabilities = [${capabilities.split(",").map((c) => `"${c.trim()}"`).join(", ")}]` : ""}${expires ? `\nexpires = "${expires}"` : ""}
 `;
@@ -2089,8 +2198,8 @@ const generateTemplate = (options, fnoxKeys) => {
 		lines.push(`catalog = "${options.catalog}"`);
 		lines.push(``);
 	}
-	if (options.agent && options.name) {
-		lines.push(generateAgentSection(options.name, options.capabilities, options.expires));
+	if (options.identity && options.name) {
+		lines.push(generateIdentitySection(options.name, options.capabilities, options.expires));
 		if (options.catalog) lines.push(`secrets = []  # Add catalog secret keys this agent needs`);
 		lines.push(``);
 	}
@@ -2203,14 +2312,14 @@ const printConfig = (config, path, resolveResult, opts) => {
 	if (resolveResult?.catalogPath) console.log(`${DIM}Catalog: ${CYAN}${resolveResult.catalogPath}${RESET}`);
 	console.log(`version: ${config.version}`);
 	console.log("");
-	if (config.agent) {
-		console.log(`${BOLD}Agent:${RESET} ${config.agent.name}`);
-		if (config.agent.consumer) console.log(`  consumer: ${config.agent.consumer}`);
-		if (config.agent.description) console.log(`  description: ${config.agent.description}`);
-		if (config.agent.capabilities) console.log(`  capabilities: ${config.agent.capabilities.join(", ")}`);
-		if (config.agent.expires) console.log(`  expires: ${config.agent.expires}`);
-		if (config.agent.services) console.log(`  services: ${config.agent.services.join(", ")}`);
-		if (config.agent.secrets) console.log(`  secrets: ${config.agent.secrets.join(", ")}`);
+	if (config.identity) {
+		console.log(`${BOLD}Identity:${RESET} ${config.identity.name}`);
+		if (config.identity.consumer) console.log(`  consumer: ${config.identity.consumer}`);
+		if (config.identity.description) console.log(`  description: ${config.identity.description}`);
+		if (config.identity.capabilities) console.log(`  capabilities: ${config.identity.capabilities.join(", ")}`);
+		if (config.identity.expires) console.log(`  expires: ${config.identity.expires}`);
+		if (config.identity.services) console.log(`  services: ${config.identity.services.join(", ")}`);
+		if (config.identity.secrets) console.log(`  secrets: ${config.identity.secrets.join(", ")}`);
 		console.log("");
 	}
 	const secretEntries = config.secret ?? {};
@@ -2284,106 +2393,6 @@ 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) => {
@@ -2407,10 +2416,10 @@ const runKeygen = (options) => {
 		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(`  [identity]`);
 			console.log(`  recipient = "${recipient}"`);
 		}, () => {
-			console.log(`${GREEN}Updated${RESET} ${CYAN}${configPath}${RESET} with agent.recipient`);
+			console.log(`${GREEN}Updated${RESET} ${CYAN}${configPath}${RESET} with identity.recipient`);
 		});
 		else {
 			console.log(`${BOLD}Next steps:${RESET}`);
@@ -2472,7 +2481,7 @@ const readCapabilities = () => {
 		text: JSON.stringify({ error: "No envpkt.toml found" })
 	}] };
 	const { config } = loaded;
-	const agentCapabilities = config.agent?.capabilities ?? [];
+	const agentCapabilities = config.identity?.capabilities ?? [];
 	const secretCapabilities = {};
 	const secretEntries = config.secret ?? {};
 	for (const [key, meta] of Object.entries(secretEntries)) if (meta.capabilities && meta.capabilities.length > 0) secretCapabilities[key] = meta.capabilities;
@@ -2480,10 +2489,10 @@ const readCapabilities = () => {
 		uri: "envpkt://capabilities",
 		mimeType: "application/json",
 		text: JSON.stringify({
-			agent: config.agent ? {
-				name: config.agent.name,
-				consumer: config.agent.consumer,
-				description: config.agent.description,
+			identity: config.identity ? {
+				name: config.identity.name,
+				consumer: config.identity.consumer,
+				description: config.identity.description,
 				capabilities: agentCapabilities
 			} : null,
 			secrets: secretCapabilities
@@ -2625,15 +2634,15 @@ const handleListCapabilities = (args) => {
 	const loaded = loadConfigForTool(args.configPath);
 	if (!loaded.ok) return loaded.result;
 	const { config } = loaded;
-	const agentCapabilities = config.agent?.capabilities ?? [];
+	const agentCapabilities = config.identity?.capabilities ?? [];
 	const secretCapabilities = {};
 	const secretEntries = config.secret ?? {};
 	for (const [key, meta] of Object.entries(secretEntries)) if (meta.capabilities && meta.capabilities.length > 0) secretCapabilities[key] = meta.capabilities;
 	return textResult(JSON.stringify({
-		agent: config.agent ? {
-			name: config.agent.name,
-			consumer: config.agent.consumer,
-			description: config.agent.description,
+		identity: config.identity ? {
+			name: config.identity.name,
+			consumer: config.identity.consumer,
+			description: config.identity.description,
 			capabilities: agentCapabilities
 		} : null,
 		secrets: secretCapabilities,
@@ -2895,16 +2904,16 @@ const runSeal = async (options) => {
 		console.error(formatError(err));
 		process.exit(2);
 	}, (c) => c);
-	if (!config.agent?.recipient) {
-		console.error(`${RED}Error:${RESET} agent.recipient is required for sealing (age public key)`);
+	if (!config.identity?.recipient) {
+		console.error(`${RED}Error:${RESET} identity.recipient is required for sealing (age public key)`);
 		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}  [identity]${RESET}`);
 		console.error(`${DIM}  recipient = "age1..."${RESET}`);
 		process.exit(2);
 	}
-	const { recipient } = config.agent;
+	const { recipient } = config.identity;
 	const configDir = dirname(configPath);
 	const envEntries = config.env ?? {};
 	const secretEntries0 = config.secret ?? {};
@@ -2914,7 +2923,7 @@ const runSeal = async (options) => {
 		console.error(`${DIM}Move these to [secret.*] only, or remove from [env.*] before sealing.${RESET}`);
 		process.exit(2);
 	}
-	const agentKey = config.agent.identity ? unwrapAgentKey(resolve(configDir, expandPath(config.agent.identity))).fold((err) => {
+	const identityKey = config.identity.key_file ? unwrapAgentKey(resolve(configDir, expandPath(config.identity.key_file))).fold((err) => {
 		const msg = err._tag === "IdentityNotFound" ? `not found: ${err.path}` : err.message;
 		console.error(`${YELLOW}Warning:${RESET} Could not unwrap agent key: ${msg}`);
 	}, (k) => k) : void 0;
@@ -2934,7 +2943,7 @@ const runSeal = async (options) => {
 	const metaKeys = targetKeys;
 	console.log(`${BOLD}Sealing ${metaKeys.length} secret(s)${RESET} with recipient ${CYAN}${recipient.slice(0, 20)}...${RESET}`);
 	console.log("");
-	const values = await resolveValues(metaKeys, options.profile, agentKey);
+	const values = await resolveValues(metaKeys, options.profile, identityKey);
 	const resolved = Object.keys(values).length;
 	const skipped = metaKeys.length - resolved;
 	if (resolved === 0) {
@@ -3007,10 +3016,10 @@ program.name("envpkt").description("Credential lifecycle and fleet management fo
 	const pkgPath = findPkgJson(dirname(fileURLToPath(import.meta.url)));
 	return pkgPath ? JSON.parse(readFileSync(pkgPath, "utf-8")).version : "0.0.0";
 })());
-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) => {
+program.command("init").description("Initialize a new envpkt.toml in the current directory").option("--from-fnox [path]", "Scaffold from fnox.toml (optionally specify path)").option("--catalog <path>", "Path to shared secret catalog").option("--identity", "Include [identity] section").option("--name <name>", "Identity name (requires --identity)").option("--capabilities <caps>", "Comma-separated capabilities (requires --identity)").option("--expires <date>", "Credential expiration YYYY-MM-DD (requires --identity)").option("--force", "Overwrite existing envpkt.toml").action((options) => {
 	runInit(process.cwd(), options);
 });
-program.command("keygen").description("Generate an age keypair for sealing secrets — run this before `seal` if you don't have a key yet").option("-c, --config <path>", "Path to envpkt.toml (updates 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) => {
+program.command("keygen").description("Generate an age keypair for sealing secrets — run this before `seal` if you don't have a key yet").option("-c, --config <path>", "Path to envpkt.toml (updates identity.recipient if found)").option("--force", "Overwrite existing identity file").option("-o, --output <path>", "Output path for identity file (default: ~/.envpkt/age-key.txt)").action((options) => {
 	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) => {

package/dist/index.d.ts

@@ -7,6 +7,19 @@ import { CallToolResult, ReadResourceResult, Resource } from "@modelcontextproto
 //#region src/core/schema.d.ts
 declare const ConsumerType: _sinclair_typebox0.TUnion<[_sinclair_typebox0.TLiteral<"agent">, _sinclair_typebox0.TLiteral<"service">, _sinclair_typebox0.TLiteral<"developer">, _sinclair_typebox0.TLiteral<"ci">]>;
 type ConsumerType = Static<typeof ConsumerType>;
+declare const IdentitySchema: _sinclair_typebox0.TObject<{
+  name: _sinclair_typebox0.TString;
+  consumer: _sinclair_typebox0.TOptional<_sinclair_typebox0.TUnion<[_sinclair_typebox0.TLiteral<"agent">, _sinclair_typebox0.TLiteral<"service">, _sinclair_typebox0.TLiteral<"developer">, _sinclair_typebox0.TLiteral<"ci">]>>;
+  description: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
+  capabilities: _sinclair_typebox0.TOptional<_sinclair_typebox0.TArray<_sinclair_typebox0.TString>>;
+  expires: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
+  services: _sinclair_typebox0.TOptional<_sinclair_typebox0.TArray<_sinclair_typebox0.TString>>;
+  key_file: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
+  recipient: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
+  secrets: _sinclair_typebox0.TOptional<_sinclair_typebox0.TArray<_sinclair_typebox0.TString>>;
+}>;
+type Identity = Static<typeof IdentitySchema>;
+/** @deprecated Use `IdentitySchema` instead */
 declare const AgentIdentitySchema: _sinclair_typebox0.TObject<{
   name: _sinclair_typebox0.TString;
   consumer: _sinclair_typebox0.TOptional<_sinclair_typebox0.TUnion<[_sinclair_typebox0.TLiteral<"agent">, _sinclair_typebox0.TLiteral<"service">, _sinclair_typebox0.TLiteral<"developer">, _sinclair_typebox0.TLiteral<"ci">]>>;
@@ -14,11 +27,10 @@ declare const AgentIdentitySchema: _sinclair_typebox0.TObject<{
   capabilities: _sinclair_typebox0.TOptional<_sinclair_typebox0.TArray<_sinclair_typebox0.TString>>;
   expires: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
   services: _sinclair_typebox0.TOptional<_sinclair_typebox0.TArray<_sinclair_typebox0.TString>>;
-  identity: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
+  key_file: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
   recipient: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
   secrets: _sinclair_typebox0.TOptional<_sinclair_typebox0.TArray<_sinclair_typebox0.TString>>;
 }>;
-type AgentIdentity = Static<typeof AgentIdentitySchema>;
 declare const SecretMetaSchema: _sinclair_typebox0.TObject<{
   service: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
   expires: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
@@ -60,14 +72,14 @@ type EnvMeta = Static<typeof EnvMetaSchema>;
 declare const EnvpktConfigSchema: _sinclair_typebox0.TObject<{
   version: _sinclair_typebox0.TNumber;
   catalog: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
-  agent: _sinclair_typebox0.TOptional<_sinclair_typebox0.TObject<{
+  identity: _sinclair_typebox0.TOptional<_sinclair_typebox0.TObject<{
     name: _sinclair_typebox0.TString;
     consumer: _sinclair_typebox0.TOptional<_sinclair_typebox0.TUnion<[_sinclair_typebox0.TLiteral<"agent">, _sinclair_typebox0.TLiteral<"service">, _sinclair_typebox0.TLiteral<"developer">, _sinclair_typebox0.TLiteral<"ci">]>>;
     description: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
     capabilities: _sinclair_typebox0.TOptional<_sinclair_typebox0.TArray<_sinclair_typebox0.TString>>;
     expires: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
     services: _sinclair_typebox0.TOptional<_sinclair_typebox0.TArray<_sinclair_typebox0.TString>>;
-    identity: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
+    key_file: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
     recipient: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
     secrets: _sinclair_typebox0.TOptional<_sinclair_typebox0.TArray<_sinclair_typebox0.TString>>;
   }>>;
@@ -108,6 +120,8 @@ declare const EnvpktConfigSchema: _sinclair_typebox0.TObject<{
 type EnvpktConfig = Static<typeof EnvpktConfigSchema>;
 //#endregion
 //#region src/core/types.d.ts
+/** @deprecated Use `Identity` instead */
+type AgentIdentity = Identity;
 type HealthStatus = "healthy" | "degraded" | "critical";
 type SecretStatus = "healthy" | "expiring_soon" | "expired" | "stale" | "missing" | "missing_metadata";
 type SecretHealth = {
@@ -132,7 +146,7 @@ type AuditResult = {
   readonly missing: number;
   readonly missing_metadata: number;
   readonly orphaned: number;
-  readonly agent?: AgentIdentity;
+  readonly identity?: Identity;
 };
 type EnvDriftStatus = "default" | "overridden" | "missing";
 type EnvDriftEntry = {
@@ -151,7 +165,7 @@ type EnvAuditResult = {
 };
 type FleetAgent = {
   readonly path: string;
-  readonly agent?: AgentIdentity;
+  readonly identity?: Identity;
   readonly min_expiry_days?: number;
   readonly audit: AuditResult;
 };
@@ -437,7 +451,7 @@ declare const generateKeypair: (options?: {
   readonly force?: boolean;
   readonly outputPath?: string;
 }) => Either<KeygenError, KeygenResult>;
-/** Update agent.recipient in an envpkt.toml file, preserving structure */
+/** Update identity.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
@@ -501,4 +515,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 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 };
+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 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

@@ -4,8 +4,8 @@ import { TypeCompiler } from "@sinclair/typebox/compiler";
 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 { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -23,20 +23,22 @@ const ConsumerType = Type.Union([
 	Type.Literal("developer"),
 	Type.Literal("ci")
 ], { description: "Classification of the agent's consumer type" });
-const AgentIdentitySchema = Type.Object({
-	name: Type.String({ description: "Agent display name" }),
+const IdentitySchema = Type.Object({
+	name: Type.String({ description: "Display name" }),
 	consumer: Type.Optional(ConsumerType),
-	description: Type.Optional(Type.String({ description: "Agent description or role" })),
-	capabilities: Type.Optional(Type.Array(Type.String(), { description: "List of capabilities this agent provides" })),
+	description: Type.Optional(Type.String({ description: "Description or role" })),
+	capabilities: Type.Optional(Type.Array(Type.String(), { description: "List of capabilities this identity provides" })),
 	expires: Type.Optional(Type.String({
 		format: "date",
-		description: "Agent credential expiration date (YYYY-MM-DD)"
+		description: "Credential expiration date (YYYY-MM-DD)"
 	})),
-	services: Type.Optional(Type.Array(Type.String(), { description: "Service dependencies for this agent" })),
-	identity: Type.Optional(Type.String({ description: "Path to encrypted agent key file (relative to config directory)" })),
-	recipient: Type.Optional(Type.String({ description: "Agent's age public key for encryption" })),
-	secrets: Type.Optional(Type.Array(Type.String(), { description: "Secret keys this agent needs from the catalog" }))
-}, { description: "Identity and capabilities of the AI agent using this envpkt" });
+	services: Type.Optional(Type.Array(Type.String(), { description: "Service dependencies" })),
+	key_file: Type.Optional(Type.String({ description: "Path to age identity file (relative to config directory)" })),
+	recipient: Type.Optional(Type.String({ description: "Age public key for encryption" })),
+	secrets: Type.Optional(Type.Array(Type.String(), { description: "Secret keys needed from the catalog" }))
+}, { description: "Identity and capabilities of the principal using this envpkt" });
+/** @deprecated Use `IdentitySchema` instead */
+const AgentIdentitySchema = IdentitySchema;
 const SecretMetaSchema = Type.Object({
 	service: Type.Optional(Type.String({ description: "Service or system this secret authenticates to" })),
 	expires: Type.Optional(Type.String({
@@ -94,7 +96,7 @@ const EnvpktConfigSchema = Type.Object({
 		default: 1
 	}),
 	catalog: Type.Optional(Type.String({ description: "Path to shared secret catalog (relative to this config file)" })),
-	agent: Type.Optional(AgentIdentitySchema),
+	identity: Type.Optional(IdentitySchema),
 	secret: Type.Optional(Type.Record(Type.String(), SecretMetaSchema, { description: "Per-secret metadata keyed by secret name" })),
 	env: Type.Optional(Type.Record(Type.String(), EnvMetaSchema, { description: "Plaintext environment defaults keyed by variable name" })),
 	lifecycle: Type.Optional(LifecycleConfigSchema),
@@ -311,12 +313,12 @@ const resolveConfig = (agentConfig, agentConfigDir) => {
 		overridden: [],
 		warnings: []
 	});
-	if (!agentConfig.agent?.secrets || agentConfig.agent.secrets.length === 0) return Left({
+	if (!agentConfig.identity?.secrets || agentConfig.identity.secrets.length === 0) return Left({
 		_tag: "MissingSecretsList",
-		message: "Config has 'catalog' but agent.secrets is missing — declare which catalog secrets this agent needs"
+		message: "Config has 'catalog' but identity.secrets is missing — declare which catalog secrets this agent needs"
 	});
 	const catalogPath = resolve(agentConfigDir, agentConfig.catalog);
-	const agentSecrets = agentConfig.agent.secrets;
+	const agentSecrets = agentConfig.identity.secrets;
 	const agentSecretEntries = agentConfig.secret ?? {};
 	return loadCatalog(catalogPath).flatMap((catalogConfig) => resolveSecrets(agentSecretEntries, catalogConfig.secret ?? {}, agentSecrets, catalogPath).map((resolvedMeta) => {
 		const merged = [];
@@ -327,16 +329,16 @@ const resolveConfig = (agentConfig, agentConfigDir) => {
 			if (agentSecretEntries[key]) overridden.push(key);
 		}
 		const { catalog: _catalog, ...agentWithoutCatalog } = agentConfig;
-		const agentIdentity = agentConfig.agent ? (() => {
-			const { secrets: _secrets, ...rest } = agentConfig.agent;
+		const identityData = agentConfig.identity ? (() => {
+			const { secrets: _secrets, ...rest } = agentConfig.identity;
 			return rest;
 		})() : void 0;
 		return {
 			config: {
 				...agentWithoutCatalog,
-				agent: agentIdentity ? {
-					...agentIdentity,
-					name: agentIdentity.name
+				identity: identityData ? {
+					...identityData,
+					name: identityData.name
 				} : void 0,
 				secret: resolvedMeta
 			},
@@ -379,16 +381,16 @@ const formatSecretFields = (meta, indent) => {
 const formatPacket = (result, options) => {
 	const { config } = result;
 	const sections = [];
-	if (config.agent) {
-		const consumer = config.agent.consumer ? ` (${config.agent.consumer})` : "";
-		sections.push(`envpkt packet: ${config.agent.name}${consumer}`);
+	if (config.identity) {
+		const consumer = config.identity.consumer ? ` (${config.identity.consumer})` : "";
+		sections.push(`envpkt packet: ${config.identity.name}${consumer}`);
 	} else sections.push("envpkt packet");
-	if (config.agent) {
+	if (config.identity) {
 		const agentLines = [];
-		if (config.agent.description) agentLines.push(`  ${config.agent.description}`);
-		if (config.agent.capabilities) agentLines.push(`  capabilities: ${config.agent.capabilities.join(", ")}`);
-		if (config.agent.services) agentLines.push(`  services: ${config.agent.services.join(", ")}`);
-		if (config.agent.expires) agentLines.push(`  expires: ${config.agent.expires}`);
+		if (config.identity.description) agentLines.push(`  ${config.identity.description}`);
+		if (config.identity.capabilities) agentLines.push(`  capabilities: ${config.identity.capabilities.join(", ")}`);
+		if (config.identity.services) agentLines.push(`  services: ${config.identity.services.join(", ")}`);
+		if (config.identity.expires) agentLines.push(`  expires: ${config.identity.expires}`);
 		if (agentLines.length > 0) sections.push(agentLines.join("\n"));
 	}
 	const secretConfig = config.secret ?? {};
@@ -494,7 +496,7 @@ const computeAudit = (config, fnoxKeys, today) => {
 		missing,
 		missing_metadata,
 		orphaned,
-		agent: config.agent
+		identity: config.identity
 	};
 };
 const computeEnvAudit = (config, env = process.env) => {
@@ -1421,6 +1423,111 @@ 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/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 identity.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 inIdentitySection = false;
+		let recipientUpdated = false;
+		let hasIdentitySection = false;
+		for (const line of lines) {
+			if (/^\[identity\]\s*$/.test(line)) {
+				inIdentitySection = true;
+				hasIdentitySection = true;
+				output.push(line);
+				continue;
+			}
+			if (/^\[/.test(line) && !/^\[identity\]\s*$/.test(line)) {
+				if (inIdentitySection && !recipientUpdated) {
+					output.push(`recipient = "${recipient}"`);
+					recipientUpdated = true;
+				}
+				inIdentitySection = false;
+				output.push(line);
+				continue;
+			}
+			if (inIdentitySection && /^recipient\s*=/.test(line)) {
+				output.push(`recipient = "${recipient}"`);
+				recipientUpdated = true;
+				continue;
+			}
+			output.push(line);
+		}
+		if (inIdentitySection && !recipientUpdated) output.push(`recipient = "${recipient}"`);
+		if (!hasIdentitySection) {
+			output.push("");
+			output.push("[identity]");
+			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/seal.ts
 /** Encrypt a plaintext string using age with the given recipient public key (armored output) */
@@ -1532,9 +1639,17 @@ const resolveAndLoad = (opts) => resolveConfigPath(opts.configPath).fold((err) =
 		configSource
 	}));
 }));
-const resolveAgentKey = (config, configDir) => {
-	if (!config.agent?.identity) return Right(void 0);
-	return unwrapAgentKey(resolve(configDir, expandPath(config.agent.identity))).fold((err) => Left(err), (key) => Right(key));
+/** Resolve identity file path with explicit fallback control */
+const resolveIdentityFilePath = (config, configDir, useDefaultFallback) => {
+	if (config.identity?.key_file) return resolve(configDir, expandPath(config.identity.key_file));
+	if (!useDefaultFallback) return void 0;
+	const defaultPath = resolveKeyPath();
+	return existsSync(defaultPath) ? defaultPath : void 0;
+};
+const resolveIdentityKey = (config, configDir) => {
+	const identityPath = resolveIdentityFilePath(config, configDir, false);
+	if (!identityPath) return Right(void 0);
+	return unwrapAgentKey(identityPath).fold((err) => Left(err), (key) => Right(key));
 };
 const detectFnoxKeys = (configDir) => detectFnox(configDir).fold(() => /* @__PURE__ */ new Set(), (fnoxPath) => readFnoxConfig(fnoxPath).fold(() => /* @__PURE__ */ new Set(), (fnoxConfig) => extractFnoxKeys(fnoxConfig)));
 const checkExpiration = (audit, failOnExpired, warnOnly) => {
@@ -1577,10 +1692,10 @@ const bootSafe = (options) => {
 		const secretEntries = config.secret ?? {};
 		const metaKeys = Object.keys(secretEntries);
 		const hasSealedValues = metaKeys.some((k) => !!secretEntries[k]?.encrypted_value);
-		const agentKeyResult = resolveAgentKey(config, configDir);
-		const agentKey = agentKeyResult.fold(() => void 0, (k) => k);
-		const agentKeyError = agentKeyResult.fold((err) => err, () => void 0);
-		if (agentKeyError && !hasSealedValues) return Left(agentKeyError);
+		const identityKeyResult = resolveIdentityKey(config, configDir);
+		const identityKey = identityKeyResult.fold(() => void 0, (k) => k);
+		const identityKeyError = identityKeyResult.fold((err) => err, () => void 0);
+		if (identityKeyError && !hasSealedValues) return Left(identityKeyError);
 		const audit = computeAudit(config, detectFnoxKeys(configDir));
 		return checkExpiration(audit, failOnExpired, warnOnly).map((warnings) => {
 			const secrets = {};
@@ -1595,7 +1710,8 @@ const bootSafe = (options) => {
 				if (inject) process.env[key] = entry.value;
 			} else overridden.push(key);
 			const sealedKeys = /* @__PURE__ */ new Set();
-			if (hasSealedValues && config.agent?.identity) unsealSecrets(secretEntries, resolve(configDir, expandPath(config.agent.identity))).fold((err) => {
+			const identityFilePath = resolveIdentityFilePath(config, configDir, true);
+			if (hasSealedValues && identityFilePath) unsealSecrets(secretEntries, identityFilePath).fold((err) => {
 				warnings.push(`Sealed value decryption failed: ${err.message}`);
 			}, (unsealed) => {
 				for (const [key, value] of Object.entries(unsealed)) {
@@ -1605,7 +1721,7 @@ const bootSafe = (options) => {
 				}
 			});
 			const remainingKeys = metaKeys.filter((k) => !sealedKeys.has(k));
-			if (remainingKeys.length > 0) if (fnoxAvailable()) fnoxExport(opts.profile, agentKey).fold((err) => {
+			if (remainingKeys.length > 0) if (fnoxAvailable()) fnoxExport(opts.profile, identityKey).fold((err) => {
 				warnings.push(`fnox export failed: ${err.message}`);
 				for (const key of remainingKeys) skipped.push(key);
 			}, (exported) => {
@@ -1667,111 +1783,6 @@ 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 */
@@ -1851,7 +1862,7 @@ const scanFleet = (rootDir, options) => {
 		const audit = computeAudit(config);
 		agents.push({
 			path: configPath,
-			agent: config.agent,
+			identity: config.identity,
 			min_expiry_days: audit.secrets.toArray().reduce((min, s) => s.days_remaining.fold(() => min, (d) => min === void 0 ? d : Math.min(min, d)), void 0),
 			audit
 		});
@@ -1934,7 +1945,7 @@ const readCapabilities = () => {
 		text: JSON.stringify({ error: "No envpkt.toml found" })
 	}] };
 	const { config } = loaded;
-	const agentCapabilities = config.agent?.capabilities ?? [];
+	const agentCapabilities = config.identity?.capabilities ?? [];
 	const secretCapabilities = {};
 	const secretEntries = config.secret ?? {};
 	for (const [key, meta] of Object.entries(secretEntries)) if (meta.capabilities && meta.capabilities.length > 0) secretCapabilities[key] = meta.capabilities;
@@ -1942,10 +1953,10 @@ const readCapabilities = () => {
 		uri: "envpkt://capabilities",
 		mimeType: "application/json",
 		text: JSON.stringify({
-			agent: config.agent ? {
-				name: config.agent.name,
-				consumer: config.agent.consumer,
-				description: config.agent.description,
+			identity: config.identity ? {
+				name: config.identity.name,
+				consumer: config.identity.consumer,
+				description: config.identity.description,
 				capabilities: agentCapabilities
 			} : null,
 			secrets: secretCapabilities
@@ -2087,15 +2098,15 @@ const handleListCapabilities = (args) => {
 	const loaded = loadConfigForTool(args.configPath);
 	if (!loaded.ok) return loaded.result;
 	const { config } = loaded;
-	const agentCapabilities = config.agent?.capabilities ?? [];
+	const agentCapabilities = config.identity?.capabilities ?? [];
 	const secretCapabilities = {};
 	const secretEntries = config.secret ?? {};
 	for (const [key, meta] of Object.entries(secretEntries)) if (meta.capabilities && meta.capabilities.length > 0) secretCapabilities[key] = meta.capabilities;
 	return textResult(JSON.stringify({
-		agent: config.agent ? {
-			name: config.agent.name,
-			consumer: config.agent.consumer,
-			description: config.agent.description,
+		identity: config.identity ? {
+			name: config.identity.name,
+			consumer: config.identity.consumer,
+			description: config.identity.description,
 			capabilities: agentCapabilities
 		} : null,
 		secrets: secretCapabilities,
@@ -2194,4 +2205,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, 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 };
+export { AgentIdentitySchema, CallbackConfigSchema, ConsumerType, EnvMetaSchema, EnvpktBootError, EnvpktConfigSchema, IdentitySchema, 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.5.0",
+  "version": "0.6.0",
   "description": "Credential lifecycle and fleet management for AI agents",
   "keywords": [
     "credentials",

package/schemas/envpkt.schema.json

@@ -17,15 +17,15 @@
       "description": "Path to shared secret catalog (relative to this config file)",
       "type": "string"
     },
-    "agent": {
-      "description": "Identity and capabilities of the AI agent using this envpkt",
+    "identity": {
+      "description": "Identity and capabilities of the principal using this envpkt",
       "type": "object",
       "required": [
         "name"
       ],
       "properties": {
         "name": {
-          "description": "Agent display name",
+          "description": "Display name",
           "type": "string"
         },
         "consumer": {
@@ -50,11 +50,11 @@
           ]
         },
         "description": {
-          "description": "Agent description or role",
+          "description": "Description or role",
           "type": "string"
         },
         "capabilities": {
-          "description": "List of capabilities this agent provides",
+          "description": "List of capabilities this identity provides",
           "type": "array",
           "items": {
             "type": "string"
@@ -62,26 +62,26 @@
         },
         "expires": {
           "format": "date",
-          "description": "Agent credential expiration date (YYYY-MM-DD)",
+          "description": "Credential expiration date (YYYY-MM-DD)",
           "type": "string"
         },
         "services": {
-          "description": "Service dependencies for this agent",
+          "description": "Service dependencies",
           "type": "array",
           "items": {
             "type": "string"
           }
         },
-        "identity": {
-          "description": "Path to encrypted agent key file (relative to config directory)",
+        "key_file": {
+          "description": "Path to age identity file (relative to config directory)",
           "type": "string"
         },
         "recipient": {
-          "description": "Agent's age public key for encryption",
+          "description": "Age public key for encryption",
           "type": "string"
         },
         "secrets": {
-          "description": "Secret keys this agent needs from the catalog",
+          "description": "Secret keys needed from the catalog",
           "type": "array",
           "items": {
             "type": "string"