homeassistant-ai
diff --git a/‎SECURITY.md‎
Lines changed: 27 additions & 0 deletions b/‎SECURITY.md‎
Lines changed: 27 additions & 0 deletions
diff --git a/‎docs/FAQ.md‎
Lines changed: 96 additions & 17 deletions b/‎docs/FAQ.md‎
Lines changed: 96 additions & 17 deletions
diff --git a/‎src/ha_mcp/errors.py‎
Lines changed: 8 additions & 0 deletions b/‎src/ha_mcp/errors.py‎
Lines changed: 8 additions & 0 deletions
diff --git a/‎src/ha_mcp/server.py‎
Lines changed: 43 additions & 0 deletions b/‎src/ha_mcp/server.py‎
Lines changed: 43 additions & 0 deletions
diff --git a/‎src/ha_mcp/settings_ui/locales/de.json‎
Lines changed: 4 additions & 1 deletion b/‎src/ha_mcp/settings_ui/locales/de.json‎
Lines changed: 4 additions & 1 deletion
diff --git a/‎src/ha_mcp/settings_ui/locales/en.json‎
Lines changed: 4 additions & 1 deletion b/‎src/ha_mcp/settings_ui/locales/en.json‎
Lines changed: 4 additions & 1 deletion
@@ -95,6 +95,33 @@ they are the intended behavior. Restricting HA permissions is done in Home
 Assistant (e.g. by creating a non-admin user and generating a token for that
 user).
 
+### Entity visibility enforce mode is best-effort concealment
+
+The opt-in entity visibility filter's **enforce mode** (`"enforce": true`, see
+the [Entity visibility filter FAQ](docs/FAQ.md#enforce-mode)) makes a hidden set
+unreadable across all tools: direct reads of a hidden entity are refused with a
+generic not-found before the tool runs, and content reads (dashboards, templates,
+automations, traces, logs, files) that would surface a hidden entity_id are
+refused on contact. It fails closed when the registry cannot be loaded. This is a
+strong barrier against an agent *incidentally* surfacing a hidden entity, not a
+cryptographic guarantee: enforcement is a text scan for the hidden entity_id, so a
+Jinja template or sandbox-adjacent computation that *derives* a hidden entity's
+state without ever naming its entity_id cannot be caught. The guaranteed property
+is that a hidden entity's data never flows to the client through a tool read —
+existence concealment
+is best-effort: the concealment error is a canonical not-found, and per-tool
+not-found shapes vary (details text, suggestions, bulk reads that normally
+partial-succeed), so a prober comparing error shapes may infer that an id is
+hidden rather than absent. The boundary covers Home Assistant entity data, not
+physical-world imagery: a camera the filter does not hide stays readable
+(`ha_get_camera_image`), and its frames could incidentally show a display that
+renders a hidden entity's state — hide the camera itself (denylist or its area)
+when its view is sensitive. Enforce mode is not a
+defense against an adversarial prompt author deliberately trying to exfiltrate a
+hidden entity's state, and (like the default filter) it is not a substitute for
+Home Assistant's own permission model — restrict what the configured token can
+reach in HA for a hard boundary.
+
 ### OAuth Bearer token design
 
 In OAuth mode, access and refresh tokens are HMAC-signed, stateless Bearer
 
@@ -333,19 +333,25 @@ ChatGPT (web, including Codex Work Mode) caches a connector's tool list and some
 
 By default the agent sees every entity. If auto-generated diagnostic or helper
 entities clutter search and overview results, you can hide a chosen set of them
-from the *collection* read tools (`ha_search`, `ha_get_overview`). This is
-**noise reduction, not access control** – a hidden entity is still returned by a
-direct `ha_get_state` / `ha_get_entity` on its `entity_id`, and still appears in
-automation, dashboard, and template content, so do not rely on it as a security
-boundary.
-
-**Reads only – it does not gate control tools.** The filter scopes what the
-*collection read* tools return. It does **not** stop an agent from calling a
-service on a hidden `entity_id`: gating writes is a separate concern handled by
-the Tool Security Policies engine (which matches on a call's arguments), not by
-visibility. Visibility is deliberately read-scoping only, precisely because it
-is noise reduction and cannot be a security boundary (content-bearing reads such
-as automation and template bodies would leak hidden entities anyway).
+from the *collection* read tools (`ha_search`, `ha_get_overview`). In its default
+form this is **noise reduction, not access control** – a hidden entity is still
+returned by a direct `ha_get_state` / `ha_get_entity` on its `entity_id`, and
+still appears in automation, dashboard, and template content, so do not rely on
+the default filter as a security boundary. The opt-in **[Enforce mode](#enforce-mode)**
+below turns it into a genuine read barrier: with `"enforce": true`, direct reads
+of a hidden entity are concealed and content reads that would surface one are
+refused across every tool.
+
+**Default form: reads only – it does not gate control tools.** Without enforce
+mode the filter only scopes what the *collection read* tools return. It does
+**not** stop an agent from calling a service on a hidden `entity_id`: gating
+writes is a separate concern handled by the Tool Security Policies engine (which
+matches on a call's arguments), not by visibility. In the default form,
+visibility is deliberately read-scoping only, precisely because it is noise
+reduction and cannot be a security boundary (content-bearing reads such as
+automation and template bodies would leak hidden entities anyway). Enforce mode
+changes this by also concealing hidden entities named in a write call's arguments
+(see below).
 
 The easiest way to configure it is the **Entity Visibility** tab in the ha-mcp
 settings UI (enable toggle, category checkboxes, area/label fields, per-entity
@@ -368,7 +374,8 @@ directory (the same directory as `tool_policy.json`; `/data` in the add-on) with
   "allow_entity_ids": [],
   "allow_areas": [],
   "allow_labels": [],
-  "respect_assist_exposure": false
+  "respect_assist_exposure": false,
+  "enforce": false
 }
 ```
 
@@ -409,12 +416,84 @@ it passes every active one.
   when it is *exposed*; an explicit un-expose cannot be observed there, so such an
   entity falls to its domain/device-class default and stays visible (fail-open).
 
+#### Enforce mode
+
+Set `"enforce": true` (or the **Enforce mode** toggle in the Entity Visibility
+tab) to turn the same hidden set into a genuine read barrier applied across
+**every** tool, not just `ha_search` / `ha_get_overview`. `enforce` is not a hide
+dimension — it does not change *which* entities are hidden, only how strongly the
+hiding is applied — so it is inert unless the filter is also `enabled` with at
+least one active hide dimension. What it covers:
+
+- **Direct reads are concealed.** A call whose arguments name a hidden entity_id
+  exactly (`ha_get_state`, `ha_get_history`, …) is refused *before the tool
+  runs* with a canonical `ENTITY_NOT_FOUND`, so the entity's state and
+  attributes never flow. Concealment of *existence* is best-effort: per-tool
+  not-found shapes vary (a bulk `ha_get_state` normally partial-succeeds, and
+  details/suggestions differ per tool), so a caller deliberately comparing
+  error shapes may infer that an id is hidden rather than absent. Note this
+  also means a bulk read that co-lists one hidden entity is refused as a whole
+  — retry without the hidden id to read the rest.
+- **Collection reads omit** hidden entities, exactly as they do without enforce.
+  In enforce mode this extends to `ha_search`'s configuration-body matches: an
+  automation, script, scene, helper, or dashboard record that references a
+  hidden entity is omitted from the config results (in the default soft mode
+  such records still appear — that is the documented soft-filter behavior).
+- **Content reads are refused on contact.** A dashboard config, template result,
+  automation/script body, trace, log, or file read whose output would surface a
+  hidden entity_id is refused with a generic `ENTITY_VISIBILITY_ENFORCED` error
+  that never names the matched id.
+- **Writes naming a hidden entity are concealed too.** The inbound argument scan
+  applies to *every* tool, including service calls: a `ha_call_service` targeting
+  a hidden entity_id is concealed as not-found, so an agent cannot confirm the
+  entity by trying to control it.
+
+What it deliberately **refuses** (their output cannot be text-scanned): sandbox
+code execution via `ha_manage_custom_tool` (`code` / `run_saved` — pure
+`list_saved` stays allowed) and screenshot/pixel output
+(`ha_get_dashboard_screenshot`, `ha_config_get_dashboard` with
+`include_screenshot`, or `ha_config_set_dashboard` with `return_screenshot`).
+
+One image surface is deliberately **exempt**: `ha_get_camera_image`. A camera
+the filter does not hide returns physical-world imagery — a photograph, not a
+rendering of Home Assistant entity data — so its frames are not gated (a hidden
+camera is concealed like any other entity). The residual case is a visible
+camera whose view happens to include a display showing a hidden entity's state;
+if a camera can see something sensitive, hide the camera too (denylist or its
+area).
+
+Enforce mode **fails closed**: if the entity registry (or the config file
+itself) cannot be loaded, the server falls back to the last good read from this
+session — and with none available, tool calls are refused rather than risk
+leaking a restricted entity. The hidden set is cached for ~30s, so an area/label
+membership change in Home Assistant can take up to that long to take effect for
+the area/label dimensions (a config edit in the settings UI applies on the next
+call).
+
+Because refuse-on-contact applies to the *whole* hidden set, broad hide
+dimensions make refusals frequent: with the default `diagnostic`/`config`
+category excludes still active, any log, automation, or dashboard read that
+mentions a diagnostic entity is refused wholesale. Enforce mode works best with
+a *targeted* deny — the private areas, labels, or entity_ids you actually need
+concealed — rather than broad decluttering dimensions.
+
+**Honest residual limits.** This is a strong barrier against *incidental*
+exposure, not a cryptographic guarantee. A Jinja template (or code) that *derives*
+a hidden entity's state without ever naming its entity_id — e.g.
+`{{ states | selectattr('state','eq','on') | list | count }}` — cannot be caught
+by a text scan. Treat enforce mode as robust protection against an agent stumbling
+onto hidden entities, not as a boundary against an adversarial prompt author who
+is deliberately trying to exfiltrate a hidden entity's state.
+
 `version` drives optimistic-concurrency for the settings UI (it bumps
 on each save so two tabs can't clobber each other); when hand-editing the file,
 leave it as-is. The config is read live per request, so edits apply on the next
-call; a missing or invalid file leaves the filter off (and, when enabled but the
-registry read degrades, results are unfiltered with a `warnings` note rather than
-silently wrong).
+call. A missing file leaves the filter off; an *invalid* one leaves the filter
+off for search/overview (with a `warnings` note) while enforce-mode safety falls
+back to the session's last good config — with none, tool calls are refused until
+the file is fixed (see *Enforce mode* above). When the filter is enabled but the
+registry read degrades, search results are unfiltered with a `warnings` note
+rather than silently wrong.
 
 ---
 
 
@@ -116,6 +116,14 @@ class ErrorCode(StrEnum):
     # backup directory is unusable). Fail-closed: nothing was changed.
     BACKUP_CAPTURE_FAILED = "BACKUP_CAPTURE_FAILED"
 
+    # Entity visibility enforce mode (#2015). A read was refused because the
+    # opt-in visibility filter's enforce mode is active and the request would
+    # surface an entity the filter hides — either the tool's output references a
+    # hidden entity, or the tool's output cannot be scanned (screenshots, sandbox
+    # code). Direct reads of a hidden entity are concealed as ENTITY_NOT_FOUND
+    # instead; this code marks the refuse-on-contact case. No data was returned.
+    ENTITY_VISIBILITY_ENFORCED = "ENTITY_VISIBILITY_ENFORCED"
+
 
 # Default suggestions for common error codes
 DEFAULT_SUGGESTIONS: dict[ErrorCode, list[str]] = {
 
@@ -251,6 +251,15 @@ def _initialize_server(self) -> None:
 
         self.mcp.add_middleware(LlmExposureMiddleware())
 
+        # Entity visibility enforce mode, INBOUND half (#2015) — always
+        # installed, consults the live config per request (no-op unless
+        # enforce is on with an active hide dimension). Must precede the
+        # read-only guard and PolicyMiddleware: a call naming a hidden
+        # entity is concealed as not-found BEFORE it can be stored verbatim
+        # in the approval queue (rendered in the settings UI) or answered
+        # with a read-only/approval response that would confirm existence.
+        self._apply_visibility_inbound_middleware()
+
         # Read Only Mode write blocker (discussion #1569) — always
         # installed, consults the live flag per call. Before
         # PolicyMiddleware so a write blocked by Read Only Mode never
@@ -269,6 +278,11 @@ def _initialize_server(self) -> None:
         # wraps the final tool surface (including the search proxies).
         self._apply_tool_security_policies()
 
+        # Entity visibility enforce mode, OUTBOUND half (#2015) — added LAST
+        # so it is innermost: its result scan sees the raw tool output before
+        # any other middleware transforms it.
+        self._apply_visibility_outbound_middleware()
+
     def _get_skills_dir(self) -> Path | None:
         """Return the bundled skills directory if it exists.
 
@@ -1125,6 +1139,35 @@ async def _list_all_tools() -> Any:
 
         self.mcp.add_middleware(StrictBpsMiddleware(list_tools=_list_all_tools))
 
+    def _apply_visibility_inbound_middleware(self) -> None:
+        """Install the enforce-mode INBOUND (conceal/refuse) middleware (#2015).
+
+        Always installed — self-no-ops at call time (loads the visibility
+        config per request and passes through unless enforce is on with an
+        active hide dimension), so a settings-UI toggle applies live in
+        standalone-HTTP/embedded mode like ``read_only_mode``. It needs the HA
+        client to fetch the registry/states for the hidden-set computation;
+        inject the lazy client accessor so no eager connection is made at
+        startup. Ordering (before read-only/policy) is owned by the caller.
+        """
+        from .visibility.enforcement import VisibilityInboundEnforcement
+
+        self.mcp.add_middleware(
+            VisibilityInboundEnforcement(get_client=lambda: self.client)
+        )
+
+    def _apply_visibility_outbound_middleware(self) -> None:
+        """Install the enforce-mode OUTBOUND (result-scan) middleware (#2015).
+
+        Same always-installed/self-no-op contract as the inbound half; the
+        caller registers it last so it is innermost and scans raw tool output.
+        """
+        from .visibility.enforcement import VisibilityOutboundEnforcement
+
+        self.mcp.add_middleware(
+            VisibilityOutboundEnforcement(get_client=lambda: self.client)
+        )
+
     # Shared action-phrased keyword block for retrieval. Some MCP clients
     # (Claude Code, others) rank candidate tools by token-overlap between
     # the user's natural-language query and each tool's `description`
 
@@ -82,8 +82,11 @@
     "accessibility.colors.clear": "Benutzerdefinierte Farben löschen",
     "accessibility.reset": "Auf Standardwerte zurücksetzen",
     "visibility.intro": "Verstecke Entitäten mit geringem Wert (automatisch generierte Diagnose- oder Helfer-Entitäten oder eine explizite Liste) aus den Sammlungs-Lese-Tools <code>ha_search</code> und <code>ha_get_overview</code>, sodass Such- und Übersichtsergebnisse weniger überladen sind. Standardmäßig ausgeschaltet; Änderungen gelten beim nächsten Tool-Aufruf.",
-    "visibility.boundary": "Rauschreduzierung, keine Zugriffskontrolle: Eine versteckte Entität wird weiterhin durch ein direktes Lesen ihrer entity_id zurückgegeben und erscheint weiterhin in Automatisierungs-, Dashboard- und Template-Inhalten. Verlasse dich nicht darauf als Sicherheitsgrenze.",
+    "visibility.boundary": "Ohne den Erzwingungsmodus (unten) ist dies Rauschreduzierung, keine Zugriffskontrolle: Eine versteckte Entität wird weiterhin durch ein direktes Lesen ihrer entity_id zurückgegeben und erscheint weiterhin in Automatisierungs-, Dashboard- und Template-Inhalten. Verlasse dich nicht allein auf den Filter als Sicherheitsgrenze.",
     "visibility.enabled": "Entitäts-Sichtbarkeitsfilter aktivieren",
+    "visibility.enforce.title": "Erzwingungsmodus",
+    "visibility.enforce.help": "Erweitert den Filter vom Aufräumen von Suche und Übersicht auf jeden Werkzeug-Lesezugriff. Ein direkter Lesezugriff auf eine versteckte Entität liefert „nicht gefunden“, und ein Inhalts-Lesezugriff (Dashboard, Template, Automatisierung, Trace, Log oder Datei), der eine versteckte Entität offenlegen würde, wird verweigert. Bestmögliche Verschleierung gegen versehentliche Offenlegung, keine gehärtete Sicherheitsgrenze.",
+    "visibility.enforce.only_enforced": "Versteckte Entitäten für alle Werkzeuge unlesbar machen (nicht nur für die Suche)",
     "visibility.categories.title": "Nach Kategorie verstecken",
     "visibility.categories.help": "Home Assistant markiert automatisch generierte Entitäten als Diagnose oder Konfiguration.",
     "visibility.categories.legend": "Zu versteckende Entitätskategorien",
 
@@ -82,8 +82,11 @@
     "accessibility.colors.clear": "Clear custom colors",
     "accessibility.reset": "Reset to defaults",
     "visibility.intro": "Hide low-value entities (auto-generated diagnostic or helper entities, or an explicit list) from the collection read tools <code>ha_search</code> and <code>ha_get_overview</code>, so search and overview results are less cluttered. Off by default; changes apply on the next tool call.",
-    "visibility.boundary": "Noise reduction, not access control: a hidden entity is still returned by a direct read of its entity_id and still appears in automation, dashboard, and template content. Do not rely on this as a security boundary.",
+    "visibility.boundary": "Without enforce mode (below), this is noise reduction, not access control: a hidden entity is still returned by a direct read of its entity_id and still appears in automation, dashboard, and template content. Do not rely on the filter alone as a security boundary.",
     "visibility.enabled": "Enable entity visibility filter",
+    "visibility.enforce.title": "Enforce mode",
+    "visibility.enforce.help": "Extends the filter from decluttering search and overview to every tool read. A direct read of a hidden entity returns “not found”, and a content read (dashboard, template, automation, trace, log, or file) that would surface a hidden entity is refused. Best-effort concealment against incidental exposure, not a hardened security boundary.",
+    "visibility.enforce.only_enforced": "Make hidden entities unreadable across all tools (not just search)",
     "visibility.categories.title": "Hide by category",
     "visibility.categories.help": "Home Assistant tags auto-generated entities as diagnostic or config.",
     "visibility.categories.legend": "Entity categories to hide",