Kordant/tasks/web-production/16-env-secrets.md

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