middleware

Overview ¶

Package middleware provides HTTP middleware for the StreamSpace API. This file implements API key authentication middleware for agents.

SECURITY: Agent API Key Authentication Middleware

This middleware validates agent API keys on incoming requests. It is used to protect agent-specific endpoints:

• POST /api/v1/agents/register (agent self-registration)
• GET /api/v1/agents/connect (WebSocket upgrade)

The middleware:

1. Extracts API key from X-Agent-API-Key header
2. Validates key format (64 hex chars)
3. Looks up agent by agent_id query/path parameter
4. Compares provided key against stored bcrypt hash
5. Updates api_key_last_used_at on successful auth
6. Sets agent_id in Gin context for downstream handlers

Usage:

agentAuth := middleware.NewAgentAuth(database)
router.POST("/agents/register", agentAuth.RequireAPIKey(), handler.RegisterAgent)
router.GET("/agents/connect", agentAuth.RequireAPIKey(), handler.HandleAgentConnection)

Package middleware - auditlog.go ¶

This file implements comprehensive audit logging for compliance and security.

The audit logger records all API requests in a structured format to support:

• Security investigations (who did what when)
• Compliance requirements (SOC2, HIPAA, GDPR, ISO 27001)
• Usage analytics (patterns, trends)
• Incident response (forensic analysis)

Why Audit Logging is Critical ¶

**Security Requirements**:

• Detect unauthorized access attempts
• Track privilege escalation
• Identify data exfiltration
• Support incident response

**Compliance Requirements**:

• SOC2: Requires audit trail of all system changes
• HIPAA: Requires audit logs retained for 6 years
• GDPR: Requires audit trail for data access/modifications
• ISO 27001: Requires logging of user activities

**Business Requirements**:

• Usage analytics and billing
• User behavior analysis
• Performance troubleshooting
• Capacity planning

Audit Log Architecture ¶

┌─────────────────────────────────────────────────────────┐
│  HTTP Request                                           │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  Audit Middleware                                       │
│  1. Capture request body (if enabled)                   │
│  2. Wrap response writer to capture response            │
│  3. Record start time                                   │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  Request Processing (handlers, business logic)          │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  After Request Completion                               │
│  1. Calculate duration                                  │
│  2. Extract user info from context                      │
│  3. Redact sensitive data (passwords, tokens)           │
│  4. Create AuditEvent struct                            │
│  5. Log asynchronously to database                      │
└─────────────────────────────────────────────────────────┘

What Gets Logged ¶

**Every Request**:

• Timestamp (when request started)
• User ID and username (if authenticated)
• HTTP method (GET, POST, PUT, DELETE, etc.)
• Request path (/api/sessions, /api/users, etc.)
• HTTP status code (200, 404, 500, etc.)
• Client IP address
• User agent string
• Request duration in milliseconds
• Errors (if any occurred)

**Conditionally Logged** (if enabled):

• Request body (max 10KB, sensitive fields redacted)
• Response body (disabled by default, too verbose)

Sensitive Data Redaction ¶

To prevent leaking credentials in audit logs, these fields are automatically redacted (replaced with "[REDACTED]"):

• password
• token
• secret
• apiKey
• api_key

Redaction applies recursively to nested objects:

Original:  {"user": "alice", "password": "secret123", "profile": {"apiKey": "xyz"}}
Redacted:  {"user": "alice", "password": "[REDACTED]", "profile": {"apiKey": "[REDACTED]"}}

Database Schema ¶

Audit logs are stored in the `audit_log` table:

CREATE TABLE audit_log (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(255),
    action VARCHAR(100),        -- HTTP method
    resource_type VARCHAR(100), -- Resource path
    resource_id VARCHAR(255),   -- Specific resource ID (if applicable)
    changes JSONB,              -- Full event details (method, path, status, etc.)
    timestamp TIMESTAMPTZ,
    ip_address VARCHAR(45)      -- IPv4 or IPv6
);

Indexes for fast queries:

• idx_audit_log_user_id: Query by user
• idx_audit_log_timestamp: Query by time range
• idx_audit_log_action: Query by action type
• idx_audit_log_resource_type: Query by resource

Performance Characteristics ¶

**Asynchronous Logging**:

• Log writing happens in a goroutine (non-blocking)
• Request completes immediately, logging happens in background
• No impact on request latency (0ms added)

**Database Impact**:

• 1 INSERT per request (~1ms write time)
• Bulk inserts possible for high-throughput (future enhancement)
• Partitioning by timestamp recommended for large datasets

**Storage Requirements**:

• ~500 bytes per event (without request/response bodies)
• ~2 KB per event (with request body)
• Example: 1 million requests/day = 500 MB/day (no bodies) or 2 GB/day (with bodies)

Retention and Compliance ¶

**Retention Policies** (configure in database):

• SOC2: 1 year minimum
• HIPAA: 6 years minimum
• GDPR: Varies by purpose
• ISO 27001: 1 year minimum

**Recommended Retention**:

• Hot storage (PostgreSQL): 90 days
• Warm storage (S3/archive): 1-7 years
• Cold storage (Glacier): 7+ years

**Cleanup Strategy**:

-- Archive old logs to S3
SELECT * FROM audit_log WHERE timestamp < NOW() - INTERVAL '90 days'
-- Then delete from PostgreSQL
DELETE FROM audit_log WHERE timestamp < NOW() - INTERVAL '90 days'

Querying Audit Logs ¶

**Common queries**:

-- User activity in last 24 hours
SELECT * FROM audit_log
WHERE user_id = 'user-123'
  AND timestamp > NOW() - INTERVAL '24 hours'
ORDER BY timestamp DESC;

-- Failed login attempts
SELECT * FROM audit_log
WHERE resource_type = '/api/auth/login'
  AND changes->>'status_code' = '401'
  AND timestamp > NOW() - INTERVAL '1 hour';

-- Resource deletions
SELECT * FROM audit_log
WHERE action = 'DELETE'
  AND timestamp > NOW() - INTERVAL '7 days';

Known Limitations ¶

1. **No log batching**: Each request = 1 DB write - Solution: Implement batch writer (future)
2. **No log rotation**: Logs grow indefinitely - Solution: Implement TTL-based cleanup (future)
3. **No request correlation**: Hard to trace multi-request operations - Solution: Add request ID middleware (implemented)
4. **Goroutine leak risk**: If database is slow, goroutines pile up - Solution: Use worker pool pattern (future)

See also:

• api/internal/middleware/request_id.go: Request correlation IDs
• api/internal/db/queries/audit.sql: Audit log queries

Package middleware provides HTTP middleware for the StreamSpace API. This file implements HTTP response compression using gzip.

Purpose: The compression middleware reduces bandwidth usage and improves response times by compressing HTTP responses with gzip encoding. This is especially beneficial for JSON API responses which typically compress to 60-80% smaller sizes.

Implementation Details: - Uses sync.Pool for gzip writer reuse (reduces memory allocations) - Configurable compression levels (BestSpeed, DefaultCompression, BestCompression) - Automatic skip for incompressible content (WebSocket, Server-Sent Events) - Wraps response writer transparently (handlers unaware of compression)

Performance Characteristics: - Best Speed (level 1): 2-3x faster, 70-80% compression ratio - Default (level 6): Balanced, 60-70% compression ratio - Best Compression (level 9): Slowest, 50-60% compression ratio - Memory: ~256KB per concurrent request (reused via sync.Pool) - CPU overhead: 1-5ms per response (depending on compression level and payload size)

Thread Safety: Safe for concurrent use. Each request gets its own gzip writer from the pool, uses it for the duration of the request, then returns it to the pool.

Usage:

// Use default compression (level 6)
router.Use(middleware.Gzip(middleware.DefaultCompression))

// Use best speed (level 1) for high-throughput APIs
router.Use(middleware.Gzip(middleware.BestSpeed))

// Exclude specific paths from compression
router.Use(middleware.GzipWithExclusions(
    middleware.DefaultCompression,
    []string{"/api/v1/ws/", "/api/v1/upload"},
))

Configuration:

// Available compression levels
middleware.NoCompression      // No compression (level 0)
middleware.BestSpeed          // Fastest compression (level 1)
middleware.DefaultCompression // Balanced (level 6)
middleware.BestCompression    // Maximum compression (level 9)

Package middleware defines constants for middleware components.

This file centralizes configuration values for: - Rate limiting (prevent brute force and DoS attacks) - CSRF protection (prevent cross-site request forgery) - Request size limits (prevent payload DoS attacks)

SECURITY FIX (2025-11-14): Extracted all magic numbers to improve code maintainability and security auditing.

Package middleware provides HTTP middleware for the StreamSpace API. This file implements CSRF (Cross-Site Request Forgery) protection.

SECURITY ENHANCEMENT (2025-11-14): Added CSRF protection using double-submit cookie pattern with constant-time comparison.

CSRF Attack Scenario (Without Protection): 1. User logs into StreamSpace (gets session cookie) 2. User visits malicious site evil.com 3. evil.com contains: <form action="https://streamspace.io/api/delete-account" method="POST"> 4. Browser automatically sends session cookie with the malicious request 5. StreamSpace deletes user's account (thinks it's a legitimate request)

CSRF Protection (Double-Submit Cookie Pattern): 1. GET request: Server generates random CSRF token, sends in both cookie AND header 2. Client stores header token (JavaScript can read it) 3. POST request: Client sends token in both cookie AND custom header 4. Server compares: cookie token == header token (using constant-time comparison) 5. If match: Request is from legitimate client (evil.com can't read/set custom headers) 6. If mismatch: Request is CSRF attack (blocked)

Why This Works: - Malicious sites can trigger POST requests (via forms, fetch) - Browsers automatically send cookies with requests (even cross-site) - BUT: Malicious sites CANNOT read cookies or set custom headers (Same-Origin Policy) - So attacker cannot get the token to put in the custom header

Implementation Details: - Token: 32 random bytes, base64-encoded (256 bits of entropy) - Comparison: Constant-time (prevents timing attacks) - Storage: In-memory map with automatic cleanup (24-hour expiry) - Exempt: GET, HEAD, OPTIONS requests (safe methods, no state change)

Usage:

router.Use(middleware.CSRFProtection())

Package middleware provides HTTP middleware for the StreamSpace API. This file implements comprehensive input validation and sanitization.

Purpose: The input validation middleware protects against injection attacks by validating and sanitizing all user input including query parameters, path parameters, and request bodies. This prevents SQL injection, XSS, command injection, LDAP injection, and path traversal attacks.

Implementation Details: - Path validation: Detects path traversal patterns (../, %2e%2e, etc.) - Query parameter validation: Checks for injection patterns in all query strings - JSON sanitization: Recursively sanitizes nested objects and arrays using bluemonday - Format validation: Validates usernames, emails, Kubernetes resource names, container images - Length limits: Prevents buffer overflow with 10KB max input size - Pattern detection: Regex-based detection of SQL, command, and LDAP injection attempts

Security Notes: This middleware provides defense-in-depth against common web vulnerabilities: - SQL Injection: Detects UNION, SELECT, DROP, etc. patterns - XSS (Cross-Site Scripting): Bluemonday strips all HTML tags and dangerous content - Command Injection: Blocks shell metacharacters (;, |, &, backticks, $()) - LDAP Injection: Detects LDAP special characters when used in combinations - Path Traversal: Prevents directory traversal attacks (../, ..\, null bytes) - Buffer Overflow: Enforces 10KB limit on input values

Thread Safety: Safe for concurrent use. Each request gets its own validation context. The bluemonday policy is thread-safe and shared across all requests.

Usage:

// Basic input validation on all routes
validator := middleware.NewInputValidator()
router.Use(validator.Middleware())

// JSON sanitization for API endpoints
router.Use(validator.SanitizeJSONMiddleware())

// Standalone validation functions
if err := middleware.ValidateUsername(username); err != nil {
    return err
}
if err := middleware.ValidateEmail(email); err != nil {
    return err
}

Configuration:

// Bluemonday uses StrictPolicy by default (strips ALL HTML)
// To customize, modify the policy in NewInputValidator()

Package middleware provides HTTP middleware for the StreamSpace API. This file implements license enforcement middleware.

LICENSE ENFORCEMENT: - Check license limits before creating resources (users, sessions, nodes) - Block actions that exceed license limits - Warn when approaching limits (80%, 90%, 95%) - Cache license information for performance

LICENSE TIERS: - Community (Free): 10 users, 20 sessions, 3 nodes - Pro: 100 users, 200 sessions, 10 nodes - Enterprise: Unlimited users, sessions, nodes

USAGE:

router.Use(middleware.LicenseEnforcement(database))
router.POST("/users", handler.CreateUser) // Will check license limits

Thread Safety: - License cache is thread-safe with mutex - Database operations are thread-safe

Dependencies: - Database: PostgreSQL licenses table

Example Usage:

// Apply middleware to admin routes
admin := router.Group("/api/v1/admin")
admin.Use(middleware.LicenseEnforcement(database))

Package middleware provides HTTP middleware for the StreamSpace API. This file implements HTTP method restriction to prevent abuse through uncommon methods.

Purpose: This middleware restricts incoming requests to only commonly-used, safe HTTP methods. It prevents security issues and attacks that exploit uncommon or dangerous methods like TRACE (XSS via HTTP response splitting) and CONNECT (proxy abuse).

Implementation Details: - AllowedHTTPMethods: Whitelist approach (only allow known-safe methods) - DisallowedHTTPMethods: Blacklist approach (explicitly block dangerous methods) - Returns 405 Method Not Allowed with Allow header - Defense in depth: Use both middlewares together for maximum security

Security Notes: Dangerous HTTP methods and why they're blocked: - TRACE: Can be used in XSS attacks (cross-site tracing)

• Reflects request in response body
• Can expose authentication cookies
• Bypasses HttpOnly cookie protection

- TRACK: Microsoft proprietary variant of TRACE (same vulnerability) - CONNECT: Used for HTTP tunneling (proxy abuse)

• Only needed for proxy servers
• Can be used to bypass firewalls
• Can create unauthorized tunnels

Allowed methods (safe for web APIs): - GET: Read resources (idempotent, safe) - POST: Create resources (not idempotent) - PUT: Update resources (idempotent) - PATCH: Partial update (not idempotent) - DELETE: Remove resources (idempotent) - OPTIONS: CORS preflight (required for browser APIs) - HEAD: Metadata only (idempotent, safe)

Thread Safety: Safe for concurrent use. No shared state between requests.

Usage:

// Whitelist safe methods (recommended)
router.Use(middleware.AllowedHTTPMethods())

// Blacklist dangerous methods (additional protection)
router.Use(middleware.DisallowedHTTPMethods())

// Defense in depth (use both)
router.Use(middleware.AllowedHTTPMethods())
router.Use(middleware.DisallowedHTTPMethods())

Package middleware provides HTTP middleware for the StreamSpace API. This file implements organization context extraction and enforcement for multi-tenancy.

SECURITY: This middleware is CRITICAL for preventing cross-tenant data access. All protected routes MUST use this middleware to ensure org_id is available in the request context for database query filtering.

Multi-Tenancy Architecture:

• Each user belongs to exactly one organization (org_id)
• org_id is embedded in JWT claims during authentication
• This middleware extracts org_id from JWT and adds to request context
• All handlers MUST use GetOrgID() to filter database queries
• Requests without valid org_id are rejected with 401 Unauthorized

Context Keys:

• "org_id": Organization ID (string)
• "org_name": Organization display name (string)
• "k8s_namespace": Kubernetes namespace for this org (string)
• "org_role": User's role within the org (string)
• "user_id": User's unique ID (string)
• "username": User's username (string)
• "role": User's system-wide role (string)

Usage:

// Apply middleware to protected routes
protected := router.Group("/api/v1")
protected.Use(middleware.OrgContextMiddleware(jwtManager))

// In handler, extract org_id for filtering
func MyHandler(c *gin.Context) {
    orgID, err := middleware.GetOrgID(c)
    if err != nil {
        c.JSON(401, gin.H{"error": "unauthorized"})
        return
    }
    // Use orgID to filter database queries
    sessions, err := db.ListSessionsByOrg(ctx, orgID)
}

Package middleware - quota.go ¶

This file implements resource quota enforcement at the API level.

The quota middleware provides the HTTP layer integration for StreamSpace's resource quota system, preventing users from exceeding their allocated CPU, memory, GPU, and session limits.

Why Quota Enforcement is Critical ¶

Without quotas, a single user could:

• Consume all cluster resources (DoS to other users)
• Launch hundreds of sessions (resource exhaustion)
• Request unlimited CPU/memory (cluster instability)
• Exceed billing limits (cost overruns)

Multi-Layered Quota Enforcement ¶

StreamSpace enforces quotas at multiple levels for defense in depth:

┌─────────────────────────────────────────────────────────┐
│  Level 1: API Middleware (This File)                   │
│  - Fast rejection before DB writes                     │
│  - HTTP 402 (Payment Required) response                │
│  - User-friendly error messages                        │
└──────────────────────┬──────────────────────────────────┘
                       │ Passed
                       ▼
┌─────────────────────────────────────────────────────────┐
│  Level 2: API Handlers (handlers/sessions.go)          │
│  - Business logic validation                           │
│  - Current usage calculation                           │
│  - Quota check with enforcer                           │
└──────────────────────┬──────────────────────────────────┘
                       │ Passed
                       ▼
┌─────────────────────────────────────────────────────────┐
│  Level 3: Kubernetes Controller                        │
│  - Admission webhook validation (future)               │
│  - Pod resource limits enforcement                     │
│  - Node resource availability check                    │
└─────────────────────────────────────────────────────────┘

Quota Types Enforced ¶

**Per-User Limits**:

• MaxSessions: Maximum concurrent sessions (e.g., 10)
• MaxCPU: Total CPU across all sessions (e.g., 16 cores)
• MaxMemory: Total memory across all sessions (e.g., 64 GB)
• MaxGPU: Number of GPU devices (e.g., 2)
• MaxStorage: Home directory size (e.g., 100 GB)

**Per-Session Limits**:

• MaxCPUPerSession: CPU per session (e.g., 8 cores)
• MaxMemoryPerSession: Memory per session (e.g., 32 GB)

Integration with Quota Enforcer ¶

This middleware is a thin wrapper around quota.Enforcer:

• Enforcer contains the core quota logic
• Enforcer queries database for user limits
• Enforcer calculates current resource usage
• Enforcer performs quota math and validation

This middleware just:

1. Extracts username from auth context
2. Injects enforcer into request context
3. Provides helper functions for handlers

Error Response Format ¶

When quota is exceeded, return HTTP 402 (Payment Required):

{
  "error": "quota_exceeded",
  "message": "CPU quota exceeded: requested 4000m, limit 8000m, current usage 5000m",
  "quota": {
    "limit": "8000m",
    "current": "5000m",
    "requested": "4000m",
    "available": "3000m"
  }
}

Usage Pattern ¶

Middleware is applied globally, enforcement is selective:

// In main.go
quotaMiddleware := middleware.NewQuotaMiddleware(enforcer)
router.Use(quotaMiddleware.Middleware())

// In session creation handler
err := middleware.EnforceSessionCreation(c, cpu, memory, gpu, currentUsage)
if err != nil {
    c.JSON(402, gin.H{"error": err.Error()})
    return
}

Known Limitations ¶

1. **Race conditions**: Two concurrent requests might both pass quota check - Solution: Database-level locking in enforcer
2. **Stale usage data**: Usage is cached briefly for performance - Solution: Short cache TTL (5 seconds) in enforcer
3. **No GPU accounting yet**: GPU quota exists but usage tracking incomplete - Solution: Implement GPU usage tracking in controller

See also:

• api/internal/quota/enforcer.go: Core quota enforcement logic
• api/internal/handlers/sessions.go: Session creation with quota checks
• controller/internal/controllers/session_controller.go: Resource limit enforcement

Package middleware provides HTTP middleware for the StreamSpace API. This file implements rate limiting to prevent brute force and DoS attacks.

SECURITY ENHANCEMENT (2025-11-14): Added in-memory rate limiting for MFA verification to prevent brute force attacks.

Rate limiting is critical for security: - MFA codes are only 6 digits (1 million combinations) - Without rate limiting, codes can be brute forced in minutes - With 5 attempts/minute limit, brute force takes ~160 days

Current Implementation: In-Memory (Development/Single-Server) - Fast: No network round-trips - Simple: No external dependencies - Limitations: Not distributed (doesn't work across multiple API servers)

Production Recommendation: Redis-Backed Rate Limiting - Distributed: Works across multiple API servers - Persistent: Survives API server restarts - Scalable: Handles millions of concurrent rate limit entries

Usage:

// In handler
limiter := middleware.GetRateLimiter()
if !limiter.CheckLimit("user:123:mfa", 5, 1*time.Minute) {
  return errors.New("rate limit exceeded")
}

Package middleware provides HTTP middleware for the StreamSpace API. This file implements request ID generation and correlation.

Purpose: The request ID middleware provides unique identifiers for each HTTP request, enabling distributed tracing, log correlation, and debugging across multiple services and components. This is essential for troubleshooting issues in production environments.

Implementation Details: - Generates UUIDv4 for each request (or accepts existing from client) - Stores in Gin context for handlers to access - Adds to response header (X-Request-ID) so clients can reference - Enables correlation across logs, metrics, and traces - Idempotent: Preserves existing request ID from upstream services

Use Cases: 1. Distributed Tracing: Follow a request across multiple microservices

• API Gateway → StreamSpace API → Kubernetes Controller → Database
• All logs share the same request ID for easy correlation

2. Log Correlation: Find all log entries for a specific request

• User reports error at 10:35:42 AM
• Search logs for request ID from error response
• View complete request lifecycle (auth, validation, processing, error)

3. Customer Support: Users can provide request ID when reporting issues

• Error message shows: "Request ID: 550e8400-e29b-41d4-a716-446655440000"
• Support team searches logs with this ID
• Full context available for debugging

4. Performance Analysis: Track slow requests end-to-end

• Identify which service/component caused the delay
• Compare timing across different layers

Thread Safety: Safe for concurrent use. Each request gets its own unique UUID.

Usage:

// Add to middleware chain (should be first for complete tracing)
router.Use(middleware.RequestID())

// Access in handlers
func MyHandler(c *gin.Context) {
    requestID := middleware.GetRequestID(c)
    log.Printf("[%s] Processing request", requestID)
}

// Client can send existing request ID for distributed tracing
// curl -H "X-Request-ID: my-trace-id" https://api.streamspace.io/sessions

Package middleware - securityheaders.go ¶

This file implements comprehensive HTTP security headers.

Security headers are the first line of defense against common web attacks. They instruct browsers how to handle content, preventing XSS, clickjacking, MITM attacks, and other security vulnerabilities.

Why Security Headers are Critical ¶

**Without security headers**, StreamSpace would be vulnerable to:

• XSS (Cross-Site Scripting): Injected scripts steal user data
• Clickjacking: UI redress attacks trick users into clicking malicious links
• MITM (Man-in-the-Middle): Unencrypted connections can be intercepted
• MIME sniffing: Browser misinterprets content type, executes malicious code
• Information leakage: Server version exposed to attackers

**With security headers**, browsers enforce:

• HTTPS-only connections (HSTS)
• No inline scripts/styles (CSP with nonces)
• No framing by other sites (X-Frame-Options)
• Correct content type interpretation (X-Content-Type-Options)
• Disabled dangerous browser features (Permissions-Policy)

Security Headers Scorecard ¶

This implementation provides A+ rating on:

• Mozilla Observatory
• SecurityHeaders.com
• Qualys SSL Labs

Architecture: Defense in Depth ¶

┌─────────────────────────────────────────────────────────┐
│  Browser                                                │
│  - Enforces all security policies                       │
│  - Blocks violations before execution                   │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTPS (enforced by HSTS)
                       ▼
┌─────────────────────────────────────────────────────────┐
│  Load Balancer / Ingress                                │
│  - TLS termination                                      │
│  - Certificate management                               │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  Security Headers Middleware (This File)               │
│  1. Generate nonce for this request                    │
│  2. Add all security headers to response                │
│  3. Pass nonce to templates via context                 │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  Application Handlers                                   │
│  - Use nonce in script/style tags                       │
│  - <script nonce="{{.csp_nonce}}">...</script>          │
└─────────────────────────────────────────────────────────┘

CSP Nonce-Based XSS Protection ¶

**Traditional CSP** (unsafe, deprecated):

	Content-Security-Policy: script-src 'self' 'unsafe-inline' 'unsafe-eval'

  - 'unsafe-inline': Allows ALL inline scripts (attacker can inject!)
  - 'unsafe-eval': Allows eval() (dangerous, can execute arbitrary code)
  - Rating: F (no real protection)

**Modern CSP with Nonces** (secure, current implementation):

	Content-Security-Policy: script-src 'self' 'nonce-xyz123'

  - Only scripts with matching nonce attribute can execute
  - Nonce changes on every request (unpredictable)
  - Attacker can't inject valid nonce (CSP blocks execution)
  - Rating: A+ (strong XSS protection)

How Nonces Work ¶

**Server-side** (this middleware):

1. Generate random nonce: "abc123def456"
2. Add to CSP header: script-src 'nonce-abc123def456'
3. Store in context: c.Set("csp_nonce", "abc123def456")

**Template rendering**:

<script nonce="{{.csp_nonce}}">
    console.log("This script is allowed");
</script>

**Browser behavior**:

• Allowed: <script nonce="abc123def456">alert('ok')</script>
• Blocked: <script>alert('injected!')</script> (no nonce)
• Blocked: <script nonce="wrong">alert('bad')</script> (wrong nonce)

Security Headers Reference ¶

**1. Strict-Transport-Security (HSTS)**:

• Forces HTTPS for 1 year
• Includes all subdomains
• Eligible for browser preload list
• Protects against: SSL stripping, MITM attacks

**2. X-Content-Type-Options**:

• Prevents MIME type sniffing
• Forces browser to respect declared content type
• Protects against: Polyglot files, content confusion

**3. X-Frame-Options**:

• Prevents clickjacking attacks
• Denies embedding in iframes
• Protects against: UI redress, iframe overlay attacks

**4. X-XSS-Protection**:

• Legacy XSS filter for old browsers
• Modern browsers use CSP instead
• Backwards compatibility only

**5. Content-Security-Policy (CSP)**:

• Whitelists allowed content sources
• Nonce-based inline script/style allowance
• Blocks all other inline content
• Protects against: XSS, code injection, data exfiltration

**6. Referrer-Policy**:

• Controls referrer information sent to other sites
• Prevents leaking sensitive URLs
• Protects against: Information disclosure

**7. Permissions-Policy**:

• Disables dangerous browser features
• Prevents unauthorized geolocation, camera, mic access
• Protects against: Feature abuse, privacy violations

**8. X-Permitted-Cross-Domain-Policies**:

• Prevents Adobe Flash/PDF content loading
• Legacy protection (Flash deprecated)
• Backwards compatibility

**9. X-Download-Options**:

• Prevents IE from executing downloads in site context
• Legacy protection for old IE versions
• Backwards compatibility

**10. Cache-Control**:

• Prevents caching of sensitive API responses
• Ensures fresh data on every request
• Protects against: Stale data, information disclosure

Production vs Development Headers ¶

**Production** (SecurityHeaders):

• Strict CSP with nonces
• No inline scripts/styles without nonces
• HSTS with preload
• Rating: A+

**Development** (SecurityHeadersRelaxed):

• Relaxed CSP (unsafe-inline, unsafe-eval allowed)
• Same-origin framing allowed
• No HSTS preload
• Rating: C (convenient for development)

Known Limitations ¶

1. **CSP nonce requires template support**: Apps not using templates can't use nonces - Solution: Hash-based CSP or external JS files only
2. **HSTS can lock out misconfigured sites**: Once enabled, hard to disable - Solution: Start with short max-age, increase gradually
3. **Permissions-Policy may break legitimate features**: Too restrictive - Solution: Enable features selectively per route
4. **No CSP reporting**: Violations not logged - Solution: Add report-uri directive (future)

See also:

• https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
• https://observatory.mozilla.org/
• https://securityheaders.com/

Package middleware provides HTTP middleware for the StreamSpace API. This file implements enhanced session security with idle timeout and concurrency limits.

Purpose: The session management middleware provides security features for user authentication sessions including automatic logout after inactivity and enforcement of concurrent session limits to prevent credential sharing and session hijacking.

Implementation Details: - Idle timeout: Automatically invalidates sessions after period of inactivity - Activity tracking: Updates last activity timestamp on every authenticated request - Concurrent sessions: Limits number of simultaneous logins per user account - Memory cleanup: Periodic background cleanup prevents memory leaks - In-memory storage: Fast but not distributed (single-server only)

Security Notes: This middleware addresses critical security concerns:

1. Idle Timeout (Prevents Session Hijacking):

• User forgets to log out on public computer
• Without timeout: Session stays active indefinitely (attacker can use it)
• With timeout: Session expires after 30 minutes of inactivity

2. Concurrent Session Limits (Prevents Credential Sharing):

• User shares login credentials with colleagues
• Without limit: Unlimited concurrent sessions (credential abuse)
• With limit: Max 5 concurrent sessions (discourages sharing)

3. Session Cleanup (Prevents Memory Leaks):

• Long-running server accumulates millions of session entries
• Without cleanup: Memory usage grows unbounded (eventual crash)
• With cleanup: Stale sessions removed every 5 minutes

Thread Safety: Safe for concurrent use. Uses sync.RWMutex for thread-safe access to session maps.

Usage:

// Create session manager with 30-minute idle timeout and max 5 concurrent sessions
sessionMgr := middleware.NewSessionManager(30*time.Minute, 5)

// Apply idle timeout check to all authenticated routes
router.Use(sessionMgr.IdleTimeoutMiddleware())

// Track session activity on every request
router.Use(sessionMgr.SessionActivityMiddleware())

// In login handler, register new session
if err := sessionMgr.RegisterSession(username, sessionID); err != nil {
    // Max sessions exceeded
    return c.JSON(403, gin.H{"error": "Maximum concurrent sessions reached"})
}

// In logout handler, unregister session
sessionMgr.UnregisterSession(username, sessionID)

Configuration:

idleTimeout: 30*time.Minute    // Session expires after 30 min inactivity
maxSessions: 5                  // Max 5 concurrent logins per user
cleanupInterval: 5*time.Minute  // Cleanup runs every 5 minutes

Package middleware provides HTTP middleware for the StreamSpace API. This file implements request size limiting to prevent DoS attacks.

SECURITY ENHANCEMENT (2025-11-14): Added request size limits to prevent denial of service via oversized payloads.

Why Request Size Limits are Critical: - Prevents memory exhaustion from giant JSON payloads - Prevents disk exhaustion from huge file uploads - Prevents slow-loris attacks with endless request bodies - Forces attackers to use many small requests (easier to detect/rate-limit)

Implementation: - Uses http.MaxBytesReader for hard limits (prevents buffer overflow) - Checks Content-Length header before processing (fail fast) - Skips for GET/HEAD/OPTIONS (no request body) - Returns 413 Payload Too Large with informative error message

Limits: - Default request body: 10MB (general API endpoints) - JSON payloads: 5MB (structured data) - File uploads: 50MB (larger files like logs, exports)

Package middleware provides HTTP middleware for the StreamSpace API. This file implements structured request logging.

Purpose: The structured logger middleware captures detailed information about every HTTP request in a consistent, machine-parseable format. This enables log analysis, alerting, debugging, and observability in production environments.

Implementation Details: - Structured format: Key-value pairs instead of unstructured text - Request correlation: Includes request ID for distributed tracing - User tracking: Logs authenticated user information when available - Performance metrics: Captures request duration in milliseconds - Error tracking: Logs Gin errors if any occurred during request processing - Configurable skipping: Can skip health check endpoints to reduce noise

Logged Fields: - request_id: Correlation ID for distributed tracing (from RequestID middleware) - method: HTTP method (GET, POST, PUT, DELETE, etc.) - path: Request path (/api/v1/sessions) - query: Query string parameters (if enabled) - status: HTTP status code (200, 404, 500, etc.) - duration: Request processing time (human-readable: "125ms") - duration_ms: Request processing time in milliseconds (for metrics: 125) - client_ip: Client IP address - user_agent: Browser/client user agent string - user_id: Authenticated user ID (if authenticated) - username: Authenticated username (if authenticated) - errors: Concatenated error messages (if any errors occurred)

Log Levels: - INFO: Successful requests (2xx status codes) - WARN: Client errors (4xx status codes) - ERROR: Server errors (5xx status codes)

Thread Safety: Safe for concurrent use. Each request logs independently.

Usage:

// Basic structured logging
router.Use(middleware.StructuredLogger())

// Custom configuration
config := middleware.DefaultStructuredLoggerConfig()
config.SkipHealthCheck = true  // Don't log /health endpoint
config.LogQuery = false         // Don't log query parameters (privacy)
router.Use(middleware.StructuredLoggerWithConfigFunc(config))

Configuration:

SkipPaths: []string{}           // Paths to skip (e.g., ["/metrics", "/health"])
SkipHealthCheck: true            // Skip /health and /api/v1/health endpoints
LogQuery: true                   // Log query parameters
LogUserAgent: true               // Log user agent string

Package middleware provides HTTP middleware for the StreamSpace API. This file implements team-based role-based access control (RBAC).

Purpose: The team RBAC middleware provides fine-grained access control for multi-tenant StreamSpace deployments where users belong to teams/groups and have different permission levels within each team. This enables enterprise features like shared sessions, team resource quotas, and delegated administration.

Implementation Details: - Database-backed permissions: Roles and permissions stored in PostgreSQL - Per-team roles: Users can have different roles in different teams - Permission-based checks: Middleware validates specific permissions (not just roles) - Session-level access: Can check if user can access sessions owned by team - Hierarchical model: Teams → Users → Roles → Permissions

Permission Model:

1. Teams (groups table):

• Organizations or departments
• Example: "Engineering", "Sales", "Data Science"

2. Team Memberships (group_memberships table):

• Links users to teams with specific roles
• Example: alice@example.com is "admin" in Engineering team

3. Roles (team_role_permissions table):

• Named permission sets
• Example: "admin", "member", "viewer"

4. Permissions:

• Fine-grained capabilities
• Example: "sessions.create", "sessions.delete", "team.manage"

Common Permissions: - sessions.view: View team sessions - sessions.create: Create sessions for team - sessions.delete: Delete team sessions - sessions.share: Share sessions with team members - team.manage: Add/remove team members - team.billing: View/manage team billing

Security Notes: This middleware enforces the principle of least privilege: - Users only have access to their own sessions OR team sessions where they have permission - Team admins can manage team resources but not other teams - Platform admins have global permissions across all teams

Thread Safety: Safe for concurrent use. Database queries are isolated per request.

Usage:

// Create team RBAC middleware
teamRBAC := middleware.NewTeamRBAC(database)

// Require specific team permission
router.POST("/api/teams/:teamId/sessions",
    teamRBAC.RequireTeamPermission("sessions.create"),
    handlers.CreateTeamSession,
)

// Require session access (owner OR team member with permission)
router.GET("/api/sessions/:id",
    teamRBAC.RequireSessionAccess("sessions.view"),
    handlers.GetSession,
)

// Check permissions manually in handler
hasPermission, err := teamRBAC.CheckTeamPermission(ctx, userID, teamID, "sessions.delete")
if !hasPermission {
    return c.JSON(403, gin.H{"error": "Insufficient permissions"})
}

Package middleware provides HTTP middleware for the StreamSpace API. This file implements request timeout enforcement.

Purpose: The timeout middleware protects the API server from slow clients and long-running operations that could exhaust server resources. It enforces maximum request duration limits and returns 408 Request Timeout if the limit is exceeded.

Implementation Details: - Uses Go context.WithTimeout for cancellation propagation - Runs handler in goroutine to detect timeout vs completion - Configurable timeout duration per route (via excluded paths) - Automatic exclusions for long-running operations (WebSocket, uploads) - Graceful cleanup: context cancellation signals handlers to abort

Security Notes: This middleware prevents several attack vectors:

1. Slowloris Attack:

• Attacker sends HTTP headers very slowly (1 byte per minute)
• Without timeout: Connections stay open indefinitely (resource exhaustion)
• With timeout: Connection closed after 30 seconds

2. Denial of Service (Resource Exhaustion):

• Attacker triggers expensive database queries or computations
• Without timeout: Server CPU/memory consumed until crash
• With timeout: Operation aborted after limit, resources freed

3. Accidental Long Operations:

• Bug causes infinite loop or extremely slow query
• Without timeout: Server hangs indefinitely
• With timeout: Request fails quickly, server recovers

Performance Characteristics: - Overhead: <1ms per request (goroutine spawn + channel operations) - Memory: ~4KB per request (goroutine stack + channel) - Cleanup: Automatic via defer and context cancellation

Thread Safety: Safe for concurrent use. Each request has its own timeout context.

Usage:

// Use default 30-second timeout
config := middleware.DefaultTimeoutConfig()
router.Use(middleware.Timeout(config))

// Custom timeout duration
router.Use(middleware.TimeoutWithDuration(60*time.Second))

// Exclude specific paths (long-running operations)
config := middleware.TimeoutConfig{
    Timeout: 30*time.Second,
    ExcludedPaths: []string{
        "/api/v1/ws/",      // WebSocket connections
        "/api/v1/upload",   // File uploads
        "/api/v1/export",   // Data exports (can be slow)
    },
}
router.Use(middleware.Timeout(config))

Configuration:

Timeout: 30*time.Second        // Maximum request duration
ErrorMessage: "Request timeout" // Error message returned to client
ExcludedPaths: []string{...}   // Paths to skip timeout enforcement

Package middleware provides HTTP middleware for the StreamSpace API. This file implements webhook authentication using HMAC-SHA256 signatures.

Purpose: The webhook authentication middleware validates that incoming webhook requests are genuinely from authorized sources by verifying cryptographic signatures. This prevents unauthorized parties from triggering webhook endpoints and injecting malicious data.

Implementation Details: - HMAC-SHA256: Industry-standard message authentication algorithm - Secret-based signing: Shared secret between sender and receiver - Hex-encoded signatures: URL-safe, easy to debug - Constant-time comparison: Prevents timing attacks - Header-based delivery: Signature sent in X-Webhook-Signature header

Security Notes: Without webhook authentication, attackers could: 1. Trigger automated actions (e.g., send notifications, create resources) 2. Inject malicious payloads (e.g., XSS in notification messages) 3. Cause denial of service (e.g., flood system with fake events) 4. Impersonate legitimate webhook sources (e.g., GitHub, Stripe, Slack)

HMAC-SHA256 prevents these attacks: - Only parties with the secret can create valid signatures - Signatures are deterministic (same payload + secret = same signature) - Cannot forge signatures without knowing the secret - Constant-time comparison prevents timing attacks

How It Works: 1. Sender (e.g., GitHub) computes HMAC-SHA256 of request body using secret 2. Sender includes signature in X-Webhook-Signature header 3. Receiver (StreamSpace) reads request body 4. Receiver computes expected signature using same secret 5. Receiver compares signatures using constant-time comparison 6. If match: Request is authentic, proceed 7. If mismatch: Request is invalid or tampered, reject with 401

Signature Format:

X-Webhook-Signature: <hex-encoded-hmac-sha256>
Example: "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"

Thread Safety: Safe for concurrent use. HMAC computation is stateless.

Usage:

// Create webhook auth with secret
webhookAuth := middleware.NewWebhookAuth("your-secret-key-here")

// Apply to webhook endpoints
router.POST("/api/webhooks/github",
    webhookAuth.Middleware(),
    handlers.HandleGitHubWebhook,
)

// Generate signature for testing (sender side)
payload := []byte(`{"event": "push", "repo": "streamspace"}`)
signature := webhookAuth.Sign(payload)
// Send as: curl -H "X-Webhook-Signature: $signature" -d "$payload" /api/webhooks

Configuration:

secret: Shared secret between sender and receiver (keep confidential!)
Recommended: Generate with: openssl rand -hex 32