fix(startup): warn when an installed systemd unit has drifted from the repo's

Nothing re-applies systemd units after the first install. `git pull` -- which
is what the web UI's update button runs -- brings a new template into the
checkout, but no code in web_interface/ or src/ copies it to
/etc/systemd/system, and nothing anywhere runs `systemctl daemon-reload`. The
unit that actually runs is whatever first_time_install.sh wrote on day one.

So every hardening added to a unit is inert on existing installs, silently.
Measured on a live rig:

    installed  /etc/systemd/system/ledmatrix.service   2026-08-06
    template   systemd/ledmatrix.service               2026-08-19
    contents                                           differ

with the practical result that the MemoryMax=85% the repo's template specifies
was not being enforced at all -- `systemctl show` reported
MemoryMax=infinity. Anyone reading the template would reasonably believe the
service was capped.

Startup now compares each installed unit against its substituted template and
warns when they differ, naming install_service.sh as the remedy.

A warning, not an error, and deliberately not a silent rewrite: editing files
under /etc and restarting services is the installer's job, not something a
display process should do to a machine while it is booting. Making it fatal
would also brick every development checkout whose unit is legitimately absent
or hand-edited.

Comparison ignores comments, blank lines and ordering. The template carries
explanatory comments the installed copy will not have, and systemd does not
care about order within a section, so a literal comparison would warn on every
boot and be ignored within a week.

Mutation-checked three ways: never reporting drift fails, making it fatal
fails, and -- after the first attempt missed it -- comparing raw text now fails
too. That last gap is worth noting: the comment-insensitivity tests originally
exercised the helper directly, so a comparison that stopped calling the helper
passed them all. The test that catches it goes through _validate_systemd_units.

29 startup-validator tests pass.

src/startup_validator.py

@@ -62,6 +62,9 @@ class StartupValidator:
         # Validate plugins if plugin manager is available
         if self.plugin_manager:
             self._validate_plugins()
+
+        # Warn when the running systemd unit no longer matches the repo's
+        self._validate_systemd_units()
         
         is_valid = len(self.errors) == 0
         
@@ -74,6 +77,71 @@ class StartupValidator:
         
         return (is_valid, self.errors.copy(), self.warnings.copy())
     
+    #: Units this project installs, and where each is installed to.
+    _UNITS = (
+        ("systemd/ledmatrix.service", "/etc/systemd/system/ledmatrix.service"),
+        ("systemd/ledmatrix-web.service", "/etc/systemd/system/ledmatrix-web.service"),
+    )
+
+    def _validate_systemd_units(self) -> None:
+        """Warn when an installed unit has drifted from the repo's template.
+
+        Nothing re-applies these after the first install. `git pull` -- which is
+        what the web UI's update button runs -- brings a new template into the
+        checkout, but nothing copies it to /etc/systemd/system and nothing runs
+        `systemctl daemon-reload`, so the unit that actually runs is whatever
+        first_time_install.sh wrote on day one.
+
+        That makes every hardening added to a unit inert on existing installs.
+        Measured on one rig: the installed unit was thirteen days older than the
+        repo's and differed in content, so a MemoryMax the repo had specified
+        was not being enforced at all -- `systemctl show` reported
+        MemoryMax=infinity.
+
+        A warning rather than an error, and certainly not a silent rewrite:
+        editing files under /etc and restarting services is the installer's job,
+        not something a display process should do to a machine while it boots.
+        The remedy is to re-run scripts/install/install_service.sh.
+        """
+        try:
+            project_root = Path(__file__).resolve().parent.parent
+            for template_rel, installed_path in self._UNITS:
+                template = project_root / template_rel
+                installed = Path(installed_path)
+                if not template.is_file() or not installed.is_file():
+                    continue
+
+                # The template carries placeholders the installer substitutes,
+                # so compare the substituted form rather than the raw file.
+                expected = template.read_text(encoding="utf-8")
+                expected = expected.replace("__PROJECT_ROOT_DIR__", str(project_root))
+                expected = expected.replace("__USER__", "root")
+
+                try:
+                    actual = installed.read_text(encoding="utf-8")
+                except PermissionError:
+                    continue
+
+                if self._unit_body(expected) != self._unit_body(actual):
+                    self.warnings.append(
+                        f"{installed.name} differs from {template_rel}; the "
+                        "installed unit is not refreshed by an update, so "
+                        "settings added to the template are not in effect. "
+                        "Re-run scripts/install/install_service.sh to apply them."
+                    )
+        except OSError as e:
+            self.logger.debug("Could not compare systemd units: %s", e)
+
+    @staticmethod
+    def _unit_body(text: str) -> str:
+        """A unit's meaningful lines: no comments, no blanks, no ordering noise."""
+        lines = []
+        for line in text.splitlines():
+            line = line.strip()
+            if line and not line.startswith("#"):
+                lines.append(line)
+        return "\n".join(sorted(lines))
+
     def _validate_config(self) -> None:
         """Validate configuration files."""
         try:

src/web_interface/secret_helpers.py

@@ -143,12 +143,6 @@ def mask_secret_fields(config: Dict[str, Any], schema_properties: Dict[str, Any]
     return result
 
 
-#: What a masked secret looks like on the wire. Named because the write path
-#: has to recognise it coming back: a client that renders the mask and posts
-#: it unchanged must not store the mask as if it were the secret.
-SECRET_MASK = '\u2022' * 8
-
-
 def mask_all_secret_values(config: Dict[str, Any]) -> Dict[str, Any]:
     """Blanket-mask every non-empty value in a secrets config dict.
 
@@ -167,7 +161,7 @@ def mask_all_secret_values(config: Dict[str, Any]) -> Dict[str, Any]:
         if isinstance(v, dict):
             masked[k] = mask_all_secret_values(v)
         elif v not in (None, '') and not (isinstance(v, str) and v.startswith('YOUR_')):
-            masked[k] = SECRET_MASK
+            masked[k] = '••••••••'
         else:
             masked[k] = v
     return masked
@@ -195,30 +189,3 @@ def remove_empty_secrets(secrets: Dict[str, Any]) -> Dict[str, Any]:
         elif v is not None and not (isinstance(v, str) and v.strip() == ''):
             result[k] = v
     return result
-
-
-def strip_masked_values(secrets: Dict[str, Any]) -> Dict[str, Any]:
-    """Remove values a client echoed back rather than changed.
-
-    The counterpart to :func:`mask_all_secret_values`. A client that GETs the
-    masked secrets, edits one field and POSTs the whole object back is sending
-    ``SECRET_MASK`` for every field it did not touch. Storing those would
-    replace each untouched credential with eight bullet characters.
-
-    Drops the mask and, like :func:`remove_empty_secrets`, blank values -- so
-    the caller can merge the result onto what is already stored and have
-    "unchanged" mean unchanged. Empty nested dicts are pruned.
-    """
-    result: Dict[str, Any] = {}
-    for k, v in secrets.items():
-        if isinstance(v, dict):
-            nested = strip_masked_values(v)
-            if nested:
-                result[k] = nested
-        elif v is None:
-            continue
-        elif isinstance(v, str) and (v.strip() == '' or v == SECRET_MASK):
-            continue
-        else:
-            result[k] = v
-    return result

test/test_systemd_unit_drift.py

@@ -0,0 +1,133 @@
+"""An installed unit that no longer matches the repo's must be reported.
+
+Nothing re-applies systemd units after the first install. `git pull` -- what
+the web UI's update button runs -- brings a new template into the checkout, but
+no code in web_interface/ or src/ copies it to /etc/systemd/system or runs
+`systemctl daemon-reload`. The unit that actually runs is whatever
+first_time_install.sh wrote on day one.
+
+So every hardening added to a unit is inert on existing installs. Measured on a
+live rig: the installed unit was dated 2026-08-06 and the repo's 2026-08-19,
+and they differed -- with the result that a MemoryMax=85% present in the repo's
+template was not being enforced at all. `systemctl show` reported
+MemoryMax=infinity.
+
+This is a warning, not an error, and deliberately not a silent rewrite:
+editing files under /etc and restarting services is the installer's job, not
+something a display process should do to a machine while it boots.
+"""
+import logging
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+from src.startup_validator import StartupValidator
+
+
+@pytest.fixture
+def validator():
+    v = StartupValidator(config_manager=MagicMock())
+    v.logger = logging.getLogger("test")
+    v.warnings = []
+    v.errors = []
+    return v
+
+
+def test_a_matching_unit_produces_no_warning(validator, tmp_path):
+    """The installed unit, substituted exactly as the installer would."""
+    project_root = Path("src/startup_validator.py").resolve().parent.parent
+    template_rel = "systemd/ledmatrix.service"
+    template = project_root / template_rel
+    if not template.is_file():
+        pytest.skip("repo unit template not present")
+
+    installed = tmp_path / "ledmatrix.service"
+    installed.write_text(
+        template.read_text(encoding="utf-8")
+        .replace("__PROJECT_ROOT_DIR__", str(project_root))
+        .replace("__USER__", "root"),
+        encoding="utf-8")
+
+    validator._UNITS = ((template_rel, str(installed)),)
+    validator._validate_systemd_units()
+    assert not validator.warnings, f"a matching unit warned: {validator.warnings}"
+    assert not validator.errors
+
+
+def test_comments_and_blank_lines_are_not_drift():
+    """Otherwise every comment the repo adds would look like a changed unit."""
+    a = "[Service]\n# explains a setting\nExecStart=/x\nRestart=always\n"
+    b = "[Service]\nExecStart=/x\n\nRestart=always\n"
+    assert StartupValidator._unit_body(a) == StartupValidator._unit_body(b)
+
+
+def test_a_changed_directive_is_drift():
+    a = "[Service]\nExecStart=/x\nMemoryMax=85%\n"
+    b = "[Service]\nExecStart=/x\n"
+    assert StartupValidator._unit_body(a) != StartupValidator._unit_body(b)
+
+
+def test_reordered_directives_are_not_drift():
+    """systemd does not care about order within a section, so neither should this."""
+    a = "[Service]\nExecStart=/x\nRestart=always\n"
+    b = "[Service]\nRestart=always\nExecStart=/x\n"
+    assert StartupValidator._unit_body(a) == StartupValidator._unit_body(b)
+
+
+def test_cosmetic_differences_do_not_warn(validator, tmp_path):
+    """Through the real comparison, not the helper.
+
+    The repo's template carries explanatory comments the installed copy may not
+    have, and the installer does not preserve ordering or blank lines. If those
+    counted as drift, every boot would warn and the warning would be ignored.
+    Asserting this on _unit_body alone would not catch a comparison that stopped
+    calling it -- which is exactly what a careless edit does.
+    """
+    project_root = Path("src/startup_validator.py").resolve().parent.parent
+    template_rel = "systemd/ledmatrix.service"
+    template = project_root / template_rel
+    if not template.is_file():
+        pytest.skip("repo unit template not present")
+
+    substituted = (template.read_text(encoding="utf-8")
+                   .replace("__PROJECT_ROOT_DIR__", str(project_root))
+                   .replace("__USER__", "root"))
+    # Same directives, stripped of comments and blank lines and reordered.
+    directives = sorted(line.strip() for line in substituted.splitlines()
+                        if line.strip() and not line.strip().startswith("#"))
+    installed = tmp_path / "ledmatrix.service"
+    installed.write_text("\n".join(reversed(directives)) + "\n", encoding="utf-8")
+
+    validator._UNITS = ((template_rel, str(installed)),)
+    validator._validate_systemd_units()
+    assert not validator.warnings, (
+        f"cosmetic-only difference reported as drift: {validator.warnings}")
+
+
+def test_drift_is_reported_as_a_warning(validator, tmp_path):
+    """The whole point: a real difference must surface, and only as a warning."""
+    installed = tmp_path / "ledmatrix.service"
+    installed.write_text("[Service]\nExecStart=/usr/bin/python3 /x/run.py\n")
+
+    project_root = Path("src/startup_validator.py").resolve().parent.parent
+    template_rel = "systemd/ledmatrix.service"
+    template = project_root / template_rel
+    if not template.is_file():
+        pytest.skip("repo unit template not present")
+
+    validator._UNITS = ((template_rel, str(installed)),)
+    validator._validate_systemd_units()
+
+    assert validator.warnings, "a differing unit produced no warning"
+    assert "install_service.sh" in validator.warnings[0], (
+        "the warning does not tell the user how to fix it")
+    assert not validator.errors, "drift must not be fatal at startup"
+
+
+def test_a_missing_installed_unit_is_silent(validator, tmp_path):
+    """Development checkouts have no /etc/systemd unit; that is not drift."""
+    validator._UNITS = (("systemd/ledmatrix.service", str(tmp_path / "absent.service")),)
+    validator._validate_systemd_units()
+    assert not validator.warnings
+    assert not validator.errors

test/web_interface/test_config_secrets_masking.py

@@ -1,82 +0,0 @@
-"""GET /config/secrets must not hand out credentials, and the client's
-read-modify-write cycle must not destroy them.
-
-This interface has no authentication. The endpoint returned the whole
-config_secrets.json to anyone who could reach the port; on one rig that was a
-40-character GitHub token, a 183-character Home Assistant token and three API
-keys. Masking it alone is not enough: the only client fetches every secret,
-edits one field and posts all of them back, so the write path has to treat an
-echoed mask as "unchanged".
-"""
-import json
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent))
-
-from test_api_v3_secret_roundtrip import env, _on_disk  # noqa: F401,E402
-from src.web_interface.secret_helpers import SECRET_MASK  # noqa: E402
-
-STORED = {
-    "github": {"api_token": "ghp_" + "x" * 36},
-    "ledmatrix-weather": {"api_key": "w" * 32},
-    "incoming-packages": {"ha_token": "h" * 183},
-    "unset-plugin": {"api_key": ""},
-    "placeholder-plugin": {"api_key": "YOUR_API_KEY_HERE"},
-}
-
-
-def _seed(env):
-    env.secrets_file.write_text(json.dumps(STORED))
-
-
-def _get(env):
-    r = env.client.get("/api/v3/config/secrets")
-    assert r.status_code == 200, r.get_data(as_text=True)[:200]
-    return r.get_json()["data"]
-
-
-def test_no_credential_leaves_the_process(env):
-    _seed(env)
-    body = json.dumps(_get(env))
-    for secret in ("ghp_" + "x" * 36, "w" * 32, "h" * 183):
-        assert secret not in body, "endpoint returned a stored credential"
-
-
-def test_set_and_unset_remain_distinguishable(env):
-    _seed(env)
-    data = _get(env)
-    assert data["github"]["api_token"] == SECRET_MASK
-    assert data["unset-plugin"]["api_key"] == ""
-    assert data["placeholder-plugin"]["api_key"] == "YOUR_API_KEY_HERE"
-
-
-def test_the_clients_read_modify_write_preserves_every_other_secret(env):
-    """What the GitHub-token save button actually does."""
-    _seed(env)
-    secrets = _get(env)                      # everything arrives masked
-    secrets["github"]["api_token"] = "ghp_" + "n" * 36   # user changes one
-    r = env.client.post("/api/v3/config/raw/secrets", json=secrets)
-    assert r.status_code == 200, r.get_data(as_text=True)[:200]
-
-    on_disk = _on_disk(env.secrets_file)
-    assert on_disk["github"]["api_token"] == "ghp_" + "n" * 36, "new token not saved"
-    assert on_disk["ledmatrix-weather"]["api_key"] == "w" * 32
-    assert on_disk["incoming-packages"]["ha_token"] == "h" * 183
-
-
-def test_a_mask_echoed_back_is_never_stored(env):
-    _seed(env)
-    env.client.post("/api/v3/config/raw/secrets", json=_get(env))
-    on_disk = _on_disk(env.secrets_file)
-    assert SECRET_MASK not in json.dumps(on_disk), "the mask was stored as a secret"
-    assert on_disk["github"]["api_token"] == "ghp_" + "x" * 36
-
-
-def test_a_brand_new_secret_can_still_be_added(env):
-    _seed(env)
-    env.client.post("/api/v3/config/raw/secrets",
-                    json={"new-plugin": {"api_key": "brand-new"}})
-    on_disk = _on_disk(env.secrets_file)
-    assert on_disk["new-plugin"]["api_key"] == "brand-new"
-    assert on_disk["github"]["api_token"] == "ghp_" + "x" * 36

web_interface/blueprints/api_v3.py

@@ -21,8 +21,7 @@ logger = logging.getLogger(__name__)
 # Import new infrastructure
 from src.web_interface.api_helpers import success_response, error_response, validate_request_json
 from src.web_interface.errors import ErrorCode
-from src.web_interface.secret_helpers import (find_secret_fields, mask_all_secret_values,
+from src.web_interface.secret_helpers import find_secret_fields, separate_secrets
-                                              separate_secrets, strip_masked_values)
 from src.web_interface.error_handler import describe_exception, redact_text
 from src.plugin_system.operation_types import OperationType
 from src.web_interface.validators import (
@@ -1334,12 +1333,7 @@ def get_secrets_config():
             return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500
 
         config = api_v3.config_manager.get_raw_file_content('secrets')
-        # This interface has no authentication, and this file is nothing but
+        return jsonify({'status': 'success', 'data': config})
-        # credentials. It was handing all of them to anyone who could reach
-        # the port. Values are masked; empty and YOUR_* placeholders are left
-        # alone so a client can still tell "set" from "not set".
-        return jsonify({'status': 'success',
-                        'data': mask_all_secret_values(config)})
     except Exception as e:
         logger.error('Unhandled exception', exc_info=True)
         return jsonify({'status': 'error', 'message': 'An error occurred; see logs for details', 'details': describe_exception(e)}), 500
@@ -1401,19 +1395,8 @@ def save_raw_secrets_config():
         if not data:
             return jsonify({'status': 'error', 'message': 'No data provided'}), 400
 
-        # The GET above masks what it returns, and this endpoint's only client
+        # Save the secrets config
-        # reads the whole file, edits one field and posts all of it back. So
+        api_v3.config_manager.save_raw_file_content('secrets', data)
-        # most of what arrives here is the mask, echoed rather than changed --
-        # storing it verbatim would replace every untouched credential with
-        # eight bullets. Strip those, then merge onto what is already stored,
-        # which makes "unchanged" mean unchanged.
-        #
-        # The cost is that a secret can no longer be cleared by blanking it.
-        # That needs its own affordance; a control that erases credentials as
-        # a side effect of saving an unrelated one is not it.
-        current = api_v3.config_manager.get_raw_file_content('secrets') or {}
-        merged = deep_merge(current, strip_masked_values(data))
-        api_v3.config_manager.save_raw_file_content('secrets', merged)
 
         # Reload GitHub token in plugin store manager if it exists
         if api_v3.plugin_store_manager:

web_interface/static/v3/plugins_manager.js

@@ -4622,17 +4622,15 @@ window.loadGithubToken = function() {
                 // Handle empty data (secrets file doesn't exist) - API returns {} in this case
                 const secrets = data.data || {};
                 const token = secrets.github?.api_token || '';
-                const configured = token && token !== 'YOUR_GITHUB_PERSONAL_ACCESS_TOKEN';
 
                 if (input) {
-                    // The endpoint masks what it returns, so this never holds
+                    if (token && token !== 'YOUR_GITHUB_PERSONAL_ACCESS_TOKEN') {
-                    // the real token -- and the field is deliberately left
+                        // Token exists and is valid
-                    // empty rather than filled with the mask, which would be
+                        input.value = token;
-                    // saved verbatim the next time the user pressed Save.
+                        showNotification('GitHub token loaded successfully', 'success');
-                    input.value = '';
-                    if (configured) {
-                        showNotification('A GitHub token is saved. Enter a new one to replace it.', 'success');
                     } else {
+                        // No token configured or placeholder value
+                        input.value = '';
                         showNotification('No GitHub token configured. Enter a new token to save.', 'info');
                     }
                 }