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 CHANGED
@@ -14,8 +14,11 @@
14
14
  [![npm downloads](https://img.shields.io/npm/dm/envilder.svg)](https://npmcharts.com/compare/envilder)
15
15
  [![CI Tests](https://github.com/macalbert/envilder/actions/workflows/tests.yml/badge.svg)](https://github.com/macalbert/envilder/actions/workflows/tests.yml)
16
16
  [![Overall Coverage](https://macalbert.github.io/envilder/badge_combined.svg)](https://macalbert.github.io/envilder/)
17
+ [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15703/badge)](https://www.bestpractices.dev/projects/15703)
18
+ [![Known Vulnerabilities](https://snyk.io/test/github/macalbert/envilder/badge.svg)](https://snyk.io/test/github/macalbert/envilder)
17
19
  [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
18
20
  [![Context7](https://img.shields.io/badge/Context7-docs_for_AI_agents-blue.svg)](https://context7.com/macalbert/envilder)
21
+ [![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/macalbert/envilder?utm_source=oss&utm_medium=github&utm_campaign=macalbert%2Fenvilder&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)](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)** Β· πŸ’‘ **[Examples](./examples/sdk/dotnet/)**
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)** Β· πŸ’‘ **[Examples](./examples/sdk/python/)**
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)** Β· πŸ’‘ **[Examples](./examples/sdk/nodejs/)**
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) or in-memory (SDKs)
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, GCP Secret Manager, and exec mode.
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
- </p>
435
-
436
- <p align="center">
437
- Supported by <a href="https://localstack.cloud">LocalStack</a>.
457
+ &nbsp;&nbsp;&nbsp;
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
- | Feature | Notes |
22
- |---------|-------|
23
- | **Mapping-based resolution** | Core functionality |
24
- | **`.env` file generation** | Core functionality |
25
- | **AWS SSM Parameter Store** | Default provider |
26
- | **AWS profile support** | `--profile` flag |
27
- | **Push mode** (`--push`) | [Guide](./docs/push-command.md) |
28
- | **GitHub Action** | [Documentation](./github-action/README.md) |
29
- | **Azure Key Vault** | Multi-backend via `$config` map-file section ([#90](https://github.com/macalbert/envilder/pull/90)) |
30
- | **Documentation website** | [envilder.com](https://envilder.com) |
31
- | **Onboarding documentation** | [Setup guide](./docs/requirements-installation.md) |
32
- | **.NET SDK** (`Envilder`) | First runtime SDK: load secrets into `IConfiguration` or `EnvilderClient`. AWS SSM + Azure Key Vault. [Documentation](./src/sdks/dotnet/README.md) |
33
- | **Python SDK** (`envilder`) | Runtime library for Python: Django, FastAPI, data pipelines. Sync API with `EnvilderClient`, `MapFileParser`, `SecretProviderFactory`. AWS SSM + Azure Key Vault. Published to PyPI. [Documentation](./src/sdks/python/README.md) |
34
- | **Node.js SDK** (`@envilder/sdk`) | Runtime library for Node.js: load secrets directly into `process.env` from a map-file. AWS SSM + Azure Key Vault. Published to npm. [Documentation](./src/sdks/nodejs/README.md) |
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
- | **Exec mode** (`--exec`) | 🟑 Medium | Inject secrets into a child process env without writing to disk (`envilder exec -- node server.js`) |
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
- | **Exec with refresh** (`--refresh-interval`) | Low | Kill & restart child process periodically with fresh secrets (requires `--exec`) |
55
- | **Hierarchical mapping** | Low | Per-environment `envilder.json` with inheritance/overrides |
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
- 1. **Email**: Send details to <mac.albert@gmail.com>
21
- 2. **Subject**: `[SECURITY] Envilder - [Brief Description]`
22
- 3. **Include**:
23
- - Description of the vulnerability
24
- - Steps to reproduce the issue
25
- - Potential impact
26
- - Suggested fix (if available)
27
- - Your contact information for follow-up
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 will acknowledge your email as soon as possible
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
@@ -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. Exec mode is not a sandbox: see
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-06-26
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
- ([#218](https://github.com/macalbert/envilder/pull/218))
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-22
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
@@ -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-06-26
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-22
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-06-26
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 ([#147](https://github.com/macalbert/envilder/pull/147))
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-06-26
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-06-26
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
@@ -112,9 +112,13 @@ options are rejected before any provider call, with exit code `125`:
112
112
 
113
113
  ### No shell
114
114
 
115
- Arguments are passed to the command as an argument list, without a shell. The
116
- command receives `$DB_URL`, `%PATH%` or `&&` literally. If you need shell
117
- features, start a shell explicitly:
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 removes the `.env` file from disk. **It does not isolate the
293
- process.**
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.0",
3
+ "version": "0.15.1",
4
4
  "packageManager": "pnpm@12.3.4+sha512.961aa41fb077da3a04a441d9f8e15ebc0c96da8ef710b2eb67bf9ee7cb0610eabd48f1fd85f51cffe73846785fa0f87c56a3a872a1d893f8446741b5cce45457",
5
- "description": "Open-source TypeScript CLI, GitHub Action, and runtime SDKs for loading secrets from AWS SSM Parameter Store and Azure Key Vault.",
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.1101.0",
97
- "@aws-sdk/client-sts": "^3.1101.0",
98
- "@aws-sdk/credential-providers": "^3.1101.0",
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.0.4",
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.9",
125
+ "lefthook": "^2.2.1",
123
126
  "secretlint": "^13.0.2",
124
- "testcontainers": "^12.0.4",
127
+ "testcontainers": "^12.2.1",
125
128
  "tsx": "catalog:",
126
129
  "typescript": "catalog:",
127
130
  "vitest": "catalog:"