wifi-densepose/docs/security-features.md

WiFi-DensePose Security Features Documentation

Overview

This document details the authentication and rate limiting features implemented in the WiFi-DensePose API, including configuration options, usage examples, and security best practices.

Table of Contents

1. Authentication
2. Rate Limiting
3. CORS Configuration
4. Security Headers
5. Configuration
6. Testing
7. Best Practices

Authentication

JWT Authentication

The API uses JWT (JSON Web Token) based authentication for securing endpoints.

Features

• Token-based authentication: Stateless authentication using JWT tokens
• Role-based access control: Support for different user roles (admin, user)
• Token expiration: Configurable token lifetime
• Refresh token support: Ability to refresh expired tokens
• Multiple authentication sources: Support for headers, query params, and cookies

Implementation Details

# Location: src/api/middleware/auth.py
class AuthMiddleware(BaseHTTPMiddleware):
    """JWT Authentication middleware."""

Public Endpoints (No authentication required):

• / - Root endpoint
• /health, /ready, /live - Health check endpoints
• /docs, /redoc, /openapi.json - API documentation
• /api/v1/pose/current - Current pose data
• /api/v1/pose/zones/* - Zone information
• /api/v1/pose/activities - Activity data
• /api/v1/pose/stats - Statistics
• /api/v1/stream/status - Stream status

Protected Endpoints (Authentication required):

• /api/v1/pose/analyze - Pose analysis
• /api/v1/pose/calibrate - System calibration
• /api/v1/pose/historical - Historical data
• /api/v1/stream/start - Start streaming
• /api/v1/stream/stop - Stop streaming
• /api/v1/stream/clients - Client management
• /api/v1/stream/broadcast - Broadcasting

Usage Examples

1. Obtaining a Token:

# Login endpoint (if implemented)
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "password"}'

2. Using Bearer Token:

# Authorization header
curl -X POST http://localhost:8000/api/v1/pose/analyze \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"data": "..."}'

3. WebSocket Authentication:

// Query parameter for WebSocket
const ws = new WebSocket('ws://localhost:8000/ws/pose?token=<your-jwt-token>');

API Key Authentication

Alternative authentication method for service-to-service communication.

# Location: src/api/middleware/auth.py
class APIKeyAuth:
    """Alternative API key authentication for service-to-service communication."""

Features:

• Simple key-based authentication
• Service identification
• Key management (add/revoke)

Usage:

# API Key in header
curl -X GET http://localhost:8000/api/v1/pose/current \
  -H "X-API-Key: your-api-key-here"

Token Blacklist

Support for token revocation and logout functionality.

class TokenBlacklist:
    """Simple in-memory token blacklist for logout functionality."""

Rate Limiting

Overview

The API implements sophisticated rate limiting using a sliding window algorithm with support for different user tiers.

Features

• Sliding window algorithm: Accurate request counting
• Token bucket algorithm: Alternative rate limiting method
• User-based limits: Different limits for anonymous/authenticated/admin users
• Path-specific limits: Custom limits for specific endpoints
• Adaptive rate limiting: Adjust limits based on system load
• Temporary blocking: Block clients after excessive violations

Implementation Details

# Location: src/api/middleware/rate_limit.py
class RateLimitMiddleware(BaseHTTPMiddleware):
    """Rate limiting middleware with sliding window algorithm."""

Default Rate Limits:

• Anonymous users: 100 requests/hour (configurable)
• Authenticated users: 1000 requests/hour (configurable)
• Admin users: 10000 requests/hour

Path-Specific Limits:

• /api/v1/pose/current: 60 requests/minute
• /api/v1/pose/analyze: 10 requests/minute
• /api/v1/pose/calibrate: 1 request/5 minutes
• /api/v1/stream/start: 5 requests/minute
• /api/v1/stream/stop: 5 requests/minute

Response Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Window: 3600
X-RateLimit-Reset: 1641234567

When rate limit is exceeded:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: Exceeded
X-RateLimit-Remaining: 0

Adaptive Rate Limiting

The system can adjust rate limits based on system load:

class AdaptiveRateLimit:
    """Adaptive rate limiting based on system load."""

Load-based adjustments:

• High load (>80%): Reduce limits by 50%
• Medium load (>60%): Reduce limits by 30%
• Low load (<30%): Increase limits by 20%

CORS Configuration

Overview

Cross-Origin Resource Sharing (CORS) configuration for browser-based clients.

Features

• Configurable origins: Whitelist specific origins
• Wildcard support: Allow all origins in development
• Preflight handling: Proper OPTIONS request handling
• Credential support: Allow cookies and auth headers
• Custom headers: Expose rate limit and other headers

Configuration

# Development configuration
cors_config = {
    "allow_origins": ["*"],
    "allow_credentials": True,
    "allow_methods": ["*"],
    "allow_headers": ["*"]
}

# Production configuration
cors_config = {
    "allow_origins": ["https://app.example.com", "https://admin.example.com"],
    "allow_credentials": True,
    "allow_methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    "allow_headers": ["Authorization", "Content-Type"]
}

Security Headers

The API includes various security headers for enhanced protection:

class SecurityHeaders:
    """Security headers for API responses."""

Headers included:

• X-Content-Type-Options: nosniff - Prevent MIME sniffing
• X-Frame-Options: DENY - Prevent clickjacking
• X-XSS-Protection: 1; mode=block - Enable XSS protection
• Referrer-Policy: strict-origin-when-cross-origin - Control referrer
• Content-Security-Policy - Control resource loading

Configuration

Environment Variables

# Authentication
ENABLE_AUTHENTICATION=true
SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256
JWT_EXPIRE_HOURS=24

# Rate Limiting
ENABLE_RATE_LIMITING=true
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_AUTHENTICATED_REQUESTS=1000
RATE_LIMIT_WINDOW=3600

# CORS
CORS_ENABLED=true
CORS_ORIGINS=["https://app.example.com"]
CORS_ALLOW_CREDENTIALS=true

# Security
ALLOWED_HOSTS=["api.example.com", "localhost"]

Settings Class

# src/config/settings.py
class Settings(BaseSettings):
    # Authentication settings
    enable_authentication: bool = Field(default=True)
    secret_key: str = Field(...)
    jwt_algorithm: str = Field(default="HS256")
    jwt_expire_hours: int = Field(default=24)
    
    # Rate limiting settings
    enable_rate_limiting: bool = Field(default=True)
    rate_limit_requests: int = Field(default=100)
    rate_limit_authenticated_requests: int = Field(default=1000)
    rate_limit_window: int = Field(default=3600)
    
    # CORS settings
    cors_enabled: bool = Field(default=True)
    cors_origins: List[str] = Field(default=["*"])
    cors_allow_credentials: bool = Field(default=True)

Testing

Test Script

A comprehensive test script is provided to verify security features:

# Run the test script
python test_auth_rate_limit.py

The test script covers:

• Public endpoint access
• Protected endpoint authentication
• JWT token validation
• Rate limiting behavior
• CORS headers
• Security headers
• Feature flag verification

Manual Testing

1. Test Authentication:

# Without token (should fail)
curl -X POST http://localhost:8000/api/v1/pose/analyze

# With token (should succeed)
curl -X POST http://localhost:8000/api/v1/pose/analyze \
  -H "Authorization: Bearer <token>"

2. Test Rate Limiting:

# Send multiple requests quickly
for i in {1..150}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    http://localhost:8000/api/v1/pose/current
done

3. Test CORS:

# Preflight request
curl -X OPTIONS http://localhost:8000/api/v1/pose/current \
  -H "Origin: https://example.com" \
  -H "Access-Control-Request-Method: GET" \
  -H "Access-Control-Request-Headers: Authorization"

Best Practices

Security Recommendations

1. Production Configuration:

   • Always use strong secret keys
   • Disable debug mode
   • Restrict CORS origins
   • Use HTTPS only
   • Enable all security headers

2. Token Management:

   • Implement token refresh mechanism
   • Use short-lived tokens
   • Implement logout/blacklist functionality
   • Store tokens securely on client

3. Rate Limiting:

   • Set appropriate limits for your use case
   • Monitor and adjust based on usage
   • Implement different tiers for users
   • Use Redis for distributed systems

4. API Keys:

   • Use for service-to-service communication
   • Rotate keys regularly
   • Monitor key usage
   • Implement key scoping

Monitoring

1. Authentication Events:

   • Log failed authentication attempts
   • Monitor suspicious patterns
   • Alert on repeated failures

2. Rate Limit Violations:

   • Track clients hitting limits
   • Identify potential abuse
   • Adjust limits as needed

3. Security Headers:

   • Verify headers in responses
   • Test with security tools
   • Regular security audits

Troubleshooting

Common Issues:

1. 401 Unauthorized:

   • Check token format
   • Verify token expiration
   • Ensure correct secret key

2. 429 Too Many Requests:

   • Check rate limit configuration
   • Verify client identification
   • Look for Retry-After header

3. CORS Errors:

   • Verify allowed origins
   • Check preflight responses
   • Ensure credentials setting matches

Disabling Security Features

For development or testing, security features can be disabled:

# Disable authentication
ENABLE_AUTHENTICATION=false

# Disable rate limiting
ENABLE_RATE_LIMITING=false

# Allow all CORS origins
CORS_ORIGINS=["*"]

Warning: Never disable security features in production!

Future Enhancements

1. OAuth2/OpenID Connect Support
2. API Key Scoping and Permissions
3. IP-based Rate Limiting
4. Geographic Restrictions
5. Request Signing
6. Mutual TLS Authentication