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.
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 | |