envguardr

The project provides an upgrade path and keeps the previous major: v4 documents a migration guide from v3 (each v3 schema
construct mapped to its v4 equivalent, with examples), the v3 documentation stays online at /v3/, v3 receives security fixes for six
months after 4.0.0, and the release pipeline publishes maintenance releases of an older major under a separate npm dist-tag
(release-) so they never replace latest.

URL: https://fontebasso.github.io/envguardr/#migrating

The project uses GitHub Issues to track individual issues, including bugs and enhancement requests.

See: https://github.com/fontebasso/envguardr/issues

No vulnerability reports have been received or resolved for this project in the last 12 months (there are no repository security advisories). Dependency alerts were fixed through regular dependency updates.

Coding style and correctness rules are enforced automatically with ESLint (typescript-eslint recommended rules) on every push and pull request in CI: https://github.com/fontebasso/envguardr/blob/main/.github/workflows/tests.yml (“Run linter” step). A failing lint fails the build.

The project does not build native binaries; it is TypeScript bundled with esbuild and published as JavaScript, so compiler and linker variables do not apply.

No native binaries are produced, so there are no debug symbols to preserve.

No native binaries are built and there is no recursive subdirectory build; the build is a single npm run build (esbuild + tsc).

The npm package is reproducible bit for bit. Dependencies are pinned by package-lock.json and installed with npm ci, and the build (esbuild + tsc) is deterministic. Verified for 4.0.0: running npm ci && npm run build && npm pack from the 4.0.0 tag produces a tarball with exactly the same sha1 (44046f5880ba2699f3aefb7431aecaecdd14d7e4) and sha512 integrity as the one published to npm by CI.

Installed and removed with standard conventions: npm install --save-dev envguardr / npm uninstall envguardr, npx envguardr, or the Docker image (docker pull docker.io/fontebasso/envguardr:4, removed with docker rmi). Documented at https://fontebasso.github.io/envguardr/#guide.

The software is distributed as an npm package and a container image; there is no make-style installation that would use DESTDIR or similar variables.

Developers set up everything, including tests, with the standard npm convention: git clone https://github.com/fontebasso envguardr && cd envguardr && npm ci && npm test. All tooling (TypeScript, esbuild, ESLint, Vitest, fast-check) is installed by npm ci from the lockfile.

Runtime and development dependencies are listed in package.json and pinned in package-lock.json, both machine-processable. Container images also ship an SBOM generated at build time.

URL: https://github.com/fontebasso/envguardr/blob/main/package.json

Dependencies are monitored continuously: Renovate opens update pull requests for npm packages, Docker base image digests and GitHub Actions pins (renovate.json); Dependabot alerts report known vulnerabilities; Socket and Snyk check every pull request; the OpenSSF Scorecard workflow reports known vulnerabilities on main. Example: the brace-expansion advisories (GHSA-6j4f-fj2g-mc7p, GHSA-qhr7-859c-m2p7, GHSA-q2hr-2g5m-vwhr) were fixed in pull request #106

All reused components are regular npm dependencies managed by package.json and package-lock.json; there are no vendored or copied third-party sources, so any component can be updated with npm (and is, through Renovate).

The code uses current Node.js APIs only (node:fs/promises, node:net) and current library versions kept up to date by Renovate; there are no deprecated APIs in use.

On every push to main and every pull request, GitHub Actions runs the full test suite on Node.js 22, 24 and 26 and reports success or failure on the pull request: tests.yml (lint and tests), fuzz.yml (property-based fuzzing) and coverage.yml (coverage with enforcedthresholds). The release workflow also runs Docker smoke tests before publishing.

Regression tests were added for most bugs fixed in the last six months. During the 4.0 cycle, each fix came with a test that failed before the fix: base paths encoded inside documentation links (tests/docs-render.test.ts), unclear errors for empty schemas, exponent defaults, numeric enum values and YAML merge keys (tests/schema-*.test.ts), --help and repeated --format handling (tests/cli.test.ts), catastrophic backtracking and missing Unicode support in pattern (tests/validators.test.ts), and URL validation (tests/url.test.ts). The June 2026 Docker path fix is covered by the release smoke test that runs the built image. The only fix without an automated test in the period was a one-line correction of the bin path in package.json.

The Vitest suite (FLOSS) has 100% statement, branch, function and line coverage, and the thresholds are enforced at 100% in vitest.config.ts; coverage runs in CI (coverage.yml) and is published to Coveralls (badge in the README).

The contribution guidelines document that new functionality and behavior changes should include corresponding automated tests.

See: https://github.com/fontebasso/envguardr/blob/main/CONTRIBUTING.md

The project uses strict TypeScript compiler settings and ESLint rules to catch potential errors as early as practical.

See: https://github.com/fontebasso/envguardr/blob/main/tsconfig.json and https://github.com/fontebasso/envguardr/blob/main/eslint.config.js

The design applies secure design principles: least privilege (the container runs as a non-root user and works read-only with all capabilities dropped; the CLI only reads the schema file and its own environment); fail-safe defaults (any unexpected error exits with code 2 and a generic message, and unknown schema keys are rejected instead of ignored); economy of mechanism (a small pipeline: load, parse, validate, report, with no network access and no plugins); complete mediation (every value is checked against the schema rules); separation of data and code (the schema is data and is never executed, unlike v3 JavaScript schemas); and confidentiality by design (environment values never reach any output, enforced by property-based tests on every exit path).

envguardr does not implement or depend on cryptographic security mechanisms as part of its functionality.

The software does not implement or use cryptography, store credentials, or communicate over the network: it reads a local schema file and its own process environment and writes the result to stdout/stderr.

The software does not implement or use cryptography, store credentials, or communicate over the network: it reads a local schemafile and its own process environment and writes the result to stdout/stderr.

The software does not implement or use cryptography, store credentials, or communicate over the network: it reads a local schema file and its own process environment and writes the result to stdout/stderr.

The software does not implement or use cryptography, store credentials, or communicate over the network: it reads a local schema file and its own process environment and writes the result to stdout/stderr.

The software does not implement or use cryptography, store credentials, or communicate over the network: it reads a local schema file and its own process environment and writes the result to stdout/stderr.

The software does not implement or use cryptography, store credentials, or communicate over the network: it reads a local schema file and its own process environment and writes the result to stdout/stderr.

Releases are signed without long-lived private keys. Container images are signed with Sigstore cosign in keyless mode (OIDC identity of the release workflow) and ship SBOM and provenance attestations; the verification command is documented in the README and the documentation. npm packages are published with npm Trusted Publishing and Sigstore provenance, verifiable with npm audit signatures. No signing key is stored on any distribution site.

URL: https://fontebasso.github.io/envguardr/#security

All inputs are validated against allowlists: the schema must match a strict structure (unknown keys, misplaced constraints and invalid values are rejected with the path of the error), YAML is parsed with the 1.2 core schema without custom tags and with an alias limit, CLI arguments accept only known commands and options, and each environment value is checked against its declared type and constraints (RFC 3986/3987 for URLs, RE2 patterns, ranges, lengths, formats).

Hardening in place: distroless non-root container image (uid 65532) that also runs with a read-only root filesystem and all capabilities dropped; images pinned by digest and signed; pattern uses RE2 so matching is linear-time and cannot be used for ReDoS by values from the environment; YAML parsing limits aliases and disables custom tags; unexpected errors never print their message.

GitHub CodeQL is executed in CI and applies security-focused static analysis rules for JavaScript/TypeScript, including checks for common vulnerability patterns.

See: https://github.com/fontebasso/envguardr/actions/runs/32522037480/job/96896115533#step:5:1

The project is implemented in TypeScript/JavaScript and does not contain software written in a memory-unsafe language such as C or C++.