NexaPG/docs/security/secret-management.md

Secret Management (Production)

This guide defines secure handling for NexaPG secrets in production deployments.

In Scope Secrets

• JWT_SECRET_KEY
• ENCRYPTION_KEY
• DB_PASSWORD
• SMTP credentials (configured in Admin Settings, encrypted at rest)

Do / Don't

Do

• Use an external secret source (Vault, cloud secret manager, orchestrator secrets, or CI/CD secret injection).
• Keep secrets out of Git history and out of image layers.
• Use strong random values:
  • JWT secret: at least 32+ bytes random
  • Fernet key: generated via Fernet.generate_key()
• Restrict access to runtime secrets (least privilege).
• Rotate secrets on schedule and on incident.
• Store production .env with strict permissions if file-based injection is used:
  • owner-only read/write (e.g., chmod 600 .env)
• Audit who can read/update secrets in your deployment platform.

Don't

• Do not hardcode secrets in source code.
• Do not commit .env with real values.
• Do not bake production secrets into Dockerfiles or image build args.
• Do not share secrets in tickets, chat logs, or CI console output.
• Do not reuse the same secrets between environments.

Recommended Secret Providers

Pick one of these models:

1. Platform/Cloud secrets
   • AWS Secrets Manager
   • Azure Key Vault
   • Google Secret Manager
2. HashiCorp Vault
3. CI/CD secret injection
   • Inject as runtime env vars during deployment
4. Docker/Kubernetes secrets
   • Prefer secret mounts or orchestrator-native secret stores

If you use plain .env files, treat them as sensitive artifacts and protect at OS and backup level.

Rotation Basics

Minimum baseline:

1. JWT_SECRET_KEY
   • Rotate on schedule (e.g., quarterly) and immediately after compromise.
   • Expect existing sessions/tokens to become invalid after rotation.
2. ENCRYPTION_KEY
   • Rotate with planned maintenance.
   • Re-encrypt stored encrypted values (target passwords, SMTP password) during key transition.
3. DB_PASSWORD
   • Rotate service account credentials regularly.
   • Apply password changes in DB and deployment config atomically.
4. SMTP credentials
   • Use dedicated sender account/app password.
   • Rotate regularly and after provider-side security alerts.

Operational Checklist

• No production secret in repository files.
• No production secret in container image metadata or build args.
• Runtime secret source documented for your environment.
• Secret rotation owner and schedule defined.
• Incident runbook includes emergency rotation steps.