envpkt 0.2.0 → 0.4.0

package/README.md

@@ -3,25 +3,60 @@
 [![Node.js CI](https://github.com/jordanburke/envpkt/actions/workflows/node.js.yml/badge.svg)](https://github.com/jordanburke/envpkt/actions/workflows/node.js.yml)
 [![npm version](https://img.shields.io/npm/v/envpkt.svg)](https://www.npmjs.com/package/envpkt)
 
-Credential lifecycle and fleet management for AI agents.
+**Credentials your agents actually understand.**
 
-**fnox handles access. envpkt handles awareness.** One file (`envpkt.toml`) answers five questions per credential: **What / Where / Why / When / How**.
+Structured metadata for every secret — capabilities, constraints, expiration, and fleet health — so agents operate within their boundaries instead of flying blind.
 
-## Why envpkt?
+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.
 
-Secrets managers store values. envpkt stores _metadata about_ those values — what service each credential authenticates to, when it expires, how to rotate it, and why it exists. This gives AI agents (and their operators) a structured way to:
+## MCP Integration
 
-- Audit credential health across a fleet of agents
-- Get warnings before secrets expire
-- Detect stale or orphaned credentials
-- Understand what capabilities each secret grants
-- Automate rotation workflows
-- Share secret metadata across agents via a central catalog
+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:
 
-envpkt works alongside your existing secrets manager (Vault, fnox, CI variables, etc.). Optionally, you can embed age-encrypted secret values directly in the TOML via **sealed packets** — making configs fully self-contained and safe to commit to git.
+```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 does not have access to secret values. See [Security Model](#security-model) for details.
+
+## Security Model
+
+envpkt operates a three-tier trust model. Each tier has different guarantees, and we're explicit about what each one protects against.
+
+**Tier 1: MCP metadata (agent-facing)** — The MCP server never returns raw credential values. This isn't a policy choice — architecturally, the server reads `envpkt.toml` which contains metadata (service names, capabilities, expiration dates, rotation URLs) but never plaintext secrets. The agent gets structured awareness of its constraints without any secret material entering the LLM context window. Prompt injection attacks cannot leak what isn't there.
+
+**Tier 2: Runtime injection (process-facing)** — `boot()` resolves secrets (from sealed packets, fnox, or environment variables) and injects them into `process.env` at startup, outside the LLM context. This is the same trust model as every Node.js application that reads from `.env`, except now secrets are encrypted at rest, scoped per-agent, and auditable. This is defense-in-depth against prompt injection — the most common attack vector — but it is not a hard boundary against agents with code execution capabilities.
+
+**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
@@ -51,7 +86,7 @@ Every project gets one `envpkt.toml` that describes its credentials. Here's a mi
 
 version = 1
 
-[meta.API_KEY]
+[secret.API_KEY]
 service = "stripe"
 ```
 
@@ -74,7 +109,7 @@ stale_warning_days = 90
 require_expiration = true
 require_service = true
 
-[meta.STRIPE_SECRET_KEY]
+[secret.STRIPE_SECRET_KEY]
 service = "stripe"
 purpose = "Process customer payments and manage subscriptions"
 capabilities = ["charges:write", "subscriptions:write"]
@@ -83,7 +118,7 @@ expires = "2027-01-15"
 rotation_url = "https://dashboard.stripe.com/apikeys"
 source = "vault"
 
-[meta.DATABASE_URL]
+[secret.DATABASE_URL]
 service = "postgres"
 purpose = "Read/write access to the billing database"
 capabilities = ["SELECT", "INSERT", "UPDATE"]
@@ -93,13 +128,81 @@ rotation_url = "https://wiki.internal/runbooks/rotate-db-creds"
 source = "vault"
 ```
 
+For non-secret configuration defaults (runtime mode, log levels, etc.), use `[env.*]`:
+
+```toml
+[env.NODE_ENV]
+value = "production"
+purpose = "Runtime environment mode"
+comment = "Override to 'development' for local testing"
+
+[env.LOG_LEVEL]
+value = "info"
+purpose = "Application log verbosity"
+```
+
 See [`examples/`](./examples/) for more configurations.
 
-## Shared Secret Catalog
+## Sealed Packets
+
+Sealed packets embed age-encrypted secret values directly in `envpkt.toml`. This makes your config fully self-contained — no external secrets backend needed at runtime.
+
+### Setup
+
+```bash
+# Generate an age keypair
+age-keygen -o identity.txt
+# public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+```
+
+Add the public key to your config and the identity file to `.gitignore`:
+
+```toml
+[agent]
+name = "my-agent"
+recipient = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"
+identity = "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.
+
+### Seal
+
+```bash
+envpkt seal
+```
+
+Each secret gets an `encrypted_value` field with age-armored ciphertext. The TOML (including ciphertext) is safe to commit.
+
+### Boot
+
+At runtime, sealed values are automatically decrypted:
+
+```typescript
+import { boot } from "envpkt"
+
+const result = boot() // decrypts sealed values, injects into process.env
+```
+
+Mixed mode is supported — sealed values take priority, with fnox as fallback for keys without `encrypted_value`.
+
+## 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.
+
+```bash
+envpkt fleet                    # Scan current directory (depth 3)
+envpkt fleet -d /opt/agents     # Scan specific directory
+envpkt fleet --depth 5          # Increase scan depth
+envpkt fleet --format json      # JSON output
+envpkt fleet --status critical  # Filter agents by health status
+```
+
+### Shared Catalog
 
 When multiple agents consume the same secrets, a **shared catalog** prevents metadata duplication. Define secret metadata once in a central file, then have each agent reference it.
 
-### Catalog file (`infra/envpkt.toml`)
+#### Catalog file (`infra/envpkt.toml`)
 
 ```toml
 version = 1
@@ -108,7 +211,7 @@ version = 1
 stale_warning_days = 90
 require_expiration = true
 
-[meta.DATABASE_URL]
+[secret.DATABASE_URL]
 service = "postgres"
 purpose = "Primary application database"
 capabilities = ["SELECT", "INSERT", "UPDATE", "DELETE"]
@@ -117,14 +220,14 @@ source = "vault"
 created = "2025-11-01"
 expires = "2026-11-01"
 
-[meta.REDIS_URL]
+[secret.REDIS_URL]
 service = "redis"
 purpose = "Caching and session storage"
 created = "2025-11-01"
 expires = "2026-11-01"
 ```
 
-### Agent file (`agents/pipeline/envpkt.toml`)
+#### Agent file (`agents/pipeline/envpkt.toml`)
 
 ```toml
 version = 1
@@ -136,11 +239,11 @@ consumer = "agent"
 secrets = ["DATABASE_URL", "REDIS_URL"]
 
 # Optional: narrow the catalog definition for this agent
-[meta.DATABASE_URL]
+[secret.DATABASE_URL]
 capabilities = ["SELECT"]
 ```
 
-### Resolve to a flat config
+#### Resolve to a flat config
 
 ```bash
 envpkt resolve -c agents/pipeline/envpkt.toml
@@ -148,54 +251,32 @@ envpkt resolve -c agents/pipeline/envpkt.toml
 
 This produces a self-contained config with catalog metadata merged in and agent overrides applied. The resolved output has no `catalog` reference — it's ready for deployment.
 
-### Merge rules
+#### Merge rules
 
-- Each field in the agent's `[meta.KEY]` override **replaces** the catalog field (shallow merge)
+- 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
 
-## Sealed Packets
+## How envpkt Compares
 
-Sealed packets embed age-encrypted secret values directly in `envpkt.toml`. This makes your config fully self-contained — no external secrets backend needed at runtime.
+The agentic credential space is splitting into approaches. Here's where envpkt fits:
 
-### Setup
+|                             | envpkt                                                      | agent-vault                 | AgentSecrets               | 1Password Agentic             | Infisical            |
+| --------------------------- | ----------------------------------------------------------- | --------------------------- | -------------------------- | ----------------------------- | -------------------- |
+| **Core approach**           | Metadata sidecar                                            | Git-based secret storage    | Proxy injection            | Browser autofill              | Secret retrieval API |
+| **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)       |
+| **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      |
 
-```bash
-# Generate an age keypair
-age-keygen -o identity.txt
-# public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
-```
+**envpkt's angle**: Competitors are fighting over how secrets move — retrieval vs. proxy vs. autofill. envpkt owns what secrets _mean_. Rate limits, expiration policies, capability scopes, rotation runbooks — structured semantics that travel with the credential. That's the layer the others don't have.
 
-Add the public key to your config and the identity file to `.gitignore`:
+> **Note**: This comparison reflects publicly available information. Verify current feature sets before making procurement decisions.
 
-```toml
-[agent]
-name = "my-agent"
-recipient = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"
-identity = "identity.txt"
-```
-
-### Seal
-
-```bash
-envpkt seal
-```
-
-Each secret gets an `encrypted_value` field with age-armored ciphertext. The TOML (including ciphertext) is safe to commit.
-
-### Boot
-
-At runtime, sealed values are automatically decrypted:
-
-```typescript
-import { boot } from "envpkt"
-
-const result = boot() // decrypts sealed values, injects into process.env
-```
-
-Mixed mode is supported — sealed values take priority, with fnox as fallback for keys without `encrypted_value`.
-
-## CLI Commands
+## CLI Reference
 
 ### `envpkt init`
 
@@ -237,18 +318,6 @@ envpkt resolve -c agent.toml --dry-run      # Preview without writing
 
 Configs without a `catalog` field pass through unchanged.
 
-### `envpkt fleet`
-
-Scan a directory tree for `envpkt.toml` files and aggregate health.
-
-```bash
-envpkt fleet                    # Scan current directory (depth 3)
-envpkt fleet -d /opt/agents     # Scan specific directory
-envpkt fleet --depth 5          # Increase scan depth
-envpkt fleet --format json      # JSON output
-envpkt fleet --status critical  # Filter agents by health status
-```
-
 ### `envpkt inspect`
 
 Display a structured view of an `envpkt.toml` file. Automatically resolves catalog references.
@@ -323,9 +392,30 @@ envpkt env check --strict               # Exit non-zero on any drift
 envpkt env check -c path/to/envpkt.toml # Specify config path
 ```
 
+### `envpkt env export`
+
+Output `export KEY='VALUE'` statements for sourcing secrets into the current shell. Secrets are resolved via sealed packets and/or fnox — the same pipeline as `envpkt exec`, but instead of spawning a subprocess, the output is designed to be `eval`'d.
+
+```bash
+# Source secrets into the current shell
+eval "$(envpkt env export)"
+
+# Use a specific fnox profile
+eval "$(envpkt env export --profile staging)"
+
+# Specify config path
+eval "$(envpkt env export -c path/to/envpkt.toml)"
+```
+
+Add to your shell startup (e.g. `~/.zshrc` or `~/.bashrc`) for automatic secret loading. envpkt's [config discovery chain](#config-resolution) finds your config automatically — no platform-specific shell logic needed:
+
+```bash
+eval "$(envpkt env export 2>/dev/null)"
+```
+
 ### `envpkt shell-hook`
 
-Output a shell function that runs `envpkt audit --format minimal` whenever you `cd` into a directory containing `envpkt.toml`.
+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
@@ -343,86 +433,34 @@ Start the envpkt MCP server (stdio transport) for AI agent integration.
 envpkt mcp
 ```
 
-## MCP Server
-
-envpkt ships an [MCP](https://modelcontextprotocol.io/) server that exposes credential metadata to AI agents. Add it to your MCP client config:
-
-```json
-{
-  "mcpServers": {
-    "envpkt": {
-      "command": "envpkt",
-      "args": ["mcp"]
-    }
-  }
-}
-```
+## Config Resolution
 
-### Tools
+Commands that read `envpkt.toml` resolve the config path via a priority chain:
 
-| 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              |
+1. **Explicit flag** — `-c path/to/envpkt.toml`
+2. **Environment variable** — `ENVPKT_CONFIG`
+3. **Discovery chain** — searches in order:
+   - `./envpkt.toml` (current working directory)
+   - Custom paths in `ENVPKT_SEARCH_PATH` (colon-separated)
+   - `~/.envpkt/envpkt.toml` (user home)
+   - Cloud storage paths (OneDrive, iCloud, Dropbox, Google Drive)
 
-### Resources
+When a config is discovered outside CWD, envpkt prints where it loaded from to stderr:
 
-| URI                     | Description                       |
-| ----------------------- | --------------------------------- |
-| `envpkt://health`       | Current credential health summary |
-| `envpkt://capabilities` | Agent and secret capabilities     |
-
-No secret values are ever exposed through the MCP server.
-
-## Schema
-
-envpkt.toml is validated against a JSON Schema. Editors with TOML + JSON Schema support will provide autocompletion and validation when the `#:schema` directive is present on line 1.
-
-The schema is published at:
-
-- npm: `envpkt/schema` (importable via package exports)
-- GitHub: `schemas/envpkt.schema.json`
-
-### Secret Metadata Fields
-
-Each `[meta.<KEY>]` section describes a secret:
-
-| Tier            | Fields                                          | Description                                 |
-| --------------- | ----------------------------------------------- | ------------------------------------------- |
-| **Scan-first**  | `service`, `expires`, `rotation_url`            | Key health indicators for audit             |
-| **Context**     | `purpose`, `capabilities`, `created`            | Why this secret exists and what it grants   |
-| **Operational** | `rotates`, `rate_limit`, `model_hint`, `source` | Runtime and provisioning info               |
-| **Sealed**      | `encrypted_value`                               | Age-encrypted secret value (safe to commit) |
-| **Enforcement** | `required`, `tags`                              | Filtering, grouping, and policy             |
-
-### Agent Identity
-
-The optional `[agent]` section identifies the AI agent:
-
-```toml
-[agent]
-name = "data-pipeline-agent"
-consumer = "agent"                     # agent | service | developer | ci
-description = "ETL pipeline processor"
-capabilities = ["read-s3", "write-postgres"]
-expires = "2027-01-01"
-services = ["aws", "postgres"]
-secrets = ["DATABASE_URL", "AWS_KEY"]  # When using a catalog
+```
+envpkt: loaded /Users/you/.envpkt/envpkt.toml
 ```
 
-### Lifecycle Policy
+### `ENVPKT_SEARCH_PATH`
 
-The optional `[lifecycle]` section configures audit behavior:
+Prepend custom search locations (colon-separated paths to `envpkt.toml` files):
 
-```toml
-[lifecycle]
-stale_warning_days = 90       # Flag secrets older than N days without updates
-require_expiration = true     # Require expires on all secrets
-require_service = true        # Require service on all secrets
+```bash
+export ENVPKT_SEARCH_PATH="$HOME/OneDrive/.envpkt/envpkt.toml:/custom/path/envpkt.toml"
 ```
 
+These are searched after CWD but before the built-in candidate paths. Useful for corporate OneDrive names, Google Drive with email in the path, or any non-standard location.
+
 ## Library API
 
 envpkt is also available as a TypeScript library with a functional programming API built on [functype](https://github.com/jordanburke/functype). All functions return `Either<Error, Result>` or `Option<T>` — no thrown exceptions.
@@ -433,6 +471,7 @@ import { boot, bootSafe, loadConfig, computeAudit, scanFleet, resolveConfig } fr
 // Boot API — load config, resolve catalog, audit, inject secrets
 const result = boot({ configPath: "envpkt.toml", inject: true })
 console.log(result.audit.status) // "healthy" | "degraded" | "critical"
+console.log(result.configSource) // "flag" | "env" | "cwd" | "search"
 
 // Safe variant returns Either instead of throwing
 const safe = bootSafe({ configPath: "envpkt.toml" })
@@ -461,6 +500,21 @@ const fleet = scanFleet("/opt/agents", { maxDepth: 3 })
 console.log(`${fleet.total_agents} agents, ${fleet.total_secrets} secrets`)
 ```
 
+### Framework Integration
+
+`boot()` runs before your agent framework initializes, making it compatible with any framework:
+
+```typescript
+import { boot } from "envpkt"
+
+// Resolve and inject credentials before agent startup
+const result = boot({ configPath: "envpkt.toml", inject: true })
+console.log(`${result.audit.status} — ${result.injected.length} secrets loaded`)
+
+// Now start your agent framework — process.env is populated
+// Works with LangChain, CrewAI, AutoGen, or any framework that reads from process.env
+```
+
 ### Packet Formatting API
 
 ```typescript
@@ -570,11 +624,58 @@ loadConfig(configPath).fold(
 )
 ```
 
+## Schema
+
+envpkt.toml is validated against a JSON Schema. Editors with TOML + JSON Schema support will provide autocompletion and validation when the `#:schema` directive is present on line 1.
+
+The schema is published at:
+
+- npm: `envpkt/schema` (importable via package exports)
+- GitHub: `schemas/envpkt.schema.json`
+
+### Secret Metadata Fields
+
+Each `[secret.<KEY>]` section describes a secret:
+
+| Tier            | Fields                                          | Description                                 |
+| --------------- | ----------------------------------------------- | ------------------------------------------- |
+| **Scan-first**  | `service`, `expires`, `rotation_url`            | Key health indicators for audit             |
+| **Context**     | `purpose`, `comment`, `capabilities`, `created` | Why this secret exists and what it grants   |
+| **Operational** | `rotates`, `rate_limit`, `model_hint`, `source` | Runtime and provisioning info               |
+| **Sealed**      | `encrypted_value`                               | Age-encrypted secret value (safe to commit) |
+| **Enforcement** | `required`, `tags`                              | Filtering, grouping, and policy             |
+
+### Agent Identity
+
+The optional `[agent]` section identifies the AI agent:
+
+```toml
+[agent]
+name = "data-pipeline-agent"
+consumer = "agent"                     # agent | service | developer | ci
+description = "ETL pipeline processor"
+capabilities = ["read-s3", "write-postgres"]
+expires = "2027-01-01"
+services = ["aws", "postgres"]
+secrets = ["DATABASE_URL", "AWS_KEY"]  # When using a catalog
+```
+
+### Lifecycle Policy
+
+The optional `[lifecycle]` section configures audit behavior:
+
+```toml
+[lifecycle]
+stale_warning_days = 90       # Flag secrets older than N days without updates
+require_expiration = true     # Require expires on all secrets
+require_service = true        # Require service on all secrets
+```
+
 ## fnox Integration
 
 envpkt integrates with [fnox](https://github.com/jordanburke/fnox) for secret resolution:
 
-- `envpkt init --from-fnox` scaffolds `[meta.*]` entries from `fnox.toml`
+- `envpkt init --from-fnox` scaffolds `[secret.*]` entries from `fnox.toml`
 - `envpkt audit` detects orphaned keys (in envpkt but not in fnox, or vice versa)
 - `envpkt exec` injects fnox secrets into the subprocess environment