security: triage the CodeQL backlog — 129 alerts, three of them live (#561)

* fix(web): escape quotes in every HTML escaper, not just & < >

The escapers are all `div.textContent = x; return div.innerHTML`. That
round-trip escapes &, < and > -- the only characters the HTML serializer
must escape in a text node -- and leaves quotes alone. Every widget then
interpolates the result into a quoted attribute value:

    value="${escapeHtml(v)}"   title="${escapeHtml(v)}"

so a value of `x" onmouseover="alert(1)` closes the attribute and adds an
event handler of its own. CodeQL reported this 83 times
(js/incomplete-html-attribute-sanitization) across the widget files.

It is one bug, not 83: the widgets each carry a standalone fallback that
did escape quotes, but they all prefer BaseWidget.escapeHtml when
window.BaseWidget exists -- which it always does in the shipped page -- so
the correct fallbacks were dead code and the incomplete shared one ran.
Fixed at each source instead of at the call sites.

app-shell.js already documented this exact gap in a comment and worked
around it by building DOM nodes by hand; that workaround stays (setting a
property cannot be got wrong), the comment is now accurate.

cache.html's delete button interpolated the cache key into
`onclick="deleteCacheFile('...')"`. Escaping cannot help there -- the
browser HTML-decodes the attribute before parsing it as JS, so `&#39;`
becomes a real `'` again -- so the key moves to a data-cache-key
attribute that the handler reads back.

url-input.js additionally wrote a value straight into an <a href> after
validating it against a schema-supplied protocol list, and that list
accepted any RFC 3986 scheme -- "javascript" included. Scriptable schemes
(javascript, data, vbscript, blob, filesystem) are now refused both when
the list is normalised and when a URL is checked against it, and the
render path routes its href through the same check instead of emitting
whatever was stored (js/xss-through-dom).

test/js/unit/test_html_escaping.js reads each escaper out of the shipped
file and runs it, so losing the quote handling again fails a test rather
than a scan.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(security): stop request-supplied names from reaching paths outside their base

Three of the py/path-injection alerts were live, not lint:

* GET /api/v3/plugins/<plugin_id>/static/<path:file_path> read any file
  whose resolved path *string-prefixed* the plugin directory. Flask's
  default converter forbids a slash but not dots, and
  get_plugin_directory('..') returned the parent of the plugins directory
  because it exists -- so every file under the project root then prefixed
  that directory, config/config_secrets.json included. The prefix check
  was also wrong on its own terms: with plugin dir "plugin-repos/foo",
  "../foo-evil/x" resolves to "plugin-repos/foo-evil/x", whose string does
  start with "plugin-repos/foo".

* POST /api/v3/plugins/of-the-day/json/delete interpolated the request
  body's file_id into f"{file_id}.json" and unlinked it, unvalidated. A
  file_id of "../../../../etc/something" deleted that file. This is the
  one finding in the batch that destroyed data rather than exposing it.

* POST /api/v3/cache/delete passed the body's key through
  CacheManager.clear_cache to DiskCache, which joined it as a filename and
  called os.remove. Same shape, same result. The guard goes in
  DiskCache.get_cache_path, the single choke point get/set/clear share, so
  every caller is covered rather than just this route. Real keys are the
  stems of files already flat in the cache directory -- that is how
  list_cache_files derives them -- so nothing legitimate is turned away.

The rest of the cluster (web_interface/app.py's asset route, the plugin
update handler, _get_plugin_version, the plugin-schema read in config.py)
was guarded in ways that held, but each had grown its own version of the
check. They now go through one helper, src/common/path_safety.py, which
returns the *sanitised value* rather than a verdict -- so a caller cannot
validate one string and open another, which is how the two real bugs
above were shaped.

Also: WiFiManager.connect_to_network took the SSID and password straight
from POST /api/v3/wifi/connect into nmcli's argv. There is no shell there,
so CodeQL's py/command-line-injection alert overstates the risk -- but
nmcli reads a leading "-" as an option, so an SSID of "--ask" asks nmcli
to run differently rather than to join a network. Both values are now
checked for shape (802.11's 32-octet SSID limit, WPA's 8-63 char
passphrase or 64-char hex key, no control characters, no leading dash)
before any subprocess runs.

test/test_path_traversal_guards.py asserts on the filesystem, not just
the status code: a handler that returns 403 and deletes the file anyway
would pass the weaker check. Twelve of its cases fail against the
unpatched code.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(web): refuse a plugin id that is not a plain name, don't truncate it

pages_v3 and scripts/dev_server.py ran request ids through
os.path.basename and carried on with what came out, so "../weather"
rendered the config form for "weather". Nothing escaped the plugins
directory -- the relative_to guards held -- but the handler answered a
request nobody made, and validating one string while the filesystem sees
another is the shape both live traversals earlier in this branch had.

Same treatment as the rest: safe_path_component rejects rather than
truncates, resolve_under returns the path it checked, and the call sites
use what those return. The three handlers that had hand-rolled
resolve-and-relative_to blocks lose about twenty lines to the shared one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(web): say what the plugin web_ui iframe actually is

The docstring claimed the fragment runs "in a sandboxed iframe". The
iframe in plugin_config.html carries no sandbox attribute, so the
fragment runs with the interface's own origin. That is fine -- the file
belongs to an installed plugin, and an installed plugin already runs
Python on the device, so the trust boundary is install rather than this
route -- but a comment promising containment that is not there is worse
than no comment. This is the context for the py/reflective-xss alert on
this handler.

Also drops the now-unused os/os.path imports.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(web): inline url-input's scheme guard at the previewLink.href sink

CodeQL flagged this line as a new high-severity js/xss-through-dom alert
on this PR even though it is already covered by SCRIPTABLE_SCHEMES: the
guard reached the sink through safeHref -> isValidUrl, two function calls
away, which its DOM-based-XSS sanitizer recognition does not trace.

Behavior is unchanged -- same scheme check, same SCRIPTABLE_SCHEMES list,
same allowedProtocols gate -- just inlined directly above the
previewLink.href assignment it guards, so the barrier is visible in the
same scope as the sink.

Added a regression test that runs the shipped onInput handler (not just
the extracted helpers) against a mocked DOM, so a future change that
reintroduces an unguarded previewLink.href assignment fails here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(security): address CodeRabbit findings on the CodeQL triage PR

- src/wifi_manager.py: reject non-ASCII WPA-PSK passphrases before any
  credential-saving or connect flow runs. NetworkManager only accepts
  printable ASCII passphrases (or a 64-char hex key); a non-ASCII value
  was previously saved/attempted before nmcli itself rejected it.

- web_interface/blueprints/api_v3/config.py: fail closed when the
  plugin config schema path can't be resolved under the plugins
  directory (e.g. a symlinked plugin dir). Previously this fell
  through with secret_fields left empty, so submitted credentials for
  that plugin were saved as ordinary, unencrypted configuration.

- web_interface/static/v3/js/widgets/plugin-file-manager.js: stop
  splicing the JSON day/column key into an inline oninput="..." handler
  string. escHtml() escapes quotes for a normal HTML attribute, but the
  browser HTML-decodes the attribute before running it as script, which
  undoes that escaping and lets a crafted column name (e.g. from an
  uploaded JSON file) break out of the JS string and execute. Cell
  edits now travel through data-day/data-col attributes read by one
  delegated 'input' listener instead.

  While in this file: fixed 6 pre-existing missing-')' typos on
  multi-line safeSetHTML(...) calls (already flagged by Biome in this
  PR's own CodeRabbit run as syntax errors blocking its lint pass).
  These predate this PR (present on main too) but made the whole file
  fail to parse in any JS engine, which is a bigger problem than the
  XSS finding itself and directly touches the same lines.

Added/extended regression tests for each fix; full suites pass
(pytest: 4580 passed, 62 skipped; JS: 84 assertions).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

src/cache/disk_cache.py

@@ -15,6 +15,8 @@ import zlib
 from typing import Dict, Any, Optional, Protocol
 from datetime import datetime
 
+from src.common.path_safety import safe_path_component
+
 try:  # optional: large speedup on the cache write path, see _dumps below
     import orjson
 except ImportError:  # pragma: no cover - exercised on hosts without the wheel
@@ -160,16 +162,30 @@ class DiskCache:
     def get_cache_path(self, key: str) -> Optional[str]:
         """
         Get the path for a cache file.
-        
+
+        The key becomes a filename, so it has to be one. Keys reach this
+        method from the web API -- POST /api/v3/cache/delete passes the
+        request body's ``key`` straight through CacheManager.clear_cache to
+        os.remove -- and a key of ``../../../../etc/whatever`` named a file
+        well outside the cache directory. Every real key is the stem of a
+        file already sitting flat in cache_dir (that is how list_cache_files
+        derives them), so rejecting anything with a path component turns
+        away only inputs that could never have been written here.
+
         Args:
             key: Cache key
-            
+
         Returns:
-            Path to cache file or None if cache is disabled
+            Path to cache file, or None if cache is disabled or the key is
+            not a usable filename
         """
         if not self.cache_dir:
             return None
-        return os.path.join(self.cache_dir, f"{key}.json")
+        safe_key = safe_path_component(key)
+        if safe_key is None:
+            self.logger.warning("Rejected unsafe cache key %r", key)
+            return None
+        return os.path.join(self.cache_dir, f"{safe_key}.json")
     
     def get(self, key: str, max_age: Optional[int] = 300) -> Optional[Dict[str, Any]]:
         """

src/common/path_safety.py

@@ -0,0 +1,125 @@
+"""One place to turn a request-supplied name into a path you can open.
+
+Every web handler that opens a file under a fixed directory had grown its own
+version of this: a regex here, an ``os.path.basename`` there, a
+``str(x).startswith(str(base))`` somewhere else. They were not equivalent.
+``startswith`` says ``plugin-repos/foo-evil`` is inside ``plugin-repos/foo``;
+validating a name in one place and rebuilding the path from the *raw* value in
+another leaves the guard checking something the filesystem never sees.
+
+Two functions, used the same way everywhere:
+
+``safe_path_component(value)``
+    ``value`` if it is one harmless path segment, otherwise ``None``.
+
+``resolve_under(base, *parts)``
+    the resolved path, or ``None`` if any part is unsafe or the result would
+    land outside ``base``.
+
+Both *return the sanitised value* rather than a boolean, so a caller cannot
+validate one string and then open another -- and so a scanner can follow what
+actually reaches ``open()``. ``os.path.basename`` does the stripping because it
+is the sanitiser CodeQL's path-injection query recognises; the equality check
+after it means an input with a directory part is rejected outright instead of
+being silently truncated to something the caller did not ask for.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, List, Optional, Union
+
+__all__ = [
+    'safe_path_component',
+    'safe_relative_parts',
+    'resolve_under',
+]
+
+# Names that are a path component syntactically but never name a real entry a
+# caller means to reach.
+_RESERVED_COMPONENTS = frozenset({'', '.', '..'})
+
+
+def safe_path_component(value: Any) -> Optional[str]:
+    """Return ``value`` when it is a single, harmless path segment.
+
+    Returns ``None`` for anything else: a non-string, an empty string, ``.`` or
+    ``..``, a value carrying a directory separator (either platform's), a drive
+    letter, or an embedded NUL.
+
+    The return value is what callers must join -- not the argument.
+    """
+    if not isinstance(value, str) or not value:
+        return None
+    if '\x00' in value:
+        return None
+
+    # basename strips any directory component, so what a caller joins cannot
+    # carry one. Comparing the result against the input rejects rather than
+    # truncates: "../etc/passwd" is an error, not a request for "passwd".
+    name = os.path.basename(value)
+    if name != value or name in _RESERVED_COMPONENTS:
+        return None
+
+    # basename only knows the host platform's separator. On POSIX a backslash
+    # is an ordinary character, and "C:" is a plausible-looking name that
+    # os.path.join would treat as a drive on Windows. Rule both out everywhere
+    # so behaviour does not depend on where the service happens to run.
+    if '/' in name or '\\' in name or os.sep in name or (os.altsep and os.altsep in name):
+        return None
+    if ':' in name and len(name) >= 2 and name[1] == ':':
+        return None
+
+    return name
+
+
+def safe_relative_parts(value: Any) -> Optional[List[str]]:
+    """Split a multi-segment relative path into safe components.
+
+    For Flask's ``<path:...>`` converter, where ``a/b/c.json`` is legitimate but
+    ``../../config/config_secrets.json`` is not. Returns the component list, or
+    ``None`` if any component fails :func:`safe_path_component`.
+    """
+    if not isinstance(value, str) or not value:
+        return None
+    if value.startswith('/') or value.startswith('\\'):
+        return None
+
+    parts: List[str] = []
+    for raw in value.replace('\\', '/').split('/'):
+        if raw == '':
+            # A trailing or doubled slash names nothing; skip it rather than
+            # rejecting a path a browser may well send.
+            continue
+        part = safe_path_component(raw)
+        if part is None:
+            return None
+        parts.append(part)
+
+    return parts or None
+
+
+def resolve_under(base: Union[str, Path], *parts: Any) -> Optional[Path]:
+    """Resolve ``base/parts...``, or ``None`` if that would escape ``base``.
+
+    Each part is validated with :func:`safe_path_component` first, so the value
+    that reaches the filesystem is the sanitised one. The containment check is
+    kept as well: it is what catches a symlink inside ``base`` pointing out of
+    it, which no amount of name validation can see.
+    """
+    safe_parts: List[str] = []
+    for part in parts:
+        component = safe_path_component(part)
+        if component is None:
+            return None
+        safe_parts.append(component)
+
+    try:
+        base_resolved = Path(base).resolve()
+        candidate = base_resolved.joinpath(*safe_parts).resolve()
+        candidate.relative_to(base_resolved)
+    except (OSError, ValueError, TypeError):
+        return None
+
+    return candidate

src/wifi_manager.py

@@ -36,7 +36,7 @@ import os
 import time
 import re
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Tuple
 from dataclasses import dataclass
 
 logger = logging.getLogger(__name__)
@@ -1248,14 +1248,28 @@ class WiFiManager:
     def connect_to_network(self, ssid: str, password: str) -> Tuple[bool, str]:
         """
         Connect to a WiFi network with failsafe to restore original connection on failure.
-        
+
         Args:
             ssid: Network SSID
             password: Network password (empty for open networks)
-            
+
         Returns:
             Tuple of (success, message)
         """
+        # Both values arrive verbatim from POST /api/v3/wifi/connect and end up
+        # as nmcli argv entries. There is no shell here, so no metacharacter
+        # can start a second command -- but nmcli reads a leading "-" as an
+        # option, so an SSID of "--ask" or "-t" is a request to run nmcli
+        # differently rather than to join a network. See _validate_ssid.
+        ssid, error = self._validate_ssid(ssid)
+        if error:
+            logger.warning("Rejected WiFi connect request: %s", error)
+            return False, error
+        password, error = self._validate_wifi_password(password)
+        if error:
+            logger.warning("Rejected WiFi connect request: %s", error)
+            return False, error
+
         # Save current connection info for failsafe restoration
         original_connection = None
         original_ssid = None
@@ -1635,6 +1649,66 @@ class WiFiManager:
             self._show_led_message("Connection error", duration=5)
             return False, str(e)
 
+    # 802.11 caps an SSID at 32 octets. Control characters cannot appear in a
+    # real one, and a leading "-" would be read by nmcli as an option rather
+    # than a network name.
+    _SSID_MAX_OCTETS = 32
+    # WPA-PSK passphrases are 8-63 printable ASCII characters, or a 64-char hex
+    # key. Anything outside that cannot authenticate, so refusing it early
+    # costs nothing and keeps argv clean.
+    _PSK_MIN_LEN = 8
+    _PSK_MAX_LEN = 63
+
+    @classmethod
+    def _validate_ssid(cls, ssid: Any) -> Tuple[str, Optional[str]]:
+        """Return (ssid, None) for a usable SSID, or ('', reason) to refuse it.
+
+        Returns the value rather than a boolean so callers pass on what was
+        checked instead of re-reading the original.
+        """
+        if not isinstance(ssid, str):
+            return '', "SSID must be text"
+        ssid = ssid.strip()
+        if not ssid:
+            return '', "SSID cannot be empty"
+        if len(ssid.encode('utf-8')) > cls._SSID_MAX_OCTETS:
+            return '', f"SSID is longer than {cls._SSID_MAX_OCTETS} bytes"
+        if any(ord(ch) < 0x20 or ord(ch) == 0x7F for ch in ssid):
+            return '', "SSID contains control characters"
+        if ssid.startswith('-'):
+            # nmcli would take this for an option, not a network name.
+            return '', "SSID cannot start with '-'"
+        return ssid, None
+
+    @classmethod
+    def _validate_wifi_password(cls, password: Any) -> Tuple[str, Optional[str]]:
+        """Return (password, None) for a usable passphrase, or ('', reason).
+
+        An empty password means an open network and is allowed through.
+        """
+        if password is None:
+            return '', None
+        if not isinstance(password, str):
+            return '', "Password must be text"
+        if password == '':
+            return '', None
+        if any(ord(ch) < 0x20 or ord(ch) == 0x7F for ch in password):
+            return '', "Password contains control characters"
+        if not password.isascii():
+            # WPA-PSK passphrases are printable ASCII only; NetworkManager
+            # rejects anything else.
+            return '', "Password must be ASCII"
+        if password.startswith('-'):
+            # Same reason as the SSID: nmcli would read it as an option.
+            return '', "Password cannot start with '-'"
+        is_hex_key = len(password) == 64 and all(c in '0123456789abcdefABCDEF' for c in password)
+        if not is_hex_key and not (cls._PSK_MIN_LEN <= len(password) <= cls._PSK_MAX_LEN):
+            return '', (
+                f"Password must be {cls._PSK_MIN_LEN}-{cls._PSK_MAX_LEN} characters "
+                f"(or a 64-character hex key)"
+            )
+        return password, None
+
     @staticmethod
     def _is_wrong_password_error(error_msg: str) -> bool:
         """Return True when nmcli's error output indicates an authentication failure."""