This document outlines security considerations and design decisions for goconfig maintainers.

Critical Security Rule: Error messages must NEVER include the actual configuration values.

Configuration values often contain sensitive data:

• API keys and tokens (e.g., API_KEY=sk-secret-token-12345)
• Database credentials and connection strings
• OAuth secrets
• Private keys
• Passwords

When validation or parsing fails, these values could be exposed through:

• Application logs
• Centralized logging systems (CloudWatch, Datadog, Splunk, etc.)
• Error tracking services (Sentry, Bugsnag, Rollbar, etc.)
• Console output during development
• Monitoring dashboards
• Stack traces in production

1. Parsing Errors

   • ❌ Bad: "error parsing value %s: %w", configuredValue, err
   • ✅ Good: "error parsing value: %w", err

2. Validation Errors

   • ❌ Bad: "value %s does not match pattern %s", actualValue, pattern
   • ✅ Good: "does not match pattern %s", pattern
   • ❌ Bad: "value %d is below minimum %d", actualValue, min
   • ✅ Good: "below minimum %d", min

3. Custom Validators

   • Validators should avoid including actual values in error messages
   • Example: Return "must start with 'sk-'" instead of "'invalid-key' must start with 'sk-'"

When reviewing changes that modify error messages:

• Error message does not include %s, %v, or %d for the actual value
• Only constraint information (min, max, pattern) is included, not user data
• Tests verify the error message format
• Documentation examples reflect the correct error format

• Issue #15: Original security concern about secrets being logged

When adding new validation:

1. Write tests that check the exact error message format
2. Ensure test expectations do NOT include actual values
3. Verify error messages only describe what's wrong, not what was provided