atelier/domains/security/secrets.md

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