fix(themes): never treat an unproven credential as the engine's account

Two Codex P1s, both about credential-to-engine identity. The second
undermines the refusal added in efe9f1d, so that fix was incomplete.

An explicit engine URL is never provably paired with a credential. On HA
OS, _addon_credential_best_effort() hands back the DISCOVERED Puppet app's
credential without checking it identifies the engine that URL points at, so
a sidecar URL plus a running app produced a credential for the wrong
account -- and my earlier check, which only tested for a MISSING
addon_credential, passed it straight through. The engine-theme actions now
refuse whenever an engine URL is set explicitly, regardless of what
discovery turned up. That pairing was documented as a safe no-op, and it
was, while the guard only wrote back its own snapshot; it stopped being one
when these actions began reading and writing a profile on request.

The capture guard has the same uncertainty but must not simply go dark:
its client-credential fallback is what protects the common single-user
Docker setup, where ha-mcp and the engine really are the same user. It
stays active and now tracks whether its credential is provably the
engine's. When it is not, the report says so and tells the agent to verify
before restoring, rather than implying the engine's account was the one
observed.

Also fixes an import in the new resolver guard that reached beyond the
package (...config from src/ha_mcp/tools/), which turned the refusal into
an INTERNAL_ERROR. The identity tests caught it.

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

Author: kingpanther13

src/ha_mcp/dashboard_screenshot/theme_guard.py

@@ -191,6 +191,10 @@ class ThemeGuard:
     _snapshot: Any = None
     _snapshot_taken: bool = False
     changed_from: Any = None
+    # False when the credential is ha-mcp's own rather than the engine's own
+    # token: it MAY be the same Home Assistant user (the common single-user
+    # setup) but that cannot be established, so the report says so.
+    credential_is_engine: bool = True
 
     @classmethod
     def for_capture(
@@ -200,12 +204,17 @@ def for_capture(
     ) -> ThemeGuard:
         """Resolve the engine user's credential for one capture batch."""
         credential = addon_credential or _client_credential(client)
+        # Only the add-on's own token provably belongs to the engine. The
+        # client fallback MAY be the same user (the common single-user setup)
+        # but that cannot be established, so the report says so rather than
+        # implying the engine account was the one observed.
+        provably_engine = addon_credential is not None
         if credential is None:
             logger.debug(
                 "Dashboard theme guard inactive: no engine credential is "
                 "discoverable in this deployment"
             )
-        return cls(credential=credential)
+        return cls(credential=credential, credential_is_engine=provably_engine)
 
     @asynccontextmanager
     async def _session(self) -> AsyncIterator[HomeAssistantWebSocketClient]:
@@ -353,6 +362,14 @@ async def detect_change(self) -> None:
             "meantime. To stop this happening at all, give the screenshot "
             "engine its own Home Assistant user and long-lived token, so "
             "its writes land on an account nobody looks at."
+            + (
+                ""
+                if self.credential_is_engine
+                else " NOTE: this was observed with ha-mcp's own Home "
+                "Assistant credential rather than the engine's own token, so "
+                "it is the engine's account only if both run as the same "
+                "user. Verify before restoring."
+            )
         )
 
 

src/ha_mcp/tools/tools_themes.py

@@ -46,11 +46,22 @@ async def _engine_credential(self) -> Any:
         engine-account setup is NOT the account ha-mcp itself authenticates
         as -- so these actions cannot simply reuse ha-mcp's own client.
         """
+        from ..config import get_global_settings
         from ..dashboard_screenshot.provision import resolve_engine
         from ..dashboard_screenshot.theme_guard import ThemeGuard
 
+        explicit_url = (
+            get_global_settings().dashboard_screenshot_engine_url or ""
+        ).strip()
         engine_target = await resolve_engine()
-        if engine_target.addon_credential is None:
+        # An explicit URL is never provably paired with a credential. Even on
+        # HA OS, _addon_credential_best_effort() hands back the DISCOVERED
+        # Puppet app's credential without checking it identifies the engine
+        # that URL points at -- so a sidecar URL plus a running app yields a
+        # credential for the wrong account. That was a safe no-op while the
+        # guard only wrote back its own snapshot; it is not safe now that
+        # these actions read and write a profile on request.
+        if explicit_url or engine_target.addon_credential is None:
             # An explicitly configured engine URL yields no addon_credential,
             # so the only fallback is ha-mcp's OWN credential -- which under
             # the dedicated-engine-account setup this feature recommends is a
@@ -65,9 +76,10 @@ async def _engine_credential(self) -> Any:
                     "identified, so its theme cannot be read or written.",
                     suggestions=[
                         (
-                            "This applies to an explicitly configured engine "
-                            + "URL (a Docker/standalone sidecar), where the "
-                            + "engine's own token is not discoverable."
+                            "This applies whenever an engine URL is set "
+                            + "explicitly: the engine's own token is not "
+                            + "discoverable, and a credential discovered via "
+                            + "the Supervisor is not provably that engine's."
                         ),
                         (
                             "Restore the theme from that account's own "

tests/src/unit/test_dashboard_screenshot_theme_guard.py

@@ -755,3 +755,37 @@ async def test_remote_cleartext_session_warns_and_sends_nothing(self) -> None:
 
         assert _FakeWsClient.instances == []
         assert guard.warnings
+
+
+class TestCredentialProvenance:
+    """A client-fallback credential is not provably the engine's account."""
+
+    def test_addon_credential_is_provably_the_engine(self) -> None:
+        guard = ThemeGuard.for_capture(_PUPPET_CREDENTIAL, _client())
+        assert guard.credential_is_engine is True
+
+    def test_client_fallback_is_not_provably_the_engine(self) -> None:
+        guard = ThemeGuard.for_capture(None, _client())
+        assert guard.credential is not None
+        assert guard.credential_is_engine is False
+
+    async def test_uncertain_provenance_is_stated_in_the_report(self) -> None:
+        """The agent must not restore a profile we cannot vouch for."""
+        _FakeWsClient.user_data[THEME_USER_DATA_KEY] = dict(_DARK_THEME)
+        guard = ThemeGuard.for_capture(None, _client())
+        await guard.take_snapshot()
+        _FakeWsClient.user_data[THEME_USER_DATA_KEY] = dict(_CLOBBERED_THEME)
+        await guard.detect_change()
+
+        assert guard.warnings
+        assert "only if both run as the same user" in guard.warnings[0]
+
+    async def test_engine_credential_report_carries_no_caveat(self) -> None:
+        _FakeWsClient.user_data[THEME_USER_DATA_KEY] = dict(_DARK_THEME)
+        guard = ThemeGuard.for_capture(_PUPPET_CREDENTIAL, None)
+        await guard.take_snapshot()
+        _FakeWsClient.user_data[THEME_USER_DATA_KEY] = dict(_CLOBBERED_THEME)
+        await guard.detect_change()
+
+        assert guard.warnings
+        assert "same user" not in guard.warnings[0]