atlas/docs/API_SECURITY.md

API Security & Rate Limiting

Overview

AtlasOS implements comprehensive API security measures including rate limiting, security headers, CORS protection, and request validation to protect the API from abuse and attacks.

Rate Limiting

Token Bucket Algorithm

The rate limiter uses a token bucket algorithm:

• Default Rate: 100 requests per minute per client
• Window: 60 seconds
• Token Refill: Tokens are refilled based on elapsed time
• Per-Client: Rate limiting is applied per IP address or user ID

Rate Limit Headers

All responses include rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Window: 60

Rate Limit Exceeded

When rate limit is exceeded, the API returns:

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "rate limit exceeded",
  "details": "too many requests, please try again later"
}

HTTP Status: 429 Too Many Requests

Client Identification

Rate limiting uses different keys based on authentication:

• Authenticated Users: user:{user_id} - More granular per-user limiting
• Unauthenticated: ip:{ip_address} - IP-based limiting

Public Endpoints

Public endpoints (login, health checks) are excluded from rate limiting to ensure availability.

Security Headers

All responses include security headers:

X-Content-Type-Options

• Value: nosniff
• Purpose: Prevents MIME type sniffing

X-Frame-Options

• Value: DENY
• Purpose: Prevents clickjacking attacks

X-XSS-Protection

• Value: 1; mode=block
• Purpose: Enables XSS filtering in browsers

Referrer-Policy

• Value: strict-origin-when-cross-origin
• Purpose: Controls referrer information

Permissions-Policy

• Value: geolocation=(), microphone=(), camera=()
• Purpose: Disables unnecessary browser features

Strict-Transport-Security (HSTS)

• Value: max-age=31536000; includeSubDomains
• Purpose: Forces HTTPS connections (only on HTTPS)
• Note: Only added when request is over TLS

Content-Security-Policy (CSP)

• Value: default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data:; font-src 'self' https://cdn.jsdelivr.net; connect-src 'self';
• Purpose: Restricts resource loading to prevent XSS

CORS (Cross-Origin Resource Sharing)

Allowed Origins

By default, the following origins are allowed:

• http://localhost:8080
• http://localhost:3000
• http://127.0.0.1:8080
• Same-origin requests (no Origin header)

CORS Headers

When a request comes from an allowed origin:

Access-Control-Allow-Origin: http://localhost:8080
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-Requested-With
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 3600

Preflight Requests

OPTIONS requests are handled automatically:

• Status: 204 No Content
• Headers: All CORS headers included
• Purpose: Browser preflight checks

Request Size Limits

Maximum Request Body Size

• Limit: 10 MB (10,485,760 bytes)
• Enforcement: Automatic via http.MaxBytesReader
• Error: Returns 413 Request Entity Too Large if exceeded

Content-Type Validation

POST, PUT, and PATCH requests must include a valid Content-Type header:

Allowed Types:

• application/json
• application/x-www-form-urlencoded
• multipart/form-data

Error Response:

{
  "code": "BAD_REQUEST",
  "message": "Content-Type must be application/json"
}

Middleware Chain Order

Security middleware is applied in the following order (outer to inner):

1. CORS - Handles preflight requests
2. Security Headers - Adds security headers
3. Request Size Limit - Enforces 10MB limit
4. Content-Type Validation - Validates request content type
5. Rate Limiting - Enforces rate limits
6. Error Recovery - Catches panics
7. Request ID - Generates request IDs
8. Logging - Logs requests
9. Audit - Records audit logs
10. Authentication - Validates JWT tokens
11. Routes - Handles requests

Public Endpoints

The following endpoints are excluded from certain security checks:

• /api/v1/auth/login - Rate limiting, Content-Type validation
• /api/v1/auth/logout - Rate limiting, Content-Type validation
• /healthz - Rate limiting, Content-Type validation
• /metrics - Rate limiting, Content-Type validation
• /api/docs - Rate limiting, Content-Type validation
• /api/openapi.yaml - Rate limiting, Content-Type validation

Best Practices

For API Consumers

1. Respect Rate Limits: Implement exponential backoff when rate limited
2. Use Authentication: Authenticated users get better rate limits
3. Include Content-Type: Always include Content-Type: application/json
4. Handle Errors: Check for 429 status and retry after delay
5. Request Size: Keep request bodies under 10MB

For Administrators

1. Monitor Rate Limits: Check logs for rate limit violations
2. Adjust Limits: Modify rate limit values in code if needed
3. CORS Configuration: Update allowed origins for production
4. HTTPS: Always use HTTPS in production for HSTS
5. Security Headers: Review CSP policy for your use case

Configuration

Rate Limiting

Rate limits are currently hardcoded but can be configured:

// In rate_limit.go
rateLimiter := NewRateLimiter(100, time.Minute) // 100 req/min

CORS Origins

Update allowed origins in security_middleware.go:

allowedOrigins := []string{
    "https://yourdomain.com",
    "https://app.yourdomain.com",
}

Request Size Limit

Modify in app.go:

a.requestSizeMiddleware(10*1024*1024) // 10MB

Error Responses

Rate Limit Exceeded

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "rate limit exceeded",
  "details": "too many requests, please try again later"
}

Status: 429 Too Many Requests

Request Too Large

{
  "code": "BAD_REQUEST",
  "message": "request body too large"
}

Status: 413 Request Entity Too Large

Invalid Content-Type

{
  "code": "BAD_REQUEST",
  "message": "Content-Type must be application/json"
}

Status: 400 Bad Request

Monitoring

Rate Limit Metrics

Monitor rate limit violations:

• Check audit logs for rate limit events
• Monitor 429 status codes in access logs
• Track rate limit headers in responses

Security Events

Monitor for security-related events:

• Invalid Content-Type headers
• Request size violations
• CORS violations (check server logs)
• Authentication failures

Future Enhancements

1. Configurable Rate Limits: Environment variable configuration
2. Per-Endpoint Limits: Different limits for different endpoints
3. IP Whitelisting: Bypass rate limits for trusted IPs
4. Rate Limit Metrics: Prometheus metrics for rate limiting
5. Distributed Rate Limiting: Redis-based for multi-instance deployments
6. Advanced CORS: Configurable CORS via environment variables
7. Request Timeout: Configurable request timeout limits