Brazilian Utils

Permissions are scoped per job: the only jobs with more than contents: read are release-please (contents/pull-requests: write), the dataset PR job (same), the npm publish job (id-token: write) and the Scorecard upload (security-events: write, id-token: write); zizmor enforces it on every pull request.

The workflows accept no free-form input: there are no workflow_dispatch inputs, and the only expressions used inside shell steps are a commit SHA and a value from the workflow's own matrix; zizmor's template-injection audit blocks anything else.

Each release's assets carry its version: the npm tarball brazilian-utils-brazilian-utils-<version>.tgz and the provenance attestation are bound to the version on the registry, the GitHub Release is tagged v<version>, and the SBOM artifact is named sbom-v<version>.

SECURITY.md "Secrets and credentials" (https://github.com/brazilian-utils/javascript/blob/main/SECURITY.md#secrets-and-credentials): no credential lives in the repository, the package or the site; npm publishing uses Trusted Publishing (OIDC) so there is no npm token; the only two secrets (Codecov and Stryker dashboard tokens) are GitHub Actions encrypted secrets readable by the workflows alone and settable only by maintainers with the Admin role; they are rotated when a maintainer leaves, when a workflow that used them is removed, on a provider exposure notice and on any suspected leak; push protection and TruffleHog detect accidental storage.

SECURITY.md "Verifying a release": consumers run npm audit signatures, which verifies the registry signature and the Sigstore provenance attestation of every installed version, and can inspect the attestation on the version's Provenance panel on npmjs.com.

The same section explains that every version is published by the Release workflow of this repository through OIDC Trusted Publishing, never from a maintainer's machine, and that the provenance attestation names the exact workflow run and commit that built it, visible on the Provenance panel of the version on npmjs.com.

SECURITY.md "Supported Versions" states that only the latest major version (2.x) is supported and receives updates, and README "Runtime support" lists the supported runtimes; older majors are unsupported and users are asked to upgrade.

SECURITY.md "Supported Versions" table marks every version below 2.0 as no longer receiving security updates; a major version stops receiving them when the next major is released.

MAINTAINERS.md "Becoming a maintainer": write access is granted only by the current maintainers, after review, to contributors with a sustained record of merged contributions; it requires two-factor authentication on GitHub and npm, starts with the lowest access that lets them do the work, and is removed after inactivity or on request.

Every version published to npm carries its CycloneDX SBOM inside the package: the release workflow generates brazilian-utils.cdx.json with npm sbom from the release tag right before npm stage publish, and package.json lists it in files, so it is installed alongside the code (node_modules/@brazilian-utils/brazilian-utils/brazilian-utils.cdx.json). The same file is kept as the sbom-<tag> artifact of the release run. The package has zero runtime dependencies, so the SBOM describes the package itself.

Single-repository project; there are no subprojects.

CONTRIBUTING.md "Useful scripts" and "Code quality gates" list every test command (npm test, coverage, Bun, Deno, browsers, mutation) and state that the Tests and Mutation tests workflows run them on every pull request and push to main; the pull request template asks contributors to run them locally.

CONTRIBUTING.md "Submitting a pull request": "Add or update tests. PRs without tests for new behavior will not be merged", plus mutation testing for changed production code; the pull request template has the matching checkbox.

SECURITY.md "Threat model" (https://github.com/brazilian-utils/javascript/blob/main/SECURITY.md#threat-model) lists the assets (package integrity, validator correctness, consumer availability, the CEP/address sent to third-party APIs), the actors and entry points (function arguments from end users, CEP API responses, fork pull requests, maintainers, CI, npm) and a threat/mitigation table covering adversarial input and prototype pollution, malicious dependencies, fork pull requests, pipeline tampering, maintainer account compromise, hostile CEP API responses and stale datasets; it is updated with every fix that reveals a missing threat.

The project publishes an OpenVEX document, openvex.json at the repository root (https://github.com/brazilian-utils/javascript/blob/main/openvex.json), with a not_affected statement (justification component_not_present, with an impact statement) for every advisory that is suppressed in the dependency scanners: today the two extract-zip advisories, a development-only transitive dependency of the browser test runner that is not present in the published package (zero runtime dependencies). npm run check:vex runs on every pull request and fails when the VEX document and the audit-ci/OSV-Scanner suppression lists disagree, so an exception cannot exist without its VEX statement. SECURITY.md "Dependency and static-analysis policy" documents the rule.

SECURITY.md "Dependency and static-analysis policy": no dependency with a known vulnerability of high or critical severity may be merged or released; lower severities are fixed in the next regular Dependabot update and before the next release when a fixed version exists; an advisory may be allow-listed only when it cannot reach the published package or the release pipeline, is named by ID in .github/workflows/check.yml so the exception is reviewable, and is removed as soon as a fix exists. The published package has zero runtime dependencies and a pull request adding one is not merged.

The same policy in SECURITY.md requires SCA violations to be addressed before a release: high and critical findings block the pull request itself (audit-ci --high, OSV-Scanner), lower severities are fixed before the next release when a fixed version exists, and the weekly Security run catches advisories published between releases; release-please only cuts a release from a main where every required check passed.

Every pull request runs audit-ci --high (Check workflow), which fails on any high or critical advisory in the dependency tree, with the two allow-listed advisories declared by ID in the workflow as non-exploitable dev-only findings, and OSV-Scanner over package-lock.json (Security workflow); both are required checks, and Dependabot opens the updates weekly. The published package has zero runtime dependencies.

SECURITY.md "Dependency and static-analysis policy": static analysis has no accepted threshold of open findings; every ESLint, TypeScript, knip, jscpd, actionlint and zizmor finding blocks the merge, OpenSSF Scorecard findings uploaded to the Security tab are worked in the next change to the affected file, and the only suppressions are the documented Stryker equivalent-mutant comment and the audit-ci allow list.

Every pull request must pass vp check (ESLint with security-relevant rules, strict TypeScript), knip, jscpd and, for the workflows, actionlint and zizmor at min-severity: low; any finding blocks the merge, with no suppression allowed except the documented Stryker equivalent-mutant comment. OpenSSF Scorecard uploads its findings to the Security tab on every push to main.