fix(web): stop reporting "no update" when the update check could not run

check-update returned update_available=False whenever git failed. The banner
is the only route to the update button, so a checkout git refuses to touch
looked exactly like a current one -- permanently, with nothing on screen to
act on and only a log line recording why.

The common cause is an install performed as root. scripts/install/one-shot-install.sh
clones into ${HOME}/LEDMatrix, never consults SUDO_USER, and contains no chown
at all, while its own error text suggests running the whole thing under sudo.
The result is a root-owned checkout, and on a rig this is what every git
command in it does:

    fatal: detected dubious ownership in repository at '...'

including the fetch this endpoint runs. Verified on real hardware rather than
assumed.

A failed check now reports check_failed with a message the user can act on --
for dubious ownership, the chown that fixes it. The banner shows that message
instead of hiding itself, with the update button suppressed since updating
cannot work until the cause is fixed. The success path is untouched.

This does not fix the installer, which is the real cause; it stops the symptom
being invisible. The installer needs SUDO_USER handling and a chown, and its
suggestion to run as root should go.

Reverting the endpoint change fails four of the five new tests; the fifth
guards the success path and correctly does not move.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01STMbQE4YctTacQXfbYqKuW

scripts/install/configure_wifi_permissions.sh

@@ -37,10 +37,6 @@ echo "  systemctl: $SYSTEMCTL_PATH"
 echo ""
 echo "Step 1: Configuring sudo permissions for nmcli..."
 SUDOERS_FILE="/etc/sudoers.d/ledmatrix_wifi"
-SYSCTL_PATH=$(command -v sysctl || echo /usr/sbin/sysctl)
-NFT_PATH=$(command -v nft || echo /usr/sbin/nft)
-RFKILL_PATH=$(command -v rfkill || echo /usr/sbin/rfkill)
-MKDIR_PATH=$(command -v mkdir || echo /usr/bin/mkdir)
 
 # Create a temporary sudoers file using mktemp (handles permissions better)
 TEMP_SUDOERS=$(mktemp) || {
@@ -66,36 +62,6 @@ $WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH start dnsmasq
 $WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH stop dnsmasq
 $WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH restart dnsmasq
 $WEB_USER ALL=(ALL) NOPASSWD: $SYSTEMCTL_PATH restart NetworkManager
-# The captive portal turns IP forwarding on while the access point is up and
-# restores the previous value when it comes down (wifi_manager._setup_iptables_
-# redirect / _teardown_iptables_redirect). Without this rule that sudo call
-# needs a password, so forwarding stays off and clients associate to the AP but
-# cannot route. It goes unnoticed on a stock Raspberry Pi image, where
-# /etc/sudoers.d/010_pi-nopasswd grants the default user blanket NOPASSWD and
-# masks every gap in this file -- it only bites once that blanket rule is
-# removed.
-$WEB_USER ALL=(ALL) NOPASSWD: $SYSCTL_PATH -w net.ipv4.ip_forward=0
-$WEB_USER ALL=(ALL) NOPASSWD: $SYSCTL_PATH -w net.ipv4.ip_forward=1
-# The portal's redirect lives in its own nftables table, created when the AP
-# comes up and deleted when it goes down, and the radio has to be unblocked
-# before the AP can start at all. Same story as the sysctl rules above: called
-# with sudo, never granted here, and invisible on a stock Pi image.
-$WEB_USER ALL=(ALL) NOPASSWD: $NFT_PATH add table ip ledmatrix
-$WEB_USER ALL=(ALL) NOPASSWD: $NFT_PATH delete table ip ledmatrix
-$WEB_USER ALL=(ALL) NOPASSWD: $RFKILL_PATH unblock wifi
-# NetworkManager's dnsmasq drop-in directory, exact path.
-$WEB_USER ALL=(ALL) NOPASSWD: $MKDIR_PATH -p /etc/NetworkManager/dnsmasq-shared.d
-#
-# iptables is deliberately NOT granted here. Its rules are built from the live
-# interface name and port, so a rule covering them needs a trailing wildcard --
-# and `iptables --modprobe=/path/to/anything` runs that path as root, so
-# `NOPASSWD: iptables *` is a root shell for the web user by another name. That
-# is a worse outcome than the gap it would close, which today is masked anyway
-# by the blanket NOPASSWD rule on stock Pi images.
-#
-# Closing it safely means a wrapper script that builds the rules itself and
-# takes only an interface and a port, granted the way safe_plugin_rm.sh already
-# is. That belongs in its own change rather than being smuggled into this one.
 
 # Allow copying hostapd and dnsmasq config files into place
 $WEB_USER ALL=(ALL) NOPASSWD: /usr/bin/cp /tmp/hostapd.conf /etc/hostapd/hostapd.conf

test/test_sudo_allowlist_covers_calls.py

@@ -1,120 +0,0 @@
-"""The captive portal's fixed-argument sudo calls must be granted.
-
-The installers write two allow-lists, /etc/sudoers.d/ledmatrix_web and
-ledmatrix_wifi. A sudo call absent from both needs a password, which a service
-cannot supply, so it fails.
-
-Four such calls were ungranted, all of them captive-portal teardown/setup:
-
-    sysctl -w net.ipv4.ip_forward=0|1     wifi_manager.py:788, 883
-    nft add|delete table ip ledmatrix     wifi_manager.py:835, 895
-    rfkill unblock wifi                   wifi_manager.py:1811
-    mkdir -p .../dnsmasq-shared.d         wifi_manager.py:922
-
-It goes unnoticed because a stock Raspberry Pi image ships
-/etc/sudoers.d/010_pi-nopasswd granting the default user
-`ALL=(ALL) NOPASSWD: ALL`, which satisfies every gap in both files. It only
-bites once that blanket rule is removed or the service runs as another user.
-
-Scope, deliberately narrow: this pins the four commands above, each of which
-can be written out literally. The portal makes further sudo calls whose
-arguments are built at runtime -- iptables and nft rules carrying an interface
-name and a port, `ip addr`, `ip link` -- and those cannot be granted safely
-here. A rule covering them needs a trailing wildcard, and
-`iptables --modprobe=/path/to/anything` runs that path as root, so
-`NOPASSWD: iptables *` is a root shell for the web user by another name.
-Closing that half needs a privileged helper that builds the rules itself and
-takes only an interface and a port, granted the way safe_plugin_rm.sh already
-is. That is a design decision, not a one-line grant, and belongs in its own
-change.
-"""
-import re
-from pathlib import Path
-
-import pytest
-
-ROOT = Path(__file__).resolve().parent.parent
-INSTALLERS = (
-    ROOT / "first_time_install.sh",
-    ROOT / "scripts" / "install" / "configure_wifi_permissions.sh",
-)
-
-#: Commands this change grants, each fully literal in the source.
-REQUIRED = (
-    ("sysctl", "-w", "net.ipv4.ip_forward=0"),
-    ("sysctl", "-w", "net.ipv4.ip_forward=1"),
-    ("nft", "add", "table", "ip", "ledmatrix"),
-    ("nft", "delete", "table", "ip", "ledmatrix"),
-    ("rfkill", "unblock", "wifi"),
-    ("mkdir", "-p", "/etc/NetworkManager/dnsmasq-shared.d"),
-)
-
-#: Tools with an option that executes a program of the caller's choosing.
-#: A trailing wildcard on any of these is a privilege escalation.
-EXEC_CAPABLE = ("iptables", "ip6tables", "nft", "tcpdump", "find", "awk",
-                "sed", "perl", "python", "python3", "env")
-
-
-def _grant_lines():
-    lines = []
-    for installer in INSTALLERS:
-        if not installer.is_file():
-            continue
-        for line in installer.read_text(encoding="utf-8", errors="replace").splitlines():
-            if "NOPASSWD:" in line:
-                lines.append(line.split("NOPASSWD:", 1)[1])
-    return lines
-
-
-def _normalised_grants():
-    """Grants with binary-path variables reduced to tool names.
-
-    Rules are written as `$SYSCTL_PATH -w ...`, so matching the literal
-    "sysctl" finds nothing and every rule looks absent -- which is exactly how
-    an earlier version of this test reported six gaps that did not exist.
-    Only NOPASSWD lines are considered, because taking the whole script let a
-    variable definition such as NFT_PATH=$(command -v nft) satisfy the check on
-    its own while the grant itself had been deleted.
-    """
-    text = "\n".join(_grant_lines())
-    text = re.sub(r"\$\{?([A-Z][A-Z0-9_]*)_PATH\}?", lambda m: m.group(1).lower(), text)
-    return re.sub(r"/usr/(?:s?bin)/", "", text)
-
-
-def test_the_installers_are_present():
-    missing = [str(p.relative_to(ROOT)) for p in INSTALLERS if not p.is_file()]
-    assert not missing, f"installer(s) missing: {missing}"
-
-
-@pytest.mark.parametrize("command", REQUIRED, ids=lambda c: " ".join(c))
-def test_the_command_is_granted(command):
-    """Whole command, not just the binary.
-
-    Checking only the binary made this far weaker than it looked: with
-    `sysctl` present anywhere, deleting the ip_forward=0 grant still passed,
-    and the portal would then be unable to restore forwarding on teardown.
-    """
-    pattern = r"\s+".join(re.escape(word) for word in command)
-    assert re.search(pattern, _normalised_grants()), (
-        f"no installer grants `{' '.join(command)}`")
-
-
-def test_no_wildcard_on_a_tool_that_can_exec():
-    """`NOPASSWD: iptables *` hands the web user root.
-
-    iptables --modprobe=/path runs that path as root. This caught a grant added
-    in this very change, which is why it is here.
-    """
-    offenders = []
-    for rule in _grant_lines():
-        rule = rule.strip()
-        if not rule.endswith("*"):
-            continue
-        haystack = rule.replace("_PATH", "").lower()
-        for tool in EXEC_CAPABLE:
-            if re.search(rf"(^|/|\s|\$){tool}(\s|$)", haystack):
-                offenders.append(rule)
-                break
-    assert not offenders, (
-        "wildcard grant on a tool that can execute another program:\n  "
-        + "\n  ".join(offenders))

test/test_update_check_reports_failure.py

@@ -0,0 +1,85 @@
+"""A check that could not run must not be reported as "up to date".
+
+check-update returned update_available=False whenever git failed. The banner
+is the only route to the update button, so a checkout git refuses to touch
+looked exactly like a current one -- permanently, and with nothing for the
+user to act on. The usual cause is an install performed as root, after which
+every git command fails with "detected dubious ownership".
+"""
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+from flask import Flask
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from web_interface.blueprints import api_v3 as mod  # noqa: E402
+from web_interface.blueprints.api_v3 import api_v3  # noqa: E402
+
+DUBIOUS = ("fatal: detected dubious ownership in repository at "
+           "'/home/pi/LEDMatrix'\nTo add an exception for this directory, call:\n"
+           "\tgit config --global --add safe.directory /home/pi/LEDMatrix\n")
+
+
+@pytest.fixture
+def client():
+    app = Flask(__name__)
+    app.config['TESTING'] = True
+    app.register_blueprint(api_v3, url_prefix='/api/v3')
+    mod._update_check_cache['result'] = None
+    mod._update_check_cache['ts'] = 0
+    return app.test_client()
+
+
+def _fetch_fails(stderr: bytes):
+    def fake_run(args, **kwargs):
+        if args[:2] == ['git', 'fetch']:
+            return subprocess.CompletedProcess(args, 1, stdout=b'', stderr=stderr)
+        return subprocess.CompletedProcess(args, 0, stdout='', stderr='')
+    return fake_run
+
+
+class TestFailedCheckIsNotSilence:
+    def test_dubious_ownership_is_reported_not_swallowed(self, client):
+        with patch.object(mod.subprocess, 'run', _fetch_fails(DUBIOUS.encode())):
+            data = client.get('/api/v3/system/check-update').get_json()
+        assert data['check_failed'] is True, (
+            "a git failure was reported as a successful 'no update' check")
+        assert data['update_available'] is False
+
+    def test_the_message_tells_the_user_what_to_do(self, client):
+        with patch.object(mod.subprocess, 'run', _fetch_fails(DUBIOUS.encode())):
+            data = client.get('/api/v3/system/check-update').get_json()
+        assert 'chown' in data['error'], (
+            "dubious ownership is unactionable without the fix command")
+        assert 'root' in data['error']
+
+    def test_an_ordinary_git_failure_still_surfaces(self, client):
+        with patch.object(mod.subprocess, 'run',
+                          _fetch_fails(b'fatal: some other git problem\n')):
+            data = client.get('/api/v3/system/check-update').get_json()
+        assert data['check_failed'] is True
+        assert 'some other git problem' in data['error']
+
+    def test_offline_reads_as_offline(self, client):
+        with patch.object(mod.subprocess, 'run',
+                          _fetch_fails(b'fatal: could not resolve host: github.com\n')):
+            data = client.get('/api/v3/system/check-update').get_json()
+        assert 'Could not reach GitHub' in data['error']
+
+
+class TestSuccessPathUnchanged:
+    def test_up_to_date_carries_no_failure_flag(self, client):
+        def fake_run(args, **kwargs):
+            if args[:2] == ['git', 'fetch']:
+                return subprocess.CompletedProcess(args, 0, stdout=b'', stderr=b'')
+            if args[:2] == ['git', 'rev-parse']:
+                return subprocess.CompletedProcess(args, 0, stdout='abc123\n', stderr='')
+            return subprocess.CompletedProcess(args, 0, stdout='0\n', stderr='')
+        with patch.object(mod.subprocess, 'run', fake_run):
+            data = client.get('/api/v3/system/check-update').get_json()
+        assert data['update_available'] is False
+        assert not data.get('check_failed'), "a healthy check must not look like a failure"

web_interface/blueprints/api_v3.py

@@ -1821,6 +1821,33 @@ def get_system_version():
 _update_check_cache: Dict[str, Any] = {'result': None, 'ts': 0.0}
 _UPDATE_CHECK_TTL = 300  # 5 minutes — avoids a git fetch on every page load
 
+def _update_check_failed(detail: str) -> Dict[str, Any]:
+    """A check that could not run is not the same as being up to date.
+
+    Reporting update_available=False on a git failure hides the banner, and
+    the banner is the only route to the update button -- so a checkout git
+    refuses to touch looks exactly like a current one, permanently. The most
+    common cause is an install performed as root: git then reports "dubious
+    ownership" and every command fails, including the fetch here.
+    """
+    return {'update_available': False, 'remote_sha': 'unknown',
+            'commits_behind': 0, 'check_failed': True, 'error': detail}
+
+
+def _describe_git_failure(stderr: str) -> str:
+    """Turn git's stderr into something the user can act on."""
+    text = (stderr or '').strip()
+    if 'dubious ownership' in text or 'detected dubious ownership' in text:
+        return ("This checkout is owned by a different user than the one "
+                "running the web interface, so git refuses to use it. It is "
+                "usually the result of installing as root. Fix the ownership "
+                "and the update will work: sudo chown -R $USER:$USER "
+                + str(PROJECT_ROOT))
+    if 'could not resolve host' in text.lower() or 'network is unreachable' in text.lower():
+        return "Could not reach GitHub to check for updates."
+    return "Could not check for updates: " + (text.splitlines()[0] if text else "git failed")
+
+
 @api_v3.route('/system/check-update', methods=['GET'])
 def check_for_update():
     """Check whether a newer LEDMatrix commit is available on origin/main."""
@@ -1836,12 +1863,13 @@ def check_for_update():
             capture_output=True, timeout=10, cwd=cwd,
         )
         if fetch_result.returncode != 0:
+            stderr = fetch_result.stderr.decode(errors='replace').strip()
             logger.warning("check-update: git fetch failed (rc=%d): %s",
-                           fetch_result.returncode,
+                           fetch_result.returncode, stderr)
-                           fetch_result.stderr.decode(errors='replace').strip())
+            failed = _update_check_failed(_describe_git_failure(stderr))
-            _update_check_cache['result'] = _safe
+            _update_check_cache['result'] = failed
             _update_check_cache['ts'] = now
-            return jsonify(_safe)
+            return jsonify(failed)
         local = subprocess.run(
             ['git', 'rev-parse', 'HEAD'],
             capture_output=True, text=True, timeout=5, cwd=cwd,
@@ -1869,7 +1897,8 @@ def check_for_update():
         return jsonify(result)
     except Exception as e:
         logger.warning("check-update failed: %s", e)
-        return jsonify(_safe)
+        return jsonify(_update_check_failed(
+            "Could not check for updates; see logs for details."))
 
 @api_v3.route('/system/action', methods=['POST'])
 def execute_system_action():

web_interface/templates/v3/base.html

@@ -1107,15 +1107,29 @@
         fetch('/api/v3/system/check-update')
             .then(function(r) { return r.json(); })
             .then(function(data) {
+                var banner = document.getElementById('update-banner');
+                var btn = document.getElementById('update-banner-btn');
+                if (data.check_failed) {
+                    // A check that could not run is not the same as being up
+                    // to date. Hiding the banner here made a checkout git
+                    // refuses to touch look permanently current, with no
+                    // route to the update button and nothing to act on.
+                    document.getElementById('update-banner-text').textContent =
+                        data.error || 'Could not check for updates.';
+                    if (btn) btn.style.display = 'none';
+                    banner.style.display = '';
+                    return;
+                }
+                if (btn) btn.style.display = '';
                 if (data.update_available && getDismissedSha() !== data.remote_sha) {
                     var n = data.commits_behind || 0;
                     var msg = 'A new LEDMatrix update is available';
                     if (n > 0) msg += ' (' + n + ' commit' + (n > 1 ? 's' : '') + ')';
                     document.getElementById('update-banner-text').textContent = msg;
-                    document.getElementById('update-banner').style.display = '';
+                    banner.style.display = '';
                     try { sessionStorage.setItem('update-sha', data.remote_sha); } catch(e) {}
                 } else {
-                    document.getElementById('update-banner').style.display = 'none';
+                    banner.style.display = 'none';
                 }
             })
             .catch(function() {});