Secrets & Config Starter

Every service reads configuration and holds credentials, and almost none of them get both right on the first pass — a process.env read that is undefined in one environment, an error object that carries the connection string into the log aggregator, a .env that was never actually ignored. This pack ships the layer that closes all three: a typed schema that refuses to let the process start on a missing or malformed variable, a redaction layer nothing logs around, ignore files proven correct against a real git repo, and a pre-commit scan that blocks thirteen credential shapes. The receipt proves it: 23 checks, hermetic — no network, no accounts, no Docker — running in about two seconds, and every one of them exists because something specific went wrong.

Three of those checks exist because they went wrong here, in OneShot's own repository, on 2026-08-02 and 2026-08-03: a migration script that printed a live database password into the build log (psql prints result rows regardless of -q, and set_config() returns the value it sets); a scaffold that shipped a real .env with no ignore file; and a repository left public for about 28 hours with paid content in it. We would rather tell you that than imply we write software that has never leaked anything.

Example use cases

• A solo founder deploying to Railway for the first time, who wants a bad environment variable to block the deploy with DATABASE_URL is blank rather than produce a running service that 500s on every request.
• An agency starting its fifth client project this year, dropping the same proven config-and-secrets layer into each one instead of re-deciding it — and wiring the pre-commit scan before a contractor's first commit rather than after.
• A team that just had an incident: a credential turned up in a log aggregator or a CI build log. The redaction layer plus the "one file reads process.env" rule is the smallest change that makes it structurally hard to repeat.
• Anyone auditing an agent-generated scaffold. Agents routinely produce projects with a real .env and no ignore file. One command tells you whether yours is one of them, instead of reading .gitignore and assuming.
• A repo adding pre-commit hygiene without adding a Python toolchain. The scanner is grep in a bash script; it installs and runs anywhere git does.

Why this pack

On the bare-agent column, specifically — these are the defects this pack pre-solves, all observed rather than imagined:

• A scaffold with a real .env and no ignore file. We shipped one on 2026-08-02. Nothing was wrong with the code; nobody had written the four lines.
• A tool echoing back the secret you just gave it. Our migration script set a database password through a set_config() bridge. set_config returns the value it sets, and psql prints result rows even with -q, so a live password went into stdout and into CI. No key-name-based redactor would have caught it — the value came back under a result-row key. Value-based redaction does.
• JSON.stringify(err) → {}. The reflex fix is String(err), which is precisely what puts the connection string in the log.
• **An over-broad .env* rule that swallows .env.example.** Silent, and everyone who clones the repo has to guess the variable names.
• A pre-commit hook installed into .git/hooks in a repo with core.hooksPath set. It never runs. Nothing tells you.

On the scanner-SaaS column — hosted secret scanners are good at what they do and solve a genuinely different problem: finding credentials that are already committed, across an organisation, retroactively. This pack is about the three places a secret gets in before that: the config layer, the log line, and the commit. They compose fine. This one costs nothing and does not require sending your source anywhere.

On hand-rolling — the redaction and validation code is a few hundred lines and is not the hard part. The hard parts are knowing that blank is missing, that set_config echoes, that .dockerignore needs .git, that railway up uploads uncommitted files, that hooks live wherever core.hooksPath says, and that a scanner which flags const password = user.password gets uninstalled in week two. That knowledge is what is encoded here, and the check suite is what keeps it encoded.

We will not claim this makes you unleakable. What the checks back is narrower and true: the specific failure modes above are closed, and the suite proves it in two seconds without touching the network.

Scale envelope

There is no runtime load story here worth inflating — this is boot-time validation plus a per-log-line transform — so the honest numbers are about codebase size and developer friction:

• Config validation cost: one pass over the schema at process start. With a few dozen variables it is microseconds; it happens once, before the first socket opens. There is no ceiling worth naming.
• Redaction cost per log line: a bounded walk (depth capped at 8, cycles detected) plus a string pass per registered secret and roughly a dozen regex passes over each string field. That is real work — noticeable if you log megabyte payloads at debug level in a hot loop. The mitigation is the one you want anyway: log level info in production and log identifiers, not payloads. If you genuinely need to log large blobs at high frequency, redact at the edge and pass the result through as a pre-redacted string.
• Scanner cost: grep across the staged file list. On a normal commit (a handful of files) it is milliseconds. Across a whole repository (--all, ~13 grep passes per file) expect seconds for thousands of files, minutes for a very large monorepo — which is why the pre-commit path scans only staged files and the full sweep belongs in CI.
• First ceiling: the schema is a single object literal in one file. Past roughly 50 variables that file wants splitting by domain (the loader does not care — pass it a merged object). Past that, the honest answer is that you have outgrown environment variables and want a secrets manager, which this pack deliberately does not implement: it is one async loader in front of loadConfig().
• Not load-tested. These are reasoned from the shipped code, not benchmark results, and are labelled that way on purpose.

Economics: the pack is free, so there is no saving to claim and none is claimed. The only cost is the tokens of one adoption pass — an author estimate of ~231k fresh tokens, not yet a measurement, because this pack is status: draft and has no receipt. That number will be replaced with the measured one, and the receipt is where you should look for it rather than here.

Verified against

• claude-opus-5
• claude-sonnet-5
• claude-haiku-4-5

Supported stacks

• node-typescript

  node

  24.18.1

Estimated buyer token cost

231,000 tokens for one build pass (estimate, not a guarantee).