envpkt 0.13.1 → 0.13.3

package/README.md

@@ -5,43 +5,38 @@
 
 **Credentials your agents actually understand.**
 
-Structured metadata for every secret — capabilities, constraints, expiration, and fleet health — so agents operate within their boundaries instead of flying blind.
+envpkt gives every credential an `envpkt.toml` entry describing _what service it authenticates to_, _what it's allowed to do_, _when it expires_, and _how to rotate it_ — while the secret values stay in your secrets manager, encrypted at rest, or injected at runtime, never committed in plaintext.
 
-Every credential in your system gets an `envpkt.toml` entry describing _what service it authenticates to_, _what it's allowed to do_, _when it expires_, and _how to rotate it_. Your agents query this metadata via MCP to understand their operating constraints. Your operators audit credential health across entire agent fleets. The secrets themselves stay where they belong — in your secrets manager, encrypted at rest, or injected at runtime — never in the agent's conversation context.
+**Day one, with zero agents,** it's an encrypted-at-rest `.env` replacement with scoped loading: scan the credentials already in your shell, seal them into a file that's safe to commit, and load them automatically on `cd`, into a single command, or as a plain `.env` for any tool that wants one.
 
-## MCP Integration
+**As you add agents,** the same metadata gives them structured awareness of their own credentials over [MCP](#for-agents-and-fleets) — capabilities, expiry, drift, fleet health — without any secret value ever entering the model's context window.
 
-envpkt ships an [MCP](https://modelcontextprotocol.io/) server that gives AI agents structured awareness of their credentials. Add it to Claude, Cursor, VS Code, or any MCP-compatible client:
+## Quick Start
 
-```json
-{
-  "mcpServers": {
-    "envpkt": {
-      "command": "envpkt",
-      "args": ["mcp"]
-    }
-  }
-}
-```
+The whole loop for a single project — discover, seal, load — with zero agents involved:
 
-### Tools
+```bash
+npm install -g envpkt
 
-| Tool               | Description                                             |
-| ------------------ | ------------------------------------------------------- |
-| `getPacketHealth`  | Get overall health status with per-secret audit results |
-| `listCapabilities` | List agent and per-secret capabilities                  |
-| `getSecretMeta`    | Get metadata for a specific secret by key               |
-| `checkExpiration`  | Check expiration status and days remaining              |
-| `getEnvMeta`       | Get metadata for environment defaults and drift status  |
+# 1. Discover the credentials already in your shell, and scaffold envpkt.toml from them
+envpkt env scan
+envpkt env scan --write
+
+# 2. Generate an age key and seal the secret values into envpkt.toml (the file is safe to commit)
+envpkt keygen
+envpkt seal
 
-### Resources
+# 3. Load them — pick whatever fits the moment:
+envpkt exec -- your-tool            # run one command with the secrets injected, scoped to it
+eval "$(envpkt shell-hook zsh)"     # add to ~/.zshrc: auto-load on cd into a project, restore on leave
+envpkt env dotenv -o .env           # materialize a .env for Docker / Wrangler / Vite / …
 
-| URI                     | Description                       |
-| ----------------------- | --------------------------------- |
-| `envpkt://health`       | Current credential health summary |
-| `envpkt://capabilities` | Agent and secret capabilities     |
+# Anytime: check health and drift
+envpkt audit
+envpkt env check
+```
 
-The MCP server exposes metadata only — it does not have access to secret values. See [Security Model](#security-model) for details.
+Encrypted secrets committed to git, loaded where you need them, with health you can audit — and not an agent in sight. Scaling the same metadata to agents and fleets is [act two](#for-agents-and-fleets).
 
 ## Security Model
 
@@ -53,30 +48,6 @@ envpkt operates a three-tier trust model. Each tier has different guarantees, an
 
 **Tier 3: Shell-level agents** — Agents with shell access (Claude Code, Devin, etc.) can read environment variables directly. Prevention isn't possible at this tier. envpkt provides encrypted storage, scoped access, and audit trails — because when prevention isn't possible, visibility is what matters.
 
-## Quick Start
-
-Start where your credentials already are — environment variables — and graduate to encrypted, per-agent-scoped metadata.
-
-```bash
-# Install
-npm install -g envpkt
-
-# Auto-discover credentials from your shell environment
-envpkt env scan
-
-# Scaffold envpkt.toml from discovered credentials
-envpkt env scan --write
-
-# Audit credential health
-envpkt audit
-
-# Check for drift between envpkt.toml and live environment
-envpkt env check
-
-# Scan a directory tree of agents
-envpkt fleet
-```
-
 ## The envpkt.toml File
 
 Every project gets one `envpkt.toml` that describes its credentials. Here's a minimal example:
@@ -236,6 +207,44 @@ A composite action resolves the credentials in `envpkt.toml` into the CI job —
 
 > Decrypting sealed packets requires the [`age`](https://github.com/FiloSottile/age) CLI on the runner (install it first, as above) — not needed if you only inject plaintext `[env.*]` defaults or resolve via fnox. Pin to a released tag (e.g. `@v0.12.0`); no moving major tag (`@v1`) is published yet. Node is assumed present; add `actions/setup-node` first to pin a version.
 
+## For agents and fleets
+
+Everything above stands on its own with no agents involved. Once you _do_ have them, the same `envpkt.toml` metadata powers three more capabilities: agents reading their own constraints over MCP, fleet-wide health monitoring, and shared catalogs across many agents.
+
+### MCP server
+
+envpkt ships an [MCP](https://modelcontextprotocol.io/) server that gives AI agents structured awareness of their credentials. Add it to Claude, Cursor, VS Code, or any MCP-compatible client:
+
+```json
+{
+  "mcpServers": {
+    "envpkt": {
+      "command": "envpkt",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Tools**
+
+| Tool               | Description                                             |
+| ------------------ | ------------------------------------------------------- |
+| `getPacketHealth`  | Get overall health status with per-secret audit results |
+| `listCapabilities` | List agent and per-secret capabilities                  |
+| `getSecretMeta`    | Get metadata for a specific secret by key               |
+| `checkExpiration`  | Check expiration status and days remaining              |
+| `getEnvMeta`       | Get metadata for environment defaults and drift status  |
+
+**Resources**
+
+| URI                     | Description                       |
+| ----------------------- | --------------------------------- |
+| `envpkt://health`       | Current credential health summary |
+| `envpkt://capabilities` | Agent and secret capabilities     |
+
+The MCP server exposes metadata only — it reads `envpkt.toml` and strips any `encrypted_value` ciphertext from responses, so prompt injection cannot leak what isn't there. See [Security Model](#security-model) for the full trust model.
+
 ## Fleet Management
 
 When you're running multiple agents, `envpkt fleet` scans a directory tree for `envpkt.toml` files and aggregates credential health across your entire fleet.
@@ -355,6 +364,19 @@ envpkt audit -c path/to/envpkt.toml # Specify config path
 
 Exit codes: `0` = healthy, `1` = degraded, `2` = critical.
 
+### `envpkt doctor`
+
+One-shot environment check: is the `age` CLI installed, is a config resolvable here, and do its sealed secrets decrypt with an available key?
+
+```bash
+envpkt doctor
+# ✓ age      v1.2.0
+# ✓ config   /path/to/envpkt.toml
+# ✓ secrets  5 resolved, 0 skipped
+```
+
+If `age` is missing it prints the platform-specific install command; if a sealed packet has no key, it lists the paths it searched. Exits non-zero when a check fails.
+
 ### `envpkt resolve`
 
 Resolve catalog references and output a flat, self-contained config.
@@ -383,6 +405,25 @@ envpkt inspect --secrets --plaintext  # Show secret values in plaintext
 
 The `--secrets` flag reads values from environment variables matching each secret key. By default values are masked (`pos•••••yapp`). Add `--plaintext` to display full values.
 
+### `envpkt diff`
+
+Compare two configs — useful for spotting drift between environments (e.g. `dev.envpkt.toml` vs `prod.envpkt.toml`). Reports keys only in each side and field-level metadata changes for shared keys. Sealed ciphertext is ignored (the same secret re-encrypts differently); a sealed↔unsealed change is reported.
+
+```bash
+envpkt diff dev.envpkt.toml prod.envpkt.toml
+# - dev.envpkt.toml
+# + prod.envpkt.toml
+#
+# [secret]
+#   - OLD_KEY
+#   + NEW_KEY
+#   ~ API_KEY
+#       expires: 2026-01-01 → 2027-01-01
+
+envpkt diff a.toml b.toml --format json   # structured diff
+envpkt diff a.toml b.toml --exit-code     # exit non-zero on any difference (CI drift gate)
+```
+
 ### `envpkt exec`
 
 Run a pre-flight audit, inject secrets from fnox into the environment, then execute a command.
@@ -470,7 +511,8 @@ Secret values are emitted **only when the package sets top-level `scope = "shell
 Generate a `cd` hook (zsh/bash) that loads a project's credentials when you enter its directory tree and restores your environment when you leave:
 
 ```bash
-eval "$(envpkt shell-hook zsh)"   # add to ~/.zshrc (or: shell-hook bash)
+eval "$(envpkt shell-hook zsh)"             # add to ~/.zshrc (or: shell-hook bash)
+eval "$(envpkt shell-hook zsh --no-audit)"  # …without the per-cd health-check line
 ```
 
 On each directory change it resolves the **nearest `envpkt.toml`, walking up from the current directory** (like `git`/`direnv` — so it works from any subdirectory, not just the project root), injects that package via `env export --track`, and restores the previous package on leave (prior values, not a blind unset). Env defaults always load; secret values load only for `scope = "shell"` packages. Backed by `envpkt config-path` — a resolve-only command that prints the active config path (no decryption).
@@ -486,18 +528,6 @@ Inject resolved secrets into a GitHub Actions job. Emits `::add-mask::` for each
 npx envpkt env github --strict
 ```
 
-### `envpkt shell-hook`
-
-Output a shell function that runs `envpkt audit --format minimal` whenever you `cd` into a directory. envpkt's config discovery chain automatically finds config files beyond CWD (see [Config Resolution](#config-resolution)), so the hook works even in directories without a local `envpkt.toml`.
-
-```bash
-# Add to your .zshrc
-eval "$(envpkt shell-hook zsh)"
-
-# Add to your .bashrc
-eval "$(envpkt shell-hook bash)"
-```
-
 ### `envpkt mcp`
 
 Start the envpkt MCP server (stdio transport) for AI agent integration.

package/dist/cli.js

@@ -8,10 +8,10 @@ import { TypeCompiler } from "@sinclair/typebox/compiler";
 import { Env, Fs, Path, Platform } from "functype-os";
 import { TomlDate, parse, stringify } from "smol-toml";
 import { FormatRegistry, Type } from "@sinclair/typebox";
-import { randomBytes } from "node:crypto";
+import { execFileSync } from "node:child_process";
 import { homedir, tmpdir } from "node:os";
 import { directSilentLogger } from "functype-log/direct";
-import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 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";
@@ -557,6 +557,63 @@ const resolveConfig = (agentConfig, agentConfigDir) => {
 	}));
 };
 //#endregion
+//#region src/fnox/identity.ts
+/** Check if the age CLI is available on PATH */
+const ageAvailable = () => Try(() => {
+	execFileSync("age", ["--version"], { stdio: "pipe" });
+	return true;
+}).fold(() => false, (v) => v);
+/** The age CLI version string (e.g. "v1.2.0"), or None if age isn't on PATH. */
+const ageVersion = () => Try(() => execFileSync("age", ["--version"], {
+	stdio: [
+		"pipe",
+		"pipe",
+		"pipe"
+	],
+	encoding: "utf-8"
+}).trim()).fold(() => Option.none(), (v) => Option(v));
+/** Platform-aware instructions for installing the age CLI. */
+const ageInstallHint = () => {
+	return `Install age:\n    ${{
+		darwin: "brew install age",
+		linux: "apt install age   (or: apk add age · dnf install age · nix-env -iA nixpkgs.age)",
+		win32: "scoop install age   (or: winget install FiloSottile.age)"
+	}[process.platform] ?? "see the install guide"}\n    https://github.com/FiloSottile/age#installation`;
+};
+/**
+* Extract the secret key from an age identity file (plain or encrypted).
+* - Plain identity files (from `age-keygen`) contain `AGE-SECRET-KEY-*` lines directly
+* - Encrypted identity files need `age --decrypt` to unwrap
+*/
+const unwrapAgentKey = (identityPath) => {
+	if (!existsSync(identityPath)) return Left({
+		_tag: "IdentityNotFound",
+		path: identityPath
+	});
+	return Try(() => readFileSync(identityPath, "utf-8")).fold((err) => Left({
+		_tag: "DecryptFailed",
+		message: `Failed to read identity file: ${err}`
+	}), (content) => {
+		const secretKeyLine = content.split("\n").find((l) => l.startsWith("AGE-SECRET-KEY-"));
+		if (secretKeyLine) return Right(secretKeyLine.trim());
+		if (!ageAvailable()) return Left({
+			_tag: "AgeNotFound",
+			message: "age CLI not found on PATH"
+		});
+		return Try(() => execFileSync("age", ["--decrypt", identityPath], {
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			encoding: "utf-8"
+		})).fold((err) => Left({
+			_tag: "DecryptFailed",
+			message: `age decrypt failed: ${err}`
+		}), (output) => Right(output.trim()));
+	});
+};
+//#endregion
 //#region src/cli/output.ts
 const RESET = "\x1B[0m";
 const BOLD = "\x1B[1m";
@@ -659,7 +716,7 @@ const formatError = (error) => {
 		case "ParseError": return `${RED}Error:${RESET} Failed to parse TOML: ${error.message}`;
 		case "ValidationError": return `${RED}Error:${RESET} Config validation failed:\n${String(error.errors)}`;
 		case "ReadError": return `${RED}Error:${RESET} Could not read file: ${error.message}`;
-		case "AgeNotFound": return `${RED}Error:${RESET} age CLI not found: ${error.message}`;
+		case "AgeNotFound": return `${RED}Error:${RESET} age is required for this operation but was not found on PATH.\n${DIM}${ageInstallHint()}${RESET}`;
 		case "DecryptFailed": return `${RED}Error:${RESET} Decrypt failed: ${error.message}`;
 		case "IdentityNotFound": return `${RED}Error:${RESET} Identity file not found: ${error.path}`;
 		case "SealKeyUnavailable": {
@@ -873,6 +930,90 @@ const runConfigPath = (options) => {
 	});
 };
 //#endregion
+//#region src/core/diff.ts
+/** Normalize a metadata value to a comparable/displayable string (`undefined` = absent). */
+const serialize = (value) => value === void 0 ? void 0 : typeof value === "string" ? value : JSON.stringify(value);
+/**
+* Field-level diff of two entries. `encrypted_value` is excluded from value comparison — the same
+* secret re-encrypts to different ciphertext, so diffing it is noise — but a change in *sealed
+* status* (present ↔ absent) is reported as a synthetic `sealed` field.
+*/
+const metaDiff = (a, b) => {
+	const ar = a;
+	const br = b;
+	const sealedChange = !!ar["encrypted_value"] === !!br["encrypted_value"] ? [] : [{
+		field: "sealed",
+		a: ar["encrypted_value"] ? "yes" : "no",
+		b: br["encrypted_value"] ? "yes" : "no"
+	}];
+	const fieldChanges = [...Object.keys(ar), ...Object.keys(br)].filter((k, i, arr) => k !== "encrypted_value" && arr.indexOf(k) === i).flatMap((field) => {
+		const av = serialize(ar[field]);
+		const bv = serialize(br[field]);
+		return av === bv ? [] : [{
+			field,
+			a: av,
+			b: bv
+		}];
+	});
+	return [...sealedChange, ...fieldChanges.sort((x, y) => x.field.localeCompare(y.field))];
+};
+const sectionDiff = (a, b) => {
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+	return {
+		onlyA: aKeys.filter((k) => !(k in b)).sort(),
+		onlyB: bKeys.filter((k) => !(k in a)).sort(),
+		changed: aKeys.filter((k) => k in b).sort().flatMap((key) => {
+			const changes = metaDiff(a[key], b[key]);
+			return changes.length === 0 ? [] : [{
+				key,
+				changes
+			}];
+		})
+	};
+};
+const isEmpty = (s) => s.onlyA.length === 0 && s.onlyB.length === 0 && s.changed.length === 0;
+/** Compare two configs by their `[secret.*]` and `[env.*]` entries (metadata, not ciphertext). */
+const diffConfigs = (a, b) => {
+	const secret = sectionDiff(a.secret ?? {}, b.secret ?? {});
+	const env = sectionDiff(a.env ?? {}, b.env ?? {});
+	return {
+		secret,
+		env,
+		identical: isEmpty(secret) && isEmpty(env)
+	};
+};
+//#endregion
+//#region src/cli/commands/diff.ts
+const formatSection = (name, s) => {
+	if (s.onlyA.length === 0 && s.onlyB.length === 0 && s.changed.length === 0) return [];
+	return [
+		`${BOLD}[${name}]${RESET}`,
+		...s.onlyA.map((k) => `  ${RED}- ${k}${RESET}`),
+		...s.onlyB.map((k) => `  ${GREEN}+ ${k}${RESET}`),
+		...s.changed.flatMap((c) => [`  ${YELLOW}~ ${c.key}${RESET}`, ...c.changes.map((ch) => `      ${ch.field}: ${DIM}${ch.a ?? "∅"}${RESET} → ${DIM}${ch.b ?? "∅"}${RESET}`)])
+	];
+};
+const loadOrExit = (path, side) => loadConfig(path).fold((err) => {
+	console.error(`${RED}Error${RESET} (${side} = ${path}): ${formatError(err)}`);
+	process.exit(2);
+}, (config) => config);
+/**
+* Compare two envpkt.toml files by their `[secret.*]` and `[env.*]` entries. Reports keys only in
+* each side and field-level metadata changes for shared keys (ciphertext is ignored; sealed-status
+* changes are reported). With `--exit-code`, exits non-zero when the configs differ.
+*/
+const runDiff = (pathA, pathB, options) => {
+	const diff = diffConfigs(loadOrExit(pathA, "a"), loadOrExit(pathB, "b"));
+	if (options.format === "json") console.log(JSON.stringify(diff, null, 2));
+	else if (diff.identical) console.log(`${GREEN}✓${RESET} no differences`);
+	else {
+		const body = [...formatSection("secret", diff.secret), ...formatSection("env", diff.env)];
+		console.log(`${DIM}- ${pathA}\n+ ${pathB}${RESET}\n\n${body.join("\n")}`);
+	}
+	if (options.exitCode && !diff.identical) process.exit(1);
+};
+//#endregion
 //#region src/fnox/cli.ts
 /** Export all secrets from fnox as key=value pairs for a given profile */
 const fnoxExport = (profile, agentKey) => {
@@ -918,46 +1059,6 @@ const fnoxAvailable = () => Try(() => {
 	return true;
 }).fold(() => false, (v) => v);
 //#endregion
-//#region src/fnox/identity.ts
-/** Check if the age CLI is available on PATH */
-const ageAvailable = () => Try(() => {
-	execFileSync("age", ["--version"], { stdio: "pipe" });
-	return true;
-}).fold(() => false, (v) => v);
-/**
-* Extract the secret key from an age identity file (plain or encrypted).
-* - Plain identity files (from `age-keygen`) contain `AGE-SECRET-KEY-*` lines directly
-* - Encrypted identity files need `age --decrypt` to unwrap
-*/
-const unwrapAgentKey = (identityPath) => {
-	if (!existsSync(identityPath)) return Left({
-		_tag: "IdentityNotFound",
-		path: identityPath
-	});
-	return Try(() => readFileSync(identityPath, "utf-8")).fold((err) => Left({
-		_tag: "DecryptFailed",
-		message: `Failed to read identity file: ${err}`
-	}), (content) => {
-		const secretKeyLine = content.split("\n").find((l) => l.startsWith("AGE-SECRET-KEY-"));
-		if (secretKeyLine) return Right(secretKeyLine.trim());
-		if (!ageAvailable()) return Left({
-			_tag: "AgeNotFound",
-			message: "age CLI not found on PATH"
-		});
-		return Try(() => execFileSync("age", ["--decrypt", identityPath], {
-			stdio: [
-				"pipe",
-				"pipe",
-				"pipe"
-			],
-			encoding: "utf-8"
-		})).fold((err) => Left({
-			_tag: "DecryptFailed",
-			message: `age decrypt failed: ${err}`
-		}), (output) => Right(output.trim()));
-	});
-};
-//#endregion
 //#region src/fnox/parse.ts
 /** Read and parse fnox.toml, extracting secret keys and profiles */
 const readFnoxConfig = (path) => Try(() => readFileSync(path, "utf-8")).fold((err) => Left({
@@ -1594,6 +1695,57 @@ const bootSafe = (options) => {
 	}));
 };
 //#endregion
+//#region src/cli/commands/doctor.ts
+const ok = (label, detail) => console.log(`  ${GREEN}✓${RESET} ${label}  ${DIM}${detail}${RESET}`);
+const warn = (label, detail) => console.log(`  ${YELLOW}—${RESET} ${label}  ${detail}`);
+const bad = (label, detail) => console.log(`  ${RED}✗${RESET} ${label}  ${detail}`);
+/** Print the resolution/key check, returning whether it passed. */
+const reportResolution = (configPath) => bootSafe({
+	configPath,
+	inject: false,
+	warnOnly: true
+}).fold((err) => {
+	if (err._tag === "SealKeyUnavailable") {
+		bad("key   ", `${err.sealedKeys.length} sealed secret(s) but no decryption key`);
+		err.searched.forEach((line) => console.log(`${DIM}        ${line}${RESET}`));
+	} else bad("config", `${err._tag}`);
+	return false;
+}, (boot) => {
+	const resolved = Object.keys(boot.secrets).length;
+	ok("secrets", `${resolved} resolved, ${boot.skipped.length} skipped`);
+	const auditColor = boot.audit.status === "healthy" ? GREEN : YELLOW;
+	console.log(`  ${auditColor}•${RESET} audit   ${DIM}${boot.audit.status}${RESET}`);
+	return true;
+});
+/**
+* One-shot environment check: is age installed, is a config resolvable, and do its sealed
+* secrets decrypt with an available key? Read-only; exits non-zero if any check fails.
+*/
+const runDoctor = (options) => {
+	console.log(`${BOLD}envpkt doctor${RESET}\n`);
+	const ageOk = ageVersion().fold(() => {
+		bad("age   ", "not found on PATH");
+		console.log(`${DIM}        ${ageInstallHint().split("\n").join("\n        ")}${RESET}`);
+		return false;
+	}, (version) => {
+		ok("age   ", version);
+		return true;
+	});
+	const resolveOk = resolveConfigPath(options.config).fold(() => {
+		warn("config", "no envpkt.toml found for this directory");
+		return true;
+	}, ({ path }) => {
+		ok("config", path);
+		return reportResolution(path);
+	});
+	console.log("");
+	if (ageOk && resolveOk) console.log(`${GREEN}✓ no issues${RESET}`);
+	else {
+		console.log(`${RED}✗ ${[!ageOk, !resolveOk].filter(Boolean).length} issue(s) found${RESET} ${CYAN}(see above)${RESET}`);
+		process.exit(1);
+	}
+};
+//#endregion
 //#region src/core/dotenv.ts
 const BARE_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
 /**
@@ -5078,6 +5230,12 @@ program.command("sort").description("Group [env.*] and [secret.*] sections and a
 program.command("upgrade").description("Upgrade envpkt to the latest version (npm install -g envpkt@latest)").action(() => {
 	runUpgrade();
 });
+program.command("diff").description("Compare two envpkt.toml configs by their secret/env entries (keys + metadata)").argument("<a>", "First config path").argument("<b>", "Second config path").option("--format <format>", "Output format: text | json", "text").option("--exit-code", "Exit non-zero when the configs differ (for CI drift gates)").action((a, b, options) => {
+	runDiff(a, b, options);
+});
+program.command("doctor").description("Check that age is installed and that the resolved config's sealed secrets can be decrypted").option("-c, --config <path>", "Path to envpkt.toml").action((options) => {
+	runDoctor(options);
+});
 program.command("config-path").description("Print the envpkt.toml path resolved for the current directory (empty if none). Resolve-only — no decryption.").option("-c, --config <path>", "Path to envpkt.toml").action((options) => {
 	runConfigPath(options);
 });

package/dist/index.d.ts

@@ -583,6 +583,32 @@ declare const quoteDotenvValue: (value: string) => string;
 /** Serialize entries to dotenv text (no trailing newline). */
 declare const formatDotenv: (entries: ReadonlyArray<DotenvEntry>, options?: FormatDotenvOptions) => string;
 //#endregion
+//#region src/core/diff.d.ts
+/** A single field that differs between two entries. `undefined` means the field is absent on that side. */
+type FieldChange = {
+  readonly field: string;
+  readonly a: string | undefined;
+  readonly b: string | undefined;
+};
+/** An entry present in both configs whose metadata differs. */
+type ChangedEntry = {
+  readonly key: string;
+  readonly changes: ReadonlyArray<FieldChange>;
+};
+/** Diff of one keyed section (`[secret.*]` or `[env.*]`). Key lists are sorted. */
+type SectionDiff = {
+  readonly onlyA: ReadonlyArray<string>;
+  readonly onlyB: ReadonlyArray<string>;
+  readonly changed: ReadonlyArray<ChangedEntry>;
+};
+type ConfigDiff = {
+  readonly secret: SectionDiff;
+  readonly env: SectionDiff;
+  readonly identical: boolean;
+};
+/** Compare two configs by their `[secret.*]` and `[env.*]` entries (metadata, not ciphertext). */
+declare const diffConfigs: (a: EnvpktConfig, b: EnvpktConfig) => ConfigDiff;
+//#endregion
 //#region src/core/toml-edit.d.ts
 /**
  * Remove a TOML section (e.g. `[secret.X]`) and all its fields through the next section or EOF.
@@ -668,4 +694,4 @@ type ToolDef = {
 declare const toolDefinitions: readonly ToolDef[];
 declare const callTool: (name: string, args: Record<string, unknown>) => CallToolResult;
 //#endregion
-export { type AgentIdentity, AgentIdentitySchema, type AliasError, type AliasTable, type AuditResult, type BootError, type BootOptions, type BootResult, type CallbackConfig, CallbackConfigSchema, type CatalogError, type CheckResult, type ConfidenceLevel, type ConfigError, type ConfigSource, ConsumerType, type CredentialPattern, type DirectLogger, type DirectTestLoggerHandle, type DotenvEntry, 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 FormatDotenvOptions, type FormatPacketOptions, type HealthStatus, type Identity, type IdentityError, IdentitySchema, type KeygenError, type KeygenResult, type LifecycleConfig, LifecycleConfigSchema, type LogEntry, type LogLevel, type LogMetadata, type MatchResult, type ResolveOptions, type ResolveResult, type ResolvedPath, type ScanOptions, type ScanResult, type SealError, type SecretDisplay, type SecretHealth, type SecretMeta, SecretMetaSchema, type SecretStatus, type TomlEditError, type ToolsConfig, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatDotenv, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, quoteDotenvValue, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };
+export { type AgentIdentity, AgentIdentitySchema, type AliasError, type AliasTable, type AuditResult, type BootError, type BootOptions, type BootResult, type CallbackConfig, CallbackConfigSchema, type CatalogError, type ChangedEntry, type CheckResult, type ConfidenceLevel, type ConfigDiff, type ConfigError, type ConfigSource, ConsumerType, type CredentialPattern, type DirectLogger, type DirectTestLoggerHandle, type DotenvEntry, type DriftEntry, type DriftStatus, type EnvAuditResult, type EnvDriftEntry, type EnvDriftStatus, type EnvMeta, EnvMetaSchema, EnvpktBootError, type EnvpktConfig, EnvpktConfigSchema, type FieldChange, type FleetAgent, type FleetHealth, type FnoxConfig, type FnoxError, type FnoxSecret, type FormatDotenvOptions, type FormatPacketOptions, type HealthStatus, type Identity, type IdentityError, IdentitySchema, type KeygenError, type KeygenResult, type LifecycleConfig, LifecycleConfigSchema, type LogEntry, type LogLevel, type LogMetadata, type MatchResult, type ResolveOptions, type ResolveResult, type ResolvedPath, type ScanOptions, type ScanResult, type SealError, type SecretDisplay, type SecretHealth, type SecretMeta, SecretMetaSchema, type SecretStatus, type SectionDiff, type TomlEditError, type ToolsConfig, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, diffConfigs, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatDotenv, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, quoteDotenvValue, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };

package/dist/index.js

@@ -2306,6 +2306,60 @@ const formatDotenv = (entries, options) => {
 	return header ? `${header}\n\n${body}` : body;
 };
 //#endregion
+//#region src/core/diff.ts
+/** Normalize a metadata value to a comparable/displayable string (`undefined` = absent). */
+const serialize = (value) => value === void 0 ? void 0 : typeof value === "string" ? value : JSON.stringify(value);
+/**
+* Field-level diff of two entries. `encrypted_value` is excluded from value comparison — the same
+* secret re-encrypts to different ciphertext, so diffing it is noise — but a change in *sealed
+* status* (present ↔ absent) is reported as a synthetic `sealed` field.
+*/
+const metaDiff = (a, b) => {
+	const ar = a;
+	const br = b;
+	const sealedChange = !!ar["encrypted_value"] === !!br["encrypted_value"] ? [] : [{
+		field: "sealed",
+		a: ar["encrypted_value"] ? "yes" : "no",
+		b: br["encrypted_value"] ? "yes" : "no"
+	}];
+	const fieldChanges = [...Object.keys(ar), ...Object.keys(br)].filter((k, i, arr) => k !== "encrypted_value" && arr.indexOf(k) === i).flatMap((field) => {
+		const av = serialize(ar[field]);
+		const bv = serialize(br[field]);
+		return av === bv ? [] : [{
+			field,
+			a: av,
+			b: bv
+		}];
+	});
+	return [...sealedChange, ...fieldChanges.sort((x, y) => x.field.localeCompare(y.field))];
+};
+const sectionDiff = (a, b) => {
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+	return {
+		onlyA: aKeys.filter((k) => !(k in b)).sort(),
+		onlyB: bKeys.filter((k) => !(k in a)).sort(),
+		changed: aKeys.filter((k) => k in b).sort().flatMap((key) => {
+			const changes = metaDiff(a[key], b[key]);
+			return changes.length === 0 ? [] : [{
+				key,
+				changes
+			}];
+		})
+	};
+};
+const isEmpty = (s) => s.onlyA.length === 0 && s.onlyB.length === 0 && s.changed.length === 0;
+/** Compare two configs by their `[secret.*]` and `[env.*]` entries (metadata, not ciphertext). */
+const diffConfigs = (a, b) => {
+	const secret = sectionDiff(a.secret ?? {}, b.secret ?? {});
+	const env = sectionDiff(a.env ?? {}, b.env ?? {});
+	return {
+		secret,
+		env,
+		identical: isEmpty(secret) && isEmpty(env)
+	};
+};
+//#endregion
 //#region src/core/toml-edit.ts
 const SECTION_RE = /^\[.+\]\s*$/;
 const MULTILINE_OPEN = "\"\"\"";
@@ -2804,4 +2858,4 @@ const startServer = async () => {
 	await server.connect(transport);
 };
 //#endregion
-export { AgentIdentitySchema, CallbackConfigSchema, ConsumerType, EnvMetaSchema, EnvpktBootError, EnvpktConfigSchema, IdentitySchema, LifecycleConfigSchema, SecretMetaSchema, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatDotenv, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, quoteDotenvValue, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };
+export { AgentIdentitySchema, CallbackConfigSchema, ConsumerType, EnvMetaSchema, EnvpktBootError, EnvpktConfigSchema, IdentitySchema, LifecycleConfigSchema, SecretMetaSchema, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, diffConfigs, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatDotenv, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, quoteDotenvValue, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envpkt",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "Credential lifecycle and fleet management for AI agents",
   "keywords": [
     "credentials",