cloud-server/QUICKSTART_SECURITY.md

# Security Features Quick Start

This guide helps you quickly set up and test the new authentication and rate limiting features.

## Prerequisites

- Node.js and npm installed
- Cloudflare Wrangler CLI installed
- Development server running

## Step 1: Configure API Key

### For Development

Edit `wrangler.toml` and add:

```toml
[vars]
API_KEY = "dev-test-key-12345"
```

### For Production

Use Cloudflare secrets (recommended):

```bash
wrangler secret put API_KEY
# Enter your secure API key when prompted
```

## Step 2: Start Development Server

```bash
npm run dev
```

The server will start at `http://127.0.0.1:8787`

## Step 3: Test Security Features

### Option A: Automated Testing (Recommended)

```bash
# Set API key to match wrangler.toml
export API_KEY="dev-test-key-12345"

# Run automated tests
./test-security.sh
```

### Option B: Manual Testing

**Test 1: Health endpoint (public)**
```bash
curl http://127.0.0.1:8787/health
# Expected: 200 OK with health status
```

**Test 2: Protected endpoint without API key**
```bash
curl http://127.0.0.1:8787/instances
# Expected: 401 Unauthorized
```

**Test 3: Protected endpoint with invalid API key**
```bash
curl -H "X-API-Key: wrong-key" http://127.0.0.1:8787/instances
# Expected: 401 Unauthorized
```

**Test 4: Protected endpoint with valid API key**
```bash
curl -H "X-API-Key: dev-test-key-12345" http://127.0.0.1:8787/instances
# Expected: 200 OK with instance data
```

**Test 5: Check security headers**
```bash
curl -I http://127.0.0.1:8787/health
# Expected: X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security
```

## Step 4: Test Rate Limiting (Optional)

Rate limits are:
- `/instances`: 100 requests per minute
- `/sync`: 10 requests per minute

To test rate limiting, send many requests quickly:

```bash
# Send 101 requests to /instances
for i in {1..101}; do
  curl -H "X-API-Key: dev-test-key-12345" \
       http://127.0.0.1:8787/instances?limit=1
done
# After 100 requests, you should receive 429 Too Many Requests
```

## Understanding Responses

### Successful Request
```json
{
  "data": [...],
  "pagination": {...},
  "meta": {...}
}
```
Status: 200 OK

### Missing/Invalid API Key
```json
{
  "error": "Unauthorized",
  "message": "Valid API key required. Provide X-API-Key header.",
  "timestamp": "2024-01-21T12:00:00.000Z"
}
```
Status: 401 Unauthorized
Headers: `WWW-Authenticate: API-Key`

### Rate Limit Exceeded
```json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later.",
  "retry_after_seconds": 45,
  "timestamp": "2024-01-21T12:00:00.000Z"
}
```
Status: 429 Too Many Requests
Headers: `Retry-After: 45`

## Common Issues

### Issue: 401 Unauthorized with correct API key

**Solution**: Verify the API key in `wrangler.toml` matches your request:
```bash
# Check wrangler.toml
grep API_KEY wrangler.toml

# Or restart the dev server
npm run dev
```

### Issue: Rate limit never triggers

**Solution**: Rate limits are per IP address. If you're behind a proxy or load balancer, all requests might appear to come from the same IP. This is expected behavior.

### Issue: Missing security headers

**Solution**: Security headers are added by the `addSecurityHeaders()` function. Check that your server is running the latest code:
```bash
# Stop and restart
npm run dev
```

## API Client Examples

### JavaScript/Node.js
```javascript
const API_KEY = 'dev-test-key-12345';
const API_URL = 'http://127.0.0.1:8787';

// Fetch instances
const response = await fetch(`${API_URL}/instances`, {
  headers: {
    'X-API-Key': API_KEY
  }
});

const data = await response.json();
console.log(data);
```

### Python
```python
import requests

API_KEY = 'dev-test-key-12345'
API_URL = 'http://127.0.0.1:8787'

# Fetch instances
response = requests.get(
    f'{API_URL}/instances',
    headers={'X-API-Key': API_KEY}
)

data = response.json()
print(data)
```

### cURL
```bash
# Basic request
curl -H "X-API-Key: dev-test-key-12345" \
     http://127.0.0.1:8787/instances

# With query parameters
curl -H "X-API-Key: dev-test-key-12345" \
     "http://127.0.0.1:8787/instances?provider=linode&limit=10"

# Trigger sync
curl -X POST \
     -H "X-API-Key: dev-test-key-12345" \
     http://127.0.0.1:8787/sync
```

## Production Deployment

### 1. Set Production API Key
```bash
wrangler secret put API_KEY
# Enter a strong, random API key (e.g., from: openssl rand -base64 32)
```

### 2. Deploy
```bash
npm run deploy
```

### 3. Test Production
```bash
# Replace with your production URL and API key
curl -H "X-API-Key: your-production-key" \
     https://your-worker.workers.dev/health
```

### 4. Monitor
Watch for:
- 401 responses (authentication failures)
- 429 responses (rate limit hits)
- Security header compliance

## Next Steps

- Read `SECURITY.md` for comprehensive security documentation
- Read `IMPLEMENTATION_NOTES.md` for technical implementation details
- Set up monitoring for authentication failures and rate limit violations
- Consider implementing API key rotation (recommended: every 90 days)

## Support

For issues or questions:
1. Check `SECURITY.md` for detailed documentation
2. Review `IMPLEMENTATION_NOTES.md` for technical details
3. Run `./test-security.sh` to verify your setup
4. Check Cloudflare Workers logs for error messages

## Security Best Practices

1. **Never commit API keys** to version control
2. **Use different keys** for development and production
3. **Rotate keys regularly** (every 90 days recommended)
4. **Monitor authentication failures** for security events
5. **Use HTTPS** in production (enforced by Strict-Transport-Security header)
6. **Store production keys** in Cloudflare Secrets, not environment variables