envilder 0.15.0 → 0.16.0

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.
Files changed (42) hide show
  1. package/README.md +80 -37
  2. package/ROADMAP.md +49 -22
  3. package/docs/SECURITY.md +35 -9
  4. package/docs/changelogs/cli.md +121 -4
  5. package/docs/changelogs/gha.md +43 -2
  6. package/docs/changelogs/sdk-dotnet.md +34 -2
  7. package/docs/changelogs/sdk-nodejs.md +22 -5
  8. package/docs/changelogs/sdk-python.md +19 -2
  9. package/docs/exec-command.md +184 -5
  10. package/lib/envilder/apps/cli/entry/Cli.d.ts.map +1 -1
  11. package/lib/envilder/apps/cli/entry/Cli.js +30 -12
  12. package/lib/envilder/apps/cli/entry/Cli.js.map +1 -1
  13. package/lib/envilder/core/application/dispatch/DispatchActionCommand.d.ts +6 -1
  14. package/lib/envilder/core/application/dispatch/DispatchActionCommand.d.ts.map +1 -1
  15. package/lib/envilder/core/application/dispatch/DispatchActionCommand.js +5 -2
  16. package/lib/envilder/core/application/dispatch/DispatchActionCommand.js.map +1 -1
  17. package/lib/envilder/core/application/dispatch/DispatchActionCommandHandler.d.ts.map +1 -1
  18. package/lib/envilder/core/application/dispatch/DispatchActionCommandHandler.js +1 -1
  19. package/lib/envilder/core/application/dispatch/DispatchActionCommandHandler.js.map +1 -1
  20. package/lib/envilder/core/application/pushSingle/PushSingleCommand.d.ts +11 -2
  21. package/lib/envilder/core/application/pushSingle/PushSingleCommand.d.ts.map +1 -1
  22. package/lib/envilder/core/application/pushSingle/PushSingleCommand.js +9 -3
  23. package/lib/envilder/core/application/pushSingle/PushSingleCommand.js.map +1 -1
  24. package/lib/envilder/core/application/pushSingle/PushSingleCommandHandler.d.ts +11 -1
  25. package/lib/envilder/core/application/pushSingle/PushSingleCommandHandler.d.ts.map +1 -1
  26. package/lib/envilder/core/application/pushSingle/PushSingleCommandHandler.js +116 -3
  27. package/lib/envilder/core/application/pushSingle/PushSingleCommandHandler.js.map +1 -1
  28. package/lib/envilder/core/domain/CliOptions.d.ts +11 -0
  29. package/lib/envilder/core/domain/CliOptions.d.ts.map +1 -1
  30. package/lib/envilder/core/domain/MapFileUpdate.d.ts +37 -0
  31. package/lib/envilder/core/domain/MapFileUpdate.d.ts.map +1 -0
  32. package/lib/envilder/core/domain/MapFileUpdate.js +105 -0
  33. package/lib/envilder/core/domain/MapFileUpdate.js.map +1 -0
  34. package/lib/envilder/core/domain/ports/IVariableStore.d.ts +9 -0
  35. package/lib/envilder/core/domain/ports/IVariableStore.d.ts.map +1 -1
  36. package/lib/envilder/core/infrastructure/variableStore/FileVariableStore.d.ts +3 -0
  37. package/lib/envilder/core/infrastructure/variableStore/FileVariableStore.d.ts.map +1 -1
  38. package/lib/envilder/core/infrastructure/variableStore/FileVariableStore.js +46 -0
  39. package/lib/envilder/core/infrastructure/variableStore/FileVariableStore.js.map +1 -1
  40. package/lib/iac/bin/main.js +2 -2
  41. package/lib/iac/bin/main.js.map +1 -1
  42. package/package.json +11 -8
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
 
@@ -30,11 +33,17 @@ them from AWS SSM or Azure Key Vault. The same mapping file works in local dev (
30
33
  CI/CD (GitHub Action), and application startup (runtime SDKs).
31
34
 
32
35
  ```bash
36
+ # Push a secret: it is stored in your cloud and mapped in envilder.json
37
+ npx envilder --key=API_KEY --value=s3cret --secret-path=/my-app/api-key
38
+
33
39
  # Zero-config: uses envilder.json and .env by default
34
40
  npx envilder
35
41
 
36
42
  # Or with explicit paths
37
43
  npx envilder --map=envilder.json --envfile=.env
44
+
45
+ # Or skip the file: run your app with the secrets in memory
46
+ npx envilder exec -- npm run dev
38
47
  ```
39
48
 
40
49
  No SaaS middleman. One versioned mapping contract. Secrets stay in your cloud.
@@ -49,6 +58,9 @@ No SaaS middleman. One versioned mapping contract. Secrets stay in your cloud.
49
58
  - **No single mapping contract.** Your cloud provider may be the source of truth for secret
50
59
  values, but each environment still needs to know how application variables map to those
51
60
  secrets. Without a versioned contract, dev, staging, and production configurations drift apart.
61
+ - **The `.env` file is readable by everything in your repo.** `.gitignore` keeps it out of commits,
62
+ not out of reach. Editors, indexers, install scripts, and AI coding agents can all read the
63
+ plaintext values sitting in your working tree.
52
64
 
53
65
  ## How Envilder solves it
54
66
 
@@ -56,6 +68,8 @@ No SaaS middleman. One versioned mapping contract. Secrets stay in your cloud.
56
68
  needs and where they live. Git-versioned, PR-reviewable, and reused across environments.
57
69
  - ⚡ **Works everywhere your code runs.** CLI for local dev, GitHub Action for CI/CD, runtime SDKs
58
70
  for application startup. Same file, same result.
71
+ - 🚫 **No `.env` file when you don't want one.** `envilder exec` starts any command with the
72
+ secrets in its environment, in any language, without writing anything to disk.
59
73
  - 🔄 **Rotate secrets without config drift.** Keep application-facing variable names stable while
60
74
  rotating real secret values in AWS SSM or Azure Key Vault. Generated `.env` files update only
61
75
  when Envilder runs again; runtime consumers must restart or resolve again.
@@ -69,6 +83,7 @@ No SaaS middleman. One versioned mapping contract. Secrets stay in your cloud.
69
83
  |---------|-------------|
70
84
  | 📋 **Declarative Mapping** | One JSON file defines how application variables map to cloud secrets. Git-versioned, PR-reviewable, and diff-able |
71
85
  | ☁️ **Cloud-native Providers** | AWS SSM and Azure Key Vault today |
86
+ | ⚡ **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
87
  | 🔌 **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
88
  | ⚙️ **GitHub Action** | Pull secrets in CI/CD. Same mapping, zero manual config |
74
89
  | 🔄 **Pull & Controlled Push** | Pull secrets to `.env`, or intentionally push local values to your cloud provider when bootstrapping or rotating |
@@ -88,46 +103,65 @@ Or install globally:
88
103
  npm install -g envilder
89
104
  ```
90
105
 
91
- > **Requirements:** Node.js v22.12+. Configure credentials and read access for either AWS SSM
92
- > or Azure Key Vault.
106
+ > **Requirements:** Node.js v22.12+. Configure credentials for either AWS SSM or Azure Key Vault,
107
+ > with read access, plus write access to push secrets.
93
108
  > See [full requirements](docs/requirements-installation.md).
94
109
 
95
- ### 2. Create a mapping file (`envilder.json`)
110
+ ### 2. Map your secrets (`envilder.json`)
96
111
 
97
- ```json
98
- {
99
- "$schema": "https://envilder.com/schema/map-file.v1.json",
100
- "DB_PASSWORD": "/my-app/db/password",
101
- "API_KEY": "/my-app/api-key"
102
- }
112
+ Push a secret and Envilder writes the mapping for you:
113
+
114
+ ```bash
115
+ npx envilder --key=API_KEY --value=s3cret --secret-path=/my-app/api-key
116
+ # ✓ Created envilder.json
117
+
118
+ npx envilder --key=DB_PASSWORD --value=pa55word --secret-path=/my-app/db/password
119
+ # ✓ Added DB_PASSWORD to envilder.json
103
120
  ```
104
121
 
105
- ### 3. Generate your `.env` file
122
+ The secrets are stored in AWS SSM, and `envilder.json` now maps each variable to its secret path:
106
123
 
107
- ```bash
108
- npx envilder
124
+ ```json
125
+ {
126
+ "API_KEY": "/my-app/api-key",
127
+ "DB_PASSWORD": "/my-app/db/password"
128
+ }
109
129
  ```
110
130
 
111
- That's it. With `envilder.json` in your current directory, no flags are needed — `--map` defaults to `envilder.json` and
112
- `--envfile` defaults to `.env`. Your secrets are pulled from AWS SSM and written to `.env`.
113
- Add `.env` to `.gitignore`. The mapping file is versioned and reviewable in PRs.
131
+ The values are never written to the file, so it is safe to commit and review in PRs. If your secrets already exist
132
+ in the cloud, write the same file by hand instead. Use `--map=<file>` to write a different file, or
133
+ `--no-map-update` to push without touching any map file.
134
+ See the [Push Command Guide](docs/push-command.md#single-variable-push) for the details.
114
135
 
115
- > 💡 Using Azure Key Vault? Add a `$config` section to your mapping file.
116
- > See [Mapping File Format](#️-mapping-file-format) below.
136
+ > 💡 Using Azure Key Vault? Add `--provider=azure --vault-url=https://my-vault.vault.azure.net` to the first push
137
+ > and Envilder writes the matching `$config`. See [Mapping File Format](#️-mapping-file-format) below.
117
138
 
118
- ### 4. Or skip the `.env` file entirely
139
+ ### 3. Run your app with the secrets
119
140
 
120
141
  ```bash
121
142
  npx envilder exec -- npm run dev
122
143
  ```
123
144
 
124
- `envilder exec` resolves the same mapping and starts your command with the secrets in its environment.
145
+ `envilder exec` resolves the mapping and starts your command with the secrets in its environment.
125
146
  Nothing is written to disk. Envilder options go before the command (or before an optional `--`); everything
126
147
  after belongs to your command. Exec mode is fail-closed: the command does not start if any secret is missing.
127
148
  It is not a sandbox: your command and everything it starts can read the secrets.
128
149
 
129
150
  📖 See the [Exec Command Guide](docs/exec-command.md) for exit codes, signals and GitHub Actions masking.
130
151
 
152
+ ### 4. Need a `.env` file? Pull it
153
+
154
+ ```bash
155
+ npx envilder
156
+ ```
157
+
158
+ With `envilder.json` in your current directory, no flags are needed — `--map` defaults to `envilder.json` and
159
+ `--envfile` defaults to `.env`. Your secrets are pulled from AWS SSM and written to `.env`.
160
+ Add `.env` to `.gitignore` and treat it as a secret.
161
+
162
+ 💡 Runnable examples: [envilder-examples](https://github.com/macalbert/envilder-examples) (Testcontainers and Aspire for
163
+ .NET, Python and TypeScript, AWS SSM and Azure Key Vault, plus `envilder exec`).
164
+
131
165
  ### 🎥 See it in action
132
166
 
133
167
  Watch how easy it is to automate your `.env` management in less than 1 minute:
@@ -141,8 +175,10 @@ what secrets your app needs and where they live in your cloud provider. The same
141
175
  the CLI, the GitHub Action, and the runtime SDKs. You can optionally include a `$config` section
142
176
  to declare which provider and settings to use.
143
177
 
144
- Add `"$schema"` to enable IDE autocomplete, inline documentation, and validation for your map
145
- files. The schema is published at
178
+ Editors that use [SchemaStore](https://www.schemastore.org/) (VS Code, JetBrains IDEs) give you autocomplete,
179
+ inline documentation and validation for `envilder.json` and `envilder.*.json` files automatically.
180
+ For any other file name, add `"$schema": "https://envilder.com/schema/map-file.v1.json"`; a single-secret push
181
+ adds it for you when the file name needs it. The schema is published at
146
182
  [envilder.com/schema/map-file.v1.json](https://envilder.com/schema/map-file.v1.json).
147
183
 
148
184
  ### Basic Format (AWS SSM, default)
@@ -151,7 +187,6 @@ When no `$config` is present, Envilder defaults to AWS SSM Parameter Store:
151
187
 
152
188
  ```json
153
189
  {
154
- "$schema": "https://envilder.com/schema/map-file.v1.json",
155
190
  "API_KEY": "/myapp/prod/api-key",
156
191
  "DB_PASSWORD": "/myapp/prod/db-password",
157
192
  "SECRET_TOKEN": "/myapp/prod/secret-token"
@@ -169,7 +204,6 @@ and uses all other keys as secret mappings:
169
204
 
170
205
  ```json
171
206
  {
172
- "$schema": "https://envilder.com/schema/map-file.v1.json",
173
207
  "$config": {
174
208
  "provider": "aws",
175
209
  "profile": "prod-account"
@@ -183,7 +217,6 @@ and uses all other keys as secret mappings:
183
217
 
184
218
  ```json
185
219
  {
186
- "$schema": "https://envilder.com/schema/map-file.v1.json",
187
220
  "$config": {
188
221
  "provider": "azure",
189
222
  "vaultUrl": "https://my-vault.vault.azure.net"
@@ -252,7 +285,7 @@ Env.Load("envilder.json");
252
285
  var dbPassword = Environment.GetEnvironmentVariable("DB_PASSWORD");
253
286
  ```
254
287
 
255
- 📖 **[Full .NET SDK docs](./src/sdks/dotnet/README.md)** · 💡 **[Examples](./examples/sdk/dotnet/)**
288
+ 📖 **[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
289
 
257
290
  ### Python SDK
258
291
 
@@ -285,7 +318,7 @@ Envilder.load('production', {
285
318
  })
286
319
  ```
287
320
 
288
- 📖 **[Full Python SDK docs](./src/sdks/python/README.md)** · 💡 **[Examples](./examples/sdk/python/)**
321
+ 📖 **[Full Python SDK docs](./src/sdks/python/README.md)** · 💡 **Examples:** [Testcontainers](https://github.com/macalbert/envilder-examples/tree/main/python-testcontainers)
289
322
 
290
323
  ### Node.js SDK
291
324
 
@@ -315,7 +348,7 @@ const secrets = await Envilder.fromMapFile('envilder.json')
315
348
  .resolve();
316
349
  ```
317
350
 
318
- 📖 **[Full Node.js SDK docs](./src/sdks/nodejs/README.md)** · 💡 **[Examples](./examples/sdk/nodejs/)**
351
+ 📖 **[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
352
 
320
353
  ## 🤖 GitHub Action
321
354
 
@@ -365,6 +398,8 @@ prebuilt action, so consumers do not need an Envilder build step.
365
398
  - [Push Command Guide](docs/push-command.md)
366
399
  - [Pull Command Guide](docs/pull-command.md)
367
400
  - [Exec Command Guide](docs/exec-command.md)
401
+ - [envilder-examples](https://github.com/macalbert/envilder-examples): runnable examples for the SDKs and `envilder exec`
402
+ (Testcontainers and Aspire, AWS SSM and Azure Key Vault)
368
403
  - [🤖 Envilder on Context7](https://context7.com/macalbert/envilder): up-to-date docs for AI coding assistants
369
404
  (Claude Code, Cursor, Copilot). Add `use context7` to your prompt, or reference the library ID `/macalbert/envilder`.
370
405
 
@@ -374,6 +409,7 @@ prebuilt action, so consumers do not need an Envilder build step.
374
409
  graph LR
375
410
  A["Mapping Contract<br/>(envilder.json)"] --> B[Envilder]:::core
376
411
  B --> C["CLI → .env file"]
412
+ B --> X["CLI exec → process env"]
377
413
  B --> D["GitHub Action → CI/CD"]
378
414
  B --> E["SDK → app memory"]
379
415
  F["AWS SSM / Azure Key Vault"]:::cloud --> B
@@ -384,7 +420,8 @@ graph LR
384
420
 
385
421
  1. **Define**: create an `envilder.json` mapping env var names to cloud secret paths
386
422
  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)
423
+ 3. **Deliver**: secrets arrive as a `.env` file (CLI/GHA), in the environment of a command you
424
+ start with `envilder exec` (CLI), or in-memory (SDKs)
388
425
  4. **Rotate**: update secret values in your cloud provider while keeping the same
389
426
  application-facing mapping. Rerun Envilder to refresh a generated `.env`, or restart/re-resolve
390
427
  in runtime consumers
@@ -404,11 +441,15 @@ layer that makes those secrets usable consistently across local development, CI/
404
441
  Use Envilder when your secrets already live in your cloud provider and you want one versioned
405
442
  `envilder.json` mapping contract everywhere your code runs.
406
443
 
444
+ `envilder exec` is not a sandbox either. It keeps secrets off the disk, but it does not isolate
445
+ the process: your command and every process it starts can read them. It also leaves an existing
446
+ `.env` file untouched, so delete it yourself when you move from pull mode to exec mode.
447
+
407
448
  ## 🏁 What's Next
408
449
 
409
- Envilder already covers CLI, GitHub Action, and runtime SDKs for .NET, Python, and Node.js.
450
+ Envilder already covers CLI (including `envilder exec`), GitHub Action, and runtime SDKs for .NET, Python, and Node.js.
410
451
 
411
- Next priorities include Go and Java SDKs, GCP Secret Manager, and exec mode.
452
+ Next priorities include Go and Java SDKs and GCP Secret Manager.
412
453
 
413
454
  See the [full roadmap](./ROADMAP.md).
414
455
 
@@ -431,17 +472,19 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md).
431
472
  <img src="./src/website/public/localstack-logo-horizontal-Dark.svg" alt="LocalStack" height="40">
432
473
  </picture>
433
474
  </a>
434
- </p>
435
-
436
- <p align="center">
437
- Supported by <a href="https://localstack.cloud">LocalStack</a>.
475
+ &nbsp;&nbsp;&nbsp;
476
+ <a href="https://snyk.io/open-source/" target="_blank" rel="noopener noreferrer">
477
+ <picture>
478
+ <source media="(prefers-color-scheme: dark)" srcset="./src/website/public/snyk-logo-Light.svg">
479
+ <source media="(prefers-color-scheme: light)" srcset="./src/website/public/snyk-logo-Dark.svg">
480
+ <img src="./src/website/public/snyk-logo-Dark.svg" alt="Snyk" height="40">
481
+ </picture>
482
+ </a>
438
483
  </p>
439
484
 
440
485
  <p align="center">
441
486
  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>.
487
+ <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
488
  </p>
446
489
 
447
490
  ## 📜 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. Since v0.16.0 a single-variable push also records the mapping in the map file (opt out with `--no-map-update`). [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,51 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
5
5
 
6
6
  ---
7
7
 
8
+ ## [0.16.0] - 2026-10-25
9
+
10
+ ### Added
11
+
12
+ * **Single-secret push records the mapping in the map file**:
13
+ `envilder --key=API_KEY --value=... --secret-path=...` now also creates or
14
+ updates `envilder.json` (or the file given with `--map`) with
15
+ `"API_KEY": "<secret-path>"`, so the next `envilder` or `envilder exec` works
16
+ without writing the map file by hand. Every run logs whether the file was
17
+ created, updated or already up to date. A new file gets `$config` for Azure,
18
+ and `$schema` only when its name is not `envilder.json` or `envilder.*.json`
19
+ (SchemaStore already covers those); an existing file keeps its key order, indentation, line
20
+ endings and `$config`. If the variable is already mapped to a different path,
21
+ the command fails before pushing. If the map file targets another provider or
22
+ vault, the secret is still pushed and a warning explains that the mapping was
23
+ not added. If writing the map file or the push fails, the map file is
24
+ restored. The secret value and the AWS profile are never written
25
+ * **`--no-map-update`**: push a single secret without reading, creating or
26
+ updating any map file
27
+
28
+ ### Changed
29
+
30
+ * A single-secret push now writes `envilder.json` in the current directory by
31
+ default. Use `--no-map-update` to keep the previous behavior. An explicit
32
+ `--map` that does not exist is created instead of being rejected
33
+
34
+ ---
35
+
36
+ ## [0.15.1] - 2026-10-22
37
+
38
+ ### Security
39
+
40
+ * Update development and build dependencies to resolve open advisories:
41
+ `undici` 8.10.2 → 8.12.3 (via `testcontainers`), `brace-expansion`,
42
+ `@grpc/grpc-js` and `@vitest/mocker`. The published `envilder` package and
43
+ its runtime dependencies are unchanged
44
+ ([#609](https://github.com/macalbert/envilder/pull/609))
45
+
46
+ ### Dependencies
47
+
48
+ * Bump `testcontainers` and `@testcontainers/localstack` from 12.2.0 to 12.2.1
49
+ * Bump `vitest` and `@vitest/coverage-v8` from 4.1.11 to 4.1.12
50
+
51
+ ---
52
+
8
53
  ## [0.15.0] - 2026-10-16
9
54
 
10
55
  ### Added
@@ -25,7 +70,8 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
25
70
  code, `128+n` for signals, `125` for Envilder errors, `126` and `127` when
26
71
  the command cannot be executed or found. `SIGTERM` and `SIGHUP` are
27
72
  forwarded and the command is awaited without a timeout, even if a signal
28
- cannot be delivered. Exec mode is not a sandbox: see
73
+ cannot be delivered. An expired AWS SSO session is recovered interactively
74
+ before the command starts. Exec mode is not a sandbox: see
29
75
  [docs/exec-command.md](../exec-command.md)
30
76
  ([#550](https://github.com/macalbert/envilder/issues/550))
31
77
 
@@ -127,7 +173,7 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
127
173
 
128
174
  ---
129
175
 
130
- ## [0.13.0] - 2026-06-26
176
+ ## [0.13.0] - 2026-07-11
131
177
 
132
178
  ### Added
133
179
 
@@ -218,6 +264,20 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
218
264
 
219
265
  ---
220
266
 
267
+ ## [0.11.1] - 2026-06-25
268
+
269
+ ### Fixed
270
+
271
+ * **AWS SSO / assumed-role profiles now resolve correctly**: Selecting an
272
+ SSO, IAM Identity Center, or assumed-role profile (via `--profile` or
273
+ `$config.profile`) now resolves credentials through the full AWS provider
274
+ chain instead of silently falling back to the default credentials.
275
+ Previously these profiles were ignored, reading and writing secrets against
276
+ the wrong AWS account
277
+ ([#364](https://github.com/macalbert/envilder/issues/364))
278
+
279
+ ---
280
+
221
281
  ## [0.11.0] - 2026-05-31
222
282
 
223
283
  ### Changed
@@ -244,7 +304,7 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
244
304
  published at `https://envilder.com/schema/map-file.v1.json`. Add
245
305
  `"$schema": "https://envilder.com/schema/map-file.v1.json"` to any map file
246
306
  for IDE autocomplete, inline documentation, and validation
247
- ([#218](https://github.com/macalbert/envilder/pull/218))
307
+ ([#217](https://github.com/macalbert/envilder/pull/217))
248
308
  * **Schema contract tests**: 39 tests validating the JSON Schema across all
249
309
  providers (AWS, Azure, GCP, HashiCorp Vault, file)
250
310
 
@@ -374,6 +434,7 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
374
434
  ### Fixed
375
435
 
376
436
  * **deps:** Move `@types/node` from `dependencies` to `devDependencies` to prevent it from being bundled as a runtime dependency
437
+ ([#135](https://github.com/macalbert/envilder/pull/135))
377
438
  * **e2e:** Use unique SSM paths per CLI test run to prevent race conditions between parallel test executions
378
439
 
379
440
  ### Dependencies
@@ -383,7 +444,7 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
383
444
 
384
445
  ---
385
446
 
386
- ## [0.8.0] - 2026-03-22
447
+ ## [0.8.0] - 2026-03-26
387
448
 
388
449
  ### Added
389
450
 
@@ -397,6 +458,13 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
397
458
  * New infrastructure adapter: `AzureKeyVaultSecretProvider` implementing `ISecretProvider`
398
459
  * New CLI option `--provider <name>` to select cloud provider (`aws` or `azure`, default: `aws`)
399
460
  * Azure authentication via `DefaultAzureCredential` (supports Azure CLI, managed identity, etc.)
461
+ * Automatic secret name normalization for Key Vault naming constraints (alphanumeric and hyphens,
462
+ 1–127 characters)
463
+
464
+ ### Security
465
+
466
+ * **Vault URL validation**: Azure Key Vault URLs must use HTTPS and match an Azure domain allowlist
467
+ (with dot-boundary checks), preventing SSRF through spoofed hostnames
400
468
 
401
469
  ### Changed
402
470
 
@@ -748,3 +816,52 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
748
816
 
749
817
  * CLI command not recognized after global install (`npm install -g envilder`)
750
818
  * Fixed missing compiled `lib/` files in published package
819
+
820
+ ---
821
+
822
+ ## [0.3.0] - 2025-05-09
823
+
824
+ ### Added
825
+
826
+ * **`--profile` option**: Choose which AWS CLI profile to use for credentials,
827
+ so you can work with different AWS accounts or configurations
828
+ ([#31](https://github.com/macalbert/envilder/pull/31))
829
+
830
+ ### Dependencies
831
+
832
+ * Bumped commander from 12.1.0 to 13.1.0, @aws-sdk/client-ssm, @types/node,
833
+ vite and @secretlint/secretlint-rule-preset-recommend
834
+
835
+ ---
836
+
837
+ ## [0.2.3] - 2025-04-13
838
+
839
+ ### Dependencies
840
+
841
+ * Bumped @aws-sdk/client-ssm from 3.670.0 to 3.716.0
842
+ * Bumped nanoid (security patch), @types/node, @biomejs/biome, secretlint and
843
+ @secretlint/secretlint-rule-preset-recommend
844
+
845
+ ---
846
+
847
+ ## [0.2.1] - 2024-10-16
848
+
849
+ ### Added
850
+
851
+ * **Preserve existing `.env` variables**: When the target `.env` already
852
+ exists, its variables are kept and only the mapped ones are added or updated
853
+ ([#5](https://github.com/macalbert/envilder/pull/5))
854
+ * Secret values are masked in console output
855
+ * Code coverage reporting published to GitHub Pages
856
+ ([#2](https://github.com/macalbert/envilder/pull/2))
857
+ * CodeQL code scanning ([#4](https://github.com/macalbert/envilder/pull/4))
858
+
859
+ ---
860
+
861
+ ## [0.1.4] - 2024-10-01
862
+
863
+ ### Added
864
+
865
+ * **Initial release**: Generate `.env` files from AWS SSM Parameter Store
866
+ using a JSON map of environment variable names to SSM parameter paths
867
+ * Supports both encrypted (`SecureString`) and plain SSM parameters