@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.
- package/ADOPTION.md +106 -124
- package/AGENTS.md +14 -13
- package/CHANGELOG.md +23 -0
- package/CODE_REVIEW.md +69 -173
- package/CONTRIBUTING.md +57 -74
- package/GUIDE.md +393 -872
- package/README.md +82 -77
- package/RELEASING.md +17 -15
- package/SECURITY.md +76 -227
- package/SUPPORT.md +21 -45
- package/VERSIONING.md +68 -105
- package/benchmarks/READING-BENCHMARKS.md +13 -7
- package/benchmarks/WRITING-BENCHMARKS.md +1 -1
- package/dist/.dts/_ipc/build-fs.d.ts +9 -14
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
- package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
- package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
- package/dist/.dts/_ipc/glob.d.ts +6 -6
- package/dist/.dts/_ipc/no-node-fs.d.ts +0 -14
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/build/lifecycle-model.d.ts +8 -3
- package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
- package/dist/.dts/build/sarif.d.ts.map +1 -1
- package/dist/.dts/helpers/index.d.ts +1 -1
- package/dist/.dts/runtime/create.d.ts +3 -0
- package/dist/.dts/runtime/create.d.ts.map +1 -1
- package/dist/.dts/runtime/document.d.ts +7 -4
- package/dist/.dts/runtime/document.d.ts.map +1 -1
- package/dist/.dts/runtime/index.d.ts +11 -10
- package/dist/.dts/runtime/index.d.ts.map +1 -1
- package/dist/.dts/runtime/types.d.ts +16 -0
- package/dist/.dts/runtime/types.d.ts.map +1 -1
- package/dist/.dts/runtime/validate.d.ts +14 -1
- package/dist/.dts/runtime/validate.d.ts.map +1 -1
- package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
- package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/_ipc/display-path.d.ts +27 -0
- package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/_ipc/glob.d.ts +22 -0
- package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/_ipc/typescript.d.ts +20 -0
- package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/assemble-project.d.ts +47 -0
- package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
- package/dist/.dts7/build/change-model.d.ts +63 -0
- package/dist/.dts7/build/change-model.d.ts.map +1 -0
- package/dist/.dts7/build/check-artifacts.d.ts +48 -0
- package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/citation-verification.d.ts +62 -0
- package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
- package/dist/.dts7/build/compatibility.d.ts +83 -0
- package/dist/.dts7/build/compatibility.d.ts.map +1 -0
- package/dist/.dts7/build/compiler-api.d.ts +12 -0
- package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/build/contract-model.d.ts +93 -0
- package/dist/.dts7/build/contract-model.d.ts.map +1 -0
- package/dist/.dts7/build/deep-equal.d.ts +9 -0
- package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
- package/dist/.dts7/build/deep-freeze.d.ts +20 -0
- package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-graph.d.ts +170 -0
- package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-model.d.ts +81 -0
- package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
- package/dist/.dts7/build/discover.d.ts +41 -0
- package/dist/.dts7/build/discover.d.ts.map +1 -0
- package/dist/.dts7/build/display-path.d.ts +6 -0
- package/dist/.dts7/build/display-path.d.ts.map +1 -0
- package/dist/.dts7/build/docs.d.ts +176 -0
- package/dist/.dts7/build/docs.d.ts.map +1 -0
- package/dist/.dts7/build/env-example.d.ts +85 -0
- package/dist/.dts7/build/env-example.d.ts.map +1 -0
- package/dist/.dts7/build/errors.d.ts +78 -0
- package/dist/.dts7/build/errors.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-cache.d.ts +74 -0
- package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-model.d.ts +50 -0
- package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-reference.d.ts +67 -0
- package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
- package/dist/.dts7/build/exclusive-group.d.ts +19 -0
- package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
- package/dist/.dts7/build/finding-model.d.ts +80 -0
- package/dist/.dts7/build/finding-model.d.ts.map +1 -0
- package/dist/.dts7/build/generate-documentation.d.ts +176 -0
- package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/generate-evidence.d.ts +77 -0
- package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
- package/dist/.dts7/build/generate-manifest.d.ts +101 -0
- package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
- package/dist/.dts7/build/generate-usage.d.ts +95 -0
- package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
- package/dist/.dts7/build/generated-banner.d.ts +43 -0
- package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/build/glob.d.ts +6 -0
- package/dist/.dts7/build/glob.d.ts.map +1 -0
- package/dist/.dts7/build/governance-fields.d.ts +34 -0
- package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
- package/dist/.dts7/build/humanize-key.d.ts +14 -0
- package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
- package/dist/.dts7/build/index.d.ts +105 -0
- package/dist/.dts7/build/index.d.ts.map +1 -0
- package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
- package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
- package/dist/.dts7/build/link.d.ts +223 -0
- package/dist/.dts7/build/link.d.ts.map +1 -0
- package/dist/.dts7/build/literal-eval.d.ts +24 -0
- package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
- package/dist/.dts7/build/live-expirations.d.ts +47 -0
- package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
- package/dist/.dts7/build/manifest.d.ts +31 -0
- package/dist/.dts7/build/manifest.d.ts.map +1 -0
- package/dist/.dts7/build/map-utils.d.ts +8 -0
- package/dist/.dts7/build/map-utils.d.ts.map +1 -0
- package/dist/.dts7/build/merge-documentation.d.ts +35 -0
- package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/ownership-model.d.ts +59 -0
- package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
- package/dist/.dts7/build/parse.d.ts +207 -0
- package/dist/.dts7/build/parse.d.ts.map +1 -0
- package/dist/.dts7/build/reference-projections.d.ts +170 -0
- package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
- package/dist/.dts7/build/sarif.d.ts +66 -0
- package/dist/.dts7/build/sarif.d.ts.map +1 -0
- package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
- package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
- package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
- package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
- package/dist/.dts7/build/source-position.d.ts +69 -0
- package/dist/.dts7/build/source-position.d.ts.map +1 -0
- package/dist/.dts7/build/tool-version.d.ts +8 -0
- package/dist/.dts7/build/tool-version.d.ts.map +1 -0
- package/dist/.dts7/build/types.d.ts +7 -0
- package/dist/.dts7/build/types.d.ts.map +1 -0
- package/dist/.dts7/build/typescript.d.ts +6 -0
- package/dist/.dts7/build/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/usage-report.d.ts +124 -0
- package/dist/.dts7/build/usage-report.d.ts.map +1 -0
- package/dist/.dts7/cli/filesystem.d.ts +7 -0
- package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
- package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
- package/dist/.dts7/evidence/define-projection.d.ts +52 -0
- package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
- package/dist/.dts7/evidence/index.d.ts +23 -0
- package/dist/.dts7/evidence/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/index.d.ts +135 -0
- package/dist/.dts7/helpers/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/processors.d.ts +32 -0
- package/dist/.dts7/helpers/processors.d.ts.map +1 -0
- package/dist/.dts7/helpers/validators.d.ts +68 -0
- package/dist/.dts7/helpers/validators.d.ts.map +1 -0
- package/dist/.dts7/node/index.d.ts +2 -0
- package/dist/.dts7/node/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/cache.d.ts +17 -0
- package/dist/.dts7/runtime/cache.d.ts.map +1 -0
- package/dist/.dts7/runtime/create.d.ts +23 -0
- package/dist/.dts7/runtime/create.d.ts.map +1 -0
- package/dist/.dts7/runtime/document.d.ts +223 -0
- package/dist/.dts7/runtime/document.d.ts.map +1 -0
- package/dist/.dts7/runtime/errors.d.ts +55 -0
- package/dist/.dts7/runtime/errors.d.ts.map +1 -0
- package/dist/.dts7/runtime/index.d.ts +25 -0
- package/dist/.dts7/runtime/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/registry.d.ts +12 -0
- package/dist/.dts7/runtime/registry.d.ts.map +1 -0
- package/dist/.dts7/runtime/reset.d.ts +8 -0
- package/dist/.dts7/runtime/reset.d.ts.map +1 -0
- package/dist/.dts7/runtime/types.d.ts +191 -0
- package/dist/.dts7/runtime/types.d.ts.map +1 -0
- package/dist/.dts7/runtime/validate.d.ts +27 -0
- package/dist/.dts7/runtime/validate.d.ts.map +1 -0
- package/dist/{build-LFHPVDQL.js → build-DNAYWD2B.js} +8 -5
- package/dist/build-DNAYWD2B.js.map +1 -0
- package/dist/build.cjs +7 -4
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +7 -4
- package/dist/build.js.map +1 -1
- package/dist/build.ts7.d.cts +1 -0
- package/dist/build.ts7.d.ts +1 -0
- package/dist/{chunk-ZW3BLAPD.js → chunk-HAGMVMN5.js} +2 -2
- package/dist/cli/index.js +3 -3
- package/dist/eslint-plugin/index.cjs +8 -5
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +8 -5
- package/dist/eslint-plugin/index.js.map +1 -1
- package/dist/eslint-plugin/index.ts7.d.cts +1 -0
- package/dist/eslint-plugin/index.ts7.d.ts +1 -0
- package/dist/evidence.ts7.d.cts +1 -0
- package/dist/evidence.ts7.d.ts +1 -0
- package/dist/helpers.ts7.d.cts +1 -0
- package/dist/helpers.ts7.d.ts +1 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/index.ts7.d.cts +1 -0
- package/dist/index.ts7.d.ts +1 -0
- package/dist/node.ts7.d.cts +1 -0
- package/dist/node.ts7.d.ts +1 -0
- package/examples/README.md +46 -80
- package/package.json +37 -6
- package/schemas/env-cap-report.schema.json +1 -1
- package/skills/env-cap/SKILL.md +1 -1
- package/skills/env-cap/references/api.md +1 -1
- package/specs/architecture.md +2 -2
- package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
- package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
- package/specs/generated-artifacts.md +14 -2
- package/dist/build-LFHPVDQL.js.map +0 -1
- /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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
advisories stay public
|
|
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
|
|
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
|
-
|
|
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
|
-
- **
|
|
52
|
-
|
|
53
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
78
|
-
|
|
79
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
`
|
|
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
|
-
|
|
192
|
-
environment-contract lifecycle.
|
|
193
|
-
|
|
194
|
-
Applications remain responsible for:
|
|
81
|
+
These stay with you:
|
|
195
82
|
|
|
196
|
-
- **
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
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
|
-
|
|
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
|
-
|
|
212
|
-
Custom validation logic controls its own errors.
|
|
91
|
+
What a reviewer of the build and publish pipeline can rely on:
|
|
213
92
|
|
|
214
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
113
|
+
This is maintainer policy, not a mechanism.
|
|
230
114
|
|
|
231
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
5
|
+
How to get help with `@maverickcer/env-cap`, report a bug, or ask for a change.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Before opening an issue
|
|
8
8
|
|
|
9
|
-
|
|
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
|
-
|
|
12
|
+
## Questions and usage help
|
|
12
13
|
|
|
13
|
-
|
|
14
|
-
|
|
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
|
-
|
|
17
|
+
## Bug reports
|
|
18
18
|
|
|
19
|
-
|
|
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
|
|
27
|
+
- Any relevant code, configuration or logs
|
|
44
28
|
|
|
45
|
-
|
|
29
|
+
A minimal reproducible example shortens the time to a fix.
|
|
46
30
|
|
|
47
|
-
## Feature
|
|
31
|
+
## Feature requests
|
|
48
32
|
|
|
49
|
-
|
|
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
|
|
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
|
-
|
|
42
|
+
Do not report security vulnerabilities through public Issues. Follow the private process in
|
|
43
|
+
[SECURITY.md](SECURITY.md).
|
|
69
44
|
|
|
70
|
-
|
|
45
|
+
## Supported versions
|
|
71
46
|
|
|
72
|
-
|
|
47
|
+
Only the latest released version receives fixes. This is policy; nothing enforces it.
|
|
73
48
|
|
|
74
|
-
|
|
49
|
+
## Response expectations
|
|
75
50
|
|
|
76
|
-
|
|
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.
|