refactor: comprehensive code review fixes across 31 files

Addresses all critical, high, medium, and low issues from full codebase
review. 494 tests pass, ruff clean, ty type-check clean.

Security:
- Add tool_error_handler context manager (exceptions.py) — standardised
  error handling, eliminates 11 bare except-reraise patterns
- Remove unused exception subclasses (ConfigurationError, UnraidAPIError,
  SubscriptionError, ValidationError, IdempotentOperationError)
- Harden GraphQL subscription query validator with allow-list and
  forbidden-keyword regex (diagnostics.py)
- Add input validation for rclone create_remote config_data: injection,
  path-traversal, and key-count limits (rclone.py)
- Validate notifications importance enum before GraphQL request (notifications.py)
- Sanitise HTTP/network/JSON error messages — no raw exception strings
  leaked to clients (client.py)
- Strip path/creds from displayed API URL via _safe_display_url (health.py)
- Enable Ruff S (bandit) rule category in pyproject.toml
- Harden container mutations to strict-only matching — no fuzzy/substring
  for destructive operations (docker.py)

Performance:
- Token-bucket rate limiter (90 tokens, 9 req/s) with 429 retry backoff (client.py)
- Lazy asyncio.Lock init via _get_client_lock() — fixes event-loop
  module-load crash (client.py)
- Double-checked locking in get_http_client() for fast-path (client.py)
- Short hex container ID fast-path skips list fetch (docker.py)
- Cap resource_data log content to 1 MB / 5,000 lines (manager.py)
- Reset reconnect counter after 30 s stable connection (manager.py)
- Move tail_lines validation to module level; enforce 10,000 line cap
  (storage.py, docker.py)
- force_terminal=True removed from logging RichHandler (logging.py)

Architecture:
- Register diagnostic tools in server startup (server.py)
- Move ALL_ACTIONS computation to module level in all tools
- Consolidate format_kb / format_bytes into shared core/utils.py
- Add _safe_get() helper in core/utils.py for nested dict traversal
- Extract _analyze_subscription_status() from health.py diagnose handler
- Validate required config at startup — fail fast with CRITICAL log (server.py)

Code quality:
- Remove ~90 lines of dead Rich formatting helpers from logging.py
- Remove dead self.websocket attribute from SubscriptionManager
- Remove dead setup_uvicorn_logging() wrapper
- Move _VALID_IMPORTANCE to module level (N806 fix)
- Add slots=True to all three dataclasses (SubscriptionData, SystemHealth, APIResponse)
- Fix None rendering as literal "None" string in info.py summaries
- Change fuzzy-match log messages from INFO to DEBUG (docker.py)
- UTC-aware datetimes throughout (manager.py, diagnostics.py)

Infrastructure:
- Upgrade base image python:3.11-slim → python:3.12-slim (Dockerfile)
- Add non-root appuser (UID/GID 1000) with HEALTHCHECK (Dockerfile)
- Add read_only, cap_drop: ALL, tmpfs /tmp to docker-compose.yml
- Single-source version via importlib.metadata (pyproject.toml → __init__.py)
- Add open_timeout to all websockets.connect() calls

Tests:
- Update error message matchers to match sanitised messages (test_client.py)
- Fix patch targets for UNRAID_API_URL → utils module (test_subscriptions.py)
- Fix importance="info" → importance="normal" (test_notifications.py, http_layer)
- Fix naive datetime fixtures → UTC-aware (test_subscriptions.py)

Co-authored-by: Claude <claude@anthropic.com>

unraid_mcp/tools/rclone.py

@@ -4,13 +4,14 @@ Provides the `unraid_rclone` tool with 4 actions for managing
 cloud storage remotes (S3, Google Drive, Dropbox, FTP, etc.).
 """
 
+import re
 from typing import Any, Literal
 
 from fastmcp import FastMCP
 
 from ..config.logging import logger
 from ..core.client import make_graphql_request
-from ..core.exceptions import ToolError
+from ..core.exceptions import ToolError, tool_error_handler
 
 
 QUERIES: dict[str, str] = {
@@ -49,6 +50,51 @@ RCLONE_ACTIONS = Literal[
     "delete_remote",
 ]
 
+# Max config entries to prevent abuse
+_MAX_CONFIG_KEYS = 50
+# Pattern for suspicious key names (path traversal, shell metacharacters)
+_DANGEROUS_KEY_PATTERN = re.compile(r"[.]{2}|[/\\;|`$(){}]")
+# Max length for individual config values
+_MAX_VALUE_LENGTH = 4096
+
+
+def _validate_config_data(config_data: dict[str, Any]) -> dict[str, str]:
+    """Validate and sanitize rclone config_data before passing to GraphQL.
+
+    Ensures all keys and values are safe strings with no injection vectors.
+
+    Raises:
+        ToolError: If config_data contains invalid keys or values
+    """
+    if len(config_data) > _MAX_CONFIG_KEYS:
+        raise ToolError(f"config_data has {len(config_data)} keys (max {_MAX_CONFIG_KEYS})")
+
+    validated: dict[str, str] = {}
+    for key, value in config_data.items():
+        if not isinstance(key, str) or not key.strip():
+            raise ToolError(
+                f"config_data keys must be non-empty strings, got: {type(key).__name__}"
+            )
+        if _DANGEROUS_KEY_PATTERN.search(key):
+            raise ToolError(
+                f"config_data key '{key}' contains disallowed characters "
+                f"(path traversal or shell metacharacters)"
+            )
+        if not isinstance(value, (str, int, float, bool)):
+            raise ToolError(
+                f"config_data['{key}'] must be a string, number, or boolean, "
+                f"got: {type(value).__name__}"
+            )
+        str_value = str(value)
+        if len(str_value) > _MAX_VALUE_LENGTH:
+            raise ToolError(
+                f"config_data['{key}'] value exceeds max length "
+                f"({len(str_value)} > {_MAX_VALUE_LENGTH})"
+            )
+        validated[key] = str_value
+
+    return validated
+
 
 def register_rclone_tool(mcp: FastMCP) -> None:
     """Register the unraid_rclone tool with the FastMCP instance."""
@@ -75,7 +121,7 @@ def register_rclone_tool(mcp: FastMCP) -> None:
         if action in DESTRUCTIVE_ACTIONS and not confirm:
             raise ToolError(f"Action '{action}' is destructive. Set confirm=True to proceed.")
 
-        try:
+        with tool_error_handler("rclone", action, logger):
             logger.info(f"Executing unraid_rclone action={action}")
 
             if action == "list_remotes":
@@ -96,9 +142,10 @@ def register_rclone_tool(mcp: FastMCP) -> None:
             if action == "create_remote":
                 if name is None or provider_type is None or config_data is None:
                     raise ToolError("create_remote requires name, provider_type, and config_data")
+                validated_config = _validate_config_data(config_data)
                 data = await make_graphql_request(
                     MUTATIONS["create_remote"],
-                    {"input": {"name": name, "type": provider_type, "config": config_data}},
+                    {"input": {"name": name, "type": provider_type, "config": validated_config}},
                 )
                 remote = data.get("rclone", {}).get("createRCloneRemote")
                 if not remote:
@@ -127,10 +174,4 @@ def register_rclone_tool(mcp: FastMCP) -> None:
 
             raise ToolError(f"Unhandled action '{action}' — this is a bug")
 
-        except ToolError:
-            raise
-        except Exception as e:
-            logger.error(f"Error in unraid_rclone action={action}: {e}", exc_info=True)
-            raise ToolError(f"Failed to execute rclone/{action}: {e!s}") from e
-
     logger.info("RClone tool registered successfully")