picpeak/docs/SECURITY_BEST_PRACTICES.md

Security Best Practices for PicPeak

JWT Secret Management

Generating Secure Secrets

Always generate cryptographically secure random secrets for JWT signing:

# Generate a 64-character hex string (256 bits)
openssl rand -hex 32

# Alternative: Generate a base64 string
openssl rand -base64 32

# Alternative: Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Environment-Specific Secrets

NEVER use the same JWT secret across different environments!

• Development: Use the secure secret in docker-compose.yml
• Staging: Generate a unique secret for staging
• Production: Generate a unique secret for production

Secret Requirements

1. Minimum Length: 32 characters (enforced by application)
2. Recommended Length: 64 characters (256 bits)
3. Character Set: Use hex or base64 encoding
4. Uniqueness: Each environment must have a unique secret

What NOT to Do

❌ Never commit real secrets to version control

# Bad - real secret in code
JWT_SECRET=my-actual-production-secret

❌ Never use predictable or weak secrets

# Bad examples
JWT_SECRET=secret123
JWT_SECRET=mycompanyname
JWT_SECRET=password
JWT_SECRET=your-secret-key

❌ Never share secrets between environments

# Bad - same secret everywhere
DEV_JWT_SECRET=same-secret
PROD_JWT_SECRET=same-secret

Secure Secret Storage

For Local Development

• Docker Compose files can contain development secrets
• These should still be secure random values

For Production

1. Environment Variables

   # Set via secure environment
   export JWT_SECRET=$(openssl rand -hex 32)
   

2. Secret Management Services

   • AWS Secrets Manager
   • HashiCorp Vault
   • Azure Key Vault
   • Kubernetes Secrets

3. CI/CD Integration

   • Store secrets in CI/CD platform's secret storage
   • Never log or echo secrets in build scripts

Secret Rotation

Implement a secret rotation strategy:

1. Regular Rotation: Rotate secrets every 90 days
2. Incident Response: Rotate immediately if compromised
3. Graceful Rotation: Support multiple valid secrets during transition

Monitoring and Alerts

1. Startup Validation: Application refuses to start without proper JWT_SECRET
2. Length Warnings: Warnings for secrets shorter than 32 characters
3. Default Detection: Critical error if default secret is detected

Additional Security Measures

Password Requirements

• Minimum 12 characters
• Mix of uppercase, lowercase, numbers, and special characters
• Check against common password lists
• Implement password strength meter

Session Security

• Implement token expiration (24 hours for admin, configurable for galleries)
• Add refresh token mechanism
• Implement token revocation
• Use secure session storage (Redis in production)

API Security

• Rate limiting on all endpoints
• Extra strict limits on authentication endpoints
• CSRF protection for state-changing operations
• Input validation on all user inputs

File Upload Security

• Validate file types by content, not just extension
• Implement virus scanning
• Limit file sizes
• Sanitize filenames
• Store files outside web root

Database Security

• Use parameterized queries (Knex.js handles this)
• Validate and sanitize all inputs
• Implement query timeouts
• Use least-privilege database users

HTTPS and Headers

• Always use HTTPS in production
• Implement security headers:
  • Strict-Transport-Security
  • X-Frame-Options
  • X-Content-Type-Options
  • Content-Security-Policy
  • X-XSS-Protection

Logging and Monitoring

• Log authentication attempts
• Monitor for suspicious patterns
• Never log sensitive data (passwords, tokens)
• Implement audit trails for admin actions

Security Checklist for Deployment

• Generate unique JWT_SECRET for environment
• Verify JWT_SECRET meets minimum requirements
• Store secrets securely (not in code)
• Enable HTTPS
• Configure security headers
• Set up rate limiting
• Enable audit logging
• Test authentication flows
• Verify file upload restrictions
• Check database query security

Incident Response

If a security incident occurs:

1. Immediate Actions

   • Rotate all secrets
   • Review access logs
   • Disable compromised accounts

2. Investigation

   • Analyze logs for unauthorized access
   • Check for data exfiltration
   • Review code changes

3. Recovery

   • Deploy security patches
   • Force password resets if needed
   • Notify affected users

4. Prevention

   • Update security practices
   • Implement additional monitoring
   • Conduct security audit