cloud-server/SECURITY.md

# Security Implementation

This document describes the authentication, rate limiting, and security measures implemented in the cloud-server API.

## API Key Authentication

### Overview
All endpoints except `/health` require API key authentication via the `X-API-Key` header.

### Implementation Details
- **Location**: `src/middleware/auth.ts`
- **Method**: Constant-time comparison using SHA-256 hashes
- **Protection**: Prevents timing attacks
- **Response**: 401 Unauthorized for missing or invalid keys

### Usage Example
```bash
# Valid request
curl -H "X-API-Key: your-api-key-here" https://api.example.com/instances

# Missing API key
curl https://api.example.com/instances
# Response: 401 Unauthorized
```

### Configuration
Set the `API_KEY` environment variable in `wrangler.toml`:

```toml
[vars]
API_KEY = "your-secure-api-key"
```

For production, use secrets instead:
```bash
wrangler secret put API_KEY
```

## Rate Limiting

### Overview
IP-based rate limiting protects against abuse and ensures fair usage.

### Rate Limits by Endpoint

| Endpoint | Limit | Window |
|----------|-------|--------|
| `/instances` | 100 requests | 1 minute |
| `/sync` | 10 requests | 1 minute |
| `/health` | No limit | - |

### Implementation Details
- **Location**: `src/middleware/rateLimit.ts`
- **Storage**: In-memory Map (suitable for Cloudflare Workers)
- **IP Detection**: Uses `CF-Connecting-IP` header (Cloudflare-specific)
- **Cleanup**: Automatic periodic cleanup of expired entries
- **Response**: 429 Too Many Requests when limit exceeded

### Response Headers
When rate limited, responses include:
- `Retry-After`: Seconds until rate limit resets
- `X-RateLimit-Retry-After`: Same as Retry-After (for compatibility)

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

## Security Headers

All responses include the following security headers:

### X-Content-Type-Options
```
X-Content-Type-Options: nosniff
```
Prevents MIME type sniffing attacks.

### X-Frame-Options
```
X-Frame-Options: DENY
```
Prevents clickjacking by blocking iframe embedding.

### Strict-Transport-Security
```
Strict-Transport-Security: max-age=31536000
```
Enforces HTTPS for one year (31,536,000 seconds).

## Endpoint Access Control

### Public Endpoints
- `/health` - No authentication required

### Protected Endpoints (Require API Key)
- `/instances` - Query instances
- `/sync` - Trigger synchronization

## Security Best Practices

### API Key Management
1. **Never commit API keys** to version control
2. **Use Cloudflare Secrets** for production:
   ```bash
   wrangler secret put API_KEY
   ```
3. **Rotate keys regularly** (recommended: every 90 days)
4. **Use different keys** for development and production

### Rate Limit Considerations
1. **Monitor usage** to adjust limits as needed
2. **Consider user tiers** for different rate limits (future enhancement)
3. **Log rate limit violations** for security monitoring

### Additional Recommendations
1. **Enable CORS** if needed for browser clients
2. **Add request logging** for audit trails
3. **Implement API versioning** for backward compatibility
4. **Consider JWT tokens** for more sophisticated authentication (future enhancement)

## Testing Authentication and Rate Limiting

### Testing Authentication
```bash
# Test missing API key (should fail)
curl -i https://api.example.com/instances

# Test invalid API key (should fail)
curl -i -H "X-API-Key: invalid-key" https://api.example.com/instances

# Test valid API key (should succeed)
curl -i -H "X-API-Key: your-api-key" https://api.example.com/instances
```

### Testing Rate Limiting
```bash
# Send multiple requests quickly
for i in {1..150}; do
  curl -H "X-API-Key: your-api-key" https://api.example.com/instances
done
# After 100 requests, should receive 429 Too Many Requests
```

### Testing Security Headers
```bash
curl -I https://api.example.com/health
# Should see X-Content-Type-Options, X-Frame-Options, and Strict-Transport-Security
```

## Architecture

### Request Flow
```
1. Request arrives
2. Check if /health endpoint → Skip to step 6
3. Authenticate API key → 401 if invalid
4. Check rate limit → 429 if exceeded
5. Route to handler
6. Add security headers
7. Return response
```

### Middleware Components

```
src/middleware/
├── auth.ts        # API key authentication
├── rateLimit.ts   # IP-based rate limiting
└── index.ts       # Middleware exports
```

## Performance Impact

### Authentication
- **Overhead**: ~1-2ms per request (SHA-256 hashing)
- **Optimization**: Constant-time comparison prevents timing attacks

### Rate Limiting
- **Overhead**: <1ms per request (Map lookup)
- **Memory**: ~100 bytes per unique IP
- **Cleanup**: Automatic periodic cleanup (1% probability per request)

### Security Headers
- **Overhead**: Negligible (<0.1ms)
- **Memory**: ~100 bytes per response

## Future Enhancements

Potential improvements for future versions:

1. **JWT Authentication**: Stateless token-based auth
2. **Role-Based Access Control**: Different permissions per endpoint
3. **API Key Scoping**: Limit keys to specific endpoints
4. **Rate Limit Tiers**: Different limits for different users
5. **Distributed Rate Limiting**: Using Cloudflare Durable Objects
6. **Request Signing**: HMAC-based request verification
7. **Audit Logging**: Comprehensive security event logging
8. **IP Whitelisting**: Allow specific IPs to bypass rate limiting