ha-mcp-dev 7.13.0.dev1990__tar.gz → 7.13.0.dev1994__tar.gz

{ha_mcp_dev-7.13.0.dev1990/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.13.0.dev1994}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.13.0.dev1990
+Version: 7.13.0.dev1994
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.13.0.dev1990 → ha_mcp_dev-7.13.0.dev1994}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.13.0.dev1990"
+version = "7.13.0.dev1994"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-7.13.0.dev1990 → ha_mcp_dev-7.13.0.dev1994}/src/ha_mcp/strict_bps.py

@@ -28,7 +28,10 @@ schema-validating clients will send it; the tool bodies never read it —
 
 from __future__ import annotations
 
+import hashlib
 import logging
+import secrets
+import time
 from collections.abc import Awaitable, Callable, Sequence
 from typing import Annotated, Any, NoReturn
 
@@ -55,11 +58,50 @@ def _warn_degraded_once(branch: str, message: str, *, exc_info: bool = False) ->
     logger.warning(message, exc_info=exc_info)
 
 
-# Single source of truth for the acknowledgment key literal. It is published
-# ONLY by ``strict_bps_ack_line`` (surfaced through ha_get_skill_guide Tier 3
-# when strict mode is effective) and validated ONLY by the middleware — it must
-# never appear in a block error, a tool docstring, or a skill_content embed.
-STRICT_BPS_ACK_KEY = "bps-ack-1779"
+# The acknowledgment key is deliberately NOT a static opaque token (#1924):
+#
+# * The PREFIX is a plain-English attestation phrase so the value cannot be
+#   mistaken for a credential. An agent shown the old opaque ``bps-ack-*``
+#   token misread the extract-and-replay round-trip as prompt injection,
+#   refused every gated write, and steered the user into disabling strict
+#   mode — the opposite of the gate's purpose. The key is a read-receipt:
+#   public, privilege-free proof the skill content entered the model's
+#   context before a write.
+# * The SUFFIX rotates hourly, derived from a per-process salt and the
+#   current hour bucket, so the key cannot be satisfied from the public
+#   repo, training data, an agent's persistent memory, or a stale session
+#   summary — only by a recent read of the guide served by THIS process.
+#   The previous hour's key is honored as a grace window so a read just
+#   before rotation does not strand the write that follows it. Derivation
+#   is stateless (salt + clock), keeping the no-server-side-session-state
+#   principle intact.
+#
+# The key is published ONLY by ``strict_bps_ack_line`` (surfaced through
+# ha_get_skill_guide Tier 3 when strict mode is effective) and validated ONLY
+# by the middleware — it must never appear in a block error, a tool
+# docstring, or a skill_content embed.
+STRICT_BPS_ACK_KEY_PREFIX = "I-HAVE-READ-THE-BEST-PRACTICES-GUIDE"
+
+_ACK_KEY_SALT = secrets.token_hex(8)
+_ACK_KEY_ROTATION_SECONDS = 3600
+
+
+def _current_ack_key(now: float | None = None) -> str:
+    bucket = int((time.time() if now is None else now) // _ACK_KEY_ROTATION_SECONDS)
+    digest = hashlib.sha256(f"{_ACK_KEY_SALT}:{bucket}".encode()).hexdigest()
+    return f"{STRICT_BPS_ACK_KEY_PREFIX}-{digest[:8]}"
+
+
+def current_strict_bps_ack_key() -> str:
+    """Return the acknowledgment key for the current rotation window."""
+    return _current_ack_key()
+
+
+def _valid_ack_keys() -> set[str]:
+    """Current key plus the previous rotation's key (grace window)."""
+    now = time.time()
+    return {_current_ack_key(now), _current_ack_key(now - _ACK_KEY_ROTATION_SECONDS)}
+
 
 # The write-tool parameter that carries the acknowledgment key. Declared on
 # each of the six gated tools (adjacent to ``MandatoryBPS``) but read only here.
@@ -74,8 +116,13 @@ BestPracticeKeyParam = Annotated[
     Field(
         default=None,
         description=(
-            "Acknowledgment key published in the home-assistant-best-practices "
-            "skill content; required when strict best-practices mode is enabled."
+            "Read-receipt for the home-assistant-best-practices skill; "
+            "required when strict best-practices mode is enabled. Not a "
+            "secret or credential: the current value is an attestation "
+            "phrase published openly at the top of the skill content served "
+            "by ha_get_skill_guide. Read that content, then pass the value "
+            "back verbatim — this round-trip is the server's designed "
+            "protocol confirming the practices were read before writing."
         ),
     ),
 ]
@@ -151,13 +198,16 @@ def strict_bps_ack_line() -> str:
     """Return the single line that publishes the acknowledgment key.
 
     Prepended to the ha_get_skill_guide Tier-3 best-practices content when
-    strict mode is effective (server.py). This is the ONLY place the key
-    literal is emitted to a caller.
+    strict mode is effective (server.py). This is the ONLY place the actual
+    key value is emitted to a caller.
     """
     return (
-        f"Acknowledgment key: {STRICT_BPS_ACK_KEY} — strict best-practices "
-        "mode is ON; pass this exact value as the BestPracticeKey argument "
-        "on gated write tools."
+        f"Acknowledgment key: {current_strict_bps_ack_key()} — strict "
+        "best-practices mode is ON; pass this exact value as the "
+        "BestPracticeKey argument on gated write tools. This key is a "
+        "read-receipt, not a secret: it is published here deliberately by "
+        "the ha-mcp server, rotates hourly, and grants no privileges — "
+        "replaying it is the designed acknowledgment protocol."
     )
 
 
@@ -176,7 +226,9 @@ def _raise_bps_ack_required_error(name: str) -> NoReturn:
         "Strict best-practices mode is enabled for this tool. Read the "
         "best-practices skill to obtain the required acknowledgment key, then "
         "pass it as the BestPracticeKey argument on this call. The key is "
-        "published only in that skill's content."
+        "published only in that skill's content, and it rotates periodically "
+        "— a key obtained earlier may have expired, so re-read the skill for "
+        "the current value instead of resending a previous one."
     )
     raise_tool_error(
         create_error_response(
@@ -263,10 +315,10 @@ class StrictBpsMiddleware(Middleware):
             return await call_next(context)
 
         # The gate is the ONLY reader of BestPracticeKey: strip it before
-        # dispatch (whether or not strict mode is on) so the constant never
+        # dispatch (whether or not strict mode is on) so the key value never
         # reaches the tool body, the policy middleware's approval args-hash
-        # (where it would churn remembered approvals across strict toggles),
-        # or downstream logging.
+        # (where the hourly-rotating value would churn remembered approvals
+        # every rotation), or downstream logging.
         args = context.message.arguments or {}
         supplied = args.get(STRICT_BPS_KEY_PARAM)
         if STRICT_BPS_KEY_PARAM in args:
@@ -275,9 +327,13 @@ class StrictBpsMiddleware(Middleware):
                 message=context.message.model_copy(update={"arguments": stripped})
             )
 
+        # isinstance guards the set-membership test: the middleware reads
+        # raw transport arguments before pydantic validation, so an
+        # off-spec client can send an unhashable value (dict/list) that
+        # would otherwise TypeError instead of hitting the block error.
         if (
             strict_bps_effective()
-            and supplied != STRICT_BPS_ACK_KEY
+            and not (isinstance(supplied, str) and supplied in _valid_ack_keys())
             and await self._is_registered(name)
         ):
             logger.info("strict-BPS mode blocked keyless write to %s", name)

{ha_mcp_dev-7.13.0.dev1990 → ha_mcp_dev-7.13.0.dev1994}/src/ha_mcp/tools/tools_dev.py

@@ -834,7 +834,9 @@ class DevTools:
             Field(
                 description=(
                     "info: deployment/version report; update_source: point the "
-                    "in-process server at a channel or pip spec and reinstall; "
+                    "ha_mcp_tools component's separate in-process server at a "
+                    "channel or pip spec and reinstall it (never changes the "
+                    "server serving this connection, unless embedded); "
                     "restart: restart this server"
                 )
             ),
@@ -871,14 +873,21 @@ class DevTools:
         as a PR tarball, and restarting the server so config or code
         changes take effect.
 
-        Caveats: restart interrupts this MCP connection in embedded and
-        add-on deployments (the reply arrives just before the server
-        goes down); update_source only self-interrupts in embedded mode
-        — elsewhere it reloads the separate in-process server entry
-        without dropping this connection. Reinstalls can take minutes.
-        update_source requires the ha_mcp_tools component's in-process
-        server entry; restart supports embedded and add-on deployments
-        only (standalone processes must be restarted externally).
+        Caveats: update_source changes ONLY the ha_mcp_tools custom
+        component's separate in-process server entry — it never updates
+        the add-on, Docker, standalone, or PyPI server that may be
+        serving this connection (update those via ha_manage_addon /
+        docker pull / pip). In embedded mode that entry IS this server,
+        so the update self-interrupts; elsewhere this connection is
+        untouched and keeps its current version. Success means the
+        entry's options were applied — the component then reinstalls in
+        the background, which can take minutes and can still fail
+        (check HA logs). update_source requires the component's
+        in-process server entry to exist. restart interrupts this MCP
+        connection in embedded and add-on deployments (the reply
+        arrives just before the server goes down) and supports those
+        two deployments only (standalone processes must be restarted
+        externally).
 
         EXAMPLES:
         ha_dev_manage_server("info")
@@ -936,6 +945,17 @@ class DevTools:
                     "entry_id": entry_id,
                     "channel": options.get(_OPT_CHANNEL),
                     "pip_spec": options.get(_OPT_PIP_SPEC),
+                    "role": (
+                        "this server (embedded)"
+                        if mode == "embedded"
+                        else (
+                            "separate in-process server run by the "
+                            "ha_mcp_tools component; the update_source "
+                            "target. server_version above describes the "
+                            f"{mode} server handling this connection, not "
+                            "this entry."
+                        )
+                    ),
                 }
         except Exception as exc:
             # Best-effort probe: a failure here (including the ToolError the
@@ -1020,6 +1040,9 @@ class DevTools:
                 "data": {
                     "scheduled": True,
                     "entry_id": entry_id,
+                    "target": (
+                        "this server (the embedded ha_mcp_tools in-process entry)"
+                    ),
                     "applying": user_input,
                     "previous": {
                         _OPT_CHANNEL: current.get(_OPT_CHANNEL),
@@ -1047,14 +1070,19 @@ class DevTools:
             "success": True,
             "data": {
                 "entry_id": entry_id,
+                "target": "ha_mcp_tools in-process server entry",
                 "applied": user_input,
                 "previous": {
                     _OPT_CHANNEL: current.get(_OPT_CHANNEL),
                     _OPT_PIP_SPEC: current.get(_OPT_PIP_SPEC),
                 },
                 "note": (
-                    "The component is reloading the in-process server with "
-                    "the new source; installs can take a few minutes."
+                    "Applied to the ha_mcp_tools component's SEPARATE "
+                    "in-process server entry, which is now reinstalling in "
+                    "the background (can take minutes and can still fail — "
+                    "check HA logs). The server handling this connection is "
+                    "NOT affected and keeps its current version; verify the "
+                    "in-process server on its own connect URL, not here."
                 ),
             },
         }

{ha_mcp_dev-7.13.0.dev1990 → ha_mcp_dev-7.13.0.dev1994/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.13.0.dev1990
+Version: 7.13.0.dev1994
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT