Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
3.0 KiB
3.0 KiB
Secrets — Derived Rules
Derives from
domains/security/first-principles.mdP9 (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, notscope: *. - One secret per environment. Dev, staging, prod use different secrets.
The .gitignore Rule
.env,.env.secrets,.env.*are in.gitignoreby 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 |