# 16. Environment Management & Secrets Rotation

meta:
  id: web-production-16
  feature: web-production
  priority: P1
  depends_on: []
  tags: [security, infrastructure, production]

objective:
- Implement secure environment variable management and automated secrets rotation

deliverables:
- Environment variable validation on startup
- Secrets manager integration (AWS Secrets Manager, Doppler, or 1Password)
- Automated secrets rotation
- Environment documentation

steps:
1. Create environment validation:
   - Create web/src/server/lib/env.ts with Zod/Valibot schema
   - Validate all required env vars on server startup
   - Fail fast with clear error messages for missing vars
   - Type-safe env access throughout codebase
2. Migrate to secrets manager:
   - Set up Doppler or AWS Secrets Manager
   - Move DATABASE_URL, JWT_SECRET, STRIPE_SECRET_KEY, CLERK_SECRET_KEY to secrets manager
   - Remove secrets from .env files in production
   - Use short-lived tokens where possible
3. Implement secrets rotation:
   - JWT secret: rotate quarterly
   - Database credentials: rotate monthly
   - Stripe keys: rotate after any suspected leak
   - API keys: rotate every 6 months
   - Automated rotation scripts
4. Add environment documentation:
   - Document all environment variables in docs/ENVIRONMENT.md
   - Mark required vs optional
   - Include examples and validation rules
   - Document secrets rotation schedule
5. Secure local development:
   - .env.example with dummy values
   - .env.local in .gitignore
   - Pre-commit hook to prevent secret commits
   - Use 1Password CLI or Doppler CLI for local secrets
6. Audit existing secrets:
   - Scan git history for leaked secrets (git-secrets, truffleHog)
   - Rotate any potentially leaked secrets
   - Enable GitHub secret scanning

tests:
- Unit: Test env validation catches missing vars
- Security: Verify no secrets in codebase with scanner
- Integration: Test secrets manager integration

acceptance_criteria:
- Server fails to start with clear error if required env var missing
- Zero secrets in codebase or git history
- All production secrets stored in secrets manager
- Rotation schedule documented and automated
- Environment documentation complete and accurate
- GitHub secret scanning enabled
- Pre-commit hooks preventing secret commits

validation:
- Remove DATABASE_URL → server exits with clear error
- Run truffleHog → no secrets found in history
- Check secrets manager → all production secrets stored
- Run rotation script → new JWT secret generated, app continues working

notes:
- Doppler is excellent for team secret management
- AWS Secrets Manager integrates well with ECS/Fargate
- Never commit .env files — use .env.example only
- Consider using sealed secrets for Kubernetes