feat: implement comprehensive environment variable credential support
- Add environment variable overrides for sensitive credentials in both Go and Rust implementations - Support MAIL2COUCH_COUCHDB_USER and MAIL2COUCH_COUCHDB_PASSWORD for CouchDB credentials - Support MAIL2COUCH_IMAP_<NAME>_USER and MAIL2COUCH_IMAP_<NAME>_PASSWORD for IMAP credentials - Implement automatic name normalization for mail source names to environment variable format - Add runtime display of active environment variable overrides - Enhance --help output in both implementations with comprehensive environment variable documentation - Add detailed environment variable section to README with usage examples and security benefits - Create comprehensive ENVIRONMENT_VARIABLES.md reference guide with SystemD, Docker, and CI/CD examples - Update all documentation indices and cross-references - Include security best practices and troubleshooting guidance - Maintain full backward compatibility with existing configuration files This enhancement addresses the high-priority security requirement to eliminate plaintext passwords from configuration files while providing production-ready credential management for both development and deployment scenarios. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
d3d104ee71
commit
8764b44a05
9 changed files with 532 additions and 13 deletions
98
README.md
98
README.md
|
|
@ -59,6 +59,7 @@ Comprehensive documentation is available in the [`docs/`](docs/) directory:
|
|||
- **[docs/README.md](docs/README.md)** - Documentation overview and quick start
|
||||
- **[docs/ANALYSIS.md](docs/ANALYSIS.md)** - Technical analysis and current status
|
||||
- **[docs/IMPLEMENTATION_COMPARISON.md](docs/IMPLEMENTATION_COMPARISON.md)** - Go vs Rust comparison
|
||||
- **[docs/ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md)** - Environment variable credential overrides
|
||||
- **[docs/FOLDER_PATTERNS.md](docs/FOLDER_PATTERNS.md)** - Folder filtering guide
|
||||
- **[docs/couchdb-schemas.md](docs/couchdb-schemas.md)** - Database schema documentation
|
||||
- **[docs/TODO.md](docs/TODO.md)** - Development roadmap and future plans
|
||||
|
|
@ -139,9 +140,50 @@ mail2couch automatically searches for configuration files in this order:
|
|||
Options:
|
||||
-c, --config FILE Path to configuration file
|
||||
-m, --max-messages N Limit messages processed per mailbox per run (0 = unlimited)
|
||||
-n, --dry-run Show what would be done without making changes
|
||||
-h, --help Show help message
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
mail2couch supports environment variable overrides for sensitive credentials, allowing you to keep passwords out of configuration files:
|
||||
|
||||
| Environment Variable | Purpose | Example |
|
||||
|---------------------|---------|---------|
|
||||
| `MAIL2COUCH_COUCHDB_USER` | Override CouchDB username | `admin` |
|
||||
| `MAIL2COUCH_COUCHDB_PASSWORD` | Override CouchDB password | `secure_password` |
|
||||
| `MAIL2COUCH_IMAP_<NAME>_USER` | Override IMAP username for source `<NAME>` | `user@gmail.com` |
|
||||
| `MAIL2COUCH_IMAP_<NAME>_PASSWORD` | Override IMAP password for source `<NAME>` | `app_password` |
|
||||
|
||||
**Name Normalization**: The `<NAME>` part is the mail source name from your configuration converted to uppercase with non-alphanumeric characters replaced by underscores.
|
||||
|
||||
**Examples**:
|
||||
- Source name `"Personal Gmail"` → `MAIL2COUCH_IMAP_PERSONAL_GMAIL_PASSWORD`
|
||||
- Source name `"Work Email"` → `MAIL2COUCH_IMAP_WORK_EMAIL_USER`
|
||||
- Source name `"Self-Hosted Mail"` → `MAIL2COUCH_IMAP_SELF_HOSTED_MAIL_PASSWORD`
|
||||
|
||||
**Usage Examples**:
|
||||
```bash
|
||||
# Override CouchDB credentials
|
||||
MAIL2COUCH_COUCHDB_PASSWORD=secret ./mail2couch
|
||||
|
||||
# Override IMAP password for a specific account
|
||||
MAIL2COUCH_IMAP_PERSONAL_GMAIL_PASSWORD=app-password ./mail2couch
|
||||
|
||||
# Use with systemd service (in service file)
|
||||
Environment="MAIL2COUCH_COUCHDB_PASSWORD=secret"
|
||||
Environment="MAIL2COUCH_IMAP_WORK_EMAIL_PASSWORD=app-pass"
|
||||
|
||||
# Combine with other options
|
||||
MAIL2COUCH_COUCHDB_USER=backup_user ./mail2couch --dry-run --max-messages 100
|
||||
```
|
||||
|
||||
**Security Benefits**:
|
||||
- ✅ Keep sensitive credentials out of configuration files
|
||||
- ✅ Use different credentials per environment (dev/staging/prod)
|
||||
- ✅ Integrate with CI/CD systems and secret management
|
||||
- ✅ Maintain backward compatibility with existing configurations
|
||||
|
||||
### Folder Pattern Examples
|
||||
|
||||
| Pattern | Description | Matches |
|
||||
|
|
@ -277,6 +319,47 @@ Basic setup for a single Gmail account:
|
|||
}
|
||||
```
|
||||
|
||||
### Secure Configuration with Environment Variables
|
||||
Configuration using placeholder values with sensitive credentials provided via environment variables:
|
||||
|
||||
```json
|
||||
{
|
||||
"couchDb": {
|
||||
"url": "http://localhost:5984",
|
||||
"user": "placeholder",
|
||||
"password": "placeholder"
|
||||
},
|
||||
"mailSources": [
|
||||
{
|
||||
"name": "Personal Gmail",
|
||||
"enabled": true,
|
||||
"protocol": "imap",
|
||||
"host": "imap.gmail.com",
|
||||
"port": 993,
|
||||
"user": "placeholder",
|
||||
"password": "placeholder",
|
||||
"mode": "archive",
|
||||
"folderFilter": {
|
||||
"include": ["INBOX", "Sent"],
|
||||
"exclude": []
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Run with environment variables:
|
||||
```bash
|
||||
# Set credentials via environment variables
|
||||
export MAIL2COUCH_COUCHDB_USER="admin"
|
||||
export MAIL2COUCH_COUCHDB_PASSWORD="secure_couchdb_password"
|
||||
export MAIL2COUCH_IMAP_PERSONAL_GMAIL_USER="your-email@gmail.com"
|
||||
export MAIL2COUCH_IMAP_PERSONAL_GMAIL_PASSWORD="your-app-password"
|
||||
|
||||
# Run mail2couch (credentials will override config placeholders)
|
||||
./mail2couch
|
||||
```
|
||||
|
||||
### Advanced Multi-Account Configuration
|
||||
Complex setup with multiple accounts, filtering, and different sync modes:
|
||||
|
||||
|
|
@ -391,10 +474,17 @@ Complex setup with multiple accounts, filtering, and different sync modes:
|
|||
## Production Deployment
|
||||
|
||||
### Security Considerations
|
||||
- Use app passwords instead of account passwords
|
||||
- Store configuration files with restricted permissions (600)
|
||||
- Use HTTPS for CouchDB connections in production
|
||||
- Consider encrypting sensitive configuration data
|
||||
- **Use Environment Variables**: Store sensitive credentials in environment variables instead of configuration files
|
||||
- **Use App Passwords**: Use app passwords instead of account passwords for IMAP authentication
|
||||
- **File Permissions**: Store configuration files with restricted permissions (600)
|
||||
- **Secure Connections**: Use HTTPS for CouchDB connections in production
|
||||
- **SystemD Integration**: Use environment variables in systemd service files:
|
||||
```ini
|
||||
[Service]
|
||||
Environment="MAIL2COUCH_COUCHDB_PASSWORD=secure_password"
|
||||
Environment="MAIL2COUCH_IMAP_GMAIL_PASSWORD=app_password"
|
||||
ExecStart=/usr/local/bin/mail2couch
|
||||
```
|
||||
|
||||
### Monitoring and Maintenance
|
||||
- Review sync metadata documents for sync health
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue