Secrets Management

Secrets Management

A secret committed to source control is already compromised — assume it is public the moment it lands in history, even on a private repo. Git history, CI logs, container layers, backups, and forks all retain it. The only safe response is rotation, not deletion. This skill is the deep reference for keeping secrets out of code, supplying them safely at runtime, and reacting correctly when one escapes. Heavy detail lives in references/; copy-paste material in examples/; a runnable leak scanner in scripts/.

Mental model

Treat a secret as runtime configuration, never as code. Code is committed, reviewed, copied, and shipped to laptops; secrets must not ride along. Separate three concerns and never collapse them:

The application code should only ever read a secret from its environment — it should never know the storage backend, the rotation cadence, or the raw value's origin. That decoupling is what lets you rotate a leaked key with zero code changes.

1. Keep secrets out of source

1. Never hardcode keys, tokens, passwords, connection strings, or private keys in source — not even "temporarily". Temporary hardcodes are how most leaks happen.
2. Commit a placeholder template (.env.example) with fake values and key names only; add the real .env to .gitignore before the first commit.
3. Add a secret scanner to pre-commit hooks and CI so a leak is caught before it reaches the remote. Run scripts/detect-hardcoded.mjs over diffs or files as a zero-dependency gate.
4. Load and validate required secrets at startup; fail fast with a clear message naming the missing var.

// Read from the environment; never embed the value. Validate at boot.
const required = ['DATABASE_URL', 'STRIPE_SECRET_KEY', 'JWT_SIGNING_KEY'];
const missing = required.filter((k) => !process.env[k]);
if (missing.length) {
  throw new Error(`Missing required secrets: ${missing.join(', ')}`);
}
const stripeKey = process.env.STRIPE_SECRET_KEY; // if this leaks, rotate the value — no code change

2. Environment variables vs secret managers

Env vars are the universal delivery mechanism, but they are not a secure store — they leak via /proc, crash dumps, child processes, and accidental console.log(process.env). For anything beyond a single dev machine, the source of truth belongs in a manager.

A manager buys you dynamic, short-lived credentials (e.g. Vault issues a DB credential that auto-expires in 1 hour), centralized audit logs, and rotation without redeploys. See references/secret-managers.md for the comparison and bootstrap-auth patterns.

3. Least privilege & short-lived credentials

• Scope every credential to the minimum resources and actions it needs; a build token does not need prod database write access.
• Prefer short-lived dynamic credentials over long-lived static keys. A credential that lives 15 minutes limits the blast radius of a leak to 15 minutes.
• Use distinct credentials per service and per environment so revocation is surgical, not a blackout.
• Never share one "god" key across services — you lose the ability to attribute and revoke.

4. Encryption in transit and at rest

• In transit: fetch secrets only over TLS; reject plaintext transports. Never pass secrets as URL query params (they land in logs, proxies, and browser history) — use headers or the request body.
• At rest: the manager encrypts its store; for data you encrypt yourself, use envelope encryption (a KMS-held key encrypts per-record data keys) rather than a single static key in config.
• Keep secrets out of logs, error reports, and APM traces. Redact at the logging boundary — see the scanner's redaction logic and references/leak-response.md.

5. Rotation

Rotation is the difference between "we had an incident" and "we had a non-event." Two triggers:

1. Scheduled — rotate on a fixed cadence (e.g. 90 days for static keys) so no credential is ancient.
2. Reactive — rotate immediately on any suspected exposure, no matter how minor it looks.

The safe pattern is overlap: provision the new credential, deploy it, verify, then revoke the old — so there is no downtime window. The full step-by-step is in references/rotation.md and a fill-in incident checklist is in examples/rotation-runbook.md.

Common pitfalls (failure modes)

• "It's a private repo, so it's fine." Forks, clones, CI caches, and future open-sourcing all expose it. Private is not secret.
• Deleting the commit instead of rotating. git rm / force-push does not erase history from clones, caches, and PR mirrors. The credential is burned — rotate it.
• Logging the whole environment. console.log(process.env) or dumping config on a crash ships every secret to your log aggregator. Redact at the boundary.
• Secrets in URLs. Query-string tokens leak into access logs, referrer headers, and proxies.
• One static key forever. No rotation means a years-old leak is still valid today.
• Over-scoped credentials. A read-only reporting job holding admin keys turns a small leak into a full compromise.
• Checking .env.example with real values. The template must contain only obviously fake placeholders.

When NOT to use / trade-offs

• A full secret manager for a solo side project is overkill — gitignored .env plus a pre-commit scanner is proportionate. Adopt a manager when you have a team, multiple environments, or compliance needs.
• Short-lived dynamic credentials add operational complexity (auth bootstrap, renewal, clock skew). If your platform can't renew reliably, a rotated static key with tight scope may be the pragmatic choice.
• Client-side secrets don't exist. Anything shipped to a browser or mobile app is public; never put a secret in front-end code — use a backend proxy or short-lived scoped tokens instead.
• Encrypting everything has key-management cost. Encrypt what's sensitive; don't build a KMS maze for non-secret config.

Files in this package

• references/secret-managers.md — env vars vs Vault/cloud managers, bootstrap auth, dynamic creds
• references/rotation.md — scheduled & reactive rotation, zero-downtime overlap pattern
• references/leak-response.md — what to do in the first hour after a leak; redaction guidance
• examples/env-example.md — a model .env.example with safe placeholders and .gitignore notes
• examples/rotation-runbook.md — fill-in incident/rotation checklist
• scripts/detect-hardcoded.mjs — zero-dep scanner that flags & redacts hardcoded secrets (--selftest)

Pairs with the secure-auth skill (where signing keys and session secrets come from), the owasp-top10 skill (A07 identification/auth failures, A02 cryptographic failures), and the security-auditor agent for a full credential-handling review.

Worked micro-example

Drill: a Slack webhook URL just landed in a public repo commit.

CLOCK STARTS:
  0-5m    revoke at the source (Slack app config) — rotation BEFORE cleanup;
          the secret is burned the moment it was pushed, not when found
  5-15m   sweep for siblings: same commit, same author, same week
          (leaks travel in packs — found: a Sentry DSN in the same PR)
  15-30m  history rewrite is OPTIONAL cleanup, revocation is the fix —
          scrapers saw it in seconds; git filter-repo only tidies appearances
  30-60m  close the hole: pre-commit scan hook + CI secret-scan gate
          (the same patterns scan-secrets.mjs ships)
POSTMORTEM Q: why was a live credential in an env a developer could paste
from? → move to short-lived tokens minted at deploy; the class dies.