envilder 0.15.0 β 0.15.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +38 -13
- package/ROADMAP.md +49 -22
- package/docs/SECURITY.md +35 -9
- package/docs/changelogs/cli.md +93 -4
- package/docs/changelogs/gha.md +32 -2
- package/docs/changelogs/sdk-dotnet.md +34 -2
- package/docs/changelogs/sdk-nodejs.md +22 -5
- package/docs/changelogs/sdk-python.md +19 -2
- package/docs/exec-command.md +184 -5
- package/package.json +11 -8
package/README.md
CHANGED
|
@@ -14,8 +14,11 @@
|
|
|
14
14
|
[](https://npmcharts.com/compare/envilder)
|
|
15
15
|
[](https://github.com/macalbert/envilder/actions/workflows/tests.yml)
|
|
16
16
|
[](https://macalbert.github.io/envilder/)
|
|
17
|
+
[](https://www.bestpractices.dev/projects/15703)
|
|
18
|
+
[](https://snyk.io/test/github/macalbert/envilder)
|
|
17
19
|
[](./LICENSE)
|
|
18
20
|
[](https://context7.com/macalbert/envilder)
|
|
21
|
+
[](https://coderabbit.ai)
|
|
19
22
|
|
|
20
23
|
## Why Envilder?
|
|
21
24
|
|
|
@@ -35,6 +38,9 @@ npx envilder
|
|
|
35
38
|
|
|
36
39
|
# Or with explicit paths
|
|
37
40
|
npx envilder --map=envilder.json --envfile=.env
|
|
41
|
+
|
|
42
|
+
# Or skip the file: run your app with the secrets in memory
|
|
43
|
+
npx envilder exec -- npm run dev
|
|
38
44
|
```
|
|
39
45
|
|
|
40
46
|
No SaaS middleman. One versioned mapping contract. Secrets stay in your cloud.
|
|
@@ -49,6 +55,9 @@ No SaaS middleman. One versioned mapping contract. Secrets stay in your cloud.
|
|
|
49
55
|
- **No single mapping contract.** Your cloud provider may be the source of truth for secret
|
|
50
56
|
values, but each environment still needs to know how application variables map to those
|
|
51
57
|
secrets. Without a versioned contract, dev, staging, and production configurations drift apart.
|
|
58
|
+
- **The `.env` file is readable by everything in your repo.** `.gitignore` keeps it out of commits,
|
|
59
|
+
not out of reach. Editors, indexers, install scripts, and AI coding agents can all read the
|
|
60
|
+
plaintext values sitting in your working tree.
|
|
52
61
|
|
|
53
62
|
## How Envilder solves it
|
|
54
63
|
|
|
@@ -56,6 +65,8 @@ No SaaS middleman. One versioned mapping contract. Secrets stay in your cloud.
|
|
|
56
65
|
needs and where they live. Git-versioned, PR-reviewable, and reused across environments.
|
|
57
66
|
- β‘ **Works everywhere your code runs.** CLI for local dev, GitHub Action for CI/CD, runtime SDKs
|
|
58
67
|
for application startup. Same file, same result.
|
|
68
|
+
- π« **No `.env` file when you don't want one.** `envilder exec` starts any command with the
|
|
69
|
+
secrets in its environment, in any language, without writing anything to disk.
|
|
59
70
|
- π **Rotate secrets without config drift.** Keep application-facing variable names stable while
|
|
60
71
|
rotating real secret values in AWS SSM or Azure Key Vault. Generated `.env` files update only
|
|
61
72
|
when Envilder runs again; runtime consumers must restart or resolve again.
|
|
@@ -69,6 +80,7 @@ No SaaS middleman. One versioned mapping contract. Secrets stay in your cloud.
|
|
|
69
80
|
|---------|-------------|
|
|
70
81
|
| π **Declarative Mapping** | One JSON file defines how application variables map to cloud secrets. Git-versioned, PR-reviewable, and diff-able |
|
|
71
82
|
| βοΈ **Cloud-native Providers** | AWS SSM and Azure Key Vault today |
|
|
83
|
+
| β‘ **Exec Mode** | `envilder exec -- <command>` runs any command with the secrets in its environment. Nothing written to disk, fail-closed, exit codes propagated. [Guide](docs/exec-command.md) |
|
|
72
84
|
| π **Runtime SDKs** | Load secrets into memory at app startup: [.NET](./src/sdks/dotnet/README.md), [Python](./src/sdks/python/README.md), [Node.js](./src/sdks/nodejs/README.md). No `.env` on disk |
|
|
73
85
|
| βοΈ **GitHub Action** | Pull secrets in CI/CD. Same mapping, zero manual config |
|
|
74
86
|
| π **Pull & Controlled Push** | Pull secrets to `.env`, or intentionally push local values to your cloud provider when bootstrapping or rotating |
|
|
@@ -128,6 +140,9 @@ It is not a sandbox: your command and everything it starts can read the secrets.
|
|
|
128
140
|
|
|
129
141
|
π See the [Exec Command Guide](docs/exec-command.md) for exit codes, signals and GitHub Actions masking.
|
|
130
142
|
|
|
143
|
+
π‘ Runnable examples: [envilder-examples](https://github.com/macalbert/envilder-examples) (Testcontainers and Aspire for
|
|
144
|
+
.NET, Python and TypeScript, AWS SSM and Azure Key Vault, plus `envilder exec`).
|
|
145
|
+
|
|
131
146
|
### π₯ See it in action
|
|
132
147
|
|
|
133
148
|
Watch how easy it is to automate your `.env` management in less than 1 minute:
|
|
@@ -252,7 +267,7 @@ Env.Load("envilder.json");
|
|
|
252
267
|
var dbPassword = Environment.GetEnvironmentVariable("DB_PASSWORD");
|
|
253
268
|
```
|
|
254
269
|
|
|
255
|
-
π **[Full .NET SDK docs](./src/sdks/dotnet/README.md)** Β· π‘ **[
|
|
270
|
+
π **[Full .NET SDK docs](./src/sdks/dotnet/README.md)** Β· π‘ **Examples:** [Testcontainers](https://github.com/macalbert/envilder-examples/tree/main/dotnet-testcontainers) Β· [Aspire](https://github.com/macalbert/envilder-examples/tree/main/dotnet-aspire)
|
|
256
271
|
|
|
257
272
|
### Python SDK
|
|
258
273
|
|
|
@@ -285,7 +300,7 @@ Envilder.load('production', {
|
|
|
285
300
|
})
|
|
286
301
|
```
|
|
287
302
|
|
|
288
|
-
π **[Full Python SDK docs](./src/sdks/python/README.md)** Β· π‘ **[
|
|
303
|
+
π **[Full Python SDK docs](./src/sdks/python/README.md)** Β· π‘ **Examples:** [Testcontainers](https://github.com/macalbert/envilder-examples/tree/main/python-testcontainers)
|
|
289
304
|
|
|
290
305
|
### Node.js SDK
|
|
291
306
|
|
|
@@ -315,7 +330,7 @@ const secrets = await Envilder.fromMapFile('envilder.json')
|
|
|
315
330
|
.resolve();
|
|
316
331
|
```
|
|
317
332
|
|
|
318
|
-
π **[Full Node.js SDK docs](./src/sdks/nodejs/README.md)** Β· π‘ **[
|
|
333
|
+
π **[Full Node.js SDK docs](./src/sdks/nodejs/README.md)** Β· π‘ **Examples:** [Testcontainers](https://github.com/macalbert/envilder-examples/tree/main/typescript-testcontainers) Β· [Aspire](https://github.com/macalbert/envilder-examples/tree/main/typescript-aspire)
|
|
319
334
|
|
|
320
335
|
## π€ GitHub Action
|
|
321
336
|
|
|
@@ -365,6 +380,8 @@ prebuilt action, so consumers do not need an Envilder build step.
|
|
|
365
380
|
- [Push Command Guide](docs/push-command.md)
|
|
366
381
|
- [Pull Command Guide](docs/pull-command.md)
|
|
367
382
|
- [Exec Command Guide](docs/exec-command.md)
|
|
383
|
+
- [envilder-examples](https://github.com/macalbert/envilder-examples): runnable examples for the SDKs and `envilder exec`
|
|
384
|
+
(Testcontainers and Aspire, AWS SSM and Azure Key Vault)
|
|
368
385
|
- [π€ Envilder on Context7](https://context7.com/macalbert/envilder): up-to-date docs for AI coding assistants
|
|
369
386
|
(Claude Code, Cursor, Copilot). Add `use context7` to your prompt, or reference the library ID `/macalbert/envilder`.
|
|
370
387
|
|
|
@@ -374,6 +391,7 @@ prebuilt action, so consumers do not need an Envilder build step.
|
|
|
374
391
|
graph LR
|
|
375
392
|
A["Mapping Contract<br/>(envilder.json)"] --> B[Envilder]:::core
|
|
376
393
|
B --> C["CLI β .env file"]
|
|
394
|
+
B --> X["CLI exec β process env"]
|
|
377
395
|
B --> D["GitHub Action β CI/CD"]
|
|
378
396
|
B --> E["SDK β app memory"]
|
|
379
397
|
F["AWS SSM / Azure Key Vault"]:::cloud --> B
|
|
@@ -384,7 +402,8 @@ graph LR
|
|
|
384
402
|
|
|
385
403
|
1. **Define**: create an `envilder.json` mapping env var names to cloud secret paths
|
|
386
404
|
2. **Resolve**: Envilder fetches each secret from your cloud vault
|
|
387
|
-
3. **Deliver**: secrets arrive as a `.env` file (CLI/GHA)
|
|
405
|
+
3. **Deliver**: secrets arrive as a `.env` file (CLI/GHA), in the environment of a command you
|
|
406
|
+
start with `envilder exec` (CLI), or in-memory (SDKs)
|
|
388
407
|
4. **Rotate**: update secret values in your cloud provider while keeping the same
|
|
389
408
|
application-facing mapping. Rerun Envilder to refresh a generated `.env`, or restart/re-resolve
|
|
390
409
|
in runtime consumers
|
|
@@ -404,11 +423,15 @@ layer that makes those secrets usable consistently across local development, CI/
|
|
|
404
423
|
Use Envilder when your secrets already live in your cloud provider and you want one versioned
|
|
405
424
|
`envilder.json` mapping contract everywhere your code runs.
|
|
406
425
|
|
|
426
|
+
`envilder exec` is not a sandbox either. It keeps secrets off the disk, but it does not isolate
|
|
427
|
+
the process: your command and every process it starts can read them. It also leaves an existing
|
|
428
|
+
`.env` file untouched, so delete it yourself when you move from pull mode to exec mode.
|
|
429
|
+
|
|
407
430
|
## π What's Next
|
|
408
431
|
|
|
409
|
-
Envilder already covers CLI, GitHub Action, and runtime SDKs for .NET, Python, and Node.js.
|
|
432
|
+
Envilder already covers CLI (including `envilder exec`), GitHub Action, and runtime SDKs for .NET, Python, and Node.js.
|
|
410
433
|
|
|
411
|
-
Next priorities include Go and Java SDKs
|
|
434
|
+
Next priorities include Go and Java SDKs and GCP Secret Manager.
|
|
412
435
|
|
|
413
436
|
See the [full roadmap](./ROADMAP.md).
|
|
414
437
|
|
|
@@ -431,17 +454,19 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
|
431
454
|
<img src="./src/website/public/localstack-logo-horizontal-Dark.svg" alt="LocalStack" height="40">
|
|
432
455
|
</picture>
|
|
433
456
|
</a>
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
<
|
|
437
|
-
|
|
457
|
+
|
|
458
|
+
<a href="https://snyk.io/open-source/" target="_blank" rel="noopener noreferrer">
|
|
459
|
+
<picture>
|
|
460
|
+
<source media="(prefers-color-scheme: dark)" srcset="./src/website/public/snyk-logo-Light.svg">
|
|
461
|
+
<source media="(prefers-color-scheme: light)" srcset="./src/website/public/snyk-logo-Dark.svg">
|
|
462
|
+
<img src="./src/website/public/snyk-logo-Dark.svg" alt="Snyk" height="40">
|
|
463
|
+
</picture>
|
|
464
|
+
</a>
|
|
438
465
|
</p>
|
|
439
466
|
|
|
440
467
|
<p align="center">
|
|
441
468
|
Envilder is also supported through the
|
|
442
|
-
<a href="https://aws.amazon.com/blogs/opensource/aws-cloud-credits-for-open-source-projects-affirming-our-commitment/">
|
|
443
|
-
AWS Open Source Credits Program
|
|
444
|
-
</a>.
|
|
469
|
+
<a href="https://aws.amazon.com/blogs/opensource/aws-cloud-credits-for-open-source-projects-affirming-our-commitment/">AWS Open Source Credits Program</a>.
|
|
445
470
|
</p>
|
|
446
471
|
|
|
447
472
|
## π License
|
package/ROADMAP.md
CHANGED
|
@@ -11,6 +11,9 @@ or directly inside application code at runtime.
|
|
|
11
11
|
> **Note:** This roadmap contains ideas and potential features based on initial vision and community feedback.
|
|
12
12
|
> Not all features are guaranteed to be implemented. Priorities may change based on user needs, feedback,
|
|
13
13
|
> and real-world usage patterns. Your input matters. Feel free to share your thoughts and suggestions!
|
|
14
|
+
>
|
|
15
|
+
> **Horizon:** "Up Next" covers the coming months and "Planned" the rest of the next twelve months
|
|
16
|
+
> (through October 2027). The [Out of scope](#-out-of-scope) section lists what Envilder does not intend to do.
|
|
14
17
|
|
|
15
18
|
---
|
|
16
19
|
|
|
@@ -18,41 +21,65 @@ or directly inside application code at runtime.
|
|
|
18
21
|
|
|
19
22
|
### β
Shipped
|
|
20
23
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
|
24
|
-
|
|
25
|
-
| **
|
|
26
|
-
|
|
|
27
|
-
| **
|
|
28
|
-
| **
|
|
29
|
-
| **
|
|
30
|
-
| **
|
|
31
|
-
| **
|
|
32
|
-
|
|
|
33
|
-
|
|
|
34
|
-
| **
|
|
24
|
+
Versions refer to each component's own changelog: [CLI](./docs/changelogs/cli.md), [GitHub Action](./docs/changelogs/gha.md), [.NET SDK](./docs/changelogs/sdk-dotnet.md), [Python SDK](./docs/changelogs/sdk-python.md) and [Node.js SDK](./docs/changelogs/sdk-nodejs.md).
|
|
25
|
+
|
|
26
|
+
| Feature | Version | Notes |
|
|
27
|
+
|---------|---------|-------|
|
|
28
|
+
| **Mapping-based resolution** | CLI v0.1.4 | Core functionality: resolve every variable declared in a JSON map file |
|
|
29
|
+
| **`.env` file generation** | CLI v0.1.4 | Core functionality |
|
|
30
|
+
| **AWS SSM Parameter Store** | CLI v0.1.4 | Default provider |
|
|
31
|
+
| **AWS profile support** | CLI v0.3.0 | `--profile` flag |
|
|
32
|
+
| **Push mode** (`--push`) | CLI v0.6.0 | Upload a `.env` file or a single variable (`--key`, `--value`, `--secret-path`) to the provider. Throttling retry and duplicate path checks since v0.7.7. [Guide](./docs/push-command.md) |
|
|
33
|
+
| **GitHub Action** | Action v0.7.0 | Pull secrets into `.env` files during workflow runs. [Documentation](./github-action/README.md) |
|
|
34
|
+
| **Azure Key Vault** | CLI v0.8.0, Action v0.8.0 | `--provider`, `--vault-url` and the `$config` map-file section. Precedence: flags > `$config` > defaults ([#90](https://github.com/macalbert/envilder/pull/90)) |
|
|
35
|
+
| **Documentation website** | CLI v0.9.1 | [envilder.com](https://envilder.com), in English, Spanish and Catalan. [Setup guide](./docs/requirements-installation.md) |
|
|
36
|
+
| **.NET SDK** (`Envilder`) | .NET SDK v0.1.0 | Load secrets into `IConfiguration`, `IServiceCollection` or `EnvilderClient`. Static facade, fluent builder and environment routing since v0.2.0. Published to NuGet. [Documentation](./src/sdks/dotnet/README.md) |
|
|
37
|
+
| **Python SDK** (`envilder`) | Python SDK v0.1.0 | Runtime library for Django, FastAPI and data pipelines. Fluent facade since v0.2.0, environment routing since v0.3.0. Published to PyPI. [Documentation](./src/sdks/python/README.md) |
|
|
38
|
+
| **Node.js SDK** (`@envilder/sdk`) | Node.js SDK v0.1.0 | Load secrets into `process.env` from a map file, with fluent builder, secret validation and environment routing. Published to npm. [Documentation](./src/sdks/nodejs/README.md) |
|
|
39
|
+
| **Map-file JSON Schema** | CLI v0.10.0, .NET SDK v0.3.0, Node.js SDK v0.2.0, Python SDK v0.4.0 | Formal spec at [`spec/map-file.v1.json`](./spec/map-file.v1.json), published at `https://envilder.com/schema/map-file.v1.json`: the contract between all SDKs and tools |
|
|
40
|
+
| **AWS identity banner** | CLI v0.12.1, Action v0.12.1 | Logs the effective AWS identity before resolving secrets (colorized since v0.13.0) |
|
|
41
|
+
| **Actionable credential errors** | CLI v0.13.0, .NET SDK v0.5.0, Node.js SDK v0.4.0, Python SDK v0.5.0 | Typed expired-credentials and expired-SSO-session errors with the exact fix (ADR-0010) |
|
|
42
|
+
| **SSO login recovery** | CLI v0.13.0 | On an interactive terminal, offers to run `aws sso login` and retries |
|
|
43
|
+
| **Secret masking in GitHub Actions** | Action v0.13.2 | Every resolved value is registered with `::add-mask::` before the `.env` file is written |
|
|
44
|
+
| **Zero-config defaults** | CLI v0.14.0 | `envilder` with no flags reads `envilder.json` and writes `.env` |
|
|
45
|
+
| **Safe `.env` writing** | CLI v0.14.0, Action v0.14.0 | Values round-trip exactly, and mapping keys a `.env` file cannot represent are rejected |
|
|
46
|
+
| **Exec mode** (`envilder exec`) | CLI v0.15.0 | `envilder exec [options] [--] <command> [args...]` starts a command with the resolved secrets in its environment, without writing a `.env` file. [Guide](./docs/exec-command.md) |
|
|
35
47
|
|
|
36
48
|
### π₯ Up Next
|
|
37
49
|
|
|
38
50
|
| Feature | Priority | Notes |
|
|
39
51
|
|---------|----------|-------|
|
|
40
|
-
| **Go SDK** (`envilder`) | π΄ High | Runtime library for Go: cloud-native apps, Kubernetes tooling. Published as Go module |
|
|
41
|
-
| **Java SDK** (`envilder`) | π΄ High | Runtime library for Java/Kotlin: Spring Boot, Android backends. Published to Maven Central |
|
|
42
|
-
| **Map-file JSON Schema** | π΄ High | Formal spec for the map-file format at `spec/`: serves as the contract between all SDKs and tools |
|
|
52
|
+
| **Go SDK** (`envilder`) | π΄ High | Runtime library for Go: cloud-native apps, Kubernetes tooling. Published as Go module ([#561](https://github.com/macalbert/envilder/issues/561) β [#562](https://github.com/macalbert/envilder/issues/562) β [#563](https://github.com/macalbert/envilder/issues/563)) |
|
|
53
|
+
| **Java SDK** (`envilder`) | π΄ High | Runtime library for Java/Kotlin: Spring Boot, Android backends. Published to Maven Central ([#569](https://github.com/macalbert/envilder/issues/569)) |
|
|
43
54
|
| **SDK conformance tests** | π΄ High | Language-agnostic test fixtures (JSON input β expected output) that all SDKs must pass |
|
|
44
|
-
| **
|
|
45
|
-
| **GCP Secret Manager** | π‘ Medium | Third cloud provider: similar DX to AWS SSM. Completes the multi-cloud trident (AWS + Azure + GCP) |
|
|
55
|
+
| **Validate command** (`envilder validate`) | π‘ Medium | Preflight check: map file, remote key existence and optional `.env` comparison, without printing values. CLI first, then the SDKs ([#532](https://github.com/macalbert/envilder/issues/532)) |
|
|
56
|
+
| **GCP Secret Manager** | π‘ Medium | Third cloud provider: similar DX to AWS SSM. Completes the multi-cloud trident (AWS + Azure + GCP) ([#573](https://github.com/macalbert/envilder/issues/573)) |
|
|
46
57
|
| **AWS Secrets Manager** | π‘ Medium | Support AWS Secrets Manager alongside SSM Parameter Store for teams using JSON-structured secrets |
|
|
47
|
-
| **Check/sync mode** (`--check`) | π‘ Medium | Validate cloud secrets vs local `.env`, fail CI if out-of-sync |
|
|
48
58
|
|
|
49
59
|
### π‘ Planned
|
|
50
60
|
|
|
51
61
|
| Feature | Priority | Notes |
|
|
52
62
|
|---------|----------|-------|
|
|
53
63
|
| **Auto-discovery mode** (`--auto`) | Medium | Fetch all parameters matching a given prefix (e.g., `/my-app/prod/*`) |
|
|
54
|
-
| **
|
|
55
|
-
| **
|
|
64
|
+
| **Local override map file** (`envilder.local.json`) | Medium | Personal, gitignored layer on top of the committed map file, on every surface (ADR-0011, [#385](https://github.com/macalbert/envilder/issues/385)) |
|
|
65
|
+
| **Environment delivery in the GitHub Action** | Medium | Export resolved values to later job steps instead of writing a `.env` file ([#478](https://github.com/macalbert/envilder/issues/478)) |
|
|
66
|
+
| **Exec with refresh** (`--refresh-interval`) | Low | Kill & restart child process periodically with fresh secrets (builds on `envilder exec`, [#479](https://github.com/macalbert/envilder/issues/479)) |
|
|
67
|
+
| **Named providers and per-environment config** | Medium | Several providers in one map file, per-environment provider settings and optional secrets, through `$config.providers`. Additive to the current schema; the flat `$config` fields are deprecated, with `envilder migrate` ([#586](https://github.com/macalbert/envilder/issues/586)) |
|
|
68
|
+
| **Per-provider packages** | Medium | Split the SDK packages per provider, so an app installs only the cloud SDKs it uses. Prerequisite for adding more providers |
|
|
69
|
+
| **Kubernetes Secrets** | Low | Read secrets from a cluster: in-cluster service account in production, kubeconfig locally |
|
|
70
|
+
| **HashiCorp Vault / OpenBao** | Low | KV secrets engine, with GitHub OIDC (JWT auth) in the Action |
|
|
71
|
+
| **Infisical** | Low | Cloud or self-hosted Infisical, with machine identities and GitHub OIDC |
|
|
72
|
+
| **Azure App Configuration** | Low | Settings and Key Vault references from App Configuration, for .NET-centric teams on Azure |
|
|
73
|
+
|
|
74
|
+
### π« Out of scope
|
|
75
|
+
|
|
76
|
+
Envilder resolves secrets from stores you already run. It does not intend to:
|
|
77
|
+
|
|
78
|
+
- **Be a secret store**: values stay in the cloud provider; Envilder never keeps its own copy outside the `.env` file or process environment you ask for
|
|
79
|
+
- **Run a hosted service or server**: everything runs locally, in CI or inside your application, with your own credentials
|
|
80
|
+
- **Manage secret lifecycle**: creating vaults, rotating values, setting expiry or access policies stays with the provider's own tooling
|
|
81
|
+
- **Encrypt `.env` files**: protecting the generated file on disk is the job of the environment that consumes it
|
|
82
|
+
- **Ship a graphical interface**: the CLI, GitHub Action and SDKs are the supported surfaces
|
|
56
83
|
|
|
57
84
|
---
|
|
58
85
|
|
package/docs/SECURITY.md
CHANGED
|
@@ -9,6 +9,12 @@ We release patches for security vulnerabilities only in the latest version:
|
|
|
9
9
|
| Latest | β
|
|
|
10
10
|
| Older | β |
|
|
11
11
|
|
|
12
|
+
## π― Security Requirements
|
|
13
|
+
|
|
14
|
+
Envilder reads secrets from AWS SSM Parameter Store or Azure Key Vault with your own credentials and writes them only to the `.env` file, process environment or application configuration you ask for. It never logs secret values, runs no server and implements no cryptography of its own.
|
|
15
|
+
|
|
16
|
+
It does not protect the generated `.env` file, the command started by `envilder exec`, or a map file that someone with write access to your repository has changed. The full list of what you can and cannot expect, together with the threat model, trust boundaries and the reasoning behind them, is in the [Security Requirements and Assurance Case](./security-assurance-case.md).
|
|
17
|
+
|
|
12
18
|
## π¨ Reporting a Vulnerability
|
|
13
19
|
|
|
14
20
|
**Please do not report security vulnerabilities through public GitHub issues.**
|
|
@@ -17,18 +23,22 @@ If you discover a security vulnerability in Envilder, please report it privately
|
|
|
17
23
|
|
|
18
24
|
### How to Report
|
|
19
25
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
26
|
+
Use either channel:
|
|
27
|
+
|
|
28
|
+
- **GitHub (preferred)**: [open a private security advisory](https://github.com/macalbert/envilder/security/advisories/new)
|
|
29
|
+
- **Email**: send details to <mac.albert@gmail.com> with the subject `[SECURITY] Envilder - [Brief Description]`
|
|
30
|
+
|
|
31
|
+
Please include:
|
|
32
|
+
|
|
33
|
+
- Description of the vulnerability
|
|
34
|
+
- Steps to reproduce the issue
|
|
35
|
+
- Potential impact
|
|
36
|
+
- Suggested fix (if available)
|
|
37
|
+
- Your contact information for follow-up
|
|
28
38
|
|
|
29
39
|
### What to Expect
|
|
30
40
|
|
|
31
|
-
- **Acknowledgment**: I
|
|
41
|
+
- **Acknowledgment**: I aim to acknowledge every report within 14 days
|
|
32
42
|
- **Initial Assessment**: I'll provide an initial assessment and prioritize based on severity
|
|
33
43
|
- **Updates**: I'll keep you informed about the progress
|
|
34
44
|
- **Resolution**: I'll work to release a fix as soon as feasible (timeline depends on severity and complexity)
|
|
@@ -131,11 +141,27 @@ When using Envilder GitHub Action:
|
|
|
131
141
|
- β Store AWS credentials in GitHub Secrets (use OIDC roles)
|
|
132
142
|
- β Use overly permissive IAM policies
|
|
133
143
|
|
|
144
|
+
## π Verifying Releases
|
|
145
|
+
|
|
146
|
+
Packages are built and published only by GitHub Actions workflows in this repository, using OIDC instead of long-lived registry tokens.
|
|
147
|
+
|
|
148
|
+
- **npm** (`envilder`, `@envilder/sdk`): published with [npm provenance](https://docs.npmjs.com/generating-provenance-statements), signed through Sigstore. After installing, run `npm audit signatures` in your project to verify the registry signatures and provenance attestations. The npm package page also links each version to the commit and workflow run that built it.
|
|
149
|
+
- **PyPI** (`envilder`): published with [PEP 740 attestations](https://docs.pypi.org/attestations/) through trusted publishing. The "Provenance" section of each file on PyPI shows the source repository and workflow. To verify locally:
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
pip install pypi-attestations
|
|
153
|
+
pypi-attestations verify pypi --repository https://github.com/macalbert/envilder pypi:envilder-<version>-py3-none-any.whl
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
- **NuGet** (`Envilder`): every package carries the NuGet.org repository signature, which you can check with `dotnet nuget verify Envilder.<version>.nupkg`.
|
|
157
|
+
- **GitHub Action**: referenced directly from this repository. For an immutable reference, pin the action to a full commit SHA instead of a tag.
|
|
158
|
+
|
|
134
159
|
## π Security Audits
|
|
135
160
|
|
|
136
161
|
This project uses:
|
|
137
162
|
|
|
138
163
|
- **Snyk**: Vulnerability scanning for dependencies
|
|
164
|
+
- **CodeQL**: Static analysis for security issues in the TypeScript code
|
|
139
165
|
- **Secretlint**: Prevents accidental secret commits
|
|
140
166
|
- **Biome**: Code quality and security linting
|
|
141
167
|
- **Dependabot**: Automated dependency updates
|
package/docs/changelogs/cli.md
CHANGED
|
@@ -5,6 +5,23 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
|
|
|
5
5
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
+
## [0.15.1] - 2026-10-22
|
|
9
|
+
|
|
10
|
+
### Security
|
|
11
|
+
|
|
12
|
+
* Update development and build dependencies to resolve open advisories:
|
|
13
|
+
`undici` 8.10.2 β 8.12.3 (via `testcontainers`), `brace-expansion`,
|
|
14
|
+
`@grpc/grpc-js` and `@vitest/mocker`. The published `envilder` package and
|
|
15
|
+
its runtime dependencies are unchanged
|
|
16
|
+
([#609](https://github.com/macalbert/envilder/pull/609))
|
|
17
|
+
|
|
18
|
+
### Dependencies
|
|
19
|
+
|
|
20
|
+
* Bump `testcontainers` and `@testcontainers/localstack` from 12.2.0 to 12.2.1
|
|
21
|
+
* Bump `vitest` and `@vitest/coverage-v8` from 4.1.11 to 4.1.12
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
8
25
|
## [0.15.0] - 2026-10-16
|
|
9
26
|
|
|
10
27
|
### Added
|
|
@@ -25,7 +42,8 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
|
|
|
25
42
|
code, `128+n` for signals, `125` for Envilder errors, `126` and `127` when
|
|
26
43
|
the command cannot be executed or found. `SIGTERM` and `SIGHUP` are
|
|
27
44
|
forwarded and the command is awaited without a timeout, even if a signal
|
|
28
|
-
cannot be delivered.
|
|
45
|
+
cannot be delivered. An expired AWS SSO session is recovered interactively
|
|
46
|
+
before the command starts. Exec mode is not a sandbox: see
|
|
29
47
|
[docs/exec-command.md](../exec-command.md)
|
|
30
48
|
([#550](https://github.com/macalbert/envilder/issues/550))
|
|
31
49
|
|
|
@@ -127,7 +145,7 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
|
|
|
127
145
|
|
|
128
146
|
---
|
|
129
147
|
|
|
130
|
-
## [0.13.0] - 2026-
|
|
148
|
+
## [0.13.0] - 2026-07-11
|
|
131
149
|
|
|
132
150
|
### Added
|
|
133
151
|
|
|
@@ -218,6 +236,20 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
|
|
|
218
236
|
|
|
219
237
|
---
|
|
220
238
|
|
|
239
|
+
## [0.11.1] - 2026-06-25
|
|
240
|
+
|
|
241
|
+
### Fixed
|
|
242
|
+
|
|
243
|
+
* **AWS SSO / assumed-role profiles now resolve correctly**: Selecting an
|
|
244
|
+
SSO, IAM Identity Center, or assumed-role profile (via `--profile` or
|
|
245
|
+
`$config.profile`) now resolves credentials through the full AWS provider
|
|
246
|
+
chain instead of silently falling back to the default credentials.
|
|
247
|
+
Previously these profiles were ignored, reading and writing secrets against
|
|
248
|
+
the wrong AWS account
|
|
249
|
+
([#364](https://github.com/macalbert/envilder/issues/364))
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
221
253
|
## [0.11.0] - 2026-05-31
|
|
222
254
|
|
|
223
255
|
### Changed
|
|
@@ -244,7 +276,7 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
|
|
|
244
276
|
published at `https://envilder.com/schema/map-file.v1.json`. Add
|
|
245
277
|
`"$schema": "https://envilder.com/schema/map-file.v1.json"` to any map file
|
|
246
278
|
for IDE autocomplete, inline documentation, and validation
|
|
247
|
-
([#
|
|
279
|
+
([#217](https://github.com/macalbert/envilder/pull/217))
|
|
248
280
|
* **Schema contract tests**: 39 tests validating the JSON Schema across all
|
|
249
281
|
providers (AWS, Azure, GCP, HashiCorp Vault, file)
|
|
250
282
|
|
|
@@ -374,6 +406,7 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
|
|
|
374
406
|
### Fixed
|
|
375
407
|
|
|
376
408
|
* **deps:** Move `@types/node` from `dependencies` to `devDependencies` to prevent it from being bundled as a runtime dependency
|
|
409
|
+
([#135](https://github.com/macalbert/envilder/pull/135))
|
|
377
410
|
* **e2e:** Use unique SSM paths per CLI test run to prevent race conditions between parallel test executions
|
|
378
411
|
|
|
379
412
|
### Dependencies
|
|
@@ -383,7 +416,7 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
|
|
|
383
416
|
|
|
384
417
|
---
|
|
385
418
|
|
|
386
|
-
## [0.8.0] - 2026-03-
|
|
419
|
+
## [0.8.0] - 2026-03-26
|
|
387
420
|
|
|
388
421
|
### Added
|
|
389
422
|
|
|
@@ -397,6 +430,13 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
|
|
|
397
430
|
* New infrastructure adapter: `AzureKeyVaultSecretProvider` implementing `ISecretProvider`
|
|
398
431
|
* New CLI option `--provider <name>` to select cloud provider (`aws` or `azure`, default: `aws`)
|
|
399
432
|
* Azure authentication via `DefaultAzureCredential` (supports Azure CLI, managed identity, etc.)
|
|
433
|
+
* Automatic secret name normalization for Key Vault naming constraints (alphanumeric and hyphens,
|
|
434
|
+
1β127 characters)
|
|
435
|
+
|
|
436
|
+
### Security
|
|
437
|
+
|
|
438
|
+
* **Vault URL validation**: Azure Key Vault URLs must use HTTPS and match an Azure domain allowlist
|
|
439
|
+
(with dot-boundary checks), preventing SSRF through spoofed hostnames
|
|
400
440
|
|
|
401
441
|
### Changed
|
|
402
442
|
|
|
@@ -748,3 +788,52 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
|
|
|
748
788
|
|
|
749
789
|
* CLI command not recognized after global install (`npm install -g envilder`)
|
|
750
790
|
* Fixed missing compiled `lib/` files in published package
|
|
791
|
+
|
|
792
|
+
---
|
|
793
|
+
|
|
794
|
+
## [0.3.0] - 2025-05-09
|
|
795
|
+
|
|
796
|
+
### Added
|
|
797
|
+
|
|
798
|
+
* **`--profile` option**: Choose which AWS CLI profile to use for credentials,
|
|
799
|
+
so you can work with different AWS accounts or configurations
|
|
800
|
+
([#31](https://github.com/macalbert/envilder/pull/31))
|
|
801
|
+
|
|
802
|
+
### Dependencies
|
|
803
|
+
|
|
804
|
+
* Bumped commander from 12.1.0 to 13.1.0, @aws-sdk/client-ssm, @types/node,
|
|
805
|
+
vite and @secretlint/secretlint-rule-preset-recommend
|
|
806
|
+
|
|
807
|
+
---
|
|
808
|
+
|
|
809
|
+
## [0.2.3] - 2025-04-13
|
|
810
|
+
|
|
811
|
+
### Dependencies
|
|
812
|
+
|
|
813
|
+
* Bumped @aws-sdk/client-ssm from 3.670.0 to 3.716.0
|
|
814
|
+
* Bumped nanoid (security patch), @types/node, @biomejs/biome, secretlint and
|
|
815
|
+
@secretlint/secretlint-rule-preset-recommend
|
|
816
|
+
|
|
817
|
+
---
|
|
818
|
+
|
|
819
|
+
## [0.2.1] - 2024-10-16
|
|
820
|
+
|
|
821
|
+
### Added
|
|
822
|
+
|
|
823
|
+
* **Preserve existing `.env` variables**: When the target `.env` already
|
|
824
|
+
exists, its variables are kept and only the mapped ones are added or updated
|
|
825
|
+
([#5](https://github.com/macalbert/envilder/pull/5))
|
|
826
|
+
* Secret values are masked in console output
|
|
827
|
+
* Code coverage reporting published to GitHub Pages
|
|
828
|
+
([#2](https://github.com/macalbert/envilder/pull/2))
|
|
829
|
+
* CodeQL code scanning ([#4](https://github.com/macalbert/envilder/pull/4))
|
|
830
|
+
|
|
831
|
+
---
|
|
832
|
+
|
|
833
|
+
## [0.1.4] - 2024-10-01
|
|
834
|
+
|
|
835
|
+
### Added
|
|
836
|
+
|
|
837
|
+
* **Initial release**: Generate `.env` files from AWS SSM Parameter Store
|
|
838
|
+
using a JSON map of environment variable names to SSM parameter paths
|
|
839
|
+
* Supports both encrypted (`SecureString`) and plain SSM parameters
|
package/docs/changelogs/gha.md
CHANGED
|
@@ -1,3 +1,14 @@
|
|
|
1
|
+
## [0.15.1] - 2026-10-22
|
|
2
|
+
|
|
3
|
+
### Security
|
|
4
|
+
|
|
5
|
+
* Update development and build dependencies to resolve open advisories
|
|
6
|
+
(`undici`, `brace-expansion`, `@grpc/grpc-js`, `@vitest/mocker`). The
|
|
7
|
+
Action bundle and its runtime dependencies are unchanged
|
|
8
|
+
([#609](https://github.com/macalbert/envilder/pull/609))
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
1
12
|
## [0.15.0] - 2026-10-16
|
|
2
13
|
|
|
3
14
|
### Changed
|
|
@@ -63,6 +74,13 @@
|
|
|
63
74
|
|
|
64
75
|
## [0.13.1] - 2026-07-31
|
|
65
76
|
|
|
77
|
+
### Added
|
|
78
|
+
|
|
79
|
+
* **GitHub Marketplace listing and root reference**: A root `action.yml`
|
|
80
|
+
publishes the Action to the GitHub Marketplace and lets workflows use it as
|
|
81
|
+
`macalbert/envilder@<version>`. The `macalbert/envilder/github-action@v0`
|
|
82
|
+
reference keeps working.
|
|
83
|
+
|
|
66
84
|
### Changed
|
|
67
85
|
|
|
68
86
|
* **Bundle the GitHub Action with esbuild**: Replace the ncc bundler so the
|
|
@@ -74,7 +92,7 @@
|
|
|
74
92
|
|
|
75
93
|
---
|
|
76
94
|
|
|
77
|
-
## [0.13.0] - 2026-
|
|
95
|
+
## [0.13.0] - 2026-07-11
|
|
78
96
|
|
|
79
97
|
### Added
|
|
80
98
|
|
|
@@ -154,6 +172,18 @@
|
|
|
154
172
|
|
|
155
173
|
---
|
|
156
174
|
|
|
175
|
+
## [0.11.1] - 2026-06-25
|
|
176
|
+
|
|
177
|
+
### Fixed
|
|
178
|
+
|
|
179
|
+
* **AWS SSO / assumed-role profiles now resolve correctly**: The bundled CLI
|
|
180
|
+
now resolves SSO, IAM Identity Center, and assumed-role profiles (via the
|
|
181
|
+
`profile` input or `$config.profile`) through the full AWS provider chain
|
|
182
|
+
instead of silently falling back to the default credentials
|
|
183
|
+
([#364](https://github.com/macalbert/envilder/issues/364))
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
157
187
|
## [0.11.0] - 2026-05-31
|
|
158
188
|
|
|
159
189
|
### Changed
|
|
@@ -216,7 +246,7 @@
|
|
|
216
246
|
|
|
217
247
|
---
|
|
218
248
|
|
|
219
|
-
## [0.8.0] - 2026-03-
|
|
249
|
+
## [0.8.0] - 2026-03-26
|
|
220
250
|
|
|
221
251
|
### Added
|
|
222
252
|
|
|
@@ -1,3 +1,17 @@
|
|
|
1
|
+
## [0.5.2] - 2026-10-16
|
|
2
|
+
|
|
3
|
+
### Fixed
|
|
4
|
+
|
|
5
|
+
* **AWS SSO / IAM Identity Center profiles resolve again**: The
|
|
6
|
+
`AWSSDK.SSO` and `AWSSDK.SSOOIDC` dependencies added in 0.4.1 were lost in
|
|
7
|
+
0.5.0, so SSO profiles (via `WithProfile()` or `$config.profile`) could fail
|
|
8
|
+
with `Assembly AWSSDK.SSOOIDC could not be found` instead of resolving
|
|
9
|
+
credentials. Both packages are referenced again, and a regression test now
|
|
10
|
+
fails the build if the SDK stops shipping them
|
|
11
|
+
([#364](https://github.com/macalbert/envilder/issues/364))
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
1
15
|
## [0.5.1] - 2026-09-26
|
|
2
16
|
|
|
3
17
|
### Documentation
|
|
@@ -8,7 +22,7 @@
|
|
|
8
22
|
|
|
9
23
|
---
|
|
10
24
|
|
|
11
|
-
## [0.5.0] - 2026-
|
|
25
|
+
## [0.5.0] - 2026-07-11
|
|
12
26
|
|
|
13
27
|
### Added
|
|
14
28
|
|
|
@@ -26,6 +40,19 @@
|
|
|
26
40
|
|
|
27
41
|
---
|
|
28
42
|
|
|
43
|
+
## [0.4.1] - 2026-06-25
|
|
44
|
+
|
|
45
|
+
### Fixed
|
|
46
|
+
|
|
47
|
+
* **AWS SSO / assumed-role profiles now resolve at runtime**: Added the
|
|
48
|
+
`AWSSDK.SSO` and `AWSSDK.SSOOIDC` dependencies so SSO and IAM Identity
|
|
49
|
+
Center profiles (via `WithProfile()` or `$config.profile`) build their
|
|
50
|
+
credentials at runtime. Previously these profiles threw
|
|
51
|
+
`Assembly AWSSDK.SSOOIDC could not be found`
|
|
52
|
+
([#364](https://github.com/macalbert/envilder/issues/364))
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
29
56
|
## [0.4.0] - 2026-05-18
|
|
30
57
|
|
|
31
58
|
### Changed
|
|
@@ -159,7 +186,7 @@ may need to add them explicitly.
|
|
|
159
186
|
### Added
|
|
160
187
|
|
|
161
188
|
* **Initial release**: Runtime library for loading secrets from AWS SSM Parameter Store or Azure Key Vault
|
|
162
|
-
directly into .NET applications ([#
|
|
189
|
+
directly into .NET applications ([#146](https://github.com/macalbert/envilder/pull/146))
|
|
163
190
|
* `EnvilderClient`: Resolves secrets from a map-file and returns them as a dictionary
|
|
164
191
|
* `MapFileParser`: Parses `envilder.json` files with `$config` section and variable mappings
|
|
165
192
|
* `SecretProviderFactory`: Creates the appropriate secret provider based on configuration
|
|
@@ -171,6 +198,11 @@ may need to add them explicitly.
|
|
|
171
198
|
* Targets .NET Standard 2.0 (compatible with .NET 6+, .NET Framework 4.6.1+)
|
|
172
199
|
* Published to NuGet as `Envilder`
|
|
173
200
|
|
|
201
|
+
### Fixed
|
|
202
|
+
|
|
203
|
+
* **Default AWS region**: `SecretProviderFactory` provides a default AWS region
|
|
204
|
+
when none is configured ([#147](https://github.com/macalbert/envilder/pull/147))
|
|
205
|
+
|
|
174
206
|
### Testing
|
|
175
207
|
|
|
176
208
|
* Unit tests with xUnit, NSubstitute, AwesomeAssertions, and AutoFixture
|
|
@@ -6,9 +6,15 @@
|
|
|
6
6
|
now links to the changelog and to `envilder.com/docs/sdks/nodejs/` with UTM
|
|
7
7
|
tags, so visits from npm to envilder.com can be measured
|
|
8
8
|
|
|
9
|
+
### Dependencies
|
|
10
|
+
|
|
11
|
+
* Raise the minimum AWS SDK versions: `@aws-sdk/client-ssm` and
|
|
12
|
+
`@aws-sdk/credential-providers` now require `^3.1101.0` (previously
|
|
13
|
+
`^3.700.0`)
|
|
14
|
+
|
|
9
15
|
---
|
|
10
16
|
|
|
11
|
-
## [0.4.0] - 2026-
|
|
17
|
+
## [0.4.0] - 2026-07-11
|
|
12
18
|
|
|
13
19
|
### Added
|
|
14
20
|
|
|
@@ -24,10 +30,6 @@
|
|
|
24
30
|
session token still throws `ExpiredCredentialsError`
|
|
25
31
|
([#379](https://github.com/macalbert/envilder/issues/379))
|
|
26
32
|
|
|
27
|
-
---
|
|
28
|
-
|
|
29
|
-
## [0.3.1] - 2026-06-26
|
|
30
|
-
|
|
31
33
|
### Fixed
|
|
32
34
|
|
|
33
35
|
* **Honor the `profile` option for the AWS region, not just credentials**:
|
|
@@ -42,6 +44,19 @@
|
|
|
42
44
|
|
|
43
45
|
---
|
|
44
46
|
|
|
47
|
+
## [0.3.1] - 2026-06-25
|
|
48
|
+
|
|
49
|
+
### Fixed
|
|
50
|
+
|
|
51
|
+
* **AWS SSO / assumed-role profiles now resolve correctly**: `withProfile()`
|
|
52
|
+
and `$config.profile` now resolve credentials through the full AWS provider
|
|
53
|
+
chain (`fromNodeProviderChain`), including SSO token resolution. Previously
|
|
54
|
+
SSO and assumed-role profiles were silently ignored, falling back to the
|
|
55
|
+
default credentials
|
|
56
|
+
([#364](https://github.com/macalbert/envilder/issues/364))
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
45
60
|
## [0.3.0] - 2026-05-31
|
|
46
61
|
|
|
47
62
|
### Changed
|
|
@@ -91,6 +106,8 @@
|
|
|
91
106
|
* **Initial release**: Node.js runtime SDK for loading secrets directly
|
|
92
107
|
into `process.env` from a map file. Supports AWS SSM Parameter Store and
|
|
93
108
|
Azure Key Vault
|
|
109
|
+
* **Batched AWS fetching**: Up to 10 SSM parameters per request
|
|
110
|
+
([#170](https://github.com/macalbert/envilder/pull/170))
|
|
94
111
|
* **Envilder facade**: `load()`, `resolveFile()`, `fromMapFile()` fluent
|
|
95
112
|
builder for one-liner or fine-grained secret loading
|
|
96
113
|
* **EnvilderClient**: Core resolver with `resolveSecrets()` and
|
|
@@ -1,3 +1,21 @@
|
|
|
1
|
+
## [0.5.2] - 2026-10-22
|
|
2
|
+
|
|
3
|
+
### Security
|
|
4
|
+
|
|
5
|
+
* Update `certifi` from 2026.2.25 to 2026.10.19 in the SDK lockfile to
|
|
6
|
+
resolve GHSA-6q48-6c7w-9gw2. `certifi` is a transitive dependency (via
|
|
7
|
+
`requests` in the Azure clients); the package's declared dependency ranges are
|
|
8
|
+
unchanged ([#609](https://github.com/macalbert/envilder/pull/609))
|
|
9
|
+
|
|
10
|
+
### Dependencies
|
|
11
|
+
|
|
12
|
+
* Bump `pyjwt` from 2.13.0 to 2.15.0 in the SDK lockfile
|
|
13
|
+
([#534](https://github.com/macalbert/envilder/pull/534))
|
|
14
|
+
* Bump `urllib3` from 2.7.0 to 2.8.0 in the SDK lockfile
|
|
15
|
+
([#535](https://github.com/macalbert/envilder/pull/535))
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
1
19
|
## [0.5.1] - 2026-09-26
|
|
2
20
|
|
|
3
21
|
### Documentation
|
|
@@ -8,7 +26,7 @@
|
|
|
8
26
|
|
|
9
27
|
---
|
|
10
28
|
|
|
11
|
-
## [0.5.0] - 2026-
|
|
29
|
+
## [0.5.0] - 2026-07-11
|
|
12
30
|
|
|
13
31
|
### Added
|
|
14
32
|
|
|
@@ -108,7 +126,6 @@
|
|
|
108
126
|
* **Initial release**: Runtime library for loading secrets from AWS SSM Parameter Store or
|
|
109
127
|
Azure Key Vault directly into Python applications
|
|
110
128
|
([#157](https://github.com/macalbert/envilder/pull/157))
|
|
111
|
-
* `Envilder` facade: High-level entry point with `load()`, `resolve_file()`, and `from_map_file()` methods
|
|
112
129
|
* `EnvilderClient`: Resolves secrets from a map-file and injects them into `os.environ`
|
|
113
130
|
* `MapFileParser`: Parses `envilder.json` files with `$config` section and variable mappings
|
|
114
131
|
* `SecretProviderFactory`: Creates the appropriate secret provider based on configuration
|
package/docs/exec-command.md
CHANGED
|
@@ -112,9 +112,13 @@ options are rejected before any provider call, with exit code `125`:
|
|
|
112
112
|
|
|
113
113
|
### No shell
|
|
114
114
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
115
|
+
Envilder does not start an extra shell: arguments are passed to the command as
|
|
116
|
+
an argument list. Your own shell still parses the command line first, so quote
|
|
117
|
+
what it should not interpret. `'$DB_URL'` or `'&&'` in single quotes reach the
|
|
118
|
+
command literally, while an unquoted `$DB_URL` expands to your shell's value
|
|
119
|
+
(not the resolved secret) and an unquoted `&&` runs a second command outside
|
|
120
|
+
`envilder exec`. If you need shell features with the secrets, start a shell
|
|
121
|
+
explicitly:
|
|
118
122
|
|
|
119
123
|
```bash
|
|
120
124
|
envilder exec -- sh -c 'echo $DB_URL'
|
|
@@ -131,6 +135,169 @@ via `cmd.exe /d /s /c` with every argument escaped. Two visible consequences:
|
|
|
131
135
|
still `127`.
|
|
132
136
|
* `cmd.exe` builtins such as `echo` or `dir` resolve and run.
|
|
133
137
|
|
|
138
|
+
## Common use cases
|
|
139
|
+
|
|
140
|
+
In every case Envilder passes the values to the command and the processes it
|
|
141
|
+
starts without creating a `.env` file, and the command's exit code becomes
|
|
142
|
+
Envilder's exit code. What the command does with the values afterwards is up
|
|
143
|
+
to it: Docker, for example, stores a container's environment in its on-disk
|
|
144
|
+
container metadata (visible with `docker inspect`) until the container is
|
|
145
|
+
removed, and a stopped `docker compose up` leaves its containers behind until
|
|
146
|
+
`docker compose down`. The paths follow the
|
|
147
|
+
`/<project>/<environment>/<service>/<key>` style used in
|
|
148
|
+
[envilder-examples](https://github.com/macalbert/envilder-examples).
|
|
149
|
+
|
|
150
|
+
### Start LocalStack with its auth token
|
|
151
|
+
|
|
152
|
+
When you need it: LocalStack needs `LOCALSTACK_AUTH_TOKEN` and you do not want
|
|
153
|
+
the token in a `.env` file or in your shell history.
|
|
154
|
+
|
|
155
|
+
```json
|
|
156
|
+
{
|
|
157
|
+
"LOCALSTACK_AUTH_TOKEN": "/envilder/development/localstack/authToken"
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
With Docker Compose, reference the variable in `compose.yaml`. Compose
|
|
162
|
+
interpolates `${...}` from the environment it runs in, so no `.env` file is
|
|
163
|
+
needed:
|
|
164
|
+
|
|
165
|
+
```yaml
|
|
166
|
+
services:
|
|
167
|
+
localstack:
|
|
168
|
+
image: localstack/localstack:stable
|
|
169
|
+
ports:
|
|
170
|
+
- "4566:4566"
|
|
171
|
+
environment:
|
|
172
|
+
LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
envilder exec -- docker compose up
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
With plain Docker, `-e NAME` without a value copies the variable from the
|
|
180
|
+
environment of the `docker` client, so the token never appears on the command
|
|
181
|
+
line:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
envilder exec -- docker run --rm -e LOCALSTACK_AUTH_TOKEN -p 4566:4566 localstack/localstack:stable
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
[envilder-examples](https://github.com/macalbert/envilder-examples) has the
|
|
188
|
+
same setup with Testcontainers (TypeScript, Python, .NET) and Aspire.
|
|
189
|
+
|
|
190
|
+
### Integration tests that start containers
|
|
191
|
+
|
|
192
|
+
When you need it: your tests start containers (for example with
|
|
193
|
+
Testcontainers) and read a token or credentials from the environment
|
|
194
|
+
(`process.env`, `os.environ`, `Environment.GetEnvironmentVariable`) to pass
|
|
195
|
+
them in.
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
envilder exec -- npm test
|
|
199
|
+
envilder exec -- dotnet test
|
|
200
|
+
envilder exec -- pytest
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
A failing test run keeps its exit code, so CI still fails. If a secret cannot
|
|
204
|
+
be resolved, the tests do not start and the exit code is `125`.
|
|
205
|
+
|
|
206
|
+
### Database migrations and one-off scripts
|
|
207
|
+
|
|
208
|
+
When you need it: a migration tool or a script needs `DATABASE_URL` once, and
|
|
209
|
+
you do not want the connection string on disk.
|
|
210
|
+
|
|
211
|
+
```json
|
|
212
|
+
{
|
|
213
|
+
"DATABASE_URL": "/my-app/development/database/url"
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
envilder exec -- npx prisma migrate deploy
|
|
219
|
+
envilder exec -- python scripts/backfill.py
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Use `--map` to run the same command against another environment, for example
|
|
223
|
+
`envilder exec --map=config/envilder.staging.json -- npx prisma migrate deploy`.
|
|
224
|
+
|
|
225
|
+
### Terraform and other IaC tools
|
|
226
|
+
|
|
227
|
+
When you need it: a Terraform input variable holds a secret. Terraform reads
|
|
228
|
+
`TF_VAR_<name>` environment variables as values for the input variable
|
|
229
|
+
`<name>`.
|
|
230
|
+
|
|
231
|
+
```json
|
|
232
|
+
{
|
|
233
|
+
"TF_VAR_db_password": "/my-app/development/database/password"
|
|
234
|
+
}
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
envilder exec -- terraform plan
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
Declare the variable with `sensitive = true` so Terraform hides it in plan
|
|
242
|
+
output. Terraform still stores values it writes into resources in its state,
|
|
243
|
+
so protect the state as usual.
|
|
244
|
+
|
|
245
|
+
### Local dev server through package scripts
|
|
246
|
+
|
|
247
|
+
When you need it: everyone on the team should start the app with the same
|
|
248
|
+
secrets by running `npm run dev`.
|
|
249
|
+
|
|
250
|
+
```json
|
|
251
|
+
{
|
|
252
|
+
"scripts": {
|
|
253
|
+
"dev": "envilder exec -- next dev"
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Add `envilder` as a dev dependency (`npm install --save-dev envilder`) so the
|
|
259
|
+
script finds it in `node_modules/.bin`.
|
|
260
|
+
|
|
261
|
+
### A step in GitHub Actions
|
|
262
|
+
|
|
263
|
+
When you need it: one step of a workflow needs the secrets, and only that step.
|
|
264
|
+
Configure AWS credentials with OIDC, then run the command through
|
|
265
|
+
`npx envilder exec`:
|
|
266
|
+
|
|
267
|
+
```yaml
|
|
268
|
+
permissions:
|
|
269
|
+
id-token: write # Required for OIDC
|
|
270
|
+
contents: read
|
|
271
|
+
|
|
272
|
+
steps:
|
|
273
|
+
- uses: actions/checkout@v5
|
|
274
|
+
- uses: aws-actions/configure-aws-credentials@v5
|
|
275
|
+
with:
|
|
276
|
+
role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
|
|
277
|
+
aws-region: us-east-1
|
|
278
|
+
- run: npx envilder exec -- npm test
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
Resolved values are registered with GitHub's log masking before the command
|
|
282
|
+
starts, and the next steps do not see them. See
|
|
283
|
+
[GitHub Actions masking](#github-actions-masking).
|
|
284
|
+
|
|
285
|
+
### Several commands with the same secrets
|
|
286
|
+
|
|
287
|
+
When you need it: you want to chain commands or keep working in a shell that
|
|
288
|
+
has the secrets.
|
|
289
|
+
|
|
290
|
+
```bash
|
|
291
|
+
envilder exec -- sh -c 'npm run migrate && exec npm start'
|
|
292
|
+
envilder exec -- bash
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
Quote the whole `sh -c` script in single quotes so your own shell does not run
|
|
296
|
+
`&&` outside `envilder exec` (see [No shell](#no-shell)). The `exec` before
|
|
297
|
+
the last command replaces the shell with it, so signals forwarded by Envilder
|
|
298
|
+
reach `npm start` directly. In the interactive shell every command you run sees
|
|
299
|
+
the secrets; type `exit` to leave it.
|
|
300
|
+
|
|
134
301
|
## Exit codes
|
|
135
302
|
|
|
136
303
|
Exit codes follow GNU `env` and `docker run`, so you can tell an Envilder
|
|
@@ -289,8 +456,9 @@ Limitations:
|
|
|
289
456
|
|
|
290
457
|
## Not a sandbox
|
|
291
458
|
|
|
292
|
-
Exec mode
|
|
293
|
-
|
|
459
|
+
Exec mode never creates a `.env` file, and it leaves any existing one
|
|
460
|
+
untouched: if you are moving from pull mode, delete your old `.env`
|
|
461
|
+
yourself. **It does not isolate the process.**
|
|
294
462
|
|
|
295
463
|
* Your command and **every process it starts** have the secrets in their
|
|
296
464
|
environment and can read them. That includes any tool or AI coding agent that
|
|
@@ -311,3 +479,14 @@ Only run commands you trust with the secrets you map.
|
|
|
311
479
|
temp directory or any Envilder configuration directory.
|
|
312
480
|
* The GitHub Action and the runtime SDKs do not offer exec mode. The SDKs
|
|
313
481
|
already resolve secrets in-process.
|
|
482
|
+
|
|
483
|
+
## Examples
|
|
484
|
+
|
|
485
|
+
[envilder-examples](https://github.com/macalbert/envilder-examples) has runnable setups:
|
|
486
|
+
|
|
487
|
+
* The repository README starts LocalStack with `envilder exec docker run ...`,
|
|
488
|
+
passing the auth token from AWS SSM into the container without a `.env`
|
|
489
|
+
file. Docker itself keeps the container's environment in its metadata until
|
|
490
|
+
the container is removed.
|
|
491
|
+
* The [`cli`](https://github.com/macalbert/envilder-examples/tree/main/cli)
|
|
492
|
+
folder walks through push, pull and exec with `npx envilder`.
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "envilder",
|
|
3
|
-
"version": "0.15.
|
|
3
|
+
"version": "0.15.1",
|
|
4
4
|
"packageManager": "pnpm@12.3.4+sha512.961aa41fb077da3a04a441d9f8e15ebc0c96da8ef710b2eb67bf9ee7cb0610eabd48f1fd85f51cffe73846785fa0f87c56a3a872a1d893f8446741b5cce45457",
|
|
5
|
-
"description": "Open-source
|
|
5
|
+
"description": "Open-source CLI, GitHub Action, and runtime SDKs for AWS SSM Parameter Store and Azure Key Vault secrets. Run any command with secrets injected (envilder exec), generate .env files, or load them in-process.",
|
|
6
6
|
"homepage": "https://envilder.com",
|
|
7
7
|
"author": {
|
|
8
8
|
"name": "MarΓ§al Albert CastellvΓ",
|
|
@@ -53,6 +53,9 @@
|
|
|
53
53
|
"ssm",
|
|
54
54
|
"parameter-store",
|
|
55
55
|
"cli",
|
|
56
|
+
"exec",
|
|
57
|
+
"secret-injection",
|
|
58
|
+
"run-with-secrets",
|
|
56
59
|
"sdk",
|
|
57
60
|
"environment",
|
|
58
61
|
"environment-variables",
|
|
@@ -93,9 +96,9 @@
|
|
|
93
96
|
],
|
|
94
97
|
"type": "module",
|
|
95
98
|
"dependencies": {
|
|
96
|
-
"@aws-sdk/client-ssm": "^3.
|
|
97
|
-
"@aws-sdk/client-sts": "^3.
|
|
98
|
-
"@aws-sdk/credential-providers": "^3.
|
|
99
|
+
"@aws-sdk/client-ssm": "^3.1149.0",
|
|
100
|
+
"@aws-sdk/client-sts": "^3.1149.0",
|
|
101
|
+
"@aws-sdk/credential-providers": "^3.1149.0",
|
|
99
102
|
"@azure/core-rest-pipeline": "^1.23.0",
|
|
100
103
|
"@azure/identity": "^4.13.1",
|
|
101
104
|
"@azure/keyvault-secrets": "^4.11.2",
|
|
@@ -111,7 +114,7 @@
|
|
|
111
114
|
"@commitlint/cli": "^21.2.0",
|
|
112
115
|
"@commitlint/config-conventional": "^21.2.0",
|
|
113
116
|
"@secretlint/secretlint-rule-preset-recommend": "^13.0.2",
|
|
114
|
-
"@testcontainers/localstack": "^12.
|
|
117
|
+
"@testcontainers/localstack": "^12.2.1",
|
|
115
118
|
"@types/cross-spawn": "^6.0.6",
|
|
116
119
|
"@types/node": "catalog:",
|
|
117
120
|
"@vitest/coverage-v8": "catalog:",
|
|
@@ -119,9 +122,9 @@
|
|
|
119
122
|
"ajv-formats": "^3.0.1",
|
|
120
123
|
"esbuild": "^0.28.1",
|
|
121
124
|
"glob": "^13.0.6",
|
|
122
|
-
"lefthook": "^2.1
|
|
125
|
+
"lefthook": "^2.2.1",
|
|
123
126
|
"secretlint": "^13.0.2",
|
|
124
|
-
"testcontainers": "^12.
|
|
127
|
+
"testcontainers": "^12.2.1",
|
|
125
128
|
"tsx": "catalog:",
|
|
126
129
|
"typescript": "catalog:",
|
|
127
130
|
"vitest": "catalog:"
|