Building AI agents, atomically
Validate result URL hosts and ports, wrap over-deep JSON, return body-or-reason from the request boundary, block non-loopback connects in tests
Juampi07d9f8cea3c5
diff --git a/atomic-forge/tools/firecrawl_search/README.md b/atomic-forge/tools/firecrawl_search/README.mdindex 5edd2e0..c58eb9b 100644--- a/atomic-forge/tools/firecrawl_search/README.md+++ b/atomic-forge/tools/firecrawl_search/README.md@@ -15,7 +15,7 @@ Searches the web or recent news through the [Firecrawl Search](https://www.firec2. Or copy the `tool/` folder directly into your project.## Configuration-- `api_key` (`SecretStr`, a plain string is accepted): Firecrawl API key. Falls back to the `FIRECRAWL_API_KEY` environment variable when empty. It is only sent in the `Authorization` header and is redacted from raised errors and log messages.+- `api_key` (`SecretStr`, a plain string is accepted): Firecrawl API key. Falls back to the `FIRECRAWL_API_KEY` environment variable when empty. It is only sent in the `Authorization` header. Raised errors, log messages and `failures` redact the configured key (when it is at least 8 characters) and anything in Firecrawl's `fc-` key format.- `base_url` (str): API base URL (default `https://api.firecrawl.dev/v2`).- `location` (str, optional): location to localise results, e.g. `Germany`.- `time_range` (str, optional): `day`, `week`, `month`, or `year`. Only applies to web results.@@ -31,8 +31,8 @@ Searches the web or recent news through the [Firecrawl Search](https://www.firec- `include_content` (bool): also return each result page as Markdown (default `False`).### Output Schema-- `results`: a list of `FirecrawlSearchResultItem` items. Each has `query`, `title`, `url`, and optional `description` (a query-relevant excerpt or snippet), `position`, `published` (news), and `content` (Markdown, when `include_content` is set). Results without a well-formed http(s) URL (one with a host and no whitespace) are skipped, and badly typed optional fields are left empty.-- `failures`: queries that failed while others returned results, each with `query` and `error` (the HTTP status and the API's error message). A key appearing in either is redacted. They are also logged as warnings.+- `results`: a list of `FirecrawlSearchResultItem` items. Each has `query`, `title`, `url`, and optional `description` (a query-relevant excerpt or snippet), `position`, `published` (news), and `content` (Markdown, when `include_content` is set). Results without a well-formed http(s) URL (a real host, a valid port, no whitespace or control characters) are skipped, and badly typed optional fields are left empty.+- `failures`: queries that failed while others returned results, each with `query` and `error` (the HTTP status and the API's error message). Keys are redacted from both as described for `api_key`. They are also logged as warnings.## UsageIf no query returns results and at least one failed (for example a wrong API key, no credits, or a malformed response), `run` raises the first error instead of returning an empty list. Redirects are not followed; they are reported as errors.diff --git a/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.py b/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.pyindex 9b3098d..f92463b 100644--- a/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.py+++ b/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.py@@ -6,7 +6,7 @@ import socketimport sysimport tracebackfrom contextlib import asynccontextmanager-from typing import AsyncIterator, Awaitable, Callable, Dict, List, Sequence, Tuple, Union+from typing import AsyncIterator, Awaitable, Callable, Dict, Iterator, List, Sequence, Tuple, TypedDict, Unionfrom unittest.mock import AsyncMock, patchimport pytest@@ -28,6 +28,14 @@ from tool.firecrawl_search import ( # noqa: E402Body = Dict[str, object]Responder = Callable[[Body], Union[web.Response, Awaitable[web.Response]]]++class Seen(TypedDict):+ """One request as the fake server received it."""++ headers: Dict[str, str]+ body: Body++DUMMY_KEY = "fc-dummy0secret0key0123456789" # a configured key in a custom formatCANONICAL_KEY = "fc-0123456789abcdef0123456789abcdef" # a key in Firecrawl's own formatKEYS = (DUMMY_KEY, DUMMY_KEY.upper(), CANONICAL_KEY, CANONICAL_KEY.upper())@@ -61,19 +69,28 @@ CONTENT_HIT = {@pytest.fixture(autouse=True)-def offline(monkeypatch):- """Keep the suite offline: any attempt to resolve a host other than the local test server fails the test."""+def offline(monkeypatch) -> Iterator[List[str]]:+ """Keep the suite offline. Resolving a host other than loopback raises gaierror, and connecting to a+ non-loopback address raises OSError; both are recorded, and the test fails unless it expected them."""attempts: List[str] = []real_getaddrinfo = socket.getaddrinfo+ real_connect = socket.socket.connect- def loopback_only(host, *args, **kwargs):+ def resolve_loopback_only(host, *args, **kwargs):if host not in LOOPBACK_HOSTS:attempts.append(str(host))raise socket.gaierror("network access is disabled in these tests")return real_getaddrinfo(host, *args, **kwargs)- monkeypatch.setattr(socket, "getaddrinfo", loopback_only)- yield+ def connect_loopback_only(sock, address):+ if isinstance(address, tuple) and address[0] not in LOOPBACK_HOSTS:+ attempts.append(str(address[0]))+ raise OSError("network access is disabled in these tests")+ return real_connect(sock, address)++ monkeypatch.setattr(socket, "getaddrinfo", resolve_loopback_only)+ monkeypatch.setattr(socket.socket, "connect", connect_loopback_only)+ yield attemptsassert attempts == []@@ -109,13 +126,13 @@ def respond_per_query(bad_query: str, bad: Responder, good: Responder) -> Respon# Test harness #################@asynccontextmanager-async def fake_firecrawl(respond: Responder) -> AsyncIterator[Tuple[str, List[Body]]]:+async def fake_firecrawl(respond: Responder) -> AsyncIterator[Tuple[str, List[Seen]]]:"""Serve POST /v2/search on a local aiohttp server; `respond(body)` builds each response."""- seen: List[Body] = []+ seen: List[Seen] = []async def handler(request: web.Request) -> web.Response:body = await request.json()- seen.append({"headers": dict(request.headers), "body": body})+ seen.append(Seen(headers=dict(request.headers), body=body))response = respond(body)return await response if asyncio.iscoroutine(response) else response@@ -135,7 +152,7 @@ def http_tool(base_url: str, api_key: str = DUMMY_KEY, **config) -> FirecrawlSeaasync def search(respond: Responder, queries: Sequence[str] = ("q",), api_key: str = DUMMY_KEY, **params-) -> Tuple[FirecrawlSearchToolOutputSchema, List[Body]]:+) -> Tuple[FirecrawlSearchToolOutputSchema, List[Seen]]:"""Run one search against a fake server and return (output, requests seen)."""async with fake_firecrawl(respond) as (base_url, seen):tool = http_tool(base_url, api_key)@@ -229,6 +246,10 @@ def test_to_item_drops_badly_typed_fields(field, value, attribute, expected):"https://example.com:8443/a?b=c#d","http://[::1]:8080/x","https://[email protected]/",+ "http://192.0.2.1:8080/x",+ "https://müller.de/straße",+ "https://xn--mller-kva.de/",+ "https://example.com/%C3%BC%20x.pdf",],)def test_to_item_keeps_valid_http_urls(url):@@ -259,6 +280,22 @@ def test_to_item_keeps_valid_http_urls(url):{"url": "https://exa mple.com/a"},{"url": "https://example.com/a\n"},{"url": "https://example.com\t/a"},+ {"url": "https://./"},+ {"url": "https://-/"},+ {"url": "https://%/"},+ {"url": "https://_x.com/"},+ {"url": "https://[:]/"},+ {"url": "https://[zz]/"},+ {"url": "https://a\x00b.com/"},+ {"url": "https://example.com/a\x7f"},+ {"url": "https://exa\u200bmple.com/"},+ {"url": "https://example.com/\xa0"},+ {"url": "https://example.com:abc/"},+ {"url": "https://example.com:99999/"},+ {"url": "https://example.com:65536/"},+ {"url": "https://example.com:0/"},+ {"url": "https://example.com:\u0664\u0664\u0663/"},+ {"url": "https://a [email protected]/"},],)def test_to_item_without_usable_url_is_none(hit):@@ -412,6 +449,14 @@ async def test_non_json_bodies_raise_with_status(response, expected):assert str(error) == f"Firecrawl search failed for 'q': {expected}"+async def test_deeply_nested_json_is_a_wrapped_failure():+ """JSON too deep for the parser must fail like any other bad body, not escape with the response in scope."""+ error = await search_error(respond_raw(status=200, text="[" * 200_000, content_type="application/json"))+ assert str(error) == "Firecrawl search failed for 'q': 200 response did not report success"+ assert_no_key(error_surfaces(error))++@pytest.mark.asyncioasync def test_redirect_is_not_followed():"""A redirect, even to another server, is reported as an error; the query is never re-sent elsewhere."""@@ -511,6 +556,25 @@ async def test_invalid_base_url_is_wrapped_and_no_frame_holds_the_key(base_url,assert_no_key(str(raised.value), repr(raised.value), *frame_locals(raised.value, is_outside_this_test_file))+ "base_url, blocked_host",+ [+ ("http://exa\nmple.com/v2", "example.com"), # yarl drops the newline, so this resolves example.com+ (f"http://{'a' * 70}.example.com/v2", f"{'a' * 70}.example.com"),+ ],+)+async def test_unresolvable_base_url_is_wrapped(offline, base_url, blocked_host):+ """A DNS failure is reported as a request failure; the offline guard answers the lookup, so nothing leaves."""+ with pytest.raises(Exception) as raised:+ await http_tool(base_url).run_async(FirecrawlSearchToolInputSchema(queries=["q"]))++ assert str(raised.value).startswith("Firecrawl search failed for 'q': request failed: ClientConnectorDNSError ")+ assert_no_key(str(raised.value), repr(raised.value), *frame_locals(raised.value, is_outside_this_test_file))+ assert offline == [blocked_host]+ offline.clear()++################# Key handling #################diff --git a/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.py b/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.pyindex 16bea80..32da97e 100644--- a/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.py+++ b/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.py@@ -3,7 +3,8 @@ import loggingimport osimport refrom concurrent.futures import ThreadPoolExecutor-from typing import Dict, List, Literal, Optional, Tuple, Union, cast+from typing import Dict, List, Literal, Optional, Tuple, Union+from urllib.parse import urlsplitimport aiohttpfrom pydantic import Field, SecretStr, field_validator@@ -111,9 +112,10 @@ class FirecrawlSearchTool(BaseTool[FirecrawlSearchToolInputSchema, FirecrawlSear# when it is long enough that replacing it cannot mangle ordinary words.KEY_PATTERN = re.compile(r"\bfc-[0-9a-f]{32}\b", re.IGNORECASE)MIN_REDACTED_KEY_LENGTH = 8- # A result is kept only when its whole URL is http(s) with a host and contains no whitespace.+ # Shape of a usable result URL: http(s), optional userinfo, a host that starts with a letter or digit (or an+ # IPv6 literal), an ASCII port, and no whitespace anywhere. urlsplit then validates the port range and IPv6.RESULT_URL_PATTERN = re.compile(- r"https?://(?:[^\s/?#@]*@)?(?:[^\s/?#@:\[\]]+|\[[0-9a-f:.]+\])(?::\d*)?(?:[/?#]\S*)?", re.IGNORECASE+ r"https?://(?:[^\s/?#@]*@)?(?:[^\W_][^\s/?#@:\[\]]*|\[[0-9a-f:.]+\])(?::[0-9]*)?(?:[/?#]\S*)?", re.IGNORECASE)def __init__(self, config: FirecrawlSearchToolConfig = FirecrawlSearchToolConfig()):@@ -130,20 +132,31 @@ class FirecrawlSearchTool(BaseTool[FirecrawlSearchToolInputSchema, FirecrawlSear"""Return the first non-empty string; result fields are provider data and may have any type."""return next((value for value in values if isinstance(value, str) and value), None)+ @classmethod+ def _usable_url(cls, url: str) -> bool:+ """True for a printable http(s) URL with a real host and an in-range, non-zero port."""+ if not (url.isprintable() and cls.RESULT_URL_PATTERN.fullmatch(url)):+ return False+ try:+ # urlsplit raises ValueError for an out-of-range port or an invalid IPv6 literal.+ return urlsplit(url).port != 0+ except ValueError:+ return False+@classmethoddef _to_item(cls, hit: object, query: str, max_content_chars: Optional[int] = None) -> Optional[FirecrawlSearchResultItem]:"""Normalise one result, or return None when it has no usable http(s) URL."""fields: Dict[str, object] = hit if isinstance(hit, dict) else {}url = str(fields.get("url"))- if not cls.RESULT_URL_PATTERN.fullmatch(url):+ if not cls._usable_url(url):return Nonecontent = cls._first_text(fields.get("markdown"))return FirecrawlSearchResultItem(query=query,- title=cls._first_text(fields.get("title"), url),+ title=cls._first_text(fields.get("title")) or url,url=url,description=cls._first_text(fields.get("description"), fields.get("snippet")),- position=fields.get("position"),+ position=FirecrawlSearchResultItem._positive_rank_or_none(fields.get("position")),published=cls._first_text(fields.get("date")),content=content[:max_content_chars] if content else None,)@@ -172,21 +185,22 @@ class FirecrawlSearchTool(BaseTool[FirecrawlSearchToolInputSchema, FirecrawlSearasync def _read_json(resp: aiohttp.ClientResponse) -> object:try:return await resp.json(content_type=None)- except ValueError:+ except (ValueError, RecursionError):+ # Invalid JSON, or JSON nested too deeply for the parser.return None- def _failure(self, status: int, reason: Optional[str], data: object) -> Optional[str]:- """Return why a response is not a successful search (only a 200 whose body says success is true is),- or None when it is. Provider text is redacted here, where it enters the tool."""+ def _check_response(self, status: int, reason: Optional[str], data: object) -> Union[Dict[str, object], str]:+ """Return the body of a successful search (a 200 whose body says success is true), or why the response+ is not one. Provider text is redacted here, where it enters the tool."""payload: Dict[str, object] = data if isinstance(data, dict) else {}if status == 200 and payload.get("success") is True:- return None+ return payloadreturn self._redact(f"{status} {payload.get('error') or reason}")async def _exchange(self, session: aiohttp.ClientSession, query: str, params: FirecrawlSearchToolInputSchema- ) -> Tuple[object, Optional[str]]:- """Send one search request and return the parsed body plus why it failed (None on success).+ ) -> Union[Dict[str, object], str]:+ """Send one search request and return the body of a successful response, or why it failed.Transport errors, timeouts and invalid URLs are turned into a failure reason here instead of propagating,because aiohttp's own frames and errors hold the request headers, Authorization included."""@@ -196,23 +210,21 @@ class FirecrawlSearchTool(BaseTool[FirecrawlSearchToolInputSchema, FirecrawlSear) as resp:payload = await self._read_json(resp)reason = resp.reason if resp.status != 200 else "response did not report success"- return payload, self._failure(resp.status, reason, payload)+ return self._check_response(resp.status, reason, payload)except (aiohttp.ClientError, asyncio.TimeoutError, ValueError) as error:- return None, self._redact(f"request failed: {type(error).__name__} {str(error) or f'after {self.timeout:g}s'}")+ return self._redact(f"request failed: {type(error).__name__} {str(error) or f'after {self.timeout:g}s'}")async def _post(self, session: aiohttp.ClientSession, query: str, params: FirecrawlSearchToolInputSchema) -> Dict[str, object]:"""Return the body of a successful search response, or raise.- The raise happens in this frame, which holds neither the response nor an aiohttp error, and the body of a- failed response is dropped first, so a traceback that captures locals cannot show a key echoed back."""- payload, failure = await self._exchange(session, query, params)- if failure:- payload = None- raise self._error(query, failure)- # _failure only returns None for a dict body that reports success.- return cast(Dict[str, object], payload)+ The raise happens in this frame, which only ever holds the redacted failure reason: no response, no aiohttp+ error and no failed body, so a traceback that captures locals cannot show a key echoed back."""+ outcome = await self._exchange(session, query, params)+ if isinstance(outcome, str):+ raise self._error(query, outcome)+ return outcome@staticmethoddef _extract_hits(payload: Dict[str, object], search_type: str) -> Optional[List[object]]:@@ -300,9 +312,9 @@ if __name__ == "__main__": # pragma: no coverload_dotenv()console = Console()- tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key=os.getenv("FIRECRAWL_API_KEY", "")))+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key=SecretStr(os.getenv("FIRECRAWL_API_KEY", ""))))- examples = [+ examples: List[Tuple[Literal["web", "news"], bool, str]] = [("web", False, "atomic agents framework"),("news", False, "AI agents"),("web", True, "atomic agents framework"),