campaign_connector/docs/security/security-setup.md

# Security Setup Guide

This guide covers security configuration for SMS Campaign Manager, including API key generation, Docker security, and best practices.

## Prerequisites

Before configuring security:

- Docker and Docker Compose installed
- Access to Android device (Termux)
- `.env` file created from `.env.example`

## Quick Setup

### Step 1: Generate API Keys

Run the key generation script:

```bash
cd /mnt/storagessd1tb/campaign_connector
python3 src/core/auth.py
```

This generates cryptographically secure keys for:

- `ADMIN_API_KEY` - Full system access
- `USER_API_KEY` - Regular operations
- `TERMUX_API_KEY` - Android device communication
- `SECRET_KEY` - Session encryption

Copy the generated keys immediately as they are only shown once.

### Step 2: Configure Environment

Back up and edit your `.env` file:

```bash
cp .env .env.backup
nano .env
```

Add the security configuration:

```env
# API Keys (generated above)
ADMIN_API_KEY=<your-admin-key>
USER_API_KEY=<your-user-key>
TERMUX_API_KEY=<your-termux-key>
SECRET_KEY=<your-secret-key>
TERMUX_API_SECRET=<same-as-termux-api-key>

# User Management
ADMIN_USERNAME=admin
ADMIN_PASSWORD=YourSecurePassword123!
```

Secure the file:

```bash
chmod 600 .env
```

### Step 3: Configure Android Device

SSH into your Android device:

```bash
ssh -p 8022 android-dev@YOUR_ANDROID_IP
```

Option A - Use the automated setup script:

```bash
cd ~/projects/sms-campaign-manager
./android/setup-api-key.sh
```

Option B - Set manually:

```bash
echo 'export SMS_API_SECRET="<your-termux-api-key>"' >> ~/.bashrc
source ~/.bashrc
```

### Step 4: Restart Services

On Ubuntu:

```bash
docker compose down
docker compose up -d --build
```

On Android (Termux):

```bash
pkill -f termux-sms-api-server.py
python ~/projects/sms-campaign-manager/android/termux-sms-api-server.py
```

### Step 5: Verify Security

Test authentication:

```bash
# Should fail (no API key)
curl http://localhost:5000/api/campaign/list

# Should succeed (with API key)
curl -H "X-API-Key: YOUR_USER_API_KEY" http://localhost:5000/api/campaign/list
```

Verify Docker security:

```bash
docker inspect sms-campaign-manager | grep -E "Privileged|NetworkMode"
# Expected: "Privileged": false, "NetworkMode": "bridge" or "default"
```

## Docker Security Configuration

The application runs with these security measures:

### Container Isolation

The container runs without privileged mode:

```yaml
services:
  sms-campaign:
    # Runs with standard permissions
    ports:
      - "5000:5000"
      - "5037:5037"
```

### Network Isolation

Uses Docker bridge networking instead of host mode, providing proper network isolation while allowing necessary port access.

### Secure Volumes

Only required directories are mounted:

```yaml
volumes:
  - ./data:/app/data
  - ./uploads:/app/uploads
  - ./logs:/app/logs
```

## API Key Roles

### Admin API Key

Full system access:

- All user permissions
- Database reset operations
- System configuration changes

Use for administrative tasks and automation scripts requiring full access.

### User API Key

Regular application access:

- Create and manage campaigns
- Send SMS messages
- Upload CSV files
- View analytics

Use for web dashboard access and team member API calls.

### Termux API Key

Android device communication:

- Send SMS via Termux API
- Query SMS history
- Device status endpoints

Used internally for server-to-device communication.

## Using API Keys

### HTTP Headers

```bash
# X-API-Key header
curl -H "X-API-Key: YOUR_KEY" http://localhost:5000/api/endpoint

# Bearer token
curl -H "Authorization: Bearer YOUR_KEY" http://localhost:5000/api/endpoint
```

### Web Dashboard

The web dashboard uses session-based authentication. Log in with username/password at `/login`. API keys are not needed for browser access after login.

## Best Practices

### Required

- Generate unique, random API keys
- Store keys only in `.env` file
- Set file permissions: `chmod 600 .env`
- Use HTTPS in production (Tailscale provides this)
- Never commit `.env` to version control

### Recommended

- Rotate API keys every 90 days
- Use different keys per environment
- Monitor logs for failed authentication
- Keep Docker and dependencies updated
- Back up `.env` securely (encrypted)

## Key Rotation

To rotate keys:

1. Generate new keys: `python3 src/core/auth.py`
2. Update `.env` on server and Android device
3. Restart all services
4. Update external scripts using old keys
5. Test all functionality
6. Securely delete old keys

## Git Security

Remove secrets from version control:

```bash
# Remove .env from git tracking
git rm --cached .env
git commit -m "Remove .env from version control"

# Verify .env is in .gitignore
grep "^.env$" .gitignore
```

## Troubleshooting

### Authentication Required Error

Missing or invalid API key:

```bash
# Check if key is loaded in container
docker compose exec sms-campaign env | grep API_KEY

# Test with correct key
curl -H "X-API-Key: YOUR_KEY" http://localhost:5000/api/campaign/list
```

### Invalid API Key Error

Key mismatch or formatting issue:

```bash
# Verify .env format (no spaces around =)
cat .env | grep API_KEY

# Restart to reload environment
docker compose restart
```

### Android Server Won't Start

Missing `SMS_API_SECRET`:

```bash
# Check if set
echo $SMS_API_SECRET

# If empty, run setup
./android/setup-api-key.sh
```

### Container Security Check

Verify Docker configuration:

```bash
# Should show "Privileged": false
docker inspect sms-campaign-manager | grep Privileged

# Should NOT show "NetworkMode": "host"
docker inspect sms-campaign-manager | grep NetworkMode
```

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `ADMIN_API_KEY` | Admin access key | Yes |
| `USER_API_KEY` | User access key | Yes |
| `TERMUX_API_KEY` | Android communication key | Yes |
| `SECRET_KEY` | Session encryption key | Yes |
| `TERMUX_API_SECRET` | Android server auth | Yes |
| `ADMIN_USERNAME` | Initial admin username | Yes |
| `ADMIN_PASSWORD` | Initial admin password | Yes |

See [Environment Variables Reference](../reference/environment-variables.md) for the complete list.

## Related Documentation

- [API Security](api-security.md) - Detailed API authentication guide
- [Authentication Setup](../setup/authentication.md) - User login configuration
- [Quick Start](../setup/quick-start.md) - Getting started guide
- [Deployment Guide](../deployment/deployment-guide.md) - Production deployment