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:

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

For Production

Use Cloudflare secrets (recommended):

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

Step 2: Start Development Server

npm run dev

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

Step 3: Test Security Features

Option A: Automated Testing (Recommended)

# 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)

curl http://127.0.0.1:8787/health
# Expected: 200 OK with health status

Test 2: Protected endpoint without API key

curl http://127.0.0.1:8787/instances
# Expected: 401 Unauthorized

Test 3: Protected endpoint with invalid API key

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

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

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:

# 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

{
  "data": [...],
  "pagination": {...},
  "meta": {...}
}

Status: 200 OK

Missing/Invalid API Key

{
  "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

{
  "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:

# 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:

# Stop and restart
npm run dev

API Client Examples

JavaScript/Node.js

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

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

# 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

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

2. Deploy

npm run deploy

3. Test Production

# 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