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