Jon Chery
72 lines
3.0 KiB
Markdown
72 lines
3.0 KiB
Markdown
# Secrets — Derived Rules
|
|
|
|
> Derives from `domains/security/first-principles.md` P9 (Secret Hygiene), P1 (Zero Trust), P6 (Crypto Correctness).
|
|
|
|
## What is a Secret
|
|
|
|
A secret is any value whose disclosure compromises the system. Examples:
|
|
- API keys, access tokens, refresh tokens
|
|
- Database passwords, service passwords
|
|
- Private keys (TLS, signing, encryption)
|
|
- OAuth client secrets, JWT signing keys
|
|
- Encryption keys (KMS, envelope encryption)
|
|
|
|
## Never in Code (P9)
|
|
|
|
- No secrets in source files. No secrets in comments. No secrets in string constants.
|
|
- No secrets in config files committed to git. Use `.env` (gitignored) or a secrets manager.
|
|
- No secrets in test fixtures. Tests use fake/dummy values, never real secrets.
|
|
|
|
## Never in Logs (P9, domains/observability P6)
|
|
|
|
- No secrets in log messages, error messages, or stack traces.
|
|
- Redact before logging: replace the secret with `[REDACTED]` or a hash.
|
|
- Never log the request body (it may contain a token). Log the request ID, not the body.
|
|
|
|
## Never in URLs (P9, P1)
|
|
|
|
- URLs are logged (server logs, proxy logs, browser history, referrer headers).
|
|
- A token in the URL is a token in everyone's logs.
|
|
- Use headers (`Authorization: Bearer ...`), not query strings.
|
|
|
|
## Never in Error Messages (P9, domains/errors)
|
|
|
|
- "Authentication failed: invalid API key sk-abc123" — the secret is in the error.
|
|
- "Authentication failed: invalid API key" — the secret is not.
|
|
- Error messages are for humans; humans do not need the secret to debug.
|
|
|
|
## Storage (P6 Crypto Correctness)
|
|
|
|
- At rest: encrypted (KMS, envelope encryption). Never plaintext on disk.
|
|
- In memory: minimal lifetime. Load on use, not on boot. Zero after use (where the language allows).
|
|
- In transit: TLS only. No plaintext HTTP for secrets, ever.
|
|
|
|
## Rotation (P5 Reversibility, P2 Least Privilege)
|
|
|
|
- Secrets are rotatable. A secret that cannot be rotated is a liability.
|
|
- Rotation is documented and rehearsed. Not improvised during an incident.
|
|
- Old secrets are revoked after rotation, not "kept just in case."
|
|
- Short-lived secrets (≤ 1 hour) are better than long-lived secrets (≤ forever).
|
|
|
|
## Scope (P2 Least Privilege)
|
|
|
|
- A secret has the minimum scope. A secret for service A does not work for service B.
|
|
- Scoped tokens: `scope: read:orders`, not `scope: *`.
|
|
- One secret per environment. Dev, staging, prod use different secrets.
|
|
|
|
## The `.gitignore` Rule
|
|
|
|
- `.env`, `.env.secrets`, `.env.*` are in `.gitignore` by default (see Atelier's own `.gitignore`).
|
|
- A secret committed to git is a leaked secret. Rotate immediately. History is forever.
|
|
- Pre-commit hooks scan for high-entropy strings. Use them.
|
|
|
|
## What Violates Secret Hygiene
|
|
|
|
| Violation | Principle |
|
|
|-----------|-----------|
|
|
| `API_KEY = "sk-abc123"` in source | P9 |
|
|
| `?token=abc` in a URL | P9, P1 |
|
|
| `console.log(req.body)` where body contains a token | P9, observability P6 |
|
|
| `catch (e) { throw new Error("DB password is pwd123") }` | P9, errors |
|
|
| Same secret in dev and prod | P2 |
|
|
| A 5-year-old API key with no rotation | P5 | |