envpkt 0.13.3 → 0.13.5

package/README.md

@@ -181,6 +181,15 @@ 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`.
 
+### Where it injects: self-launched vs serverless
+
+Whether envpkt can replace a cloud secret store depends on one thing: **do you control how the process starts?**
+
+- **You launch it** (server, container, VM, k8s, systemd) → `envpkt exec -- yourapp` or `boot()` injects the decrypted values straight into the process environment. No cloud secret store needed: the sealed `envpkt.toml` ships with the app, and only the age key has to reach the runtime (N secrets collapse to 1 key).
+- **A platform launches it** (Cloudflare Workers, AWS Lambda, Vercel) → you don't own the launch, and the `age` CLI can't run inside the per-request isolate, so the platform's secret store is unavoidable. envpkt becomes the source of truth that populates and audits that store — not the injector.
+
+> Rule of thumb: **own the launch → `exec`/`boot`, no store. Platform owns the launch → store required, envpkt feeds and audits it.** Full details: [Runtime injection guide](https://envpkt.dev/guides/runtime-injection/).
+
 ## GitHub Actions
 
 A composite action resolves the credentials in `envpkt.toml` into the CI job — with secret values masked in the log — so later steps just see them as environment variables:
@@ -191,7 +200,7 @@ A composite action resolves the credentials in `envpkt.toml` into the CI job —
 # Sealed packets are decrypted with the `age` CLI (not preinstalled on runners).
 - run: sudo apt-get update && sudo apt-get install -y age
 
-- uses: jordanburke/envpkt@v0.12.0
+- uses: jordanburke/envpkt@v0
   with:
     config: ./envpkt.toml
     strict: "true" # fail the build if a credential is expired/unhealthy
@@ -205,7 +214,36 @@ A composite action resolves the credentials in `envpkt.toml` into the CI job —
 
 **Inputs:** `config`, `version` (npm version to run, default `latest`), `strict`, `profile`.
 
-> 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.
+> 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. Reference `@v0` for the moving major tag (re-pointed to each `0.x` release), or pin an exact release like `@v0.13.4` for immutability. `@v1` ships when envpkt reaches 1.0. Node is assumed present; add `actions/setup-node` first to pin a version.
+
+### Anti-rot CI gate
+
+A hand-maintained `envpkt.toml` is documentation, and documentation rots. The fix is a failing build: each `--strict` check exits non-zero so a stale or drifted config blocks the merge. Each gate is **metadata-only** (no secret values) and targets a different failure mode — compose the ones that fit:
+
+```bash
+# 1. Secret health — runs anywhere, no live env or age key needed.
+#    Fails on expired / stale (> lifecycle.stale_warning_days) / missing / missing-metadata.
+envpkt audit --strict            # exit 1 = degraded, 2 = critical
+
+# 2. Cross-environment parity — keep dev/staging/prod tracking the same keys.
+envpkt diff dev.envpkt.toml prod.envpkt.toml --exit-code
+
+# 3. Drift vs the live environment — run where the env is actually populated
+#    (a deployed host or a pre-deploy step), NOT a bare CI runner: with no env
+#    set, every var reads as "missing" and the gate false-fails.
+envpkt env check --strict        # exit 1 on any drift (missing / untracked)
+```
+
+**Where each belongs.** `audit --strict` and `diff --exit-code` are environment-independent — drop them in any PR/CI job as a merge gate. `env check --strict` compares the config against the _live_ environment, so it belongs in a pre-deploy step or a host healthcheck, after the env is populated (e.g. `eval "$(envpkt env export)"`), not in a stock CI runner.
+
+```yaml
+# PR gate: block merges when the config rots (no secrets, no age key required)
+- uses: jordanburke/envpkt@v0.13.4
+  with: { config: ./envpkt.toml, strict: "true" }
+- run: envpkt diff dev.envpkt.toml prod.envpkt.toml --exit-code
+```
+
+> Freshness in the sense of "verified live within N days" (a credential that still _authenticates_, not just one that hasn't _expired_ on paper) is a [verification](#) capability reserved for the hosted offering — `--strict` enforces everything checkable offline today.
 
 ## For agents and fleets
 
@@ -424,6 +462,20 @@ 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 copy`
+
+Copy a secret or env entry from one config to another. For a sealed secret, the value is unsealed with the **source's** age key and resealed for the **destination's** `identity.recipient` automatically — so you can move a credential between configs that use different keys without ever handling the plaintext yourself. Env entries (and secrets with no sealed value) copy as metadata only. The kind (secret vs env) is detected from where the key lives in the source.
+
+```bash
+envpkt copy DATABASE_URL --from prod.envpkt.toml --to staging.envpkt.toml
+envpkt copy DATABASE_URL --from prod.envpkt.toml --to staging.envpkt.toml --as DB_URL  # rename on copy
+envpkt copy PORT --to other.envpkt.toml          # --from defaults to the resolved config here
+envpkt copy API_KEY --to b.toml --force          # overwrite if it already exists in the destination
+envpkt copy API_KEY --to b.toml --dry-run        # preview without writing
+```
+
+`--from`/`--to` default to the config resolved for the current directory (and must already exist). On copy, `created` is reset to today and `last_rotated_at` is dropped (it's the source's rotation history). Copying a sealed secret needs the source key to unseal and the destination's `identity.recipient` to reseal.
+
 ### `envpkt exec`
 
 Run a pre-flight audit, inject secrets from fnox into the environment, then execute a command.