Harden tool param key normalization and character checks

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

hyperbrowser/tools/__init__.py

@@ -137,13 +137,44 @@ def _to_param_dict(params: Mapping[str, Any]) -> Dict[str, Any]:
         ) from exc
     for key in param_keys:
         if isinstance(key, str):
-            if not key.strip():
+            try:
+                normalized_key = key.strip()
+                if not isinstance(normalized_key, str):
+                    raise TypeError("normalized tool param key must be a string")
+            except HyperbrowserError:
+                raise
+            except Exception as exc:
+                raise HyperbrowserError(
+                    "Failed to normalize tool param key",
+                    original_error=exc,
+                ) from exc
+            if not normalized_key:
                 raise HyperbrowserError("tool params keys must not be empty")
-            if key != key.strip():
+            try:
+                has_surrounding_whitespace = key != normalized_key
+            except HyperbrowserError:
+                raise
+            except Exception as exc:
+                raise HyperbrowserError(
+                    "Failed to normalize tool param key",
+                    original_error=exc,
+                ) from exc
+            if has_surrounding_whitespace:
                 raise HyperbrowserError(
                     "tool params keys must not contain leading or trailing whitespace"
                 )
-            if any(ord(character) < 32 or ord(character) == 127 for character in key):
+            try:
+                contains_control_character = any(
+                    ord(character) < 32 or ord(character) == 127 for character in key
+                )
+            except HyperbrowserError:
+                raise
+            except Exception as exc:
+                raise HyperbrowserError(
+                    "Failed to validate tool param key characters",
+                    original_error=exc,
+                ) from exc
+            if contains_control_character:
                 raise HyperbrowserError(
                     "tool params keys must not contain control characters"
                 )

tests/test_tools_mapping_inputs.py

@@ -48,6 +48,19 @@ def __init__(self):
         self.extract = _AsyncExtractManager()
 
 
+def _run_scrape_tool_sync(params: Mapping[str, object]) -> None:
+    client = _Client()
+    WebsiteScrapeTool.runnable(client, params)
+
+
+def _run_scrape_tool_async(params: Mapping[str, object]) -> None:
+    async def run() -> None:
+        client = _AsyncClient()
+        await WebsiteScrapeTool.async_runnable(client, params)
+
+    asyncio.run(run())
+
+
 def test_tool_wrappers_accept_mapping_inputs():
     client = _Client()
     params = MappingProxyType({"url": "https://example.com"})
@@ -207,3 +220,86 @@ def __getitem__(self, key: str) -> object:
         WebsiteScrapeTool.runnable(client, _BrokenValueMapping())
 
     assert exc_info.value.original_error is None
+
+
+@pytest.mark.parametrize("runner", [_run_scrape_tool_sync, _run_scrape_tool_async])
+def test_tool_wrappers_wrap_param_key_strip_failures(runner):
+    class _BrokenStripKey(str):
+        def strip(self, chars=None):  # type: ignore[override]
+            _ = chars
+            raise RuntimeError("tool param key strip exploded")
+
+    with pytest.raises(
+        HyperbrowserError, match="Failed to normalize tool param key"
+    ) as exc_info:
+        runner({_BrokenStripKey("url"): "https://example.com"})
+
+    assert isinstance(exc_info.value.original_error, RuntimeError)
+
+
+@pytest.mark.parametrize("runner", [_run_scrape_tool_sync, _run_scrape_tool_async])
+def test_tool_wrappers_preserve_hyperbrowser_param_key_strip_failures(runner):
+    class _BrokenStripKey(str):
+        def strip(self, chars=None):  # type: ignore[override]
+            _ = chars
+            raise HyperbrowserError("custom tool param key strip failure")
+
+    with pytest.raises(
+        HyperbrowserError, match="custom tool param key strip failure"
+    ) as exc_info:
+        runner({_BrokenStripKey("url"): "https://example.com"})
+
+    assert exc_info.value.original_error is None
+
+
+@pytest.mark.parametrize("runner", [_run_scrape_tool_sync, _run_scrape_tool_async])
+def test_tool_wrappers_wrap_non_string_param_key_strip_results(runner):
+    class _BrokenStripKey(str):
+        def strip(self, chars=None):  # type: ignore[override]
+            _ = chars
+            return object()
+
+    with pytest.raises(
+        HyperbrowserError, match="Failed to normalize tool param key"
+    ) as exc_info:
+        runner({_BrokenStripKey("url"): "https://example.com"})
+
+    assert isinstance(exc_info.value.original_error, TypeError)
+
+
+@pytest.mark.parametrize("runner", [_run_scrape_tool_sync, _run_scrape_tool_async])
+def test_tool_wrappers_wrap_param_key_character_validation_failures(runner):
+    class _BrokenIterKey(str):
+        def strip(self, chars=None):  # type: ignore[override]
+            _ = chars
+            return self
+
+        def __iter__(self):
+            raise RuntimeError("tool param key iteration exploded")
+
+    with pytest.raises(
+        HyperbrowserError, match="Failed to validate tool param key characters"
+    ) as exc_info:
+        runner({_BrokenIterKey("url"): "https://example.com"})
+
+    assert isinstance(exc_info.value.original_error, RuntimeError)
+
+
+@pytest.mark.parametrize("runner", [_run_scrape_tool_sync, _run_scrape_tool_async])
+def test_tool_wrappers_preserve_hyperbrowser_param_key_character_validation_failures(
+    runner,
+):
+    class _BrokenIterKey(str):
+        def strip(self, chars=None):  # type: ignore[override]
+            _ = chars
+            return self
+
+        def __iter__(self):
+            raise HyperbrowserError("custom tool param key iteration failure")
+
+    with pytest.raises(
+        HyperbrowserError, match="custom tool param key iteration failure"
+    ) as exc_info:
+        runner({_BrokenIterKey("url"): "https://example.com"})
+
+    assert exc_info.value.original_error is None