@avi2dg/checks 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.32.0
+
+Released 2026-09-29.
+
+### Features
+
+- **delivery:** add checks-secrets gate that fails a range whose commits add a secret [#112](https://github.com/avi2d/checks/pull/112)
+- **delivery:** open a release pull request daily and tag it when it merges [#111](https://github.com/avi2d/checks/pull/111)
+
 ## 0.31.0
 
 Released 2026-09-28.

package/README.md

@@ -127,6 +127,7 @@ The table groups the gates by vector, the part of a repository each one judges.
 | docs | [`checks-docs`](docs/gates/checks-docs.md) | the range, and every agent file at the head commit | every repository |
 | delivery | [`checks-commit-identity`](docs/gates/checks-commit-identity.md) | the range | every repository |
 | delivery | [`checks-ci-wiring`](docs/gates/checks-ci-wiring.md) | the working tree | every repository |
+| delivery | [`checks-secrets`](docs/gates/checks-secrets.md) | the range | every repository |
 | dependencies | [`checks-advisories`](docs/gates/checks-advisories.md) | the range | a repository tracking `bun.lock` |
 
 <!-- end generated gates -->
@@ -141,6 +142,8 @@ These bins run on their own:
 - [`checks-changelog`](docs/gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
 - [`checks-release-notes`](docs/gates/checks-release-notes.md) writes one `CHANGELOG.md` section to a file for a GitHub release.
 - [`checks-release-report`](docs/gates/checks-release-report.md) tells whether the history holds unreleased features or fixes since the last tag.
+- [`checks-release-pr`](docs/gates/checks-release-pr.md) opens or refreshes the pull request that releases the next version, and dispatches its checks.
+- [`checks-release-tag`](docs/gates/checks-release-tag.md) tags a landed release commit with its version and dispatches the release workflow on the tag.
 - [`checks-vendor`](docs/gates/checks-vendor.md) pins each library its `prepare` arguments name to a shared read-only clone and links it under `repos/`.
 
 `checks-lint` has [its own page](docs/gates/checks-lint.md), which says which range it resolves.

package/docs/configs/commit-messages.md

@@ -23,6 +23,11 @@ It lints the pull request title and nothing else.
 The title is the enforced subject because a squash merge uses it as the main commit subject, and per-commit messages are not linted.
 GitHub appends ` (#N)` to the squashed subject, so the workflow lints the title with that suffix attached, and the header length limit applies to the landed subject, not the bare title.
 The workflow moves git's comment character off `#`, so a title starting with `#` is linted like any other.
+The workflow also triggers on `workflow_dispatch`, since GitHub holds the `pull_request` runs of a release pull request the workflow token opens until a maintainer approves them, as [checks-release-pr](../gates/checks-release-pr.md) says.
+A dispatched run carries no pull request, so the workflow reads the title of the one open pull request its branch heads, and fails when there is none.
+That lookup needs the workflow's `pull-requests: read` permission.
+It reports a dispatched run's result on the head commit as a `commitlint` status, since GitHub keeps a dispatched run's check off the pull request.
+The kit's own `.github/workflows/commitlint.yml` shows the step.
 
 It never sees a commit's author or committer fields, nor the `Co-authored-by` trailer GitHub writes from a foreign author when it squashes, so it cannot enforce who a commit belongs to.
 [checks-commit-identity](../gates/checks-commit-identity.md) is that enforcement.

package/docs/design.md

@@ -162,8 +162,24 @@ So a checkout without tags, a fork, and a branch that merged `main` in all write
 A section keeps the date it was written, because the squash merge that lands the release commit may fall on another day.
 Entries come from commit subjects, which are the squash-merged pull request titles that commitlint holds to the conventional format.
 A commit body holds the branch's own messages, and nothing lints it, so no entry comes from a body.
-The changelog arrives in the release pull request, and no workflow pushes to the repository.
-The only write access the release path holds is the `github-release` job's `contents: write`, which creates or updates the GitHub release from the tag's `CHANGELOG.md` section.
+The changelog arrives in the release pull request, and no workflow pushes to a branch a person works on.
+
+## A release is cut every day
+
+A release waits for no quiet moment, since a busy repository always has work under way.
+The daily release opens the release pull request from `main` whenever it holds a feature or a fix since the last tag, and the pull request merges through the repository's usual merge path once its checks pass.
+`checks-release-pr` writes only to the `release/<branch>` branch it owns, and rebuilds that branch on `main` rather than merging `main` into it, so the changelog it carries is the one the build writes.
+`checks-release-tag` writes only the `v*` tag of a release commit that already landed.
+The `github-release` job's `contents: write` creates or updates the GitHub release from the tag's `CHANGELOG.md` section.
+
+Both jobs act with the workflow token.
+GitHub starts no run for a push that token makes, and holds the runs of a pull request it opens until a maintainer approves them.
+A GitHub App or a personal token would start them, but either is a credential each repository stores and someone rotates.
+So `checks-release-pr` dispatches the required checks on the release head, and `checks-release-tag` dispatches the release workflow on the tag, since a dispatch is the one run the token can start.
+GitHub keeps a dispatched run's checks off the pull request, and branch protection does not count them.
+So each dispatched job reports its result as a commit status named for the job, which a required check of that name counts.
+Where a status and a check share a name, branch protection requires both, so the status never passes a pull request whose own check failed.
+The cost is a `workflow_dispatch` trigger and a status step on each workflow a release needs, a title lint that reads its title from the open pull request, and the repository setting that lets the token open a pull request.
 
 ## The docs gate judges what a change touches
 
@@ -238,6 +254,24 @@ The kit caps each entry at 30 days and measures a range from the head's dates, a
 `--all` measures from the current time instead, because a head's dates never move in a repository that takes no commit, and an entry measured from them would never expire.
 The file is JSON because `Bun.TOML` cannot parse a TOML date.
 
+## Secrets fail in every commit of the range
+
+`checks-secrets` scans each commit in the range rather than the files at the head.
+A secret a commit adds stays in that commit after a later commit deletes it, and a pushed branch has already sent it to the forge.
+So the fix is to rewrite the commit that added it, and to rotate the secret once it has left the machine.
+
+In a merge commit the gate scans only the merge's own resolution, the difference from the merge git would make on its own.
+A diff against the first parent would also scan what the merge brings in from the other parent, so a branch that merges main would fail on a secret main already holds, from before the range.
+Git gives no such diff for an octopus merge and warns instead of failing, so the gate refuses to scan one rather than pass a commit it never read.
+
+The gate runs gitleaks rather than a hand-written pattern list, because its default config already holds over 200 rules for the token shapes of common services.
+The kit's own rules in `src/delivery/gitleaks.toml` add only the VPN keys and proxy links those rules miss.
+The kit pins gitleaks by version and SHA-256 for the reason it pins OSV-Scanner.
+
+No finding can be accepted.
+A secret has no false positive worth keeping in git, because a placeholder carries the same shape without the value.
+So the gate ignores a repository's `.gitleaks.toml`, `.gitleaksignore` and `gitleaks:allow` comments, which would each let one repository pass what another fails.
+
 ## Related topics
 
 - [checks](../README.md)

package/docs/gates/checks-commit-identity.md

@@ -11,6 +11,9 @@ audience: consumers
 The author and committer of each commit must be allowed.
 A commit whose trailer block carries a `Co-authored-by` trailer, as git parses it, is refused.
 `GitHub <noreply@github.com>` is allowed as committer only.
+`github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>` is allowed as author only of a commit whose subject is `chore: release <version>`, with or without the pull request number a squash merge adds.
+GitHub attributes the release commit [checks-release-pr](checks-release-pr.md) makes to that bot, since it commits through the workflow token.
+Such a commit may carry a `Co-authored-by` trailer naming that bot, since GitHub adds one to some squash merges of a pull request the bot opened, and every other trailer is refused.
 
 ## What it reads
 

package/docs/gates/checks-lint.md

@@ -46,7 +46,7 @@ With two arguments, the base and head override range discovery.
 
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
-checks-lint: 1 of 12 gate(s) failed: checks-comment-gate
+checks-lint: 1 of 13 gate(s) failed: checks-comment-gate
 ```
 
 <!-- end generated lint-sample -->

package/docs/gates/checks-release-notes.md

@@ -55,6 +55,7 @@ name: release
 on:
   push:
     tags: ["v*"]
+  workflow_dispatch:
 permissions:
   contents: read
   id-token: write
@@ -65,6 +66,8 @@ jobs:
       - uses: actions/checkout@v5
         with:
           fetch-depth: 0
+      - name: ref is a tag
+        run: test "$GITHUB_REF_TYPE" = tag
       - uses: oven-sh/setup-bun@v2
       - run: bun install --frozen-lockfile
       - run: bun run build
@@ -102,6 +105,7 @@ name: release
 on:
   push:
     tags: ["v*"]
+  workflow_dispatch:
 permissions:
   contents: read
 jobs:
@@ -113,6 +117,8 @@ jobs:
       - uses: actions/checkout@v5
         with:
           fetch-depth: 0
+      - name: ref is a tag
+        run: test "$GITHUB_REF_TYPE" = tag
       - uses: oven-sh/setup-bun@v2
       - run: bun install --frozen-lockfile
       - run: bun run build
@@ -127,7 +133,10 @@ jobs:
         run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/release-notes.md"
 ```
 
-Cut a release by merging a pull request that holds only the version bump and the built changelog, then tagging the merge commit on the target branch and pushing the tag.
+A release is a pull request that holds only the version bump and the built changelog, which [checks-release-pr](checks-release-pr.md) opens once a day.
+When it lands, [checks-release-tag](checks-release-tag.md) tags the merge commit and dispatches this workflow on the tag.
+A tag the workflow token pushes starts no `push` run, so the workflow triggers on `workflow_dispatch` as well, and refuses a dispatch on a ref that is not a tag.
+A tag a person pushes starts the same workflow through its `push` trigger.
 The workflow refuses a tag that disagrees with `package.json`, so the tag always names the section the notes come from.
 
 ## When it runs

package/docs/gates/checks-release-pr.md

@@ -0,0 +1,185 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-release-pr
+
+`checks-release-pr` opens or refreshes the one pull request that releases the next version, and dispatches its checks on its head.
+
+## What it checks
+
+It lists the unreleased changes the way [checks-release-report](checks-release-report.md) does, and does nothing when there are none.
+It bumps the version `package.json` holds by the kit's rule:
+
+| Unreleased changes | Below 1.0.0 | From 1.0.0 |
+| --- | --- | --- |
+| a breaking change | minor | major |
+| a feature and no breaking change | minor | minor |
+| only fixes, performance changes or reverts | patch | patch |
+
+It refuses when the last release tag names a version other than the one `package.json` holds, since an untagged bump means a release landed that nothing published.
+The refusal points at the `tag` job of `daily-release` on the release commit, whose own refusal says what to fix, rather than at a tag pushed by hand.
+It refuses a version that is not a plain `major.minor.patch`.
+It writes the next version into `package.json`, runs `bun run build` so the build writes `CHANGELOG.md`, and commits every tracked file the build changed as `chore: release <version>`.
+The commit's one parent is `HEAD`.
+It makes the commit through the GitHub API, which attributes it to `github-actions[bot]` and signs it, so the job sets no git identity.
+It checks that the tree GitHub built matches the tree the build wrote.
+It points the branch `release/<branch>` at the commit, where `<branch>` is the branch `HEAD` is on.
+It opens a pull request from that branch into `<branch>` titled `chore: release <version>`, with the body `Release <version>.`, or retitles the open one to the new version.
+It then dispatches each workflow its arguments name on the release branch.
+GitHub holds the `pull_request` runs of a pull request the workflow token opens until a maintainer approves them, so the dispatch is what runs the required checks on the release head.
+GitHub keeps a dispatched run's checks off the pull request, so each dispatched job reports its result as a commit status named for the job, which the required check of that name counts.
+When the release branch already holds this version on top of `HEAD` and its pull request carries the right title, it pushes nothing and dispatches nothing.
+It leaves the working tree as it found it.
+
+## What it reads
+
+It reads the `v*` tags, the commit subjects since the last one and `package.json` from the checkout.
+It refuses a shallow checkout, a detached `HEAD` and a working tree with changes to tracked files.
+It reads the release branch from `origin` with `git ls-remote` and `git fetch`.
+It calls the GitHub API through `gh api`, which takes the repository from the checkout's remote and the token from `GH_TOKEN`.
+The token needs `contents: write`, `pull-requests: write` and `actions: write`.
+The repository needs **Allow GitHub Actions to create and approve pull requests** turned on under its Actions settings, or GitHub refuses the pull request.
+
+## Arguments
+
+```sh
+checks-release-pr <workflow>...
+```
+
+Each argument names a workflow file under `.github/workflows/` whose jobs report the checks the default branch requires, such as `ci.yml` and `commitlint.yml`.
+Each named workflow triggers on `workflow_dispatch`.
+Name no workflow that runs something else on dispatch, such as a mutation baseline.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | nothing is unreleased, or the release pull request is open on the current `HEAD` and its checks are dispatched |
+| 2 | the arguments do not parse, a refusal above applies, the build fails, or a GitHub API call fails |
+
+## Sample output
+
+A run that opens the pull request prints the build's own output, then one line:
+
+```
+release-pr: opened https://github.com/acme/widget/pull/12 to release 0.4.0, and dispatched ci.yml, commitlint.yml on release/main
+```
+
+A run on the same `HEAD` the next day prints one line:
+
+```
+release-pr: https://github.com/acme/widget/pull/12 releases 0.4.0 from 3f2a9c81d0b4 and is current
+```
+
+## When it runs
+
+The daily release workflow below runs it once a day on the default branch.
+Run the workflow by hand with `gh workflow run daily-release` to refresh the release pull request sooner.
+
+## Running it in CI
+
+A repository takes the daily release as `.github/workflows/daily-release.yml`.
+The `pull-request` job runs on the schedule, and the `tag` job runs when a release commit lands on `main`, as [checks-release-tag](checks-release-tag.md) says:
+
+```yaml
+name: daily-release
+on:
+  schedule:
+    - cron: "29 3 * * *"
+  workflow_dispatch:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  pull-request:
+    if: github.event_name != 'push'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    concurrency:
+      group: release-pull-request
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      pull-requests: write
+      actions: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - name: open or refresh the release pull request
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: ./node_modules/.bin/checks-release-pr ci.yml commitlint.yml
+  tag:
+    if: "github.event_name == 'push' && startsWith(github.event.head_commit.message, 'chore: release ')"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      actions: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - name: tag the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: ./node_modules/.bin/checks-release-tag release.yml
+```
+
+A public repository keeps `runs-on: ubuntu-latest`.
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || fromJSON('["self-hosted","Linux","X64","winbox"]') }}` on both jobs, as its other workflows do.
+A repository whose build needs more than Bun adds the steps its `.github/workflows/ci.yml` runs before `bun run build` to both jobs, and nothing after it.
+Neither job runs a test suite or a mutation run.
+On a hosted runner the `pull-request` job takes about 25 seconds, which GitHub bills as one minute, whether it opens, refreshes or leaves the pull request alone.
+A private repository runs it on its self-hosted runner, which bills no minutes.
+The `tag` job runs only when a release lands, and a job its `if` skips bills nothing.
+The checks it dispatches are the release pull request's own required checks, and they run again only when `main` moves under it.
+The pull request also lists its own `pull_request` runs as waiting for approval.
+Nothing requires them, and approving them runs the same checks again.
+
+The daily release needs the repository's other workflows to accept the dispatch:
+
+- `.github/workflows/ci.yml` and `.github/workflows/commitlint.yml` trigger on `workflow_dispatch`, grant `statuses: write`, and end each required job with the step below.
+  `commitlint.yml` also grants `pull-requests: read`, which the title lookup needs.
+- The title lint reads the title of the one open pull request its branch heads when the event carries none, as [Commit messages](../configs/commit-messages.md) says.
+- `.github/workflows/release.yml` triggers on `workflow_dispatch` and refuses a ref that is not a tag, as [checks-release-notes](checks-release-notes.md) shows.
+- **Allow GitHub Actions to create and approve pull requests** is on, which the call after the step sets.
+- A release pull request holds current `main` when it merges.
+  One that merges behind `main` lands a changelog short of the commits `main` gained, and `checks-release-tag` refuses to tag it.
+
+The step reports a dispatched run's result as a commit status on the head commit:
+
+```yaml
+      - name: report the result on the head commit
+        if: always() && github.event_name == 'workflow_dispatch'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          STATE: ${{ job.status == 'success' && 'success' || 'failure' }}
+        run: gh api "repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA" -f state="$STATE" -f context="$GITHUB_JOB" -f target_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --silent
+```
+
+The status takes the job's id as its name, so a required job's id is the check name the branch requires.
+Where a status and a check share a name, branch protection requires both, so the status never passes a pull request whose own check failed.
+The call turns the repository setting on:
+
+```sh
+gh api --method PUT repos/<owner>/<repo>/actions/permissions/workflow -F can_approve_pull_request_reviews=true
+```
+
+## Related topics
+
+- [checks-release-report](checks-release-report.md)
+- [checks-release-tag](checks-release-tag.md)
+- [checks-changelog](checks-changelog.md)
+- [checks-release-notes](checks-release-notes.md)

package/docs/gates/checks-release-report.md

@@ -27,7 +27,7 @@ checks-release-report
 ```
 
 It takes no arguments.
-Run it before cutting a tag to decide whether a release is due.
+Run it to see whether a release is due and what it holds.
 
 ## Exit codes
 
@@ -55,10 +55,12 @@ release-report: no unreleased changes since v0.1.0
 
 ## When it runs
 
-Only a person or a scheduler deciding when to cut a release runs it.
+A person runs it to see what the next release holds.
+[checks-release-pr](checks-release-pr.md) reads the same changes before it opens the release pull request.
 A repository with no versioned releases does not need it.
 
 ## Related topics
 
 - [checks-changelog](checks-changelog.md)
 - [checks-release-notes](checks-release-notes.md)
+- [checks-release-pr](checks-release-pr.md)

package/docs/gates/checks-release-tag.md

@@ -0,0 +1,63 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-release-tag
+
+`checks-release-tag` tags a landed release commit with its version and dispatches the release workflow on the tag.
+
+## What it checks
+
+It reads the subject of `HEAD`, and does nothing unless the subject is `chore: release <version>`, with or without the ` (#N)` a squash merge adds.
+It refuses a release commit whose `package.json` holds another version.
+It tags `HEAD` as `v<version>` and pushes the tag to `origin`.
+A tag the workflow token pushes starts no `push` workflow, so it then dispatches the workflow its argument names on the tag.
+It does nothing when `v<version>` already tags `HEAD`, so a rerun after a release never publishes it twice.
+When the dispatch fails after the push, it names `gh workflow run <workflow> --ref v<version>`.
+A rerun then finds the tag and does nothing, so that command is what dispatches the release workflow by hand.
+It refuses when `v<version>` already tags another commit.
+Before it pushes the tag, it runs `bun run build` and refuses when the build rewrites a committed file.
+That happens when a release pull request merged behind `main`, so its `CHANGELOG.md` lacks the commits `main` gained.
+The refusal says to open a `chore: cancel the unpublished <version>` pull request that returns `package.json` to the last tag's version and commits what `bun run build` then writes to `CHANGELOG.md`.
+The build reads the returned version as a revert, so it drops the unpublished section, and the next `daily-release` run cuts the release again with every change since the last tag.
+
+## What it reads
+
+It reads the subject of `HEAD` and `package.json` from the checkout, and the tag from `origin` with `git ls-remote`.
+The build it runs reads the whole history, so the checkout fetches all of it.
+It pushes the tag with the credentials the checkout holds.
+It calls the GitHub API through `gh api`, which takes the repository from the checkout's remote and the token from `GH_TOKEN`.
+The token needs `contents: write` and `actions: write`.
+
+## Arguments
+
+```sh
+checks-release-tag <workflow>
+```
+
+The argument names the release workflow file under `.github/workflows/`, such as `release.yml`.
+That workflow triggers on `workflow_dispatch` and keeps its own guards, as [checks-release-notes](checks-release-notes.md) shows.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | `HEAD` is no release commit, its tag already tags it, or the tag is pushed and the release workflow dispatched |
+| 2 | the arguments do not parse, `package.json` disagrees with the subject, the tag tags another commit, the build fails or rewrites a committed file, or the push or a GitHub API call fails |
+
+## Sample output
+
+A run that tags the release prints the build's own output, then one line:
+
+```
+release-tag: tagged 3f2a9c81d0b4 as v0.4.0, and dispatched release.yml on it
+```
+
+## When it runs
+
+The `tag` job of the daily release workflow runs it on each push to `main` whose head commit reads as a release, as [checks-release-pr](checks-release-pr.md#running-it-in-ci) shows.
+
+## Related topics
+
+- [checks-release-pr](checks-release-pr.md)
+- [checks-release-notes](checks-release-notes.md)

package/docs/gates/checks-secrets.md

@@ -0,0 +1,93 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-secrets
+
+`checks-secrets` is the gate that fails a range whose commits add a secret, such as an API token, a private key, a VPN key or a proxy link that carries its credential.
+
+## What it checks
+
+It scans the lines each commit in the range adds, in every file the commit adds or modifies, with gitleaks.
+In a merge commit it scans the lines the merge's own resolution adds, such as a key written while resolving a conflict, and not what the merge brings in from the other parent.
+It exits 2 when a commit it scans is an octopus merge, one with three or more parents, because git gives no resolution diff for one.
+It fails on each secret the scan finds, and names its file, its line, the rule that matched and the commit that added it.
+A secret one commit adds and a later commit in the range removes still fails, because the first commit still holds it.
+It guards new changes only, and never scans a commit before the range, so a secret already in the history takes no part.
+
+It runs gitleaks' default rules, which know the API keys and tokens of common services and private keys in PEM form, and eight rules of the kit's own that report a secret:
+
+| Rule | What it matches | What passes |
+| --- | --- | --- |
+| `wireguard-key` | a WireGuard or AmneziaWG private or pre-shared key value, 44 base64 characters, under a name that ends in `PrivateKey`, `PresharedKey` or `psk`, such as a real key after `PrivateKey =`, `"privateKey":`, `wg_private_key:` or `client_psk:` | a placeholder such as `<private-key>` or `${WG_PRIVATE_KEY}` |
+| `wireguard-key-file` | a line that holds only a WireGuard or AmneziaWG key, 44 base64 characters, in a file whose name holds `priv`, `preshared`, `pre_shared`, `pre-shared` or `psk`, such as the `privatekey` file `wg genkey \| tee privatekey` writes, whatever else the name holds | a bare key in a file with any other name, such as `publickey` or `peer.pub`, and a placeholder such as `<private-key>` |
+| `wireguard-dot-key-file` | a line that holds only a WireGuard or AmneziaWG key in a file whose name ends in `.key`, such as `wg0.key` | a file whose name ends in `pub.key` or `public.key`, such as `server-public.key`, unless `wireguard-key-file` matches its name |
+| `proxy-userinfo-link` | a `vless://`, `vmess://`, `ss://`, `trojan://`, `hysteria://`, `hysteria2://`, `hy2://`, `tuic://`, `socks://`, `socks5://`, `socks5h://`, `wireguard://` or `wg://` link whose credential before an `@` has a Shannon entropy above 2.5 bits per character, such as a real password before the `@` of a `trojan://` link or a real private key before the `@` of a `wireguard://` link, and a template reference with real text around it, such as a literal user before `:${PASS}` or a non-empty default in `${PASS:-…}` | a link with no credential such as `socks5://127.0.0.1:1080`, a low-entropy credential such as `pw@` or `user@`, a placeholder credential such as `vless://<uuid>@<host>`, a credential that is only template references, such as `{password}`, `$PASS`, `{{ password }}` or `%(password)s` naming a variable that starts with a letter or underscore, or any `${…}` interpolation except a shell default such as `${PASS:-value}`, such as `${pass}`, `${pass:-}`, `${pass:?message}` or `${encodeURIComponent(pass)}`, including a user part such as `$USER:$PASS@`, and a link to `example.com`, `example.net`, `example.org`, a host under `.example`, `.invalid` or `.test`, or `localhost` |
+| `proxy-base64-link` | a `vmess://`, `ss://` or `ssr://` link whose payload is 16 or more base64 characters with a Shannon entropy above 4.2 bits per character, whatever follows it | a placeholder such as `vmess://<base64-config>`, a link to a host and port such as `ss://vpn.home.net:8388`, and a payload an `@` follows, which `proxy-userinfo-link` judges |
+| `proxy-query-credential-first` | the first `auth`, `auth_str`, `obfsParam`, `obfs-password`, `password` or `pk` query value of one of the links `proxy-userinfo-link` names or an `ssr://` link, whose Shannon entropy is above 2.5 bits per character, such as a real password in the `auth` of a `hysteria://` link or a real private key in the `pk` of a `wg://` link, whatever parameters come before or after it | a low-entropy value such as `auth=pw`, a placeholder value such as `auth=<password>`, a value that is only template references as `proxy-userinfo-link` describes, such as `auth={auth}`, `auth=${HY_AUTH:?set HY_AUTH}` or `auth=${encodeURIComponent("a b")}`, and a link to one of the example hosts above |
+| `proxy-query-credential-last` | the last of these query values in such a link, judged the same way, so a real value after a low-entropy or template one still fails | what passes `proxy-query-credential-first` |
+| `proxy-subscription-url` | 16 or more token characters with a Shannon entropy above 3.0 bits per character after the `sub`, `subs`, `subscribe`, `subscription` or `link` path segment of an `http` or `https` URL, or in any `token`, `key`, `uuid` or `id` query value on a line that holds such a URL, each judged on its own | a `token`, `key`, `uuid` or `id` value on a line with no such URL, and a URL to one of the example hosts above |
+
+A ninth rule, `proxy-subscription-path`, reports nothing: it finds the URL `proxy-subscription-url` needs on the same line.
+
+These rules do not catch:
+
+- a real query value between two others of these parameters in one link whose values are low-entropy or template references, such as a real `auth` between an `obfsParam=pw` or `obfsParam=${OBFS}` and a `password=pw`
+- a real `auth`, `auth_str`, `obfsParam`, `obfs-password`, `password` or `pk` query value of an `http` or `https` URL, or of a scheme the table does not name, because the kit's query rules judge share links only, and gitleaks' default rules catch such a value only now and then
+- a credential that begins with `${` and is not a shell default such as `${PASS:-value}`, `${PASS-value}`, `${PASS:=value}` or `${PASS:+value}`, because it reads as an interpolation, even when it holds a fallback such as `${auth ?? "value"}`
+
+No setting accepts a finding.
+It ignores a repository's `.gitleaks.toml`, its `.gitleaksignore` and every `gitleaks:allow` comment.
+It skips the paths gitleaks' default config skips, such as lockfiles, images and `node_modules/`.
+
+## What it reads
+
+It reads the commits of the range from git, not the working tree.
+It needs git 2.36 or newer, which diffs a merge against the merge git would make on its own, and it exits 2 on an older git.
+It reads its rules from `src/delivery/gitleaks.toml` in the installed package.
+
+It runs gitleaks 8.30.1, pinned by the SHA-256 of each platform's archive and of the binary inside it.
+On first use it downloads the archive from the scanner's GitHub release and unpacks the binary into `~/.cache/avi2dg-checks/gitleaks/8.30.1/`.
+It checks the binary's SHA-256 again on every run and exits 2 on a copy that differs.
+Builds are pinned for macOS and Linux, each on x64 and arm64.
+On any other platform it exits 2, and no setting runs a scanner other than the pinned build.
+A cold cache downloads about 8 MB.
+
+## Arguments
+
+```sh
+checks-secrets <base-ref> <head-ref>
+checks-secrets <ref>
+```
+
+With two arguments it scans each commit from the merge base of the two refs to the head.
+With one it scans that commit alone.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | no commit in the range adds a secret |
+| 1 | a commit in the range adds a secret |
+| 2 | a ref does not resolve, or a commit it scans is an octopus merge, or no verified scanner is at hand, or git is older than 2.36, or gitleaks fails |
+
+## Sample output
+
+```
+secrets: the range adds 3 secret(s); put a placeholder such as <private-key> in its place in the commit that added it, and rotate any secret that left this machine:
+  vpn/links.txt:1 proxy-userinfo-link in e19e45c2: A proxy share link that carries its credential before the @, such as vless://, trojan://, socks5:// or wireguard://
+  vpn/wg0.conf:2 wireguard-key in e19e45c2: A WireGuard or AmneziaWG private or pre-shared key
+  vpn/wg0.conf:7 wireguard-key in e19e45c2: A WireGuard or AmneziaWG private or pre-shared key
+```
+
+The report never prints a secret.
+
+## When it runs
+
+`checks-lint` runs it over each pull request's range in every repository, as [checks-lint](checks-lint.md) says.
+A local `bun run lint` runs it over the commits the branch adds, so it fails before a push.
+
+## Related topics
+
+- [checks-lint](checks-lint.md)
+- [Why it is shaped this way](../design.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -29,6 +29,10 @@
     "src/delivery/changelog-write.ts",
     "src/delivery/release-notes.ts",
     "src/delivery/release-report.ts",
+    "src/delivery/release.ts",
+    "src/delivery/release-pr.ts",
+    "src/delivery/release-tag.ts",
+    "src/delivery/github.ts",
     "src/testing/test-layout.ts",
     "src/testing/test.ts",
     "src/testing/test-skips.ts",
@@ -43,6 +47,9 @@
     "src/testing/subsumed-tests.ts",
     "src/delivery/ci-wiring.ts",
     "src/delivery/shell-command.ts",
+    "src/delivery/secrets.ts",
+    "src/delivery/gitleaks.ts",
+    "src/delivery/gitleaks.toml",
     "src/quality/comment-matchers.ts",
     "src/docs/prose-matchers.ts",
     "src/quality/comments.ts",
@@ -60,6 +67,7 @@
     "src/dependencies/advisories.ts",
     "src/dependencies/advisory-rules.ts",
     "src/dependencies/osv-scanner.ts",
+    "src/dependencies/pinned-binary.ts",
     "src/docs/doc-agents.ts",
     "src/docs/doc-outline.ts",
     "src/docs/doc-rules.ts",
@@ -93,6 +101,8 @@
     "checks-changelog": "src/delivery/changelog-write.ts",
     "checks-release-notes": "src/delivery/release-notes.ts",
     "checks-release-report": "src/delivery/release-report.ts",
+    "checks-release-pr": "src/delivery/release-pr.ts",
+    "checks-release-tag": "src/delivery/release-tag.ts",
     "checks-lint-coverage": "src/quality/lint-coverage.sh",
     "checks-test-layout": "src/testing/test-layout.ts",
     "checks-test": "src/testing/test.ts",
@@ -110,7 +120,8 @@
     "checks-quarantine-clock": "src/testing/quarantine-clock.ts",
     "checks-docs": "src/docs/docs.ts",
     "checks-vendor": "src/dependencies/vendor.ts",
-    "checks-advisories": "src/dependencies/advisories.ts"
+    "checks-advisories": "src/dependencies/advisories.ts",
+    "checks-secrets": "src/delivery/secrets.ts"
   },
   "scripts": {
     "prepare": "bun src/dependencies/vendor.ts --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json",

package/src/core/gates.ts

@@ -43,6 +43,7 @@ export const KIT_GATES = [
   { bin: "checks-comment-gate", vector: "quality", file: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-suppressions-ratchet", vector: "complexity", file: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-ci-wiring", vector: "delivery", file: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-secrets", vector: "delivery", file: "secrets.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-docs", vector: "docs", file: "docs.ts", reads: "range", alsoReads: "every agent file at the head commit", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-repetition", vector: "complexity", file: "repetition.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-unused", vector: "complexity", file: "unused.ts", reads: "tree", appliesTo: LINTED_SOURCE },