talk2me/SECURITY.md

# Security Configuration Guide

This document outlines security best practices for deploying Talk2Me.

## Secrets Management

Talk2Me includes a comprehensive secrets management system with encryption, rotation, and audit logging.

### Quick Start

```bash
# Initialize secrets management
python manage_secrets.py init

# Set a secret
python manage_secrets.py set TTS_API_KEY

# List secrets
python manage_secrets.py list

# Rotate secrets
python manage_secrets.py rotate ADMIN_TOKEN
```

See [SECRETS_MANAGEMENT.md](SECRETS_MANAGEMENT.md) for detailed documentation.

## Environment Variables

**NEVER commit sensitive information like API keys, passwords, or secrets to version control.**

### Required Security Configuration

1. **TTS_API_KEY**
   - Required for TTS server authentication
   - Set via environment variable: `export TTS_API_KEY="your-api-key"`
   - Or use a `.env` file (see `.env.example`)

2. **SECRET_KEY**
   - Required for Flask session security
   - Generate a secure key: `python -c "import secrets; print(secrets.token_hex(32))"`
   - Set via: `export SECRET_KEY="your-generated-key"`

3. **ADMIN_TOKEN**
   - Required for admin endpoints
   - Generate a secure token: `python -c "import secrets; print(secrets.token_urlsafe(32))"`
   - Set via: `export ADMIN_TOKEN="your-admin-token"`

### Using a .env File (Recommended)

1. Copy the example file:
   ```bash
   cp .env.example .env
   ```

2. Edit `.env` with your actual values:
   ```bash
   nano .env  # or your preferred editor
   ```

3. Load environment variables:
   ```bash
   # Using python-dotenv (add to requirements.txt)
   pip install python-dotenv
   
   # Or source manually
   source .env
   ```

### Python-dotenv Integration

To automatically load `.env` files, add this to the top of `app.py`:

```python
from dotenv import load_dotenv
load_dotenv()  # Load .env file if it exists
```

### Production Deployment

For production deployments:

1. **Use a secrets management service**:
   - AWS Secrets Manager
   - HashiCorp Vault
   - Azure Key Vault
   - Google Secret Manager

2. **Set environment variables securely**:
   - Use your platform's environment configuration
   - Never expose secrets in logs or error messages
   - Rotate keys regularly

3. **Additional security measures**:
   - Use HTTPS only
   - Enable CORS restrictions
   - Implement rate limiting
   - Monitor for suspicious activity

### Docker Deployment

When using Docker:

```dockerfile
# Use build arguments for non-sensitive config
ARG TTS_SERVER_URL=http://localhost:5050/v1/audio/speech

# Use runtime environment for secrets
ENV TTS_API_KEY=""
```

Run with:
```bash
docker run -e TTS_API_KEY="your-key" -e SECRET_KEY="your-secret" talk2me
```

### Kubernetes Deployment

Use Kubernetes secrets:

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: talk2me-secrets
type: Opaque
stringData:
  tts-api-key: "your-api-key"
  flask-secret-key: "your-secret-key"
  admin-token: "your-admin-token"
```

### Rate Limiting

Talk2Me implements comprehensive rate limiting to prevent abuse:

1. **Per-Endpoint Limits**:
   - Transcription: 10/min, 100/hour
   - Translation: 20/min, 300/hour
   - TTS: 15/min, 200/hour

2. **Global Limits**:
   - 1,000 requests/minute total
   - 50 concurrent requests maximum

3. **Automatic Protection**:
   - IP blocking for excessive requests
   - Request size validation
   - Burst control

See [RATE_LIMITING.md](RATE_LIMITING.md) for configuration details.

### Security Checklist

- [ ] All API keys removed from source code
- [ ] Environment variables configured
- [ ] `.env` file added to `.gitignore`
- [ ] Secrets rotated after any potential exposure
- [ ] HTTPS enabled in production
- [ ] CORS properly configured
- [ ] Rate limiting enabled and configured
- [ ] Admin endpoints protected with authentication
- [ ] Error messages don't expose sensitive info
- [ ] Logs sanitized of sensitive data
- [ ] Request size limits enforced
- [ ] IP blocking configured for abuse prevention

### Reporting Security Issues

If you discover a security vulnerability, please report it to:
- Create a private security advisory on GitHub
- Or email: security@yourdomain.com

Do not create public issues for security vulnerabilities.