@maverickcer/env-cap 0.7.3 → 0.7.5

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 (238) hide show
  1. package/ADOPTION.md +106 -124
  2. package/AGENTS.md +14 -13
  3. package/CHANGELOG.md +23 -0
  4. package/CODE_REVIEW.md +69 -173
  5. package/CONTRIBUTING.md +57 -74
  6. package/GUIDE.md +393 -872
  7. package/README.md +82 -77
  8. package/RELEASING.md +17 -15
  9. package/SECURITY.md +76 -227
  10. package/SUPPORT.md +21 -45
  11. package/VERSIONING.md +68 -105
  12. package/benchmarks/READING-BENCHMARKS.md +13 -7
  13. package/benchmarks/WRITING-BENCHMARKS.md +1 -1
  14. package/dist/.dts/_ipc/build-fs.d.ts +9 -14
  15. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  16. package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
  17. package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
  18. package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
  19. package/dist/.dts/_ipc/glob.d.ts +6 -6
  20. package/dist/.dts/_ipc/no-node-fs.d.ts +0 -14
  21. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
  22. package/dist/.dts/build/lifecycle-model.d.ts +8 -3
  23. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  24. package/dist/.dts/build/sarif.d.ts.map +1 -1
  25. package/dist/.dts/helpers/index.d.ts +1 -1
  26. package/dist/.dts/runtime/create.d.ts +3 -0
  27. package/dist/.dts/runtime/create.d.ts.map +1 -1
  28. package/dist/.dts/runtime/document.d.ts +7 -4
  29. package/dist/.dts/runtime/document.d.ts.map +1 -1
  30. package/dist/.dts/runtime/index.d.ts +11 -10
  31. package/dist/.dts/runtime/index.d.ts.map +1 -1
  32. package/dist/.dts/runtime/types.d.ts +16 -0
  33. package/dist/.dts/runtime/types.d.ts.map +1 -1
  34. package/dist/.dts/runtime/validate.d.ts +14 -1
  35. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  36. package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
  37. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
  38. package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
  39. package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
  40. package/dist/.dts7/_ipc/display-path.d.ts +27 -0
  41. package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
  42. package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
  43. package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
  44. package/dist/.dts7/_ipc/glob.d.ts +22 -0
  45. package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
  46. package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
  47. package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
  48. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  49. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  50. package/dist/.dts7/_ipc/typescript.d.ts +20 -0
  51. package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
  52. package/dist/.dts7/build/assemble-project.d.ts +47 -0
  53. package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
  54. package/dist/.dts7/build/change-model.d.ts +63 -0
  55. package/dist/.dts7/build/change-model.d.ts.map +1 -0
  56. package/dist/.dts7/build/check-artifacts.d.ts +48 -0
  57. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
  58. package/dist/.dts7/build/citation-verification.d.ts +62 -0
  59. package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
  60. package/dist/.dts7/build/compatibility.d.ts +83 -0
  61. package/dist/.dts7/build/compatibility.d.ts.map +1 -0
  62. package/dist/.dts7/build/compiler-api.d.ts +12 -0
  63. package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
  64. package/dist/.dts7/build/contract-model.d.ts +93 -0
  65. package/dist/.dts7/build/contract-model.d.ts.map +1 -0
  66. package/dist/.dts7/build/deep-equal.d.ts +9 -0
  67. package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
  68. package/dist/.dts7/build/deep-freeze.d.ts +20 -0
  69. package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
  70. package/dist/.dts7/build/dependency-graph.d.ts +170 -0
  71. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
  72. package/dist/.dts7/build/dependency-model.d.ts +81 -0
  73. package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
  74. package/dist/.dts7/build/discover.d.ts +41 -0
  75. package/dist/.dts7/build/discover.d.ts.map +1 -0
  76. package/dist/.dts7/build/display-path.d.ts +6 -0
  77. package/dist/.dts7/build/display-path.d.ts.map +1 -0
  78. package/dist/.dts7/build/docs.d.ts +176 -0
  79. package/dist/.dts7/build/docs.d.ts.map +1 -0
  80. package/dist/.dts7/build/env-example.d.ts +85 -0
  81. package/dist/.dts7/build/env-example.d.ts.map +1 -0
  82. package/dist/.dts7/build/errors.d.ts +78 -0
  83. package/dist/.dts7/build/errors.d.ts.map +1 -0
  84. package/dist/.dts7/build/evidence-cache.d.ts +74 -0
  85. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
  86. package/dist/.dts7/build/evidence-model.d.ts +50 -0
  87. package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
  88. package/dist/.dts7/build/evidence-reference.d.ts +67 -0
  89. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
  90. package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
  91. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
  92. package/dist/.dts7/build/exclusive-group.d.ts +19 -0
  93. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
  94. package/dist/.dts7/build/finding-model.d.ts +80 -0
  95. package/dist/.dts7/build/finding-model.d.ts.map +1 -0
  96. package/dist/.dts7/build/generate-documentation.d.ts +176 -0
  97. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
  98. package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
  99. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
  100. package/dist/.dts7/build/generate-evidence.d.ts +77 -0
  101. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
  102. package/dist/.dts7/build/generate-manifest.d.ts +101 -0
  103. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
  104. package/dist/.dts7/build/generate-usage.d.ts +95 -0
  105. package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
  106. package/dist/.dts7/build/generated-banner.d.ts +43 -0
  107. package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
  108. package/dist/.dts7/build/glob.d.ts +6 -0
  109. package/dist/.dts7/build/glob.d.ts.map +1 -0
  110. package/dist/.dts7/build/governance-fields.d.ts +34 -0
  111. package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
  112. package/dist/.dts7/build/humanize-key.d.ts +14 -0
  113. package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
  114. package/dist/.dts7/build/index.d.ts +105 -0
  115. package/dist/.dts7/build/index.d.ts.map +1 -0
  116. package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
  117. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
  118. package/dist/.dts7/build/link.d.ts +223 -0
  119. package/dist/.dts7/build/link.d.ts.map +1 -0
  120. package/dist/.dts7/build/literal-eval.d.ts +24 -0
  121. package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
  122. package/dist/.dts7/build/live-expirations.d.ts +47 -0
  123. package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
  124. package/dist/.dts7/build/manifest.d.ts +31 -0
  125. package/dist/.dts7/build/manifest.d.ts.map +1 -0
  126. package/dist/.dts7/build/map-utils.d.ts +8 -0
  127. package/dist/.dts7/build/map-utils.d.ts.map +1 -0
  128. package/dist/.dts7/build/merge-documentation.d.ts +35 -0
  129. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
  130. package/dist/.dts7/build/ownership-model.d.ts +59 -0
  131. package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
  132. package/dist/.dts7/build/parse.d.ts +207 -0
  133. package/dist/.dts7/build/parse.d.ts.map +1 -0
  134. package/dist/.dts7/build/reference-projections.d.ts +170 -0
  135. package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
  136. package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
  137. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
  138. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
  139. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
  140. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
  141. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
  142. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
  143. package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
  144. package/dist/.dts7/build/sarif.d.ts +66 -0
  145. package/dist/.dts7/build/sarif.d.ts.map +1 -0
  146. package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
  147. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
  148. package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
  149. package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
  150. package/dist/.dts7/build/source-position.d.ts +69 -0
  151. package/dist/.dts7/build/source-position.d.ts.map +1 -0
  152. package/dist/.dts7/build/tool-version.d.ts +8 -0
  153. package/dist/.dts7/build/tool-version.d.ts.map +1 -0
  154. package/dist/.dts7/build/types.d.ts +7 -0
  155. package/dist/.dts7/build/types.d.ts.map +1 -0
  156. package/dist/.dts7/build/typescript.d.ts +6 -0
  157. package/dist/.dts7/build/typescript.d.ts.map +1 -0
  158. package/dist/.dts7/build/usage-report.d.ts +124 -0
  159. package/dist/.dts7/build/usage-report.d.ts.map +1 -0
  160. package/dist/.dts7/cli/filesystem.d.ts +7 -0
  161. package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
  162. package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
  163. package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
  164. package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
  165. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
  166. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
  167. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
  168. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
  169. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
  170. package/dist/.dts7/evidence/define-projection.d.ts +52 -0
  171. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
  172. package/dist/.dts7/evidence/index.d.ts +23 -0
  173. package/dist/.dts7/evidence/index.d.ts.map +1 -0
  174. package/dist/.dts7/helpers/index.d.ts +135 -0
  175. package/dist/.dts7/helpers/index.d.ts.map +1 -0
  176. package/dist/.dts7/helpers/processors.d.ts +32 -0
  177. package/dist/.dts7/helpers/processors.d.ts.map +1 -0
  178. package/dist/.dts7/helpers/validators.d.ts +68 -0
  179. package/dist/.dts7/helpers/validators.d.ts.map +1 -0
  180. package/dist/.dts7/node/index.d.ts +2 -0
  181. package/dist/.dts7/node/index.d.ts.map +1 -0
  182. package/dist/.dts7/runtime/cache.d.ts +17 -0
  183. package/dist/.dts7/runtime/cache.d.ts.map +1 -0
  184. package/dist/.dts7/runtime/create.d.ts +23 -0
  185. package/dist/.dts7/runtime/create.d.ts.map +1 -0
  186. package/dist/.dts7/runtime/document.d.ts +223 -0
  187. package/dist/.dts7/runtime/document.d.ts.map +1 -0
  188. package/dist/.dts7/runtime/errors.d.ts +55 -0
  189. package/dist/.dts7/runtime/errors.d.ts.map +1 -0
  190. package/dist/.dts7/runtime/index.d.ts +25 -0
  191. package/dist/.dts7/runtime/index.d.ts.map +1 -0
  192. package/dist/.dts7/runtime/registry.d.ts +12 -0
  193. package/dist/.dts7/runtime/registry.d.ts.map +1 -0
  194. package/dist/.dts7/runtime/reset.d.ts +8 -0
  195. package/dist/.dts7/runtime/reset.d.ts.map +1 -0
  196. package/dist/.dts7/runtime/types.d.ts +191 -0
  197. package/dist/.dts7/runtime/types.d.ts.map +1 -0
  198. package/dist/.dts7/runtime/validate.d.ts +27 -0
  199. package/dist/.dts7/runtime/validate.d.ts.map +1 -0
  200. package/dist/{build-LFHPVDQL.js → build-DNAYWD2B.js} +8 -5
  201. package/dist/build-DNAYWD2B.js.map +1 -0
  202. package/dist/build.cjs +7 -4
  203. package/dist/build.cjs.map +1 -1
  204. package/dist/build.js +7 -4
  205. package/dist/build.js.map +1 -1
  206. package/dist/build.ts7.d.cts +1 -0
  207. package/dist/build.ts7.d.ts +1 -0
  208. package/dist/{chunk-ZW3BLAPD.js → chunk-HAGMVMN5.js} +2 -2
  209. package/dist/cli/index.js +3 -3
  210. package/dist/eslint-plugin/index.cjs +8 -5
  211. package/dist/eslint-plugin/index.cjs.map +1 -1
  212. package/dist/eslint-plugin/index.js +8 -5
  213. package/dist/eslint-plugin/index.js.map +1 -1
  214. package/dist/eslint-plugin/index.ts7.d.cts +1 -0
  215. package/dist/eslint-plugin/index.ts7.d.ts +1 -0
  216. package/dist/evidence.ts7.d.cts +1 -0
  217. package/dist/evidence.ts7.d.ts +1 -0
  218. package/dist/helpers.ts7.d.cts +1 -0
  219. package/dist/helpers.ts7.d.ts +1 -0
  220. package/dist/index.cjs.map +1 -1
  221. package/dist/index.js.map +1 -1
  222. package/dist/index.ts7.d.cts +1 -0
  223. package/dist/index.ts7.d.ts +1 -0
  224. package/dist/node.ts7.d.cts +1 -0
  225. package/dist/node.ts7.d.ts +1 -0
  226. package/examples/README.md +46 -80
  227. package/package.json +37 -6
  228. package/schemas/env-cap-report.schema.json +1 -1
  229. package/skills/env-cap/SKILL.md +1 -1
  230. package/skills/env-cap/references/api.md +1 -1
  231. package/specs/architecture.md +2 -2
  232. package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
  233. package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
  234. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
  235. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
  236. package/specs/generated-artifacts.md +14 -2
  237. package/dist/build-LFHPVDQL.js.map +0 -1
  238. /package/dist/{chunk-ZW3BLAPD.js.map → chunk-HAGMVMN5.js.map} +0 -0
package/SECURITY.md CHANGED
@@ -1,270 +1,119 @@
1
1
  # Security policy
2
2
 
3
- This document defines the security boundaries and threat model for
4
- `env-cap`: what protections the package intentionally provides, what
5
- responsibilities remain with the application, and why those boundaries exist.
3
+ env-cap's runtime refuses filesystem access, ambient environment reads, network access and values in errors. Each row below names the check that enforces a refusal and where it stops.
6
4
 
7
- For implementation details such as contract redaction, error handling,
8
- `.env.example` generation, and documentation handling, see the [Security
9
- section of the Guide](GUIDE.md#security-model). This document describes the policy
10
- those mechanisms enforce rather than duplicating their implementation details.
5
+ The short version of each runtime rule, with its test, is in the [Guide's security model](GUIDE.md#security-model).
11
6
 
12
7
  ## Reporting a vulnerability
13
8
 
14
- Report suspected security vulnerabilities privately through a
15
- [GitHub security advisory](https://github.com/maverickcer/env-cap/security/advisories/new).
9
+ Report a suspected vulnerability privately through a [GitHub security advisory](https://github.com/maverickcer/env-cap/security/advisories/new). Private vulnerability reporting is enabled on the repository.
16
10
 
17
- Alternatively, contact the maintainer through the contact information
18
- provided on the npm package page.
11
+ You can also contact the maintainer at the address on the npm package page.
19
12
 
20
- Please do not create a public issue for a suspected vulnerability before it
21
- has been reviewed and triaged.
13
+ Please do not open a public issue for a suspected vulnerability before it has been triaged.
22
14
 
23
15
  ## Disclosure
24
16
 
25
- Reports are handled in private until they can be disclosed without helping an attacker. A report is
26
- acknowledged, assessed and prioritised by severity, exploitability and impact; acknowledgement does not
27
- promise that it is accepted as a vulnerability or that a fix can be provided.
17
+ This is maintainer policy, not a mechanism.
28
18
 
29
- When a fix is available, a security advisory is published on this repository naming the affected versions,
30
- the patched version, the severity, what a user can do if they cannot upgrade at once, and whether
31
- exploitation is known to have occurred. It does not publish a working exploit or details that expose other
32
- systems before their owners have had time to update. If a vulnerability is being exploited, or a fix cannot
33
- be released promptly, users are warned and given mitigations before the fix is complete. Resolved
34
- advisories stay public: a record of vulnerabilities handled openly is part of what this package asks you to
35
- trust.
19
+ 1. Reports are handled in private until disclosure no longer helps an attacker.
20
+ 2. A report is acknowledged, assessed, and prioritized by severity, exploitability and impact. Acknowledgement does not mean it is accepted or that a fix is possible.
21
+ 3. When a fix exists, an advisory on this repository names the affected and patched versions, the severity, the mitigations, and whether exploitation is known.
22
+ 4. An advisory never includes a working exploit.
23
+ 5. If a vulnerability is exploited, or a fix cannot ship promptly, users get mitigations before the fix.
24
+ 6. Resolved advisories stay public.
36
25
 
37
26
  ## Runtime security model
38
27
 
39
- The runtime package (`createEnv`, `validateEnv`, and imports from the package
40
- root) is intentionally limited to environment processing and validation. It
41
- does not attempt to become a secret-management platform.
28
+ The runtime is the package root (`createEnv`, `validateEnv` and the rest). It processes and validates values you pass in; it is not a secret manager.
42
29
 
43
- The runtime does not:
30
+ | The runtime does not | Enforced by | Where it blocks | Limit |
31
+ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------ |
32
+ | Touch the filesystem | ESLint bans `node:fs` and `node:child_process` in `src/` outside `src/cli`; the `AmbientCapabilities` check scans the packed tarball | `lint`, `contract` | The tarball scan is textual and skips bundled dependencies |
33
+ | Read `process.env` | `AmbientCapabilities` allows `process.env` only in the CLI and the ESLint plugin; the browser-bundle test rejects `process.` | `contract` | Textual; `globalThis["process"]` would evade both |
34
+ | Import a Node module or use a Node global | `test/runtime/browser-bundle.test.ts` bundles the runtime for the browser and checks the output | `contract` | A third-party import would be bundled without failing the test |
35
+ | Open a network connection | The `ipc/no-network` lint rule on env-cap's own `src/` | `lint`, `contract` | Source lint only. It does not cover the bundled TypeScript compiler |
36
+ | Show values when a contract is logged | `test/runtime/create.test.ts`: `console.log`, `String()`, `JSON.stringify` and template interpolation print a redacted marker | `contract` | Spreading a contract or calling `Object.entries()` on it reads every value |
37
+ | Put values in errors | `test/runtime/validate.test.ts`: errors carry variable names, contract names and your messages | `contract` | A message your own validator or processor builds from the value is passed through verbatim |
38
+ | Store, fetch or rotate secrets | No such code exists | None | A statement about the source, not a check |
44
39
 
45
- - **Persist secrets.**
46
- Resolved environment values exist only in memory. After successful
47
- validation, values are frozen and retained for the lifetime of the process.
48
- The runtime never writes secrets to disk, databases, external services, or
49
- persistent storage.
40
+ Three more runtime properties matter to a reviewer:
50
41
 
51
- - **Retrieve secrets.**
52
- The package has no integrations with secret-management systems such as
53
- HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, or Google Secret
54
- Manager. Applications are responsible for obtaining secrets through their
55
- existing infrastructure and passing resolved values into:
42
+ - **Values stay in memory.** The record of validated values is frozen and kept for the life of the process. The freeze is shallow: an object, array or `URL` a processor returns stays mutable.
43
+ - **Documentation is inert.** `documentEnv()` has no runtime effect (`test/runtime/document.test.ts`). Fields such as `expiresAt` are read only by the build-time analysis.
44
+ - **Contracts hold only what validation needs:** `default`, `processor`, `validator`, `context`, and a name for error messages.
56
45
 
57
- ```ts
58
- validateEnv({ values })
59
- ```
60
-
61
- * **Manage secret lifecycle operations.**
62
- There is no rotation engine, scheduler, command execution, or automated
63
- refresh process. Fields such as `expiresAt` and refresh instructions from
64
- `documentEnv()` are documentation metadata only. They are consumed by
65
- generated artifacts and never executed by the runtime.
46
+ ## Dual-package hazard
66
47
 
67
- * **Send telemetry.**
68
- No package entry point (`.`, `./build`, or `./helpers`) performs network
69
- requests or sends usage information.
48
+ The runtime keeps state in module scope: the registry that links a contract to its schema (`src/runtime/registry.ts`) and the validation cache (`src/runtime/cache.ts`). If one dependency loads the ESM build and another the CommonJS build, Node creates two separate copies of that state.
70
49
 
71
- * **Log secret values.**
72
- The library does not write logs or emit environment values. Validation
73
- errors contain contract information, variable names, and messages produced
74
- by user-provided processors or validators, but the library itself never
75
- inserts raw or processed secret values into errors.
50
+ No package that ships both formats can prevent this. env-cap makes the failure loud instead ([ADR 0041](specs/decisions/0041-dual-package-hazard-checked-documented.md)):
76
51
 
77
- * **Embed documentation metadata into runtime state.**
78
- `documentEnv()` is intentionally inert during execution. Documentation
79
- fields are only consumed by build-time static analysis and are not retained
80
- by the runtime validation system.
52
+ 1. A contract from one copy, passed to `validateEnv()` or `resetEnvCache()` from the other, throws a `TypeError`.
53
+ 2. `isEnvContract()` from the other copy returns `false`.
54
+ 3. Nothing validates against the wrong schema or reads a stale cache.
81
55
 
82
- Runtime contracts intentionally contain only:
56
+ `test/runtime/dual-package-hazard.test.ts` pins these results on the built `dist/` files, in one Node process. Keep each `createEnv()` call and the `validateEnv()` call that consumes it on the same import style.
83
57
 
84
- - variable definitions required for processing (`default`, `processor`,
85
- `validator`)
86
- - resolved, frozen values accessible through explicit property access
87
- - minimal identity information required for runtime errors
58
+ ## Build-time security model
88
59
 
89
- Information that exists only for humans, operators, or generated artifacts
90
- belongs in `documentEnv()`. Responsibilities such as secret storage, rotation,
91
- telemetry, and access auditing belong to infrastructure outside this package.
60
+ The build entry (`./build`, the CLI and the Action) analyzes source. It does not run it.
92
61
 
93
- ## Dual-package hazard
62
+ | The build step | Enforced by | Limit |
63
+ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
64
+ | Never imports, requires or evaluates a schema file | `test/build/parse.test.ts` (a throwing top-level statement never runs); ESLint bans `eval` and `new Function` in `src/` | Lint does not ban `import()`, `require()`, `vm` or workers in `src/build`; [CODE_REVIEW.md](CODE_REVIEW.md) covers them |
65
+ | Resolves only literal values and reports the rest as unresolved | `test/build/parse.test.ts`, `test/build/literal-eval.test.ts` | None found |
66
+ | Rejects an output path that is absolute outside the root or climbs out with `..` | `test/build/manifest-generate.test.ts`, `test/build/documentation-generate.test.ts`, `test/build/check-artifacts.test.ts` | The check is lexical. A symlinked directory inside the root can still lead outside it |
67
+ | Never overwrites an existing `.env.example` by default | `test/build/env-example.test.ts` (it writes a timestamped sibling) | `onExisting: "overwrite"` opts out |
68
+ | Never descends into `node_modules` or `.git`, whatever `include` and `exclude` say | `test/build/discover.test.ts` | None found |
69
+ | Reads a listed package's schema without walking its directory | `test/build/resolution/resolve-package-schema.test.ts` | Only packages you name in `packages` |
70
+ | Never resolves a path alias into `node_modules` | `src/_ipc/resolve-tsconfig-paths.ts`, tested in internal-package-contract; `ManagedFiles` keeps the copy identical | The copy is outside env-cap's own coverage and mutation runs |
71
+ | Never imports `node:fs` | ESLint, and `AmbientCapabilities`; the caller passes a `BuildFileSystem` | Textual scan |
94
72
 
95
- The runtime keeps identity-sensitive state in module scope: the private
96
- `WeakMap` that associates a contract object with its schema
97
- (`src/runtime/registry.ts`), and the validation cache
98
- (`src/runtime/cache.ts`). If a consumer's dependency tree resolves
99
- `env-cap` through two different specifiers — one importer
100
- getting the ESM build, one `require()`r getting the CJS build, via a mixed
101
- ESM/CJS dependency graph or a re-exporting intermediate package — Node
102
- loads two entirely separate module instances, each with its own registry
103
- and cache. No npm package that ships both ESM and CJS builds can prevent
104
- this; it is a property of how Node's two module systems resolve
105
- independently.
106
-
107
- `env-cap` treats this as a checked, documented risk class rather than an
108
- unstated unknown
109
- ([ADR 0041](specs/decisions/0041-dual-package-hazard-checked-documented.md));
110
- `test/runtime/dual-package-hazard.test.ts` pins the exact consequence in
111
- CI. That consequence is **fail-fast, not silent corruption**: a contract
112
- created by `createEnv()` in one instance and passed to `validateEnv()`,
113
- `resetEnvCache()`, or `isEnvContract()` resolved from the other instance is
114
- not recognized — `validateEnv()`/`resetEnvCache()` throw a `TypeError`
115
- ("this value was not created by createEnv()") and `isEnvContract()` returns
116
- `false`, immediately and visibly, rather than validating against the wrong
117
- schema or reading a stale cache. Keep each capability's `createEnv()` call
118
- and the `validateEnv()` call that consumes its manifest resolving through
119
- the same module specifier (the normal case for an application that imports
120
- `env-cap` one way throughout).
73
+ A rejected output path fails before anything is written. A direct call throws that pass's error type. Through `generateEnvArtifacts()` or the CLI, the failure is collected into `EnvProjectGenerationError`.
121
74
 
122
- ## Build-time security model
75
+ **Cross-package discovery** reads a schema from an installed dependency only when you name that package in `packages` ([ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md)). For each named package it reads one `package.json`, then one declared file. That file must be a `.ts` or `.tsx` file inside the package, not a symlink out of it, and under a size cap. It never calls `readdir`, and it never follows a package's own dependencies.
123
76
 
124
- `generateEnvManifest()` (`./build`) is a static-analysis tool, not an
125
- execution engine.
126
-
127
- The build system:
128
-
129
- - **Never imports or executes schema files.**
130
- Schema files are analyzed as TypeScript ASTs. Only safe literal
131
- expressions are evaluated, such as strings, numbers, booleans, arrays, and
132
- object literals.
133
-
134
- Dynamic expressions such as:
135
-
136
- - function calls
137
- - variables
138
- - computed values
139
- - interpolated template strings
140
-
141
- are treated as unresolved information and reported rather than executed or
142
- guessed.
143
-
144
- - **Never writes outside the configured project root.**
145
- All generated output paths (`location`, `docs.location`,
146
- `envExample.location`) are resolved and verified against `root` before any
147
- file is written.
148
-
149
- Paths that escape the configured root through absolute paths or traversal
150
- segments fail before any file is written. A direct `generateEnvManifest()`/
151
- `generateDocumentation()`/`generateUsageReport()` call throws that pass's
152
- own error type (`EnvManifestGenerationError`/`EnvDocumentationGenerationError`/
153
- `EnvUsageAnalysisError`); through `generateEnvArtifacts()` or the CLI (the
154
- primary documented workflow), the same escape is aggregated into
155
- `EnvProjectGenerationError` instead.
156
-
157
- - **Never overwrites existing hand-managed `.env.example` files.**
158
- If a generated example would conflict with an existing file, the generator
159
- preserves the original and writes generated output separately.
160
-
161
- - **Avoids unnecessary traversal of dependency directories.**
162
- The general file-discovery walk that powers `include`/`exclude` glob
163
- matching excludes directories such as `node_modules` and `.git` during
164
- traversal rather than scanning and filtering afterward -- this walk never
165
- descends into `node_modules` at all, regardless of `include`/`exclude`.
166
-
167
- A separate, narrow mechanism exists for reading a schema
168
- that lives only inside an installed dependency: the `packages` option
169
- (see [ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md)).
170
- It is opt-in -- no package is ever considered unless its exact name
171
- appears in a `packages` array the consuming project supplies -- and
172
- bounded by construction, not by a traversal exclusion: it reads exactly
173
- one `package.json` per named package to find a declared entry point, then
174
- reads exactly one declared file, verified to be a real file (not a
175
- symlink escaping the package directory) under a fixed size cap, before it
176
- is parsed. It never calls `readdir` on any directory, named package or
177
- not, and a package's own transitive dependencies are never considered.
178
-
179
- A second, separate mechanism resolves TypeScript path
180
- aliases (`compilerOptions.paths`/`baseUrl` in `tsconfig.json`) during
181
- static analysis, on by default (see
182
- [ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md)).
183
- Unlike `packages`, it never crosses into `node_modules`: any resolution
184
- landing on a path containing a `node_modules` segment is discarded, so a
185
- bare specifier can only ever resolve into `node_modules` through the
186
- `packages` mechanism above, never through alias resolution. It only ever
187
- resolves to a real `.ts`/`.tsx` file already inside the scanned project.
77
+ **Path-alias resolution** reads `compilerOptions.paths` and `baseUrl` and is on by default ([ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md)). A result inside `node_modules` is discarded, so only `packages` can reach installed code.
188
78
 
189
79
  ## Application responsibilities
190
80
 
191
- `env-cap` intentionally does not attempt to solve problems outside the
192
- environment-contract lifecycle.
193
-
194
- Applications remain responsible for:
81
+ These stay with you:
195
82
 
196
- - **Protecting documentation metadata.**
197
- Values passed to `documentEnv()` are ordinary source-code data. If an
198
- `env.schema.ts` file is imported into a browser bundle, documentation fields
199
- inside that file may be included in the client output.
83
+ - **Keep secrets out of documentation.** `documentEnv()` values are ordinary source. If a schema file reaches a browser bundle, its descriptions, runbook links and notes ship with it.
84
+ - **Write safe validators.** A message such as `` `Invalid value: ${value}` `` exposes the value wherever the error is logged. env-cap passes your message through unchanged.
85
+ - **Do not spread contracts.** Spreading one reads every value into a plain object.
86
+ - **Store and rotate secrets elsewhere.** env-cap validates values after your infrastructure supplies them.
87
+ - **Treat validation contexts as filters.** A context decides whether a run validates a variable. It is not access control and not a bundling boundary ([ADR 0022](specs/decisions/0022-validation-contexts.md)).
200
88
 
201
- This means:
202
-
203
- - descriptions are public
204
- - runbook links are public
205
- - operational notes are public
206
- - lifecycle instructions are public
207
-
208
- Documentation metadata must never contain credentials, private keys, or
209
- information that should not appear in a client bundle.
89
+ ## Supply-chain posture
210
90
 
211
- - **Writing safe processors and validators.**
212
- Custom validation logic controls its own errors.
91
+ What a reviewer of the build and publish pipeline can rely on:
213
92
 
214
- For example:
93
+ | Control | Mechanism | Limit |
94
+ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
95
+ | `main` requires a pull request, resolved review threads, and the `contract` and `lint` checks | Ruleset; `BranchProtection` check | Admins can bypass; no approving review is required |
96
+ | Releases publish over npm OIDC trusted publishing with a provenance attestation | `.github/workflows/release.yml` and the shared release workflow it calls; the repository holds no `NPM_TOKEN` | A manual last-resort publish ([RELEASING.md](RELEASING.md)) carries no attestation |
97
+ | The release checks that npm serves the version with its attestation | The release workflow's final verification step | It reports a failure; it cannot unpublish |
98
+ | A release publishes only a tree whose `contract` job passed, after `npm run verify` and an install-and-import of that tarball | The shared release workflow | It looks at `contract`, not `required`. No env-cap release has run on this workflow version yet |
99
+ | A person merges every release pull request | The Changesets flow; release pull requests are never merged automatically | An admin can merge a `major` changeset; the workflow only posts a notice |
100
+ | Version tags `v<x.y.z>` cannot be moved or deleted | A tag ruleset on `refs/tags/v*.*.*` | Admins can bypass rulesets. The floating `v0` tag moves on each release by design |
101
+ | Production dependency licences, `npm audit` and Socket alerts are reviewed | The `Licenses`, `SecurityDeps` and `SecuritySocket` checks in `contract`; each accepted alert needs a record | Socket alerts on the bundled compiler (network, shell, environment, filesystem) are recorded, not removed |
102
+ | No secrets are committed | The `SecuritySecrets` check | Pattern-based |
103
+ | A pull request with an open code-scanning alert on its ref fails | The `CodeScanning` check | Alerts that exist only on `main`, such as Scorecard's, are not visible to a pull request |
104
+ | Shipped JavaScript is unminified, and every URL in `dist/` has a reviewed record | The `NoMinify` and `DistNoUrls` checks | None found |
105
+ | Coverage stays above fixed floors | `vitest.config.ts` thresholds, enforced in `contract` | A pull request can lower a floor; reviewers treat that as a reviewed change |
215
106
 
216
- ```ts
217
- throw new Error(`Invalid value: ${value}`)
218
- ```
107
+ The runtime, helpers and evidence entries also run under Bun and Deno (`test/cross-runtime/`). That job does not yet block a merge. The build entry and the CLI are Node-only.
219
108
 
220
- may expose a secret if the thrown message is later logged. The package
221
- protects values passing through its own runtime boundaries but cannot
222
- sanitize arbitrary application-generated error messages.
109
+ [RELEASING.md](RELEASING.md#first-time-setup) describes the one-time trusted-publisher setup.
223
110
 
224
- - **Managing secret storage and rotation.**
225
- Obtaining, storing, rotating, and revoking secrets are infrastructure
226
- responsibilities. `env-cap` validates configuration after it has been
227
- supplied; it does not replace a secret-management system.
111
+ ## Supported versions
228
112
 
229
- ## Supply-chain posture
113
+ This is maintainer policy, not a mechanism.
230
114
 
231
- For a reviewer checking this project's publish/build pipeline rather than
232
- its runtime API: releases are published via npm's OIDC trusted publishing
233
- (`.github/workflows/release.yml`) — there is no long-lived `NPM_TOKEN`
234
- secret in this repository to leak, rotate, or scope. The workflow's
235
- `id-token: write` permission is exchanged for a short-lived publish
236
- credential per run, tied to this exact repository and workflow file, and
237
- the same OIDC flow attaches npm provenance attestations to each published
238
- version. The runtime and helpers entry points are verified against real
239
- Node, Bun, and Deno engines in CI (`test/cross-runtime/`), not merely
240
- asserted to be isomorphic by inspection. Test coverage is enforced
241
- ratchet-up-only (see `vitest.config.ts`; [`CONTRIBUTING.md`](CONTRIBUTING.md)
242
- forbids lowering a threshold to accommodate a drop). See
243
- [`RELEASING.md`](RELEASING.md#first-time-setup) for the one-time
244
- trusted-publisher setup this depends on.
115
+ **Before 1.0:** security fixes go to the latest published `0.x` only. There is no long-term-support branch. Upgrading to the latest `0.x` is the only supported fix.
245
116
 
246
- ## Supported versions
117
+ **From 1.0:** security fixes will be backported to the previous major's latest minor for at least six months after a new major ships. The maintainer may extend that window. Once an end date is stated for a major, it will not be shortened.
247
118
 
248
- This project has not reached a `1.0` release.
249
-
250
- **Today, before `1.0`:** security fixes are provided on the latest published
251
- `0.x` version only. There is no separate long-term-support branch and no
252
- extended security-support policy yet -- an application pinned to an older
253
- `0.x` release does not receive backported fixes; upgrading to the latest
254
- `0.x` is the only supported remediation path.
255
-
256
- **Starting at `1.0`:** once this project ships a `1.0` release, security
257
- fixes will be backported to the latest minor release of the previous major
258
- version for a minimum of six months after a new major version ships. This
259
- window may be extended at the maintainer's discretion -- for example, to
260
- give large downstream consumers more migration time -- but once a minimum
261
- end date has been stated for a given major version's backport window, it
262
- will never be shortened. Fixes for the current major version continue to
263
- target its latest published minor/patch release, exactly as fixes do today
264
- for `0.x`; the backport commitment only extends that same treatment one
265
- major version back, for a bounded time.
266
-
267
- This is a forward commitment about a future release line, not a claim that
268
- backporting has already been exercised -- see
269
- [`ADOPTION.md`](ADOPTION.md#versioning-stability-and-long-term-support) for
270
- how to weigh that distinction today.
119
+ This commitment covers a future release line and has not been exercised yet. [ADOPTION.md](ADOPTION.md#versioning-stability-and-long-term-support) explains how to weigh it.
package/SUPPORT.md CHANGED
@@ -2,37 +2,21 @@
2
2
 
3
3
  # Support
4
4
 
5
- Thank you for using `@maverickcer/env-cap`.
5
+ How to get help with `@maverickcer/env-cap`, report a bug, or ask for a change.
6
6
 
7
- This document explains how to get help, report issues, and request improvements.
7
+ ## Before opening an issue
8
8
 
9
- ## Before Opening a Discussion or Issue
9
+ - Read the README and the guides it links.
10
+ - Search the existing GitHub Issues; a question may already have an answer.
10
11
 
11
- Please take a moment to:
12
+ ## Questions and usage help
12
13
 
13
- - Read the project documentation and README.
14
- - Search existing GitHub Discussions.
15
- - Search existing GitHub Issues.
14
+ Open a GitHub Issue. Questions, design discussion, integration advice and general feedback all go there;
15
+ this repository does not use GitHub Discussions.
16
16
 
17
- This helps reduce duplicate reports and may provide an immediate answer.
17
+ ## Bug reports
18
18
 
19
- ## Questions and Usage Help
20
-
21
- If you have questions about using `@maverickcer/env-cap`, need help understanding its behavior, or would like guidance on best practices, please start a **GitHub Discussion**.
22
-
23
- Discussions are the best place for:
24
-
25
- - Usage questions
26
- - Design discussions
27
- - Architecture advice
28
- - Integration guidance
29
- - General feedback
30
-
31
- ## Bug Reports
32
-
33
- If you believe you have found a bug, please open a **GitHub Issue**.
34
-
35
- When reporting a bug, include:
19
+ Open a GitHub Issue and include:
36
20
 
37
21
  - The version of `@maverickcer/env-cap`
38
22
  - Your Node.js version
@@ -40,37 +24,29 @@ When reporting a bug, include:
40
24
  - Steps to reproduce the issue
41
25
  - Expected behavior
42
26
  - Actual behavior
43
- - Any relevant code snippets, configuration, or logs
27
+ - Any relevant code, configuration or logs
44
28
 
45
- Whenever possible, provide a minimal reproducible example.
29
+ A minimal reproducible example shortens the time to a fix.
46
30
 
47
- ## Feature Requests
31
+ ## Feature requests
48
32
 
49
- Feature requests are welcome.
50
-
51
- Before opening a new request, please search existing Issues and Discussions to avoid duplicates.
52
-
53
- A strong feature request explains:
33
+ Search existing Issues first. A strong request explains:
54
34
 
55
35
  - The problem being solved
56
36
  - Why the current behavior is insufficient
57
37
  - The proposed API or workflow
58
38
  - Alternative solutions that were considered
59
39
 
60
- ## Security Vulnerabilities
61
-
62
- Please **do not** report security vulnerabilities through public Issues or Discussions.
63
-
64
- Instead, follow the responsible disclosure process described in `SECURITY.md`.
65
-
66
- ## Supported Versions
40
+ ## Security vulnerabilities
67
41
 
68
- Only the latest released version is actively supported.
42
+ Do not report security vulnerabilities through public Issues. Follow the private process in
43
+ [SECURITY.md](SECURITY.md).
69
44
 
70
- Older releases may receive limited support or no updates.
45
+ ## Supported versions
71
46
 
72
- ## Response Expectations
47
+ Only the latest released version receives fixes. This is policy; nothing enforces it.
73
48
 
74
- `@maverickcer/env-cap` is maintained as an open source project.
49
+ ## Response expectations
75
50
 
76
- While all Issues and Discussions are appreciated, response times cannot be guaranteed. Community participation is encouraged, and well-documented bug reports and feature proposals help improve the project for everyone.
51
+ `@maverickcer/env-cap` is maintained as an open source project. No response time is promised. Well-documented reports and
52
+ proposals are read first.