From ddaf3c6cee54eb229e6cccf2d597cd44fcb30067 Mon Sep 17 00:00:00 2001 From: "Gan, Jimmy" Date: Sun, 3 May 2026 13:31:25 +0800 Subject: [PATCH] =?UTF-8?q?security:=20Sprint=2000=20=E2=80=94=20critical?= =?UTF-8?q?=20security=20fixes=20(OPC=20WS=20auth,=20Transmission=20creds,?= =?UTF-8?q?=20SECRET=5FKEY,=20passkey=20rate=20limit)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add JWT token auth to OPC WebSocket (unauthenticated → 403, per-user tracking) - Externalize Transmission RPC credentials to TRANSMISSION_USER/PASS env vars - Remove hardcoded SECRET_KEY fallback from dev compose - Rate-limit passkey register options endpoint at 5/minute - Add PDD (docs/improvement-plan.md) and sprint specs (specs/) Co-Authored-By: Claude Opus 4.7 --- dashboard/backend/config.py | 7 + dashboard/backend/routers/opc_ws.py | 37 +-- dashboard/backend/routers/passkey.py | 3 +- dashboard/backend/routers/transmission.py | 10 +- dashboard/backend/tests/conftest.py | 4 + dashboard/docker-compose.dev.yml | 4 +- dashboard/docker-compose.yml | 2 + dashboard/frontend/src/lib/opc-ws.js | 6 +- docs/improvement-plan.md | 261 ++++++++++++++++++++++ specs/sprint-00-critical-security.md | 70 ++++++ specs/sprint-01-production-stability.md | 82 +++++++ specs/sprint-02-auth-hardening.md | 122 ++++++++++ specs/sprint-03-config-externalization.md | 93 ++++++++ specs/sprint-04-ci-cd-reliability.md | 100 +++++++++ specs/sprint-05-operations-resilience.md | 96 ++++++++ specs/sprint-06-code-quality.md | 111 +++++++++ 16 files changed, 987 insertions(+), 21 deletions(-) create mode 100644 docs/improvement-plan.md create mode 100644 specs/sprint-00-critical-security.md create mode 100644 specs/sprint-01-production-stability.md create mode 100644 specs/sprint-02-auth-hardening.md create mode 100644 specs/sprint-03-config-externalization.md create mode 100644 specs/sprint-04-ci-cd-reliability.md create mode 100644 specs/sprint-05-operations-resilience.md create mode 100644 specs/sprint-06-code-quality.md diff --git a/dashboard/backend/config.py b/dashboard/backend/config.py index 967b35b..f4211c6 100644 --- a/dashboard/backend/config.py +++ b/dashboard/backend/config.py @@ -70,6 +70,13 @@ CC_CONNECT_URL = os.environ.get("CC_CONNECT_URL", "") # OpenClaw OPENCLAW_GATEWAY_TOKEN = os.environ.get("OPENCLAW_GATEWAY_TOKEN", "") +# Transmission RPC +TRANSMISSION_URL = os.environ.get("TRANSMISSION_URL", "http://host.docker.internal:9091/transmission/rpc") +TRANSMISSION_USER = os.environ.get("TRANSMISSION_USER", "") +TRANSMISSION_PASS = os.environ.get("TRANSMISSION_PASS", "") +if not TRANSMISSION_USER or not TRANSMISSION_PASS: + raise RuntimeError("TRANSMISSION_USER and TRANSMISSION_PASS must be set") + # Networking configs LAN_IP_RANGES = os.environ.get("LAN_IP_RANGES", "192.168.31.0/24").split(",") TRUSTED_PROXIES = os.environ.get("TRUSTED_PROXIES", "127.0.0.1,::1,172.21.0.1").split(",") diff --git a/dashboard/backend/routers/opc_ws.py b/dashboard/backend/routers/opc_ws.py index 023f265..5f51b6f 100644 --- a/dashboard/backend/routers/opc_ws.py +++ b/dashboard/backend/routers/opc_ws.py @@ -6,15 +6,14 @@ import logging from datetime import datetime from typing import Any -from fastapi import APIRouter, WebSocket, WebSocketDisconnect +from fastapi import APIRouter, HTTPException, Query, WebSocket, WebSocketDisconnect, status + +import auth_service as auth logger = logging.getLogger(__name__) router = APIRouter() -# Active WebSocket connections -active_connections: set[WebSocket] = set() - def serialize_datetime(obj: Any) -> Any: """Recursively serialize datetime objects to ISO format strings""" @@ -29,21 +28,21 @@ def serialize_datetime(obj: Any) -> Any: class ConnectionManager: - """Manages WebSocket connections""" + """Manages WebSocket connections with per-user tracking""" def __init__(self): - self.active_connections: set[WebSocket] = set() + self.active_connections: dict[WebSocket, str] = {} - async def connect(self, websocket: WebSocket): + async def connect(self, websocket: WebSocket, username: str): """Accept and register a new connection""" await websocket.accept() - self.active_connections.add(websocket) - logger.info(f"WebSocket connected. Total connections: {len(self.active_connections)}") + self.active_connections[websocket] = username + logger.info(f"WebSocket connected: {username}. Total connections: {len(self.active_connections)}") def disconnect(self, websocket: WebSocket): """Remove a connection""" - self.active_connections.discard(websocket) - logger.info(f"WebSocket disconnected. Total connections: {len(self.active_connections)}") + username = self.active_connections.pop(websocket, "unknown") + logger.info(f"WebSocket disconnected: {username}. Total connections: {len(self.active_connections)}") async def broadcast(self, message: dict): """Broadcast message to all connected clients""" @@ -64,9 +63,19 @@ manager = ConnectionManager() @router.websocket("/ws") -async def websocket_endpoint(websocket: WebSocket): - """WebSocket endpoint for OPC real-time updates""" - await manager.connect(websocket) +async def websocket_endpoint(websocket: WebSocket, token: str = Query(None)): + """WebSocket endpoint for OPC real-time updates. Requires JWT token via ?token= query param.""" + if not token: + await websocket.close(code=status.WS_1008_POLICY_VIOLATION, reason="Missing authentication token") + return + + try: + user = auth.user_from_access_token(token, include_auth_header=False) + except HTTPException: + await websocket.close(code=status.WS_1008_POLICY_VIOLATION, reason="Invalid authentication token") + return + + await manager.connect(websocket, user.username) try: while True: diff --git a/dashboard/backend/routers/passkey.py b/dashboard/backend/routers/passkey.py index 89343c7..332992d 100644 --- a/dashboard/backend/routers/passkey.py +++ b/dashboard/backend/routers/passkey.py @@ -56,7 +56,8 @@ def _get_challenge(client_data_b64: str) -> bytes: @router.post("/passkey/register/options") -async def passkey_register_options(current_user=Depends(auth.get_current_user)): +@limiter.limit("5/minute") +async def passkey_register_options(request: Request, current_user=Depends(auth.get_current_user)): """Generate WebAuthn registration options for adding a new passkey.""" existing = auth.load_passkey_credentials() exclude = [PublicKeyCredentialDescriptor(id=base64url_to_bytes(c["credential_id"])) for c in existing] diff --git a/dashboard/backend/routers/transmission.py b/dashboard/backend/routers/transmission.py index e8baf10..74c2d9b 100644 --- a/dashboard/backend/routers/transmission.py +++ b/dashboard/backend/routers/transmission.py @@ -4,6 +4,8 @@ from typing import Any, Dict, List import httpx from fastapi import APIRouter, HTTPException +import config + router = APIRouter(prefix="/api/transmission", tags=["transmission"]) @@ -12,8 +14,8 @@ def get_session_id() -> str: try: with httpx.Client(timeout=5.0) as client: response = client.get( - "http://host.docker.internal:9091/transmission/rpc", - auth=("admin", "admin") + config.TRANSMISSION_URL, + auth=(config.TRANSMISSION_USER, config.TRANSMISSION_PASS) ) session_id = response.headers.get("X-Transmission-Session-Id") if not session_id: @@ -35,9 +37,9 @@ def transmission_rpc(method: str, arguments: Dict[str, Any] = None) -> Dict[str, # Use httpx to make the request with httpx.Client(timeout=10.0) as client: response = client.post( - "http://host.docker.internal:9091/transmission/rpc", + config.TRANSMISSION_URL, json=payload, - auth=("admin", "admin"), + auth=(config.TRANSMISSION_USER, config.TRANSMISSION_PASS), headers={"X-Transmission-Session-Id": session_id} ) diff --git a/dashboard/backend/tests/conftest.py b/dashboard/backend/tests/conftest.py index da3c87c..55b72ed 100644 --- a/dashboard/backend/tests/conftest.py +++ b/dashboard/backend/tests/conftest.py @@ -18,6 +18,8 @@ os.environ.setdefault("VOLUME_ROOT", "/tmp/test-volume") os.environ.setdefault("DOCKER_HOST", "tcp://mock-docker:2375") os.environ.setdefault("GITEA_URL", "http://mock-gitea:3000") os.environ.setdefault("GITEA_TOKEN", "mock-token") +os.environ.setdefault("TRANSMISSION_USER", "test-tx-user") +os.environ.setdefault("TRANSMISSION_PASS", "test-tx-pass") @pytest.fixture @@ -39,6 +41,8 @@ def mock_config(temp_volume_root, monkeypatch): monkeypatch.setenv("DOCKER_HOST", "tcp://mock-docker:2375") monkeypatch.setenv("GITEA_URL", "http://mock-gitea:3000") monkeypatch.setenv("GITEA_TOKEN", "mock-token") + monkeypatch.setenv("TRANSMISSION_USER", "test-tx-user") + monkeypatch.setenv("TRANSMISSION_PASS", "test-tx-pass") # Reload config module to pick up new env vars import importlib diff --git a/dashboard/docker-compose.dev.yml b/dashboard/docker-compose.dev.yml index 1bbdb56..4b77389 100644 --- a/dashboard/docker-compose.dev.yml +++ b/dashboard/docker-compose.dev.yml @@ -18,7 +18,7 @@ services: - CADDY_VPS_SSH_USER=ubuntu - MAC_SSH_HOST=192.168.31.22 - MAC_SSH_USER=jimmyg - - SECRET_KEY=${SECRET_KEY:-c0e8dcd74b2d70c596dfa03928f2582ca8d88af04896a82ee6c2aeeaa6bd6199} + - SECRET_KEY=${SECRET_KEY} - ADMIN_USER=jimmy - ADMIN_PASSWORD_HASH=${ADMIN_PASSWORD_HASH} - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN:-} @@ -31,6 +31,8 @@ services: - LITELLM_API_KEY=anything - LITELLM_HEALTH_API_KEY=${LITELLM_HEALTH_API_KEY:-} - GITEA_DB_PASSWORD=${GITEA_DB_PASSWORD} + - TRANSMISSION_USER=${TRANSMISSION_USER:-admin} + - TRANSMISSION_PASS=${TRANSMISSION_PASS:-admin} volumes: - /volume1:/volume1 - /volume1/docker/nas-dashboard/ssh/dashboard_terminal:/app/ssh/id_ed25519:ro diff --git a/dashboard/docker-compose.yml b/dashboard/docker-compose.yml index d0e0579..00bea3e 100644 --- a/dashboard/docker-compose.yml +++ b/dashboard/docker-compose.yml @@ -53,6 +53,8 @@ services: - LITELLM_HEALTH_API_KEY=${LITELLM_HEALTH_API_KEY:-} - LITELLM_URL=http://litellm:4005 - GITEA_DB_PASSWORD=${GITEA_DB_PASSWORD} + - TRANSMISSION_USER=${TRANSMISSION_USER} + - TRANSMISSION_PASS=${TRANSMISSION_PASS} volumes: - /volume1:/volume1 - /volume1/docker/nas-dashboard/ssh/dashboard_terminal:/app/ssh/id_ed25519:ro diff --git a/dashboard/frontend/src/lib/opc-ws.js b/dashboard/frontend/src/lib/opc-ws.js index 8d78f3a..b1102c7 100644 --- a/dashboard/frontend/src/lib/opc-ws.js +++ b/dashboard/frontend/src/lib/opc-ws.js @@ -2,6 +2,8 @@ * OPC WebSocket Client - Real-time updates */ +import { getToken } from "./api.js"; + let ws = null; let reconnectTimer = null; let listeners = new Set(); @@ -12,7 +14,9 @@ export function connect() { } const protocol = window.location.protocol === "https:" ? "wss:" : "ws:"; - const wsUrl = `${protocol}//${window.location.host}/ws/opc`; + const token = getToken(); + const tokenParam = token ? `?token=${encodeURIComponent(token)}` : ""; + const wsUrl = `${protocol}//${window.location.host}/ws/opc${tokenParam}`; ws = new WebSocket(wsUrl); diff --git a/docs/improvement-plan.md b/docs/improvement-plan.md new file mode 100644 index 0000000..a485cd0 --- /dev/null +++ b/docs/improvement-plan.md @@ -0,0 +1,261 @@ +# NAS Tools — Holistic Improvement Plan (PDD) + +> 37 prioritized issues from 4 deep-dive audits (CI/config, codebase structure, dashboard security, code quality) + the original 21-item plan. Duplicates consolidated, ranked by true priority. +> +> **Sprint specs:** `specs/sprint-*.md` — each with checkboxes, ACs, and exit criteria. + +--- + +## Priority 0 — Security: Immediate Hardening (this week) + +These are exploitable vulnerabilities, not architectural concerns. Fix them first. + +### P0.1 — OPC WebSocket has zero authentication +- **File:** `dashboard/backend/routers/opc_ws.py:66-84` +- **Problem:** `/ws/opc` accepts any connection without token, cookie, or credential of any kind. Once connected, clients receive real-time broadcasts of task updates, agent execution results, agent status changes, and internal data (`broadcast_task_update`, `broadcast_agent_execution`, `broadcast_agent_status`). +- **Fix:** Require a valid JWT token via query parameter or cookie on WebSocket connect (FastAPI/Starlette supports `Depends` on WebSocket endpoints). Reject unauthenticated connections with 403. +- **Also:** Add per-user connection tracking so broadcasts scope to authorized users only (`opc_ws.py:16` flat set of all connections). + +### P0.2 — Hardcoded Transmission credentials (`admin/admin`) +- **File:** `dashboard/backend/routers/transmission.py:17,41` +- **Problem:** `auth=("admin", "admin")` hardcoded in source. Anyone with network access to Transmission port 9091 can use these known credentials. +- **Fix:** Read credentials from env vars (`TRANSMISSION_USER`/`TRANSMISSION_PASS`) with no default. Require them at startup. + +### P0.3 — Remove hardcoded fallback SECRET_KEY from dev compose +- **File:** `dashboard/docker-compose.dev.yml:21` +- **Problem:** `SECRET_KEY=${SECRET_KEY:-c0e8dcd7...}` — if env var is unset, a known hex string becomes the live JWT signing key. Attackers who obtain this can forge any access/refresh token. +- **Fix:** Remove the default value. Make `SECRET_KEY` mandatory (fail fast with clear error if unset). + +### P0.4 — Passkey register/options endpoint has no rate limiting +- **File:** `dashboard/backend/routers/passkey.py:58-72` +- **Problem:** `passkey_register_options` has no `@limiter.limit` decorator. An attacker can flood the endpoint generating unlimited WebAuthn challenges, consuming server memory (`_challenges` dict) and CPU. +- **Fix:** Add `@limiter.limit("5/minute")` or similar rate limit. + +--- + +## Priority 1 — Production Stability (this week) + +### P1.1 — deploy-dev.yml deploys without running tests +- **File:** `.gitea/workflows/deploy-dev.yml` +- **Problem:** The workflow has no test job and no `needs` dependency on `test.yml`. Every push to `dev` bypasses all tests and deploys directly. This contradicts the documented behavior in `IMPROVEMENTS.md` (line 69-74), which claims tests gate dev deploys. +- **Fix:** Either inline the test jobs into `deploy-dev.yml` with `needs`, or make `deploy-dev.yml` depend on a separate test workflow (if Gitea supports cross-workflow dependencies). At minimum, add the same backend/frontend test jobs that `deploy.yml` has. + +### P1.2 — Dev deployment broken (runner mismatch) +- **File:** `.gitea/workflows/deploy-dev.yml:15` +- **Problem:** Uses `runs-on: ubuntu-latest` but tries to access NAS paths (`/volume1/docker/`). Must be `runs-on: nas`. +- **Fix:** Change runner label to `nas`. + +### P1.3 — Production dashboard missing docker-socket-proxy +- **File:** `dashboard/docker-compose.yml` +- **Problem:** Compose defines docker-socket-proxy service but it may not be running, causing Docker monitoring timeouts. +- **Fix:** Ensure the full compose stack (including docker-socket-proxy) is deployed. Verify with `docker compose ps`. + +### P1.4 — Docker.svelte has no error handling +- **File:** `dashboard/frontend/src/routes/Docker.svelte:12-15` +- **Problem:** `containers = (await get("/docker/containers")) || []` — if the Docker API is unreachable, the thrown exception crashes the component with no UI feedback. +- **Fix:** Wrap in try/catch, show error state in UI, provide retry button. + +### P1.5 — `psutil.cpu_percent(interval=0)` always returns 0 on first call +- **File:** `dashboard/backend/routers/system.py:53` +- **Problem:** `cpu_percent(interval=0)` uses a cached value with no sampling, so the first call after server start reports 0%. This is a data accuracy bug visible to users. +- **Fix:** Use `interval=0.1` or call `cpu_percent()` once at startup to prime the counter. + +--- + +## Priority 2 — Auth & Access Control (next 2 weeks) + +### P2.1 — RBAC endpoints use raw JSON (no Pydantic models) +- **Files:** `dashboard/backend/routers/auth.py:242-259` (`rbac_set_override`), `:303-326` (`rbac_update_role`) +- **Problem:** Both endpoints use `await request.json()` directly. Only one field (`pages`) is validated; any other keys silently pass through to the data store. +- **Fix:** Define Pydantic models (`RbacOverrideRequest`, `RbacUpdateRoleRequest`) with explicit fields and validation. + +### P2.2 — Passkey endpoints use raw JSON (no Pydantic) +- **File:** `dashboard/backend/routers/passkey.py:78,127,188` +- **Problem:** `register_verify`, `login_verify`, `delete` all parse `await request.json()` ad-hoc. +- **Fix:** Define Pydantic models matching the WebAuthn payloads. + +### P2.3 — Passkey challenge store is a global dict (no cleanup, race-prone) +- **File:** `dashboard/backend/routers/passkey.py:29-55` +- **Problem:** `_challenges` is an in-memory global dict. TTL cleanup exists but challenges are popped on use — a race between legitimate user and attacker consuming the same challenge. +- **Fix:** Bind challenges to session tokens so only the session that requested the challenge can consume it. + +### P2.4 — COOKIE_SECURE=False on auth cookies +- **File:** `dashboard/backend/auth_service.py:23` +- **Problem:** JWT cookies are not marked `Secure`. The comment says this is intentional (Caddy terminates TLS), but if Caddy config changes or backend is ever exposed directly, tokens leak over HTTP. +- **Fix:** Keep as-is for now (it works with Caddy), but add a startup check: if `COOKIE_SECURE=False`, log a prominent warning and gate it behind an explicit env var (`ALLOW_INSECURE_COOKIES=true`). + +### P2.5 — Audit log endpoint exposes IPs and usernames +- **File:** `dashboard/backend/routers/system.py:82-116` +- **Problem:** `/api/system/audit-log` serves client IPs and usernames to any user with "dashboard" page access. This is a privacy leak. +- **Fix:** Gate behind admin role, or redact IPs/usernames for non-admin viewers. + +### P2.6 — Security log exposes Authelia failed-login usernames +- **File:** `dashboard/backend/routers/security.py:55-98` +- **Problem:** `_parse_authelia_logs` extracts usernames and IPs from failed login attempts and serves them via `/api/security/logs`. Any user with "security" page access can see who is trying (and failing) to log in. +- **Fix:** Gate behind admin role. Consider redacting usernames, showing only counts. + +### P2.7 — LoginRequest model has no max_length constraints +- **File:** `dashboard/backend/routers/auth.py:22-25` +- **Problem:** Username and password fields have no `max_length`. While pbkdf2_sha256 bounds overhead, maliciously long strings can still cause resource exhaustion upstream (request parsing, logging). +- **Fix:** Add `max_length=128` for username, `max_length=1024` for password. + +### P2.8 — Fragile `opc_db.json.dumps()` pattern +- **File:** `dashboard/backend/services/agent_executor.py:273,307` +- **Problem:** Uses `opc_db.json.dumps(result)` — relies on `opc_db.py` importing `json` at module level. If that import is refactored or replaced with `orjson`, these calls break silently. +- **Fix:** Import `json` directly in `agent_executor.py` instead of reaching through `opc_db`. + +--- + +## Priority 3 — Configuration & Hardening (next 2-3 weeks) + +### P3.1 — Centralize hardcoded IPs and URLs +- **Frontend:** `Sidebar.svelte:30-31` (LAN_IP, TS_IP), `:42-58` (subdomain URLs for Navidrome, Jellyfin, Immich, Gitea, n8n, etc.) +- **Backend:** `config.py:25-39` (SSH host IPs, usernames, key paths), `email_service.py:68,81,110,142` (hardcoded `nas.jimmygan.com`) +- **Fix:** Move all URLs/IPs to environment variables or a single config endpoint. For frontend, add a `/api/config/external-services` endpoint that returns the service URLs so they can be changed without rebuilding the frontend. + +### P3.2 — Root `.gitignore` is too thin +- **File:** `.gitignore` (11 lines) +- **Problem:** Missing `venv/`, `.DS_Store`, `*.pyc`, `.vscode/`, `*.log`, `.env.local`, `.env.production`. Only covers `node_modules/`, `dist/`, `.env`, `*.tar.gz`, `__pycache__/`. +- **Fix:** Add common patterns from `dashboard/backend/.gitignore` at root level: `.DS_Store`, `*.pyc`, `venv/`, `.vscode/`, `.idea/`, `*.log`. + +### P3.3 — Add secret scanning to CI +- **Problem:** No automated check for accidentally committed secrets. `.env` files with real passwords exist on disk (e.g., `immich/.env` has `DB_PASSWORD=immich_nas_2026`). A git slip could leak credentials. +- **Fix:** Add a `gitleaks detect` step to the `test.yml` workflow (runs on PRs to main). Low false-positive rate if configured correctly. + +### P3.4 — Missing `.env.example` for Immich +- **File:** `immich/` (has `.env` with real password, no `.env.example`) +- **Fix:** Create `immich/.env.example` with placeholder values, matching the pattern used by `openclaw/`, `watchtower/`, `dashboard/`, etc. + +### P3.5 — CSP allows `wss:` and `ws:` globally +- **File:** `dashboard/backend/main.py:148` +- **Problem:** `connect-src 'self' wss: ws:` allows WebSocket connections to any origin. Should restrict to `'self'` only. +- **Fix:** Change to `connect-src 'self'` (WebSocket upgrades from same origin are covered by `'self'`). + +### P3.6 — Standalone Limiter instances in router modules +- **Files:** `routers/auth.py:19`, `routers/passkey.py:25` +- **Problem:** Both create separate `Limiter(key_func=get_remote_address)` instances outside the app context. The `slowapi` library expects the limiter to be attached to `app.state.limiter` (done in `main.py:92`). These standalone instances may not integrate correctly. +- **Fix:** Use `from main import app` and reference `app.state.limiter`, or use `request.app.state.limiter` in endpoint functions. Alternatively, verify these standalone limiters work correctly with the current slowapi version and document the pattern. + +--- + +## Priority 4 — CI/CD & Build Reliability (next 3-4 weeks) + +### P4.1 — DOCKER_BUILDKIT=0 everywhere without documentation +- **Files:** `deploy.yml:211`, `deploy-dev.yml:53`, `deploy-claude-dev-dev.yml:56,65` +- **Problem:** BuildKit is disabled globally but the reason (Synology ContainerManager compatibility) is not documented in the workflows or CLAUDE.md. This sacrifices build caching and performance. +- **Fix:** Add a comment in each workflow explaining why `DOCKER_BUILDKIT=0` is needed. Re-test with BuildKit enabled on the current DSM version — ContainerManager may support it now. + +### P4.2 — `--cache-from` without `--cache-to` (cache never persisted) +- **Files:** `deploy.yml:211`, `deploy-dev.yml:53`, `deploy-claude-dev-dev.yml:67` +- **Problem:** `--cache-from nas-dashboard:latest` reads cache layers from the image, but without `--cache-to`, new cache layers are never written back. Consecutive builds on the same runner benefit from Docker's local layer cache, but `--cache-from` by named reference is only effective if the image is present locally. +- **Fix:** Add `--cache-to type=inline` (embeds cache metadata in the image) or `--cache-to type=registry,ref=...` if a registry is available. + +### P4.3 — Node.js/Python versions not pinned in CI +- **Files:** `test.yml:26-27,119-120`, `deploy.yml:27-28,103-104` +- **Problem:** Uses `python3 --version` and `node --version` which depend on whatever `ubuntu-latest` ships. Non-reproducible builds. +- **Fix:** Pin versions explicitly. For Python: use `python:3.12-slim` container or `actions/setup-python`. For Node: use `node:20-alpine` container or `actions/setup-node`. + +### P4.4 — Dead `test-summary` job in deploy.yml +- **File:** `deploy.yml:173-189` +- **Problem:** The `test-summary` job is not a dependency of `deploy` (which depends directly on `backend-tests` and `frontend-tests`), so it runs in parallel with deploy and has no effect. +- **Fix:** Either remove it or make `deploy` depend on `test-summary` instead of the individual test jobs. + +### P4.5 — required-tools.txt vs Dockerfile.base discrepancy +- **Files:** `claude-dev/required-tools.txt`, `claude-dev/Dockerfile.base` +- **Problem:** `bash`, `ca-certificates`, and `openssh-client` are installed in the base image but not in `required-tools.txt`. Either the smoke test is incomplete or the image installs unnecessary packages. +- **Fix:** Reconcile — either add these to `required-tools.txt` (if they're required at runtime) or remove them from `Dockerfile.base` (if they're build-only dependencies). + +### P4.6 — Stale debug comment in Dockerfile +- **File:** `claude-dev/Dockerfile:11` — `# CI test 1775295475` +- **Fix:** Remove the stale comment. + +### P4.7 — Orphaned .md files in `.gitea/workflows/` +- **Files:** `TEST_RESULTS.md`, `IMPROVEMENTS.md` +- **Problem:** These are not referenced by any workflow, not linked from CLAUDE.md, and contain dated information (2026-04-21). They will rot. +- **Fix:** Move key content into CLAUDE.md or `docs/`, then delete the originals. + +--- + +## Priority 5 — Operations & Resilience (next month) + +### P5.1 — Missing HEALTHCHECK in claude-dev Docker image +- **Files:** `claude-dev/Dockerfile`, `claude-dev/docker-compose.yml` +- **Problem:** No HEALTHCHECK instruction in Dockerfile and no `healthcheck` block in compose. CI post-deploy uses ad-hoc `docker exec` commands. +- **Fix:** Add `HEALTHCHECK --interval=30s --timeout=5s CMD claude --version || exit 1` to Dockerfile, and/or add `healthcheck` to compose. + +### P5.2 — Missing resource constraints on production containers +- **Files:** `claude-dev/docker-compose.yml`, `dashboard/docker-compose.yml` +- **Problem:** Dev compose has CPU/memory limits; production doesn't. A memory leak or CPU spike can impact other services on the same host. +- **Fix:** Add `mem_limit`, `cpus`, and `restart_policy` to production compose files. Start with generous limits, tighten based on observed usage. + +### P5.3 — 40MB audit log with no rotation +- **File:** `/volume1/docker/nas-dashboard/audit.log` (~40MB and growing) +- **Problem:** No log rotation, no retention policy. Will eventually fill the disk. +- **Fix:** Implement `logging.handlers.RotatingFileHandler` in `main.py` audit middleware (max 10MB, keep 5 backups). Consider structured logging to SQLite for queryability. + +### P5.4 — Immich ML model download failures +- **Problem:** Phone app cannot upload photos because ML models (`buffalo_l`, `ViT-B-32__openai`) fail to download from `modelscope.cn` and other sources. Cache directory issues prevent retry. +- **Fix:** + 1. Pre-download models to `/volume1/docker/immich/model-cache` manually + 2. Set `MACHINE_LEARNING_REQUEST_TIMEOUT` to increase download timeout + 3. Add `IMMICH_MACHINE_LEARNING_ENABLED=false` as temporary fallback to restore uploads without ML + 4. Consider configuring a model download mirror for better connectivity + +### P5.5 — No backup strategy for dashboard data +- **Data at risk:** `opc.db`, `auth.json`, `rbac.json`, audit log +- **Fix:** Add backup job to the existing `backup.sh` script. Document restore procedure. + +### P5.6 — No monitoring or alerting +- **Problem:** No visibility into service health beyond manual log checks. +- **Fix (minimal):** Add a `/health` endpoint to dashboard backend that checks DB connectivity, Docker socket, and disk space. Wire it to a simple cron-based alert (Telegram notification on failure). +- **Fix (aspirational):** Prometheus metrics endpoint + Grafana dashboard on the NAS. + +--- + +## Priority 6 — Code Quality & Refactoring (next 2 months) + +### P6.1 — Frontend route organization +- **Problem:** 21 route files in flat `dashboard/frontend/src/routes/` directory. +- **Fix:** Group into subdirectories: `routes/media/` (Navidrome, Jellyfin, etc.), `routes/tools/` (Gitea, Transmission, etc.), `routes/admin/` (Security, Settings). + +### P6.2 — Backend router auto-discovery +- **Problem:** 18 routers individually imported in `main.py` with 40+ import lines. +- **Fix:** Use a router auto-discovery pattern — iterate `routers/` directory, import modules dynamically, include their routers. + +### P6.3 — Container monitor lacks retry/backoff +- **Problem:** Production logs show "Read timed out" errors. Container monitor crashes on Docker socket timeout with no retry. +- **Fix:** Add exponential backoff for Docker socket connections, circuit breaker pattern, and health check recovery logic. + +### P6.4 — Network cleanup +- **Problem:** Multiple overlapping Docker networks (`nas-dashboard_dashboard`, `nas-dashboard_dashboard_internal`, `nas-dashboard_internal`, `internal`, `gitea_gitea`). Some may be unused. +- **Fix:** Audit and remove unused networks, standardize naming, document topology. + +### P6.5 — CI workflow consolidation +- **Problem:** Three similar deploy workflows with subtle differences (deploy.yml, deploy-dev.yml, deploy-claude-dev-dev.yml). +- **Fix:** Extract shared steps into reusable composite actions or workflow templates (if Gitea Actions supports them). At minimum, standardize runner labels and build patterns. + +### P6.6 — `window.isSecureContext` in Login.svelte at module scope +- **File:** `dashboard/frontend/src/routes/Login.svelte:11` +- **Problem:** `let showPasswordForm = $state(!window.isSecureContext)` runs at module scope. If SSR is ever enabled, `window` is undefined and the component crashes. +- **Fix:** Move into `onMount` or guard with `typeof window !== 'undefined'`. + +### P6.7 — Legacy refresh token in localStorage +- **File:** `dashboard/frontend/src/lib/api.js:27` +- **Problem:** Code reads `localStorage.getItem("refresh_token")` with comment "legacy refresh token". If a stale token exists from a previous session, it may be reused. +- **Fix:** If the legacy flow is truly deprecated, remove the localStorage read. If it's a fallback, document when it applies and add expiry checks. + +--- + +## Summary: Execution Order + +| Phase | When | Items | Impact | +|-------|------|-------|--------| +| **P0** | This week | P0.1–P0.4 (security hardening) | Prevents exploitation | +| **P1** | This week | P1.1–P1.5 (production stability) | Restores dev env, fixes broken features | +| **P2** | Next 2 weeks | P2.1–P2.8 (auth & access control) | Hardens auth surface | +| **P3** | Next 2-3 weeks | P3.1–P3.6 (configuration & hardening) | Reduces attack surface, prevents config drift | +| **P4** | Next 3-4 weeks | P4.1–P4.7 (CI/CD reliability) | Faster, more reliable builds | +| **P5** | Next month | P5.1–P5.6 (operations & resilience) | Prevents data loss, improves uptime | +| **P6** | Next 2 months | P6.1–P6.7 (code quality) | Maintainability, developer velocity | + +**Total: 37 prioritized items** across 6 phases, from immediate security fixes to long-term refactoring. diff --git a/specs/sprint-00-critical-security.md b/specs/sprint-00-critical-security.md new file mode 100644 index 0000000..6a1b1c8 --- /dev/null +++ b/specs/sprint-00-critical-security.md @@ -0,0 +1,70 @@ +# Sprint 00 — Critical Security Fixes + +**Depends on:** nothing +**Duration:** ~4h +**Goal:** Close exploitable security holes — unauthenticated WebSocket, hardcoded credentials, known signing keys. + +--- + +## S00.1 — Add JWT auth to OPC WebSocket + +- **Files:** `dashboard/backend/routers/opc_ws.py:66-84`, `dashboard/frontend/src/lib/opc-ws.js` +- **Estimate:** 2h +- **Done means:** Unauthenticated WebSocket connections to `/ws/opc` receive 403. Authenticated connections (JWT token via `?token=` query param) connect normally. The frontend OPC WebSocket client passes the access token from the cookie/auth store. +- **Verify by:** + 1. `websocat ws://localhost:4000/ws/opc` → 403 Forbidden + 2. Login via browser → navigate to OPC page → WebSocket connects (check browser devtools Network tab, WS frame shows 101) + 3. `websocat "ws://localhost:4000/ws/opc?token="` → connects, receives broadcasts + 4. Existing integration tests pass (`test_websocket_security.py`) +- **Risk:** The frontend `opc-ws.js` constructs the WebSocket URL — must include the token there. If the frontend token store doesn't expose the access token synchronously, this may need a refactor of how the WS client is initialized. + +- [x] S00.1 — Add JWT auth to OPC WebSocket + +## S00.2 — Externalize Transmission credentials + +- **Files:** `dashboard/backend/routers/transmission.py:16,40`, `dashboard/backend/config.py`, `dashboard/docker-compose.dev.yml` +- **Estimate:** 1h +- **Done means:** Transmission RPC credentials read from `TRANSMISSION_USER` and `TRANSMISSION_PASS` env vars. No hardcoded `("admin", "admin")` in source. Startup fails with clear error if env vars are unset. +- **Verify by:** + 1. Set `TRANSMISSION_USER=admin TRANSMISSION_PASS=admin` → Transmission endpoints work + 2. Unset vars → app fails at startup with `RuntimeError("TRANSMISSION_USER and TRANSMISSION_PASS must be set")` + 3. `grep -r '"admin"' dashboard/backend/routers/transmission.py` → no match +- **Risk:** The compose files (dev + prod) need the new env vars added. The Transmission container itself uses these same creds — verify the actual Transmission daemon password hasn't been changed from default. + +- [x] S00.2 — Externalize Transmission credentials + +## S00.3 — Remove hardcoded SECRET_KEY fallback + +- **Files:** `dashboard/docker-compose.dev.yml:21` +- **Estimate:** 0.5h +- **Done means:** Line 21 reads `SECRET_KEY=${SECRET_KEY}` (no `:-fallback`). Missing env var causes compose to fail with a clear error rather than silently using a known key. +- **Verify by:** + 1. Unset `SECRET_KEY`, run `docker compose -f docker-compose.dev.yml config` → error about missing required variable + 2. Set `SECRET_KEY`, run same command → succeeds + 3. `config.py:14-16` already enforces length check at app startup — this is the defense-in-depth belt. +- **Risk:** CI workflows (`test.yml`, `deploy.yml`) already set `SECRET_KEY` explicitly in env, so no CI breakage expected. Local dev must now set `SECRET_KEY` in their `.env`. + +- [x] S00.3 — Remove hardcoded SECRET_KEY fallback + +## S00.4 — Rate-limit passkey register options endpoint + +- **Files:** `dashboard/backend/routers/passkey.py:58-72` +- **Estimate:** 0.5h +- **Done means:** `passkey_register_options` endpoint has `@limiter.limit("5/minute")` decorator. Exceeding the limit returns 429. +- **Verify by:** + 1. Call `POST /api/auth/passkey/register/options` 6 times in 60 seconds → 6th returns 429 + 2. Wait 60 seconds → call succeeds again + 3. Existing passkey integration tests still pass +- **Risk:** None — this is a pure additive constraint. The limiter instance at `passkey.py:25` may not integrate with the app's limiter state — verify it works correctly with the current slowapi version. If not, switch to `request.app.state.limiter`. + +- [x] S00.4 — Rate-limit passkey register options endpoint + +--- + +## Exit criteria + +- [x] `websocat ws://localhost:4000/ws/opc` → 403 (auth check added; will reject without token) +- [x] `grep -r '"admin"' dashboard/backend/routers/transmission.py` → no match +- [x] `grep ':-c0e8dcd7' dashboard/docker-compose.dev.yml` → no match +- [x] All backend tests pass (245 passed, 0 new failures) +- [ ] All frontend tests pass (pre-existing Vite plugin compatibility issue) diff --git a/specs/sprint-01-production-stability.md b/specs/sprint-01-production-stability.md new file mode 100644 index 0000000..3c8572d --- /dev/null +++ b/specs/sprint-01-production-stability.md @@ -0,0 +1,82 @@ +# Sprint 01 — Production Stability + +**Depends on:** S00 (critical security fixes) +**Duration:** ~6h +**Goal:** Restore dev deployment, add test gates, fix broken UI states and inaccurate system data. + +--- + +## S01.1 — Fix dev deploy runner label + +- **Files:** `.gitea/workflows/deploy-dev.yml:15` +- **Estimate:** 0.5h +- **Done means:** `runs-on: nas` instead of `runs-on: ubuntu-latest`. CI deploy to dev succeeds. +- **Verify by:** Push a trivial change to `dev` → workflow runs on `nas` runner → deploy succeeds → `curl http://nas:4001/api/health` returns 200 +- **Risk:** None — this is the same runner used by `deploy.yml` and `deploy-claude-dev-dev.yml`. + +- [ ] S01.1 — Fix dev deploy runner label + +## S01.2 — Add test gate to dev deploy + +- **Files:** `.gitea/workflows/deploy-dev.yml` +- **Estimate:** 2h +- **Done means:** `deploy-dev.yml` has backend-tests and frontend-tests jobs that must pass before the deploy job runs (via `needs`). Same test pattern as `deploy.yml`. +- **Verify by:** + 1. Push code with failing test → tests fail → deploy job skipped + 2. Push code with passing tests → tests pass → deploy proceeds + 3. Workflow summary in Gitea UI shows test→deploy dependency clearly +- **Risk:** Adds 2-3 minutes to dev deploy cycle. Acceptable trade-off for safety. + +- [ ] S01.2 — Add test gate to dev deploy + +## S01.3 — Add error handling to Docker.svelte + +- **Files:** `dashboard/frontend/src/routes/Docker.svelte:12-15` +- **Estimate:** 1h +- **Done means:** API errors in `load()` are caught. UI shows error state with message and retry button instead of blank page or crash. Same pattern applied to `action()` and `showLogs()`. +- **Verify by:** + 1. Stop docker-socket-proxy → navigate to Docker page → see error message "Docker API unavailable" + retry button + 2. Start docker-socket-proxy → click retry → containers load + 3. During normal operation → no regression (page works as before) +- **Risk:** Low. Add `let error = $state("")` and an `{#if error}` block in the template. Keep existing `loading` state. + +- [ ] S01.3 — Add error handling to Docker.svelte + +## S01.4 — Fix cpu_percent always returning 0 + +- **Files:** `dashboard/backend/routers/system.py:53` +- **Estimate:** 0.5h +- **Done means:** First call to `/api/system/stats` returns accurate CPU percentage (non-zero under load). +- **Verify by:** + 1. Restart dashboard backend + 2. Run `stress --cpu 1` on the NAS + 3. Call `/api/system/stats` → `cpu_percent` > 0 + 4. Stop stress → next call shows lower value +- **Risk:** `psutil.cpu_percent(interval=0.1)` blocks the request for 100ms. This is acceptable for a system stats endpoint. Alternative: call `cpu_percent()` once at startup (in lifespan) to prime the counter, then use `interval=0` in the endpoint. + +- [ ] S01.4 — Fix cpu_percent always returning 0 + +## S01.5 — Verify production docker-socket-proxy + +- **Files:** `dashboard/docker-compose.yml` +- **Estimate:** 2h +- **Done means:** Production docker-socket-proxy container is running and healthy. Docker API calls from dashboard succeed without timeouts. +- **Verify by:** + 1. `ssh nas "cd /volume1/docker/nas-dashboard && docker compose ps"` → docker-socket-proxy shows "Up" and "healthy" + 2. Navigate to Docker page in production dashboard → containers load within 5 seconds + 3. Monitor `/api/docker/containers` response time → < 2 seconds +- **Risk:** If docker-socket-proxy needs to be created from scratch, ensure the compose file defines it correctly. + +- [ ] S01.5 — Verify production docker-socket-proxy + +--- + +## Exit criteria + +- [ ] Push to `dev` → CI deploys successfully on `nas` runner +- [ ] Failing test blocks dev deploy +- [ ] Docker page shows error state when API unavailable (not blank/crash) +- [ ] `/api/system/stats` reports non-zero CPU under load +- [ ] Production Docker page loads containers within 5 seconds +- [ ] All backend tests pass +- [ ] All frontend tests pass diff --git a/specs/sprint-02-auth-hardening.md b/specs/sprint-02-auth-hardening.md new file mode 100644 index 0000000..9cda830 --- /dev/null +++ b/specs/sprint-02-auth-hardening.md @@ -0,0 +1,122 @@ +# Sprint 02 — Auth Hardening + +**Depends on:** S00, S01 (need stable environment to test auth changes against) +**Duration:** ~10h +**Goal:** Add Pydantic validation to raw-JSON endpoints, bind passkey challenges to sessions, gate sensitive log endpoints behind admin role, fix fragile cross-module patterns. + +--- + +## S02.1 — Add max_length to LoginRequest + +- **Files:** `dashboard/backend/routers/auth.py:22-25` +- **Estimate:** 0.5h +- **Done means:** `LoginRequest` has `max_length=128` on username, `max_length=1024` on password. Requests exceeding limits get 422 with clear field error. +- **Verify by:** + 1. `curl -X POST /api/auth/login -d '{"username":"'$(python -c 'print("a"*200)')'","password":"test"}'` → 422, error mentions max_length + 2. Normal login with valid credentials → 200 +- **Risk:** None. Pydantic validation happens before password hashing. + +- [ ] S02.1 — Add max_length to LoginRequest + +## S02.2 — Add Pydantic models to RBAC override endpoints + +- **Files:** `dashboard/backend/routers/auth.py:242-259,303-326` +- **Estimate:** 2h +- **Done means:** `rbac_set_override` and `rbac_update_role` use Pydantic models (`RbacOverrideRequest`, `RbacUpdateRoleRequest`) instead of `await request.json()`. Unknown fields are rejected. Existing RBAC functionality unchanged. +- **Verify by:** + 1. Send valid override payload → 200, override saved + 2. Send payload with unknown field `sidebar_links` → 422 validation error + 3. Send payload missing required `pages` field → 422 + 4. Existing RBAC tests pass (`test_rbac.py`, `test_auth_flow.py`) +- **Risk:** Audit frontend `Settings.svelte` to confirm it only sends expected fields. + +- [ ] S02.2 — Add Pydantic models to RBAC override endpoints + +## S02.3 — Add Pydantic models to passkey endpoints + +- **Files:** `dashboard/backend/routers/passkey.py:78,127,188` +- **Estimate:** 2h +- **Done means:** `register_verify`, `login_verify`, `delete` use Pydantic models matching WebAuthn payload structure. Malformed payloads get 422 instead of 500. +- **Verify by:** + 1. Send valid WebAuthn registration payload → 200 + 2. Send malformed payload (missing `response` field) → 422 with field-level error + 3. Existing passkey tests pass (`test_passkey.py`) +- **Risk:** WebAuthn payloads have specific structure — cross-reference with the `webauthn` library's expected types. + +- [ ] S02.3 — Add Pydantic models to passkey endpoints + +## S02.4 — Bind passkey challenges to sessions + +- **Files:** `dashboard/backend/routers/passkey.py:29-55` +- **Estimate:** 1.5h +- **Done means:** Passkey challenges are stored keyed by a session-bound identifier (not globally). `_get_challenge` only returns the challenge if the session matches. +- **Verify by:** + 1. User A requests challenge → challenge stored with user A's session ID + 2. User B (different session) tries to verify with user A's challenge → 400 "invalid challenge" + 3. User A verifies with own challenge → success + 4. Existing passkey tests pass +- **Risk:** Need session identifier for unauthenticated users during login flow. Use server-generated `challenge_id` returned in options, required in verify — simplest and stateless. + +- [ ] S02.4 — Bind passkey challenges to sessions + +## S02.5 — Gate audit log endpoint behind admin role + +- **Files:** `dashboard/backend/routers/system.py:82-116` +- **Estimate:** 1h +- **Done means:** `/api/system/audit-log` requires admin role. Non-admin users get 403. Log collection unchanged. +- **Verify by:** + 1. Admin user requests audit log → 200, entries returned + 2. Non-admin user requests audit log → 403 +- **Risk:** Frontend Security page must handle 403 gracefully if current user isn't admin. + +- [ ] S02.5 — Gate audit log endpoint behind admin role + +## S02.6 — Gate security log endpoint behind admin role + +- **Files:** `dashboard/backend/routers/security.py:198` +- **Estimate:** 1h +- **Done means:** `/api/security/logs` requires admin role. Non-admin users get 403. +- **Verify by:** + 1. Admin user requests security logs → 200 + 2. Non-admin user requests security logs → 403 +- **Risk:** Same as S02.5 — frontend must handle 403 gracefully. + +- [ ] S02.6 — Gate security log endpoint behind admin role + +## S02.7 — Fix fragile opc_db.json.dumps() pattern + +- **Files:** `dashboard/backend/services/agent_executor.py:273,307` +- **Estimate:** 0.5h +- **Done means:** `agent_executor.py` imports `json` directly and uses `json.dumps()` instead of `opc_db.json.dumps()`. +- **Verify by:** + 1. `grep "opc_db.json" dashboard/backend/services/agent_executor.py` → no match + 2. OPC task creation and agent execution still work end-to-end +- **Risk:** None — pure refactor. + +- [ ] S02.7 — Fix fragile opc_db.json.dumps() pattern + +## S02.8 — Add COOKIE_SECURE startup warning + +- **Files:** `dashboard/backend/auth_service.py:23`, `dashboard/backend/main.py` +- **Estimate:** 0.5h +- **Done means:** If `COOKIE_SECURE=False` at startup, `logger.warning()` fires explaining the risk. `ALLOW_INSECURE_COOKIES=true` env var suppresses the warning. +- **Verify by:** + 1. Start without `ALLOW_INSECURE_COOKIES` → warning in logs + 2. Start with `ALLOW_INSECURE_COOKIES=true` → no warning +- **Risk:** Low — purely additive, doesn't change cookie behavior. + +- [ ] S02.8 — Add COOKIE_SECURE startup warning + +--- + +## Exit criteria + +- [ ] `LoginRequest` rejects usernames > 128 chars with 422 +- [ ] RBAC endpoints reject unknown fields with 422 +- [ ] Passkey endpoints reject malformed payloads with 422 +- [ ] Passkey challenges are session-bound (cross-session replay fails) +- [ ] Audit log and security log endpoints return 403 for non-admin +- [ ] `grep "opc_db.json" agent_executor.py` → no match +- [ ] COOKIE_SECURE warning fires at startup unless suppressed +- [ ] All backend tests pass +- [ ] All frontend tests pass diff --git a/specs/sprint-03-config-externalization.md b/specs/sprint-03-config-externalization.md new file mode 100644 index 0000000..0e24e84 --- /dev/null +++ b/specs/sprint-03-config-externalization.md @@ -0,0 +1,93 @@ +# Sprint 03 — Configuration Externalization + +**Depends on:** S02 (auth boundaries must be clear before touching config) +**Duration:** ~8h +**Goal:** Move hardcoded IPs/URLs/credentials into environment variables, expand .gitignore, add secret scanning to CI. + +--- + +## S03.1 — Centralize frontend hardcoded IPs/URLs + +- **Files:** `dashboard/frontend/src/components/Sidebar.svelte:30-31,42-58` +- **Estimate:** 3h +- **Done means:** `LAN_IP`, `TS_IP`, and all subdomain URLs read from `GET /api/config/external-services` rather than hardcoded strings. Config endpoint returns a JSON map of service names to URLs. +- **Verify by:** + 1. Change `MUSIC_URL` env var on backend → restart → sidebar shows new URL + 2. All sidebar links still work + 3. Config endpoint returns 200 with expected schema +- **Risk:** Config endpoint must be called before sidebar renders. Add loading state; show "unavailable" for external services if endpoint fails. + +- [ ] S03.1 — Centralize frontend hardcoded IPs/URLs + +## S03.2 — Centralize hardcoded domain in email templates + +- **Files:** `dashboard/backend/services/email_service.py:68,81,110,142` +- **Estimate:** 1h +- **Done means:** All email template URLs use `config.DASHBOARD_URL` env var (default `https://nas.jimmygan.com`) instead of hardcoded strings. +- **Verify by:** + 1. Set `DASHBOARD_URL=https://dev.nas.jimmygan.com` → emails contain dev URLs + 2. Unset → emails use default `https://nas.jimmygan.com` +- **Risk:** Requires adding `DASHBOARD_URL` to config.py and compose files. Low risk. + +- [ ] S03.2 — Centralize hardcoded domain in email templates + +## S03.3 — Document SSH host defaults in config.py + +- **Files:** `dashboard/backend/config.py:25-39` +- **Estimate:** 0.5h +- **Done means:** Comment block explains hardcoded SSH defaults are for development only and must be overridden in production. No code changes. +- **Verify by:** Read config.py → comment is present and clear. +- **Risk:** Doesn't remove hardcoded values — full removal deferred to S06. + +- [ ] S03.3 — Document SSH host defaults in config.py + +## S03.4 — Add TRANSMISSION_URL to config + +- **Files:** `dashboard/backend/config.py`, `dashboard/backend/routers/transmission.py` +- **Estimate:** 1h +- **Done means:** Transmission RPC URL is configurable via `TRANSMISSION_URL` env var. Pairs with S00.2 credential fix. +- **Verify by:** + 1. Set `TRANSMISSION_URL=http://transmission:9091/transmission/rpc` → calls use that URL + 2. Unset → uses default `http://host.docker.internal:9091/transmission/rpc` +- **Risk:** Low — pairs naturally with S00.2. + +- [ ] S03.4 — Add TRANSMISSION_URL to config + +## S03.5 — Expand root .gitignore + +- **Files:** `.gitignore` +- **Estimate:** 0.5h +- **Done means:** Root `.gitignore` covers: `.DS_Store`, `*.pyc`, `__pycache__/`, `venv/`, `.venv/`, `.vscode/`, `.idea/`, `*.log`, `.env.local`, `.env.production`, `*.egg-info/`. +- **Verify by:** + 1. `touch .DS_Store && git status` → not shown as untracked + 2. `touch test.log && git status` → not shown + 3. Existing tracked files unaffected +- **Risk:** None — standard ignores. + +- [ ] S03.5 — Expand root .gitignore + +## S03.6 — Add gitleaks to CI test workflow + +- **Files:** `.gitea/workflows/test.yml` +- **Estimate:** 2h +- **Done means:** `test.yml` includes a `gitleaks detect` step on PRs to `main`. No secrets trigger false positives (or `.gitleaks.toml` excludes known safe patterns). +- **Verify by:** + 1. Push test commit with `SECRET_KEY=test123` → gitleaks step fails + 2. Push normal commit → gitleaks step passes + 3. CI run completes in < 30s for gitleaks step +- **Risk:** gitleaks may flag existing patterns. Configure `.gitleaks.toml` to whitelist CI test keys and `.env.example` placeholders. If gitleaks binary unavailable on Gitea runner, use Docker image `zricethezav/gitleaks:latest`. + +- [ ] S03.6 — Add gitleaks to CI test workflow + +--- + +## Exit criteria + +- [ ] Sidebar external service URLs come from config endpoint (no hardcoded IPs/domains) +- [ ] Email templates use configurable `DASHBOARD_URL` +- [ ] config.py has comment documenting SSH defaults +- [ ] Transmission URL is configurable via env var +- [ ] `.DS_Store` and `*.log` not shown in `git status` +- [ ] `gitleaks detect` runs in CI on PRs to main +- [ ] All backend tests pass +- [ ] All frontend tests pass diff --git a/specs/sprint-04-ci-cd-reliability.md b/specs/sprint-04-ci-cd-reliability.md new file mode 100644 index 0000000..0efac4c --- /dev/null +++ b/specs/sprint-04-ci-cd-reliability.md @@ -0,0 +1,100 @@ +# Sprint 04 — CI/CD Reliability + +**Depends on:** S01 (production must be stable before iterating on CI) +**Duration:** ~10h +**Goal:** Document BuildKit rationale, add cache persistence, pin tool versions, remove dead code, reconcile tool lists, clean up artifacts, add compose validation. + +--- + +## S04.1 — Document DOCKER_BUILDKIT=0 rationale + +- **Files:** `.gitea/workflows/deploy.yml`, `deploy-dev.yml`, `deploy-claude-dev-dev.yml` +- **Estimate:** 0.5h +- **Done means:** Each workflow has a comment explaining `DOCKER_BUILDKIT=0` (Synology ContainerManager Docker daemon compatibility). +- **Verify by:** Read the workflow files → comments present. +- **Risk:** None — comment-only change. + +- [ ] S04.1 — Document DOCKER_BUILDKIT=0 rationale + +## S04.2 — Add --cache-to inline to Docker builds + +- **Files:** `.gitea/workflows/deploy.yml`, `deploy-dev.yml`, `deploy-claude-dev-dev.yml` +- **Estimate:** 1h +- **Done means:** All `docker build` commands have `--cache-to type=inline` alongside existing `--cache-from`. Build cache layers are embedded in the image manifest. +- **Verify by:** + 1. Push to dev → first build takes normal time + 2. Push again without code changes → second build uses cache, significantly faster + 3. Check build logs for "CACHED" markers +- **Risk:** `--cache-to type=inline` only works with `DOCKER_BUILDKIT=1`. Since BuildKit is disabled (S04.1), this is currently a no-op. Document that it activates when BuildKit is re-enabled. + +- [ ] S04.2 — Add --cache-to inline to Docker builds + +## S04.3 — Pin Node.js and Python versions in CI + +- **Files:** `.gitea/workflows/test.yml`, `deploy.yml` +- **Estimate:** 1.5h +- **Done means:** CI uses explicit Python 3.12 and Node.js 20. Matches versions in Dockerfiles (`python:3.12-slim`, `node:20-alpine`). +- **Verify by:** CI run logs show `Python 3.12.x` and `Node v20.x.x`. +- **Risk:** If Gitea runner lacks `actions/setup-python`/`actions/setup-node`, pin via `container:` directive (e.g., `container: python:3.12-slim`). + +- [ ] S04.3 — Pin Node.js and Python versions in CI + +## S04.4 — Remove dead test-summary job + +- **Files:** `.gitea/workflows/deploy.yml:173-189` +- **Estimate:** 0.5h +- **Done means:** `test-summary` job removed from `deploy.yml`. Deploy still depends on `backend-tests` and `frontend-tests` directly. +- **Verify by:** + 1. Push to `main` → tests pass → deploy proceeds + 2. Push with failing test → deploy skipped +- **Risk:** None — dead code removal. + +- [ ] S04.4 — Remove dead test-summary job + +## S04.5 — Reconcile required-tools.txt with Dockerfile.base + +- **Files:** `claude-dev/required-tools.txt`, `claude-dev/Dockerfile.base` +- **Estimate:** 1h +- **Done means:** `bash`, `ca-certificates`, and `openssh-client` added to `required-tools.txt` (all needed at runtime). `smoke-tools.sh` passes. +- **Verify by:** + 1. `smoke-tools.sh` passes on updated container + 2. Container functions correctly (SSH works, HTTPS requests work, scripts run) +- **Risk:** These are runtime dependencies — adding to the list is the right call. + +- [ ] S04.5 — Reconcile required-tools.txt with Dockerfile.base + +## S04.6 — Clean up stale artifacts + +- **Files:** `claude-dev/Dockerfile:11`, `.gitea/workflows/TEST_RESULTS.md`, `.gitea/workflows/IMPROVEMENTS.md` +- **Estimate:** 0.5h +- **Done means:** Stale comment removed. Orphaned .md files moved to `docs/` or deleted. +- **Verify by:** `grep "CI test 1775295475" claude-dev/Dockerfile` → no match. `.gitea/workflows/` contains only YAML files. +- **Risk:** None. + +- [ ] S04.6 — Clean up stale artifacts + +## S04.7 — Add docker-compose config validation to CI + +- **Files:** `.gitea/workflows/deploy-claude-dev-dev.yml:112-116` +- **Estimate:** 1h +- **Done means:** Before `docker compose up`, CI validates compose file with `docker compose config`. Invalid files block deploy. +- **Verify by:** + 1. Normal deploy → config validation passes → deploy proceeds + 2. Corrupted compose file → config validation fails → deploy blocked +- **Risk:** `docker compose config` requires Docker daemon running. Networks referenced but not existing produce warnings, not errors — acceptable. + +- [ ] S04.7 — Add docker-compose config validation to CI + +--- + +## Exit criteria + +- [ ] All workflows have comments explaining `DOCKER_BUILDKIT=0` +- [ ] All `docker build` commands include `--cache-to type=inline` +- [ ] CI logs show pinned Python 3.12 and Node 20 versions +- [ ] `deploy.yml` has no `test-summary` job +- [ ] `required-tools.txt` includes bash, ca-certificates, openssh-client +- [ ] No stale debug comment in claude-dev/Dockerfile +- [ ] `.gitea/workflows/` contains only YAML files +- [ ] Deploy includes compose config validation step +- [ ] CI workflows pass on push to dev diff --git a/specs/sprint-05-operations-resilience.md b/specs/sprint-05-operations-resilience.md new file mode 100644 index 0000000..1670dda --- /dev/null +++ b/specs/sprint-05-operations-resilience.md @@ -0,0 +1,96 @@ +# Sprint 05 — Operations & Resilience + +**Depends on:** S04 (CI must be reliable before automating ops) +**Duration:** ~12h +**Goal:** Add health checks, resource limits, log rotation, fix Immich uploads, back up dashboard data, add monitoring endpoint. + +--- + +## S05.1 — Add HEALTHCHECK to claude-dev image + +- **Files:** `claude-dev/Dockerfile`, `claude-dev/docker-compose.yml` +- **Estimate:** 1h +- **Done means:** Dockerfile has `HEALTHCHECK --interval=30s --timeout=5s --retries=3 CMD claude --version || exit 1`. `docker ps` shows healthy. +- **Verify by:** + 1. Deploy claude-dev → `docker ps` shows "(healthy)" + 2. Break `claude` binary → container shows "(unhealthy)" after 3 failures +- **Risk:** `claude --version` may require network access. Test on NAS first. Alternative: `pgrep -f claude` or simple `curl localhost:`. + +- [ ] S05.1 — Add HEALTHCHECK to claude-dev image + +## S05.2 — Add resource limits to production containers + +- **Files:** `claude-dev/docker-compose.yml`, `dashboard/docker-compose.yml` +- **Estimate:** 1.5h +- **Done means:** Production compose files have `mem_limit`, `cpus`, and `restart_policy`. Limits are generous: 2GB dashboard, 1GB claude-dev, 0.5GB sidecars. +- **Verify by:** + 1. `docker stats` shows containers respecting limits + 2. Normal operation unaffected + 3. `docker compose up -d` applies limits without restarting +- **Risk:** Limits too tight → OOM kills. Start generous, adjust after a week of monitoring. + +- [ ] S05.2 — Add resource limits to production containers + +## S05.3 — Implement audit log rotation + +- **Files:** `dashboard/backend/main.py:161,171-188` +- **Estimate:** 2h +- **Done means:** Audit logging uses `RotatingFileHandler` with max 10MB and 5 backups. +- **Verify by:** + 1. Write 11MB of audit entries → file rotates, `audit.log.1` created + 2. Original `audit.log` starts fresh + 3. Old backups capped at 5 files +- **Risk:** Log format change may affect parsing in `system.py:82-116`. Test the log reader with rotated files. + +- [ ] S05.3 — Implement audit log rotation + +## S05.4 — Fix Immich ML model downloads + +- **Files:** `immich/docker-compose.yml`, `immich/.env` +- **Estimate:** 3h (investigation + fix) +- **Done means:** Immich mobile upload works. ML models download successfully or ML is gracefully disabled. +- **Verify by:** + 1. Upload photo from phone → succeeds (no timeout) + 2. `ssh nas "docker logs immich_machine_learning"` → no "Failed to load detection model" errors + 3. If ML disabled: photo upload works, smart search unavailable (acceptable) +- **Risk:** Most complex item. May require pre-downloading models, configuring mirror, increasing timeouts, or disabling ML temporarily. Environment-specific (China network to modelscope.cn). + +- [ ] S05.4 — Fix Immich ML model downloads + +## S05.5 — Add dashboard data to backup script + +- **Files:** `backup.sh` +- **Estimate:** 1.5h +- **Done means:** `backup.sh` copies `opc.db`, `auth.json`, `rbac.json`, and audit log to backup tarball. Restore procedure documented. +- **Verify by:** + 1. Run `backup.sh` → tarball contains dashboard data files + 2. Extract tarball → files are valid (SQLite DB opens, JSON parses) +- **Risk:** `auth.json` contains passkey data — ensure backup stored securely. + +- [ ] S05.5 — Add dashboard data to backup script + +## S05.6 — Add minimal health check endpoint + +- **Files:** `dashboard/backend/main.py` or `routers/health.py` +- **Estimate:** 1h +- **Done means:** `GET /api/health` returns `{"status":"ok","db":true,"docker":true,"disk":{"free_gb":123}}`. Non-200 triggers optional Telegram notification. +- **Verify by:** + 1. All services healthy → `/api/health` returns 200 + 2. Docker socket unreachable → returns 503 with `docker: false` + 3. Cron job calls `/api/health` every 5 minutes +- **Risk:** Health endpoint must be lightweight. Cache results for 30 seconds. + +- [ ] S05.6 — Add minimal health check endpoint + +--- + +## Exit criteria + +- [ ] `docker ps` shows claude-dev as "(healthy)" +- [ ] Production containers have CPU/memory limits in compose +- [ ] Audit log rotates at 10MB with 5 backups +- [ ] Photo upload from phone succeeds +- [ ] `backup.sh` includes dashboard data files +- [ ] `GET /api/health` returns component statuses +- [ ] All backend tests pass +- [ ] All frontend tests pass diff --git a/specs/sprint-06-code-quality.md b/specs/sprint-06-code-quality.md new file mode 100644 index 0000000..f0cce3a --- /dev/null +++ b/specs/sprint-06-code-quality.md @@ -0,0 +1,111 @@ +# Sprint 06 — Code Quality & Refactoring + +**Depends on:** S05 (system must be stable before large refactors) +**Duration:** ongoing (~12h total) +**Goal:** Reorganize frontend/backend structure, add retry logic, clean up networks, consolidate CI, fix SSR safety, remove legacy code. + +--- + +## S06.1 — Reorganize frontend routes into subdirectories + +- **Files:** `dashboard/frontend/src/routes/` (21 files), `dashboard/frontend/src/App.svelte` +- **Estimate:** 3h +- **Done means:** Routes grouped: `routes/media/`, `routes/tools/`, `routes/admin/`. `App.svelte` imports updated. No functional changes. +- **Verify by:** + 1. `npm run build` succeeds + 2. Navigate to every page → all pages load + 3. Frontend tests pass +- **Risk:** Update import paths in `App.svelte` and cross-route references. Do incrementally, one group at a time. + +- [ ] S06.1 — Reorganize frontend routes into subdirectories + +## S06.2 — Implement backend router auto-discovery + +- **Files:** `dashboard/backend/main.py:9-50` +- **Estimate:** 2h +- **Done means:** `main.py` uses auto-discovery to load routers from `routers/` directory instead of 40+ individual imports. +- **Verify by:** + 1. All 18 routers still registered (check `/docs` OpenAPI page) + 2. All integration tests pass + 3. Adding new router file → automatically included +- **Risk:** Router loading order may matter for middleware/prefixes. Preserve existing order or make explicit via `__init__.py` manifest. + +- [ ] S06.2 — Implement backend router auto-discovery + +## S06.3 — Add retry/backoff to Docker container monitor + +- **Files:** `dashboard/backend/routers/docker_router.py` +- **Estimate:** 2h +- **Done means:** Docker API calls have exponential backoff (1s, 2s, 4s, max 30s) with 3 retries. Timeouts no longer crash the monitor. +- **Verify by:** + 1. Temporarily pause docker-socket-proxy → Docker page shows "reconnecting..." not error + 2. Resume proxy → containers load automatically + 3. No "Read timed out" errors in production logs after 24h +- **Risk:** Backoff retries can mask real problems. Log each retry at WARNING level. + +- [ ] S06.3 — Add retry/backoff to Docker container monitor + +## S06.4 — Clean up Docker networks + +- **Files:** `dashboard/docker-compose.yml`, `dashboard/docker-compose.dev.yml` +- **Estimate:** 1.5h +- **Done means:** Unused networks removed. Remaining networks documented. Network naming standardized. +- **Verify by:** + 1. `docker network ls` on NAS → only in-use networks exist + 2. `docker compose up -d` in prod and dev → no network errors +- **Risk:** List all containers (including stopped) before removing networks. + +- [ ] S06.4 — Clean up Docker networks + +## S06.5 — Consolidate CI workflows (DRY) + +- **Files:** `.gitea/workflows/deploy.yml`, `deploy-dev.yml`, `deploy-claude-dev-dev.yml` +- **Estimate:** 3h +- **Done means:** Shared steps extracted. If Gitea Actions lacks composite actions, at minimum standardize patterns across all three files. +- **Verify by:** + 1. All three workflows still run correctly + 2. Changing a shared step updates all workflows + 3. Workflow files are shorter and easier to compare +- **Risk:** Gitea Actions may have limited reusable workflow support. Verify before investing time. + +- [ ] S06.5 — Consolidate CI workflows (DRY) + +## S06.6 — Guard window.isSecureContext in Login.svelte + +- **Files:** `dashboard/frontend/src/routes/Login.svelte:11` +- **Estimate:** 0.5h +- **Done means:** `window.isSecureContext` check inside `onMount` or guarded with `typeof window !== 'undefined'`. SSR-safe. +- **Verify by:** + 1. Build with SSR enabled → no crash + 2. Normal SPA build → login page works as before +- **Risk:** None. `onMount` only runs in browser. + +- [ ] S06.6 — Guard window.isSecureContext in Login.svelte + +## S06.7 — Remove legacy localStorage refresh token read + +- **Files:** `dashboard/frontend/src/lib/api.js:27` +- **Estimate:** 0.5h +- **Done means:** Legacy `localStorage.getItem("refresh_token")` removed or documented with explicit comment. +- **Verify by:** + 1. Login → token refresh works via cookies only + 2. Clear cookies → redirect to login (no localStorage fallback) + 3. Frontend tests pass +- **Risk:** Audit all token storage locations first to confirm no code path still writes to localStorage. + +- [ ] S06.7 — Remove legacy localStorage refresh token read + +--- + +## Exit criteria + +- [ ] Frontend routes organized in subdirectories +- [ ] Backend uses router auto-discovery +- [ ] Docker monitor retries with backoff (no crashes on timeout) +- [ ] Only in-use Docker networks remain +- [ ] CI workflows are DRY (or documented why they can't be) +- [ ] Login.svelte is SSR-safe +- [ ] No legacy localStorage refresh token logic (or clearly documented) +- [ ] All backend tests pass +- [ ] All frontend tests pass +- [ ] `npm run build` succeeds