Brazilian Utils

Every workflow declares a top-level permissions: contents: read, so any job that does not state its own permissions runs read-only; the few jobs that need more (release-please, the dataset PR job, the Scorecard upload) escalate at job level only. zizmor's excessive-permissions audit runs on every pull request and fails the build if a workflow drops this.

Releases follow Semantic Versioning and are cut by release-please: each one gets a git tag (e.g. v2.4.0), a GitHub Release and the matching version on npm (https://www.npmjs.com/package/@brazilian-utils/brazilian-utils?activeTab=versions). CHANGELOG.md records every version.

CHANGELOG.md is generated by release-please from the Conventional Commits history and the same text becomes the GitHub Release notes; security fixes appear as fix: entries and any advisory is linked from the release.

CI and the release job install with npm ci from package-lock.json; every GitHub Action is pinned to a full commit SHA and updated by Dependabot (.github/dependabot.yml); the release is built and published only by the workflow.

Every version is published with npm provenance: a Sigstore attestation signed by the release workflow's OIDC identity that covers the package tarball and its sha512 integrity hash, recorded in the public transparency log, plus the registry's own signature. Consumers verify both with npm audit signatures; the attestation is shown on the version's Provenance panel on npmjs.com.

CONTRIBUTING.md "Zero runtime dependencies" and "Supply chain" describe the no-runtime-dependency rule, npm ci from the lockfile, SHA-pinned actions, weekly Dependabot updates, OSV-Scanner, audit-ci and lockfile-lint.

README "Development" and CONTRIBUTING.md "Getting started" document the requirements (Node.js 24 per .nvmrc, npm) and the commands (npm install, npm run check, npm test, npm run build); the toolchain (Vite+) is a dev dependency, nothing global is needed.

MAINTAINERS.md (https://github.com/brazilian-utils/javascript/blob/main/MAINTAINERS.md) lists the maintainers, the only accounts with write/admin access to the repository and publish rights on npm; .github/CODEOWNERS mirrors it.

MAINTAINERS.md "Roles" defines the contributor, maintainer and automation roles and what each one does (review, merge, release approval on npm with 2FA, triage of security reports, datasets and toolchain upkeep); CONTRIBUTING.md "Governance" points to it.

CONTRIBUTING.md requires tests for new behaviour, passing lint/type/coverage/duplication/unused-code/mutation gates, Conventional Commit messages, docs in both languages, no runtime dependencies, no unagreed breaking changes and an API Extractor baseline review; the pull request template repeats the checklist.

The Check (format, lint, types, dependency and lockfile checks, API baseline, audit-ci), Tests, Build, Mutation tests and Security workflows run on every pull request and are required status checks on main; a merge with a failing check needs an explicit, audited administrator bypass.

The Tests workflow runs the full vitest suite with coverage on every pull request (Node.js 20/22/24/26, Bun, Deno and Chrome/Firefox/Edge/Safari), and the Mutation tests workflow runs Stryker; both are required before merging.

CONTRIBUTING.md "Architecture" describes the layout (src/<util>/, _internals, generated datasets), the rule that utilities are synchronous, stateless and side-effect free, the two utilities that perform network I/O and how they treat responses, the trust boundary of the published package, and the actors around the code (consumers, contributors, maintainers, CI, Dependabot, release-please).

The package's only interface is its exported functions: docs/utilities.md documents every one with parameters, return values and examples, and the public API surface is checked in CI against the reviewed baseline reports/api/brazilian-utils.api.md (API Extractor). The only external interfaces the code itself calls, the public CEP APIs used by getAddressInfoByCep and getCepInfoByAddress, are described in those utilities' docs and in the Architecture section.

SECURITY.md "What's in scope" records the assessment for a zero-dependency utility library: the likely problems are unsafe behaviour of a validator or formatter on adversarial input (ReDoS, prototype pollution, dynamic code), the two utilities that consume external CEP APIs, and the integrity of the build and release tooling; the controls follow from it (mutation-tested suites, no runtime dependencies, SHA-pinned actions, OIDC publishing with provenance, workflow linting, OpenSSF Scorecard on every push).

SECURITY.md "Response timeline" and "Disclosure": reports are acknowledged within 7 days, assessed within 14 days and fixed or mitigated within 90 days of confirmation; the reporter is kept informed, a new date is agreed when a fix needs longer, and the fix is released together with a GitHub Security Advisory.

SECURITY.md provides two private channels: GitHub Private Vulnerability Reporting on the repository (Security tab → "Report a vulnerability"), which opens a private thread with the maintainers, and the e-mail support@brazilian-utils.com.br.

SECURITY.md "Disclosure": every confirmed vulnerability is published as a GitHub Security Advisory with a CVE, listing affected and fixed versions and any workaround, at https://github.com/brazilian-utils/javascript/security/advisories. None has been reported to date.