Merge pull request #540 from brazilian-utils/claude/osps-baseline-level-2-docs

docs+ci: OSPS Baseline Levels 2–3 — security policies, DCO, MAINTAINERS.md, secret scanning, SBOM in the package, Context7

Author: hyanmandian

.github/workflows/check.yml

@@ -56,5 +56,8 @@ jobs:
       - name: Check llms.txt/llms-full.txt are up to date
         run: npm run build:llms && git diff --exit-code -- docs/llms.txt docs/llms-full.txt
 
+      - name: Check the VEX statements against the suppressed advisories
+        run: npm run check:vex
+
       - name: Audit dependencies
         run: npx --yes audit-ci@7.1.0 --high --allowlist GHSA-jmr9-qjv8-65gv GHSA-7pqw-9j4j-h8q3

.github/workflows/context7.yml

@@ -0,0 +1,37 @@
+# Asks Context7 (https://context7.com/brazilian-utils/javascript) to re-index the documentation
+# whenever what it reads changes on `main`; without this it refreshes on its own schedule. The
+# request needs the CONTEXT7_API_KEY secret from the Context7 dashboard (Settings -> Secrets and
+# variables -> Actions); until it is set, the job says so and exits green.
+name: Context7
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "README.md"
+      - "context7.json"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  refresh:
+    name: Refresh the Context7 index
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    env:
+      CONTEXT7_API_KEY: ${{ secrets.CONTEXT7_API_KEY }}
+
+    steps:
+      - name: Trigger the refresh
+        run: |
+          if [ -z "$CONTEXT7_API_KEY" ]; then
+            echo "::notice::CONTEXT7_API_KEY is not set, skipping the Context7 refresh"
+            exit 0
+          fi
+          curl --silent --show-error --fail-with-body -X POST https://context7.com/api/v1/refresh \
+            -H "Content-Type: application/json" \
+            -H "Authorization: Bearer $CONTEXT7_API_KEY" \
+            -d '{"libraryName": "/brazilian-utils/javascript"}'

.github/workflows/release.yml

@@ -112,6 +112,11 @@ jobs:
           echo "npm ${npm_version}"
           echo "${npm_version}" | awk -F. '{ exit !($1 > 11 || ($1 == 11 && $2 >= 15)) }'
 
+      - name: Generate the CycloneDX SBOM shipped inside the package
+        # `files` in package.json lists brazilian-utils.cdx.json, so the tarball carries it;
+        # --package-lock-only reads the lockfile instead of installing anything.
+        run: npm sbom --sbom-format cyclonedx --omit dev --package-lock-only > brazilian-utils.cdx.json
+
       - name: Stage on npm
         run: npm stage publish --provenance --access public
 

.github/workflows/security.yml

@@ -52,6 +52,28 @@ jobs:
           scan-args: |
             --lockfile=package-lock.json
 
+  secrets:
+    name: Scan for committed secrets
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # The scan walks the commits between the base and the head of the pull request (or of
+          # the push), so it needs the history, not just the checked-out tree.
+          fetch-depth: 0
+          persist-credentials: false
+
+      # GitHub's push protection rejects known token formats at push time; this is the second,
+      # tool-independent check, over the commits of the pull request or push and, on the weekly
+      # run and on a manual one, over the whole history.
+      - name: Run TruffleHog
+        uses: trufflesecurity/trufflehog@f714bf454f350590f4a24c3ddb1aef02c35bf5b6 # v3.97.5
+        with:
+          extra_args: --results=verified,unknown
+
   scorecard:
     name: OpenSSF Scorecard
     # Scorecard only analyses the default branch, so pull requests are skipped.

.gitignore

@@ -7,6 +7,11 @@ node_modules
 dist
 coverage
 .stryker-tmp
+# Nothing in the project reads one, so a local `.env` never has a reason to be committed.
+.env
+.env.*
+# The SBOM is generated by the release workflow right before publishing.
+*.cdx.json
 # Every report is generated (stryker, coverage, jscpd) except the API Extractor baseline, which is
 # committed so that `npm run check:api` compares the public API against the reviewed one instead of
 # writing a new file on every run.

CONTRIBUTING.md

@@ -53,11 +53,41 @@ and is invoked through the `npm` scripts below, so you don't need to install any
 | `npm run check:api:update`                                                                                                | Rewrites the committed API Extractor baseline `reports/api/brazilian-utils.api.md` from the current build; run it when a public signature changes on purpose and commit the new report.                                                                                  |
 | `npm run check:commits`                                                                                                   | Checks the commit messages since `origin/main` with commitlint (Conventional Commits).                                                                                                                                                                                   |
 | `npm run check:lockfile`                                                                                                  | Checks `package-lock.json` only resolves to the npm registry over HTTPS with integrity hashes (lockfile-lint).                                                                                                                                                           |
+| `npm run check:vex`                                                                                                       | Checks that every advisory suppressed for `audit-ci` and OSV-Scanner has a `not_affected` statement in `openvex.json`, and nothing else does.                                                                                                                            |
 
 Before opening a pull request, make sure `npm run check` and `npm run test` both pass locally. If your
 change touches runtime behavior, also consider running the Bun/Deno scripts above. The library is
 tested and must keep working on Node.js, Bun, Deno and in browsers.
 
+## Architecture
+
+The library is a flat collection of pure functions, so there is not much architecture to learn,
+but the few rules below hold everywhere:
+
+- `src/<util>/<util>.ts` is one exported utility, next to its `<util>.test.ts`; `src/index.ts`
+  re-exports it and `package.json` exposes it as a subpath import, so consumers bundle only what
+  they call.
+- `src/_internals/` holds the helpers shared between utilities (check-digit arithmetic, `mod10`/
+  `mod11`, TLV parsing for Pix, sanitizers). `src/_internals/constants/` holds the datasets
+  (banks, municipalities, CNAE, CBO, CFOP, NCM, legal natures), generated by the `scripts/`
+  from their official sources and refreshed by the `Update datasets` workflow through
+  a pull request, never edited by hand.
+- Utilities are synchronous, stateless and side-effect free: input in, value out, no globals, no
+  environment access, no dynamic code. The two exceptions are `getAddressInfoByCep` and
+  `getCepInfoByAddress`, the only utilities that do I/O: they query public CEP APIs (BrasilAPI,
+  ViaCEP and the alternatives listed in their docs) over HTTPS through
+  `src/_internals/fetch-with-retry`, treat every response as untrusted input and never send anything
+  but the CEP or address being looked up.
+- There are no runtime dependencies (see [Zero runtime dependencies](#zero-runtime-dependencies)),
+  so the trust boundary of the published package is this repository, its build toolchain and the
+  npm registry; [MAINTAINERS.md](MAINTAINERS.md) lists who can change what, and
+  [SECURITY.md](SECURITY.md) how a release is verified.
+
+The actors around the code are the consumers of the npm package, the contributors (pull requests
+from forks), the maintainers (review, merge, release approval) and the automation: GitHub Actions
+builds, tests and publishes, Dependabot and the `Update datasets` workflow open update pull requests, and
+release-please turns merged commits into releases.
+
 ## Adding a new utility
 
 Brazilian Utils follows a consistent folder convention for every utility. To add a new one (for
@@ -248,16 +278,21 @@ export that goes missing.
 - Every GitHub Action is pinned to a full commit SHA with the version in a trailing comment
   (Dependabot updates both). Checkouts use `persist-credentials: false`.
 - The `Security` workflow lints the workflows themselves with
-  [actionlint](https://github.com/rhysd/actionlint) and [zizmor](https://github.com/zizmorcore/zizmor)
-  and scans `package-lock.json` with [OSV-Scanner](https://google.github.io/osv-scanner/); the
-  `Check` workflow runs `audit-ci` and lockfile-lint on top. The `Security` workflow also runs the
+  [actionlint](https://github.com/rhysd/actionlint) and [zizmor](https://github.com/zizmorcore/zizmor),
+  scans `package-lock.json` with [OSV-Scanner](https://google.github.io/osv-scanner/) and scans the
+  commits of every pull request (the whole history on the weekly run) for leaked secrets with
+  [TruffleHog](https://github.com/trufflesecurity/trufflehog), next to GitHub's own secret scanning
+  and push protection; the `Check` workflow runs `audit-ci` and lockfile-lint on top, and
+  `npm run check:vex` keeps the advisories those two suppress accounted for in `openvex.json` (see
+  SECURITY.md). The `Security` workflow also runs the
   [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/brazilian-utils/javascript) on
   every push to `main` and weekly: it grades the repository configuration (pinned actions, token
   permissions, branch protection, code review, dependency updates, SAST) rather than the code,
   publishes the score and uploads the findings to the Security tab.
-- Every release run keeps `brazilian-utils.cdx.json` as a workflow artifact (`sbom-<tag>`), a
-  CycloneDX SBOM of the published package generated with `npm sbom` from the release tag; releases
-  are immutable here, so the file cannot be attached to the release itself. The package has no
+- Every release ships `brazilian-utils.cdx.json` inside the package, a CycloneDX SBOM generated
+  with `npm sbom` from the release tag right before staging on npm, and keeps the same file as a
+  workflow artifact (`sbom-<tag>`); releases are immutable here, so the file cannot be attached to
+  the release itself. The package has no
   runtime dependencies, so the document describes the package itself; it exists for consumers
   whose supply-chain policy requires one.
 - Commit messages are checked with commitlint on every pull request, since release-please derives
@@ -300,6 +335,19 @@ chore(deps-dev): bump vitest
 Releases are cut from these commit types (see [Releasing](#releasing) below), so an accurate
 type/scope matters.
 
+### Developer Certificate of Origin
+
+Every commit must carry a `Signed-off-by` line, as in the Linux kernel: it is your statement that
+you wrote the change, or have the right to submit it, under the project's MIT license, per the
+[Developer Certificate of Origin](https://developercertificate.org). Git adds the line for you:
+
+```bash
+git commit -s
+```
+
+`git commit -s --amend` (or `git rebase --signoff main`) fixes a commit that is missing it. Use a
+real name and an e-mail address that reaches you; GitHub's `noreply` address is fine.
+
 ## Breaking changes
 
 This library is used in production by many projects, so please do not introduce breaking changes
@@ -350,6 +398,13 @@ No local `npm login`/`npm publish` or tagging is ever needed to cut a release.
 6. Open a pull request against `main` using a Conventional Commit-style title. Fill in the pull
    request template checklist.
 
+## Governance
+
+[MAINTAINERS.md](MAINTAINERS.md) lists who maintains the project, what each role can do and how
+write access is granted and removed. In short: contributors send pull requests from forks, one
+maintainer reviews and merges them, the same maintainers approve releases on npm, and access grows
+with a track record of merged contributions, never before.
+
 ## Recognition
 
 We use [all-contributors](https://github.com/all-contributors/all-contributors) to recognize

MAINTAINERS.md

@@ -0,0 +1,55 @@
+# Maintainers
+
+This file lists who maintains Brazilian Utils, what each role can do and how someone gets there.
+Everything here applies to the `brazilian-utils/javascript` repository and to the
+`@brazilian-utils/brazilian-utils` package on npm.
+
+## Current maintainers
+
+| Maintainer                                 | GitHub                                         | Since |
+| ------------------------------------------ | ---------------------------------------------- | ----- |
+| Hyan Mandian (project lead, npm publisher) | [@hyanmandian](https://github.com/hyanmandian) | 2018  |
+
+Maintainers are the only accounts with write access to the repository and are the
+[code owners](.github/CODEOWNERS) of every path. The list above is the single source of truth;
+`.github/CODEOWNERS` and the repository collaborators on GitHub mirror it.
+
+## Roles
+
+**Contributor**: anyone who opens an issue, a discussion or a pull request from a fork. No standing
+access is needed; the CI runs the pull request with a read-only token. Contributors are credited
+in the README through all-contributors (see [Recognition](CONTRIBUTING.md#recognition)).
+
+**Maintainer**: reviews and merges pull requests, triages issues and security reports, merges the
+release pull request and approves the staged version on npm with 2FA, keeps the datasets and the
+toolchain updated, and speaks for the project in discussions. Maintainers have the `Admin` role on
+the repository, are members of the `brazilian-utils` GitHub organization (which requires two-factor
+authentication for every member) and are publishers of the package on npm (two-factor
+authentication required, publishing only through the repository's trusted publisher). They hold
+the repository's secrets under the policy in [SECURITY.md](SECURITY.md#secrets-and-credentials).
+
+**Automation**: GitHub Actions (build, tests, publish), Dependabot and release-please act with
+short-lived tokens scoped to each job (`permissions:` in every workflow); none of them can merge a
+pull request or publish a version without a maintainer's action.
+
+## Becoming a maintainer
+
+Write access is granted by the current maintainers, after review, to contributors with a sustained
+record of merged contributions (code, docs, datasets or tooling) and a track record of good
+judgment in reviews and discussions, typically over several months. The steps are:
+
+1. An existing maintainer proposes the contributor, and the current maintainers agree.
+2. The contributor enables two-factor authentication on GitHub and on npm.
+3. They receive the lowest access that lets them do the work (`Write` on the repository first;
+   `Admin` and the npm publisher role only when they take on releases), are added to this file and
+   to `.github/CODEOWNERS`, and are announced in a discussion.
+
+Maintainers who become inactive for a year or so, or who ask to step down, move to an
+**emeritus** list here and have their access removed; they are welcome back at any time through
+the same steps. Access is also reviewed whenever the GitHub organization or the npm package
+settings change.
+
+## Contact
+
+Use the channels in [SUPPORT.md](SUPPORT.md) for questions and [SECURITY.md](SECURITY.md) for
+vulnerabilities; e-mail (support@brazilian-utils.com.br) reaches the maintainers directly.