security: Sprint 00 — critical security fixes (OPC WS auth, Transmission creds, SECRET_KEY, passkey rate limit)

- 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 <noreply@anthropic.com>

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(",")

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:

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]

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}
             )
 

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

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

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

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);
 

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.

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=<valid_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)

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

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

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

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

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:<port>`.
+
+- [ ] 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

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