ha-mcp-dev 7.5.0.dev589__tar.gz → 7.5.0.dev590__tar.gz

{ha_mcp_dev-7.5.0.dev589/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.5.0.dev590}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.5.0.dev589
+Version: 7.5.0.dev590
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -342,6 +342,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **[FastMCP](https://github.com/jlowin/fastmcp)**: Excellent MCP server framework
 - **[Model Context Protocol](https://modelcontextprotocol.io/)**: Standardized AI-application communication
 - **[Claude Code](https://github.com/anthropics/claude-code)**: AI-powered coding assistant
+- **[PolicyLayer](https://policylayer.com/)**: Argument-path predicate DSL shape (`args.domain in [...]` with `eq`/`in`/`regex`/`contains`/`exists`/...) inspired the per-tool approval rule schema (#966).
 
 ## 👥 Contributors
 
@@ -390,6 +391,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **[@drseanwing](https://github.com/drseanwing)** — Progress emission via FastMCP `Context` in long-running tools (#1124); tool-discovery / categorized-search docs (#1123).
 - **[@fnordpig](https://github.com/fnordpig)** — Config subentry support (#1393) and Assist pipeline management tool (#1392).
 - **[@paul43210](https://github.com/paul43210)** — `array_patch` mode in `ha_manage_addon` for atomic GET-modify-POST (#1063).
+- **[@L1AD](https://github.com/L1AD)** — Filed #966 proposing tool security policies; pointed to PolicyLayer's MCP-security work as prior art that inspired the predicate DSL shape.
 
 ---
 

{ha_mcp_dev-7.5.0.dev589 → ha_mcp_dev-7.5.0.dev590}/README.md

@@ -312,6 +312,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **[FastMCP](https://github.com/jlowin/fastmcp)**: Excellent MCP server framework
 - **[Model Context Protocol](https://modelcontextprotocol.io/)**: Standardized AI-application communication
 - **[Claude Code](https://github.com/anthropics/claude-code)**: AI-powered coding assistant
+- **[PolicyLayer](https://policylayer.com/)**: Argument-path predicate DSL shape (`args.domain in [...]` with `eq`/`in`/`regex`/`contains`/`exists`/...) inspired the per-tool approval rule schema (#966).
 
 ## 👥 Contributors
 
@@ -360,6 +361,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **[@drseanwing](https://github.com/drseanwing)** — Progress emission via FastMCP `Context` in long-running tools (#1124); tool-discovery / categorized-search docs (#1123).
 - **[@fnordpig](https://github.com/fnordpig)** — Config subentry support (#1393) and Assist pipeline management tool (#1392).
 - **[@paul43210](https://github.com/paul43210)** — `array_patch` mode in `ha_manage_addon` for atomic GET-modify-POST (#1063).
+- **[@L1AD](https://github.com/L1AD)** — Filed #966 proposing tool security policies; pointed to PolicyLayer's MCP-security work as prior art that inspired the predicate DSL shape.
 
 ---
 

{ha_mcp_dev-7.5.0.dev589 → ha_mcp_dev-7.5.0.dev590}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.5.0.dev589"
+version = "7.5.0.dev590"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.5.0.dev589 → ha_mcp_dev-7.5.0.dev590}/src/ha_mcp/config.py

@@ -100,6 +100,13 @@ class Settings(BaseSettings):
     # Dramatically reduces idle context token usage for LLMs.
     enable_tool_search: bool = Field(False, alias="ENABLE_TOOL_SEARCH")
 
+    # Tool security policies middleware — opt-in gate that routes high-stakes
+    # tool calls through a per-tool policy with out-of-band web-UI approval
+    # (issue #966). Disabled by default.
+    enable_tool_security_policies: bool = Field(
+        False, alias="ENABLE_TOOL_SECURITY_POLICIES"
+    )
+
     # Managed YAML config editing — allows ha_config_set_yaml to add,
     # replace, or remove top-level keys in configuration.yaml and package
     # files. Disabled by default; only for YAML-only features with no UI/API path.
@@ -330,6 +337,7 @@ FEATURE_FLAG_FIELDS: tuple[tuple[str, str, type], ...] = (
         "HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION",
         bool,
     ),
+    ("enable_tool_security_policies", "ENABLE_TOOL_SECURITY_POLICIES", bool),
 )
 
 # Override-file location is the same data dir that holds tool_config.json

{ha_mcp_dev-7.5.0.dev589 → ha_mcp_dev-7.5.0.dev590}/src/ha_mcp/errors.py

@@ -89,6 +89,13 @@ class ErrorCode(StrEnum):
     SANDBOX_SYNTAX_UNSUPPORTED = "SANDBOX_SYNTAX_UNSUPPORTED"
     SANDBOX_RUNTIME_ERROR = "SANDBOX_RUNTIME_ERROR"
 
+    # Tool security policy gating (#966). The middleware gates a tool
+    # call awaiting user approval, the user denied it, or the policy
+    # file itself failed to load (treated as a fail-closed safety stop).
+    USER_APPROVAL_REQUIRED = "USER_APPROVAL_REQUIRED"
+    USER_DENIED = "USER_DENIED"
+    POLICY_LOAD_FAILED = "POLICY_LOAD_FAILED"
+
 
 # Default suggestions for common error codes
 DEFAULT_SUGGESTIONS: dict[ErrorCode, list[str]] = {
@@ -240,7 +247,9 @@ def create_error_response(
         }
     """
     # Use provided suggestions or fall back to defaults
-    error_suggestions = suggestions if suggestions else DEFAULT_SUGGESTIONS.get(code, [])
+    error_suggestions = (
+        suggestions if suggestions else DEFAULT_SUGGESTIONS.get(code, [])
+    )
 
     error_dict: dict[str, Any] = {
         "code": code.value,
@@ -331,14 +340,20 @@ def create_validation_error(
     context: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """Create a validation error response."""
-    code = ErrorCode.VALIDATION_INVALID_JSON if invalid_json else ErrorCode.VALIDATION_FAILED
+    code = (
+        ErrorCode.VALIDATION_INVALID_JSON
+        if invalid_json
+        else ErrorCode.VALIDATION_FAILED
+    )
     # Build context, prioritizing explicit context but adding parameter if provided
     final_context: dict[str, Any] = {}
     if context:
         final_context.update(context)
     if parameter:
         final_context["parameter"] = parameter
-    return create_error_response(code, message, details, context=final_context if final_context else None)
+    return create_error_response(
+        code, message, details, context=final_context if final_context else None
+    )
 
 
 def create_config_error(

ha_mcp_dev-7.5.0.dev590/src/ha_mcp/policy/__init__.py

@@ -0,0 +1 @@
+"""Tool security policies for high-stakes MCP tool calls."""

ha_mcp_dev-7.5.0.dev590/src/ha_mcp/policy/approval_queue.py

@@ -0,0 +1,264 @@
+"""In-memory, per-process approval queue with args-hash binding and remember-cache."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import secrets
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Any, Literal
+
+import anyio
+
+logger = logging.getLogger(__name__)
+
+Decision = Literal["pending", "approved", "denied"]
+
+
+def compute_args_hash(args: dict[str, Any]) -> str:
+    """Canonical sha256 of args. Same hash function used at insert and lookup."""
+    payload = json.dumps(args, sort_keys=True, separators=(",", ":"), default=str)
+    return hashlib.sha256(payload.encode()).hexdigest()
+
+
+@dataclass
+class PendingApproval:
+    token: str
+    tool_name: str
+    args_hash: str
+    args: dict[str, Any]
+    created_at: datetime
+    expires_at: datetime
+    _decision: Decision = "pending"
+    _event: anyio.Event = field(default_factory=anyio.Event)
+
+    @property
+    def decision(self) -> Decision:
+        return self._decision
+
+    def decide(self, outcome: Literal["approved", "denied"]) -> bool:
+        """Transition pending -> outcome exactly once. Returns False if already decided."""
+        if self._decision != "pending":
+            return False
+        self._decision = outcome
+        self._event.set()
+        return True
+
+    async def wait(self) -> Decision:
+        """Block until decided; return the final Decision."""
+        await self._event.wait()
+        return self._decision
+
+    def __post_init__(self) -> None:
+        if self.expires_at <= self.created_at:
+            raise ValueError("expires_at must be after created_at")
+
+
+class ApprovalQueue:
+    """In-memory per-process approval queue with args-hash binding.
+
+    Pending approvals are bound to (tool_name, sha256(canonical_args)).
+    A re-call with mutated args produces a different hash and a new
+    pending entry, so an approval cannot be silently repurposed.
+
+    **Single-process only.** Multi-worker deployments (e.g.
+    ``uvicorn --workers N``) are unsupported — approvals created on
+    worker A do NOT propagate to worker B, so a re-call routed to a
+    different worker will look like a brand-new approval request.
+    The standard ha-mcp deployments (stdio, addon, ha-mcp-web) all
+    run single-worker.
+
+    **Restart loses pending tokens.** The persistent ``tool_policy.json``
+    rules survive a restart, but any in-flight approval tokens do not.
+    Users will need to re-issue an approval click after a restart.
+    """
+
+    # Hard cap on pending entries to prevent memory exhaustion if an LLM
+    # in a retry loop with mutated args creates a new entry every call.
+    # When the cap is hit, eviction runs in this order:
+    #   1. _sweep_expired() — drop TTL-elapsed entries first
+    #   2. then evict already-resolved (approved/denied) entries by age
+    #   3. only if still over the cap, evict oldest pending entries —
+    #      and fire their _event so any waiter wakes up immediately
+    #      rather than blocking the full wait_seconds against a row
+    #      that no longer exists.
+    # 1000 is well above any realistic interactive use; an attacker
+    # probing past the cap just churns the queue.
+    PENDING_CAP = 1000
+
+    def __init__(self) -> None:
+        self._by_token: dict[str, PendingApproval] = {}
+        self._remember: dict[tuple[str, str], datetime] = {}
+        # Serialises find_or_create against concurrent on_call_tool
+        # invocations with identical (tool_name, args_hash) — without it
+        # two coroutines could both find() == None then both create()
+        # separate pending entries, and approving one would leave the
+        # other waiter blocked forever.
+        self._create_lock = anyio.Lock()
+
+    # --- remember cache ---
+    def remember(self, tool_name: str, args_hash: str, *, minutes: int) -> None:
+        if minutes <= 0:
+            return
+        self._remember[(tool_name, args_hash)] = datetime.now(UTC) + timedelta(
+            minutes=minutes
+        )
+
+    def is_remembered(self, tool_name: str, args_hash: str) -> bool:
+        until = self._remember.get((tool_name, args_hash))
+        if until is None:
+            return False
+        if datetime.now(UTC) >= until:
+            self._remember.pop((tool_name, args_hash), None)
+            return False
+        return True
+
+    def clear_remember_cache(self) -> None:
+        """Drop every remembered approval. Called when the policy is
+        saved so a tightened rule takes effect immediately instead of
+        being silently bypassed by an in-flight remembered approval
+        until its window expires."""
+        self._remember.clear()
+
+    # --- pending entries lifecycle ---
+    def create(
+        self,
+        tool_name: str,
+        args_hash: str,
+        args: dict[str, Any],
+        *,
+        ttl_minutes: int,
+    ) -> PendingApproval:
+        # Enforce PENDING_CAP. Order matters — see class docstring.
+        if len(self._by_token) >= self.PENDING_CAP:
+            self._sweep_expired()
+            if len(self._by_token) >= self.PENDING_CAP:
+                self._evict_to_make_room()
+        now = datetime.now(UTC)
+        entry = PendingApproval(
+            token=secrets.token_urlsafe(24),
+            tool_name=tool_name,
+            args_hash=args_hash,
+            args=args,
+            created_at=now,
+            expires_at=now + timedelta(minutes=ttl_minutes),
+        )
+        self._by_token[entry.token] = entry
+        return entry
+
+    async def find_or_create(
+        self,
+        tool_name: str,
+        args_hash: str,
+        args: dict[str, Any],
+        *,
+        ttl_minutes: int,
+    ) -> PendingApproval:
+        """Atomic find-then-create: prevents two concurrent on_call_tool
+        coroutines with identical (tool_name, args_hash) from creating
+        two separate pending entries that would then each block their
+        own waiter independently."""
+        async with self._create_lock:
+            existing = self.find(tool_name, args_hash)
+            if existing is not None:
+                return existing
+            return self.create(tool_name, args_hash, args, ttl_minutes=ttl_minutes)
+
+    def find(self, tool_name: str, args_hash: str) -> PendingApproval | None:
+        self._sweep_expired()
+        for entry in self._by_token.values():
+            if entry.tool_name == tool_name and entry.args_hash == args_hash:
+                return entry
+        return None
+
+    def get(self, token: str) -> PendingApproval | None:
+        self._sweep_expired()
+        return self._by_token.get(token)
+
+    def list_pending(self) -> list[PendingApproval]:
+        self._sweep_expired()
+        return [e for e in self._by_token.values() if e.decision == "pending"]
+
+    def approve(self, token: str) -> bool:
+        """Mark the entry approved. Returns False if unknown or already decided."""
+        entry = self._by_token.get(token)
+        if entry is None:
+            # WARNING because on a security-gating endpoint this means
+            # either a UI bug, a stale tab racing the sweeper, or an
+            # attacker probing tokens — operator should see it.
+            logger.warning("approval_queue.approve: unknown token %s", token)
+            return False
+        ok = entry.decide("approved")
+        if not ok:
+            # INFO — could be a legitimate race (two approvers, or
+            # quick double-click) rather than a security signal.
+            logger.info(
+                "approval_queue.approve: token %s already decided as %s",
+                token,
+                entry.decision,
+            )
+        return ok
+
+    def deny(self, token: str) -> bool:
+        """Mark the entry denied. Returns False if unknown or already decided."""
+        entry = self._by_token.get(token)
+        if entry is None:
+            logger.warning("approval_queue.deny: unknown token %s", token)
+            return False
+        ok = entry.decide("denied")
+        if not ok:
+            logger.info(
+                "approval_queue.deny: token %s already decided as %s",
+                token,
+                entry.decision,
+            )
+        return ok
+
+    def remove(self, token: str) -> None:
+        self._by_token.pop(token, None)
+
+    def consume_and_maybe_remember(
+        self, entry: PendingApproval, *, remember_minutes: int
+    ) -> None:
+        self.remove(entry.token)
+        if remember_minutes > 0:
+            self.remember(entry.tool_name, entry.args_hash, minutes=remember_minutes)
+
+    def _sweep_expired(self) -> None:
+        now = datetime.now(UTC)
+        stale = [t for t, e in self._by_token.items() if e.expires_at <= now]
+        for t in stale:
+            self._by_token.pop(t, None)
+
+    def _evict_to_make_room(self) -> None:
+        """Evict one entry to bring us back under PENDING_CAP.
+
+        Resolved entries (approved/denied) go first — they're already
+        decided and only sitting in the queue because the UI hasn't
+        picked them up yet. If none exist, fall back to the oldest
+        pending entry AND fire its event so any waiter in
+        _wait_for_decision wakes up immediately and observes the
+        eviction instead of blocking the full wait_seconds against a
+        row that no longer exists.
+        """
+        overflow = len(self._by_token) - self.PENDING_CAP + 1
+        # Sort by (still-pending? then by age) so resolved entries are
+        # at the front of the evict list.
+        ordered = sorted(
+            self._by_token.values(),
+            key=lambda e: (e.decision == "pending", e.created_at),
+        )
+        for stale in ordered[:overflow]:
+            if stale.decision == "pending":
+                logger.warning(
+                    "approval_queue: PENDING_CAP hit — evicting pending token %s "
+                    "(no resolved entries to drop); waiter will be notified",
+                    stale.token,
+                )
+                # Best-effort wake — _event.set() is idempotent and safe
+                # on any state. Without this the waiter blocks until its
+                # wait_seconds deadline.
+                stale._event.set()
+            self._by_token.pop(stale.token, None)

ha_mcp_dev-7.5.0.dev590/src/ha_mcp/policy/evaluator.py

@@ -0,0 +1,144 @@
+"""Evaluate a tool call against a Policy. Pure functions — no I/O, no state."""
+
+import logging
+import re
+from collections.abc import Iterator
+from enum import StrEnum
+from typing import Any
+
+from .model import Policy, Predicate, Rule
+
+logger = logging.getLogger(__name__)
+
+
+class Verdict(StrEnum):
+    ALLOW = "allow"
+    REQUIRE_APPROVAL = "require_approval"
+
+
+def iter_path_values(args: dict[str, Any], path: str) -> Iterator[Any]:
+    """Yield every value the dotted path resolves to.
+
+    The leading ``args`` segment is implicit and stripped. A ``*`` segment
+    fans out across the current node — across dict values for dicts,
+    across items for lists — so ``args.*`` yields every top-level
+    argument, ``args.config.*`` yields every leaf of the ``config``
+    sub-dict, and so on. Empty iterator = no match.
+    """
+    parts = path.split(".")
+    if parts[0] == "args":
+        parts = parts[1:]
+
+    def walk(cur: Any, rest: list[str]) -> Iterator[Any]:
+        if not rest:
+            yield cur
+            return
+        head, tail = rest[0], rest[1:]
+        if head == "*":
+            if isinstance(cur, dict):
+                for v in cur.values():
+                    yield from walk(v, tail)
+            elif isinstance(cur, (list, tuple)):
+                for v in cur:
+                    yield from walk(v, tail)
+            return
+        if isinstance(cur, dict) and head in cur:
+            yield from walk(cur[head], tail)
+
+    yield from walk(args, parts)
+
+
+def _ci(x: Any) -> Any:
+    """Lower-case strings for case-insensitive comparison; pass other
+    types through unchanged so type semantics (int != "1") survive.
+    Used on both sides of every string op — security gates should fire
+    whether the caller wrote 'Lock' or 'LOCK' or 'lock'."""
+    return x.lower() if isinstance(x, str) else x
+
+
+def _op_matches(val: Any, op: str, pv: Any) -> bool:
+    """Apply one op to one concrete value. Predicate dispatches over
+    the candidate values (which may be many for wildcard paths).
+
+    String comparisons are case-insensitive (security gates shouldn't
+    care whether the LLM lowercased its args). Non-string types
+    preserve their natural comparison semantics.
+    """
+    match op:
+        case "eq":
+            return bool(_ci(val) == _ci(pv))
+        case "neq":
+            return bool(_ci(val) != _ci(pv))
+        case "in":
+            return _ci(val) in [_ci(x) for x in (pv or [])]
+        case "not_in":
+            return _ci(val) not in [_ci(x) for x in (pv or [])]
+        case "regex":
+            # `regex` is re.search (substring match). Anchor with ^...$
+            # for full-match. re.IGNORECASE so '^light\.' matches 'Light.x'.
+            return (
+                isinstance(val, str)
+                and isinstance(pv, str)
+                and re.search(pv, val, re.IGNORECASE) is not None
+            )
+        case "contains":
+            if isinstance(val, str) and isinstance(pv, str):
+                return pv.lower() in val.lower()
+            return isinstance(val, (list, tuple, set)) and pv in val
+        case "gt":
+            try:
+                return bool(val > pv)
+            except TypeError:
+                # Numeric rule against a non-numeric arg value — log so
+                # users can tell their "temperature > 30" rule isn't
+                # silently never firing because the arg is a string.
+                logger.debug(
+                    "policy: gt type-mismatch (val=%r pv=%r) — predicate skipped",
+                    val,
+                    pv,
+                )
+                return False
+        case "lt":
+            try:
+                return bool(val < pv)
+            except TypeError:
+                logger.debug(
+                    "policy: lt type-mismatch (val=%r pv=%r) — predicate skipped",
+                    val,
+                    pv,
+                )
+                return False
+    return False
+
+
+def match_predicate(predicate: Predicate, args: dict[str, Any]) -> bool:
+    values = list(iter_path_values(args, predicate.path))
+    if predicate.op == "exists":
+        return bool(values)
+    if not values:
+        return False
+    # Existential semantics: a wildcard path matches if ANY value at the
+    # wildcard satisfies the op. For non-wildcard paths there's at most
+    # one value so the any() collapses to a single check.
+    return any(_op_matches(v, predicate.op, predicate.value) for v in values)
+
+
+def match_rule(rule: Rule, tool_name: str, args: dict[str, Any]) -> bool:
+    if rule.tool_name != "*" and rule.tool_name != tool_name:
+        return False
+    return all(match_predicate(p, args) for p in rule.when)
+
+
+def find_matching_rule(
+    tool_name: str, args: dict[str, Any], policy: Policy
+) -> Rule | None:
+    for rule in policy.rules:
+        if match_rule(rule, tool_name, args):
+            return rule
+    return None
+
+
+def evaluate(tool_name: str, args: dict[str, Any], policy: Policy) -> Verdict:
+    if find_matching_rule(tool_name, args, policy) is not None:
+        return Verdict.REQUIRE_APPROVAL
+    return Verdict.ALLOW