/secrets-management

name: secrets-management
description: Handle secrets safely across the lifecycle — keep them out of source, load from env or a secret manager, scope to least privilege, encrypt in transit and at rest, rotate on a schedule, and respond fast when one leaks. Deep reference with runbooks, examples, and a runnable leak scanner.
type: skill
version: 2.0.1
updated: 2026-07-27

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:

| Concern | Question | Answer | |---|---|---| | Storage | where does the truth live? | a secret manager (Vault, cloud KMS/Secrets Manager) | | Delivery | how does the app get it? | injected env var or a fetch at boot, over TLS | | Lifecycle | how does it change? | rotation on a schedule + on suspected leak |

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.

| Approach | Good for | Watch out for | |---|---|---| | `.env` file (gitignored) | local dev only | easy to commit by accident; no rotation, no audit | | Platform env vars (CI/PaaS) | small apps, single-tenant | visible to anyone with dashboard access; static | | Secret manager (Vault, AWS/GCP/Azure) | production, teams | needs auth bootstrap; adds a runtime dependency | | Cloud KMS (envelope encryption) | encrypting data + secrets | key policy mistakes are silent until exploited |

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`](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