linearvoid/SECURITY.md

Security Guide

This document summarizes security controls and best practices for Linear Void.

Security Model Overview

Security is layered across:

• Cloudflare edge
• nginx reverse proxy
• chat/admin backend
• container and host operations

Authentication and Sessions

Admin access is session-cookie based.

• Login endpoint: /api/admin/login
• Session endpoint: /api/admin/session
• Logout endpoint: /api/admin/logout
• Cookie: linearvoid_admin_session
• Cookie flags: HttpOnly, SameSite=Strict, Secure over HTTPS
• Session expiry enforced server-side

Best practices:

• Set strong ADMIN_USERNAME and ADMIN_PASSWORD values.
• Rotate admin credentials periodically.
• Keep ADMIN_SESSION_TTL_HOURS aligned with operational policy.

Transport Security

• Enforce HTTPS for app/admin endpoints.
• Use WSS for chat WebSocket.
• Keep Cloudflare TLS mode strict and valid at origin.

Reverse Proxy Controls

nginx controls include:

• auth_request guard for /admin and /api/admin paths
• dedicated unauthorized behavior for admin API responses
• explicit websocket upgrade headers for /ws
• upload body-size limits for resumable media chunk uploads

Best practices:

• Keep proxy body-size and timeout settings aligned across all proxy layers.
• Avoid exposing backend service ports publicly unless required.

Input Validation and Upload Safety

Server-side protections include:

• extension allow-list for media uploads
• MIME checks
• file-size ceiling (2GB)
• resumable chunk bounds and chunk-index validation
• media path safety checks on delete

Best practices:

• Keep upload chunk size bounded.
• Reject unsupported content types consistently.
• Monitor 4xx/5xx rates on upload routes.

Rate Limiting and Abuse Controls

• Chat rate limiting uses Redis INCR + EXPIRE windows.
• Current baseline: more than 10 messages in 10 seconds is throttled.
• Moderation actions are logged for auditability.

Best practices:

• Tune thresholds by observed abuse patterns.
• Keep moderation logs reviewed and retained per policy.

Infrastructure and Secrets

• Store secrets in .env (not in committed source).
• Use Gitea Actions secrets for CI/CD credentials and admin credentials.
• Restrict Docker host control plane exposure.
• Limit who can read deployment environment files.

Cloudflare and Edge Security

Recommended baseline:

• WAF enabled
• Rate limits on sensitive paths
• Bot protection where appropriate
• Cache rules scoped carefully to avoid caching private/control-plane content

Data Protection and Retention

• Persistent data: postgres, redis append-only, chat state, playlist/media metadata
• Backup and restore drills should be periodic
• Restore procedures should be tested in isolated environments

Logging and Monitoring for Security

Track and alert on:

• repeated failed admin login attempts
• spikes in 401 and 403 responses
• sudden upload errors (413/400/500 patterns)
• unusual websocket disconnect or message-rate anomalies

Hardening Checklist

• HTTPS/WSS enforced end-to-end
• Strong admin credentials configured
• Secrets only in env/secrets stores
• Proxy auth and websocket headers validated
• Upload limits and validation active
• Rate limiting active and tested
• Cloudflare WAF/rate-limit rules active
• Backup/restore drills completed
• Security-related monitoring alerts routed

Incident Response Baseline

1. Detect issue (alerts/logs/user reports).
2. Triage scope (edge, proxy, app, data plane).
3. Contain impact (rate limit, credential rotate, route disable).
4. Recover services and verify health.
5. Record timeline and corrective actions.