Scan for secrets before a commit exists, and again in CI

[SociableSteve]

Problem

This is a public repository, developed against live installs holding Google OAuth refresh tokens, a
GitHub token and LLM provider API keys. The credentials live in caroline.config.json and
data/google-tokens.json, both correctly ignored today, and nothing but that .gitignore stands
between a real key and a public commit.

One control is in place and works: GitHub secret scanning and push protection are enabled on this
repository, so a recognised provider credential is blocked at push time, server-side, where
--no-verify cannot reach it.

It protects exactly one repository, and it is the one that already has it. That is the shape of the
problem:

• A fork inherits none of it. Push protection is a per-repository setting owned by whoever owns
  the repository. A fork is a different repository with different settings, and its owner can turn
  the setting off or never have it on. Anyone mirroring the code into a private repository has no
  secret scanning at all without Advanced Security, and anyone pushing to a host that is not GitHub
  has nothing whatever. A public project's protections have to travel with the code, and a
  repository setting does not.
• Non-provider patterns are disabled even here. Push protection currently catches credentials
  it can attribute to a known provider. It does not catch a private key, a generic API key, a
  password in a connection string, or an unrecognised token format. Caroline's own session and MCP
  tokens are exactly that shape.
• Nothing runs before the commit exists. Feedback arrives at push time, when the secret is
  already in a local commit and in the reflog. Removing it then is a history rewrite rather than an
  amend, and on a shared branch it is a rewrite everyone else pays for.
• Nothing checks a pull request. A secret in a form push protection does not recognise is
  reviewed by a human reading a diff, which is not a control.
• A fixture is the likely route in. The test strategy commits recorded provider payloads,
  scrubbed of real addresses, names and repository identifiers. Scrubbing is a manual step and the
  material being scrubbed came from a real account. This risk lands on contributors, in their own
  forks, where none of this repository's settings apply.

Expected outcome

The protection is part of the repository rather than part of this repository's configuration, so a
fork gets it too.

• The check is committed to the repository and travels with a clone. A control that has to be
  configured per fork protects only the forks whose owners thought about it.
• Secrets are caught before the commit exists, for the common case of a local mistake, so nothing
  has to be rewritten out of history.
• The same check runs in CI and blocks a pull request, whatever the contributor's machine is set up
  to do and whatever --no-verify was passed. The local check is fast feedback; CI is the gate.
• The CI check is required on the protected branch, so a change that removes or alters the workflow
  produces a missing required check rather than a silently absent one. An absent check is invisible
  in the way a failing one is not.
• Coverage extends past recognised provider formats to private keys, generic credentials and
  Caroline's own token shapes.
• False positives are manageable and suppressible deliberately, with the suppression committed and
  reviewable. A noisy check gets turned off, and a check that has been turned off is worse than none
  because it still reads as protection.
• Installing the local hook is one documented step a contributor meets when they start. A hook that
  lives only in somebody's .git/hooks is invisible to everyone else and lost on the next clone,
  which is the same reason repository conventions do not belong in git-ignored directories.

Open questions

1. Which scanner. The same one locally and in CI, so a commit accepted by the hook is not
   rejected a minute later by a different tool with different rules.
2. Whether history is scanned once, as a baseline, separately from scanning each change.
3. Whether the non-provider patterns toggle is turned on here as well. It is a repository
   setting and so is not a substitute for anything above, but it costs nothing and closes the
   provider-shaped gap for this repository while the committed checks close it for every clone.

[SociableSteve]

Decision: secretlint for the standing check, gitleaks once for the history baseline

Answering the first two open questions. The third is recommended rather than settled, below.

1. Which scanner: secretlint

The deciding constraint is the one this issue is built on, that the control has to travel with a
clone rather than being configured per fork. That is a distribution question before it is a
detection question, and it rules out the two obvious candidates.

gitleaks is the usual recommendation and it is not abandoned: the repository was pushed on
2026-08-19 with 19 commits in the preceding 90 days, MIT, 28.9k stars. Its last tagged release is
v8.30.1 from 2026-03-21, so releases have slowed, and there is now an active fork,
betterleaks/betterleaks, created 2026-02-03 and pushed 2026-08-20 with 1.7k stars. None of that
is disqualifying. What disqualifies it here is that it is a Go binary, so it cannot arrive from
npm ci, and the only npm distribution is @ziul285/gitleaks: version 1.0.0, published
2025-04-06, one maintainer. That is not an acceptable dependency for the one check in this
repository whose failure mode is a real credential in a public commit.

env-guard, from a dev.to article making exactly this issue's argument, is a Python package in a
repository with no Python toolchain, and the project is a hobby project: created 2026-04-30, last
pushed 2026-05-09, zero stars, zero forks, one contributor, 18 commits, no tagged releases. It is
also not installable as documented. PyPI 404s on env-guard, env_guard and env-guard-scanner.
There is an envguard on PyPI, but it is version 0.1 by a different author and is an unrelated
tool for checking missing variables in .env files, so following the article and correcting the
name installs something else entirely.

secretlint is npm-native, MIT, v13.0.4 published 2026-07-22, 1.26M downloads a week. As a
devDependency it lands from the lockfile, so a fork gets the protection without its owner having
configured anything, which is the criterion this issue exists for.

Its published rules cover this repository's actual exposure close to item for item: privatekey,
database-connection-string, github, gcp for the Google OAuth tokens, anthropic, openai,
basicauth, and rule-pattern for Caroline's own session and MCP token shapes, which is the
non-provider gap named above. filter-comments gives suppressions that are committed and
reviewable.

There is no hook tooling in the repository today, no .husky and no prepare script, so this
change brings one. A prepare script means the hook installs on npm install, which is better
than the documented step this issue asks for: there is no step.

Per-rule severity is how the "false positives are manageable" criterion gets met. Caroline's own
token patterns block; a noisier generic rule can sit at warning. A check nobody has had to disable
is the point.

The scanner is pointed at .gitignore with --secretlintignore rather than given its own ignore
file. .gitignore is already the authoritative list of what holds real credentials, including
caroline.config.json and data/, and a second parallel ignore file is a second thing to keep in
step.

The constraint about one tool locally and in CI is satisfied: both sides run the same secretlint
and the same .secretlintrc.json, so a commit the hook accepts is not rejected a minute later.

2. History gets a baseline scan: yes, once, with gitleaks

Secretlint lints files, it does not walk history, so the one-off baseline is a separate exercise
from the standing check. It is run by hand with gitleaks over the full history and the result is
recorded. That does not reintroduce the problem the paragraph above avoids: a historical audit runs
once and gates nothing ongoing, so it does not have to be installable from the lockfile, and the
"same tool both sides" constraint is about the recurring check.

3. The non-provider patterns toggle: recommended, not yet decided

Still open, and noted here rather than settled. Turning it on costs nothing and closes the
provider-shaped gap for this repository, while the committed checks above close it for every clone.
It is a repository setting, so it is not a substitute for any of them, which is what the question
was asking. Recommended, pending a decision.