Refactor code structure for improved readability and maintainability

SECURITY.md

@@ -0,0 +1,127 @@
+# 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.