ouroboros-ai 0.28.8.dev4__tar.gz → 0.28.8.dev7__tar.gz

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.28.8.dev4
+Version: 0.28.8.dev7
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev7}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.28.8.dev4'
-__version_tuple__ = version_tuple = (0, 28, 8, 'dev4')
+__version__ = version = '0.28.8.dev7'
+__version_tuple__ = version_tuple = (0, 28, 8, 'dev7')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev7}/src/ouroboros/mcp/client/adapter.py

@@ -258,12 +258,31 @@ class MCPClientAdapter:
 
             import httpx
             from mcp.client.streamable_http import streamable_http_client
-            from mcp.shared._httpx_utils import create_mcp_http_client
+
+            from ouroboros import __version__ as _ouroboros_version
 
             timeout = httpx.Timeout(config.timeout, read=max(config.timeout, 300.0))
-            http_client = create_mcp_http_client(
-                headers=config.headers if config.headers else None,
+
+            # Compose headers with a stable User-Agent for observability.
+            # Now that we own the httpx client (no longer going through the
+            # mcp SDK's private helper), set the UA explicitly so that MCP
+            # servers can still identify the ouroboros client in their logs.
+            # Caller-supplied headers take precedence.
+            default_headers = {
+                "User-Agent": f"ouroboros-mcp-client/{_ouroboros_version}",
+            }
+            if config.headers:
+                merged_headers: dict[str, str] = {**default_headers, **config.headers}
+            else:
+                merged_headers = default_headers
+
+            http_client = httpx.AsyncClient(
+                headers=merged_headers,
                 timeout=timeout,
+                # SSRF hardening: do not follow redirects. An attacker-controlled
+                # server could otherwise 302 us into a loopback / metadata URL
+                # that bypasses the static URL validation in MCPServerConfig.
+                follow_redirects=False,
             )
             self._http_client = http_client
 

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev7}/src/ouroboros/mcp/types.py

@@ -8,7 +8,110 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 from enum import StrEnum
+import ipaddress
+import os
 from typing import Any
+from urllib.parse import urlparse
+
+# Schemes permitted for SSE / HTTP / STREAMABLE_HTTP transports.
+_ALLOWED_URL_SCHEMES = frozenset({"http", "https"})
+
+# Environment flag that intentionally re-enables loopback / private / link-local
+# IP literals for local development. Leave unset in production.
+_ALLOW_LOCAL_TRANSPORT_ENV = "OUROBOROS_ALLOW_LOCAL_TRANSPORT"
+
+# Well-known hostnames that resolve to loopback addresses.  These bypass the
+# ``ipaddress.ip_address()`` check (they raise ``ValueError`` because they are
+# not IP literals), so we must block them explicitly.
+_LOOPBACK_HOSTNAMES = frozenset({"localhost"})
+
+
+def _validate_transport_url(url: str, transport: str) -> None:
+    """Validate a transport URL against common SSRF vectors.
+
+    The MCP client will dial whatever URL is configured for SSE, HTTP, or
+    STREAMABLE_HTTP transports. Without hardening, that turns any untrusted
+    caller that can influence the ``url`` field into an SSRF primitive able to
+    reach cloud metadata services (169.254.169.254), loopback services, or
+    private RFC1918 ranges. This helper rejects the common vectors before a
+    connection is attempted.
+
+    Blocks:
+        * Non-http(s) schemes (``file://``, ``gopher://``, ``ftp://`` ...).
+        * URLs carrying userinfo (``user:pass@host``) used for credential
+          smuggling / host confusion.
+        * URLs with an empty hostname (e.g. bare ``http://``).
+        * Literal IPs resolving to loopback, link-local, or private ranges,
+          unless the ``OUROBOROS_ALLOW_LOCAL_TRANSPORT=1`` dev escape is set.
+
+    DNS resolution is intentionally out of scope for this static validation;
+    runtime code that follows redirects should be hardened separately (the
+    adapter sets ``follow_redirects=False``).
+
+    Args:
+        url: The transport URL to validate.
+        transport: Name of the transport (used only in error messages).
+
+    Raises:
+        ValueError: If any SSRF guard is triggered.
+    """
+
+    parsed = urlparse(url)
+    scheme = parsed.scheme.lower()
+
+    if scheme not in _ALLOWED_URL_SCHEMES:
+        msg = (
+            f"Only http:// and https:// URLs are supported for {transport} "
+            f"transport, got: {parsed.scheme}://"
+        )
+        raise ValueError(msg)
+
+    if parsed.username or parsed.password:
+        msg = "Transport URL must not contain userinfo (credentials)"
+        raise ValueError(msg)
+
+    hostname = parsed.hostname
+    if not hostname:
+        msg = "Transport URL must include a hostname"
+        raise ValueError(msg)
+
+    allow_local = os.environ.get(_ALLOW_LOCAL_TRANSPORT_ENV, "0") == "1"
+
+    # Strip IPv6 brackets (urlparse already does, but be defensive).
+    host_literal = hostname.strip("[]")
+
+    # Check for well-known loopback hostnames before attempting IP parsing.
+    # These bypass the IP-literal checks because they are DNS names, but
+    # they resolve to loopback addresses and must be blocked unless the
+    # dev escape hatch is enabled.
+    if host_literal in _LOOPBACK_HOSTNAMES:
+        if allow_local:
+            return
+        msg = (
+            f"Transport URL points to a local hostname: "
+            f"{hostname}. Set {_ALLOW_LOCAL_TRANSPORT_ENV}=1 for local dev."
+        )
+        raise ValueError(msg)
+
+    try:
+        ip = ipaddress.ip_address(host_literal)
+    except ValueError:
+        # Not an IP literal -- a DNS name. Static validation ends here.
+        return
+
+    if allow_local:
+        return
+
+    if ip.is_loopback or ip.is_link_local or ip.is_private or ip.is_multicast:
+        msg = (
+            f"Transport URL points to loopback/link-local/private IP: "
+            f"{hostname}. Set {_ALLOW_LOCAL_TRANSPORT_ENV}=1 for local dev."
+        )
+        raise ValueError(msg)
+
+    if ip.is_reserved or ip.is_unspecified:
+        msg = f"Transport URL points to reserved/unspecified IP: {hostname}"
+        raise ValueError(msg)
 
 
 class TransportType(StrEnum):
@@ -71,6 +174,8 @@ class MCPServerConfig:
         ):
             msg = f"url is required for {self.transport} transport"
             raise ValueError(msg)
+        if self.url:
+            _validate_transport_url(self.url, str(self.transport))
 
 
 @dataclass(frozen=True, slots=True)

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev7}/tests/unit/mcp/client/test_adapter.py

@@ -1,5 +1,6 @@
 """Tests for MCP client adapter."""
 
+import inspect
 from unittest.mock import AsyncMock, MagicMock
 
 from ouroboros.mcp.client.adapter import MCPClientAdapter
@@ -134,3 +135,19 @@ class TestMCPClientAdapterRetry:
         assert adapter._max_retries == 5
         assert adapter._retry_wait_initial == 2.0
         assert adapter._retry_wait_max == 20.0
+
+
+class TestNoPrivateAPIImport:
+    """Verify private MCP SDK imports are not used."""
+
+    def test_no_private_httpx_utils_import(self) -> None:
+        """adapter.py must not import from mcp.shared._httpx_utils (private API)."""
+        import ouroboros.mcp.client.adapter as adapter_module
+
+        source = inspect.getsource(adapter_module)
+        assert "_httpx_utils" not in source, (
+            "adapter.py still references the private mcp.shared._httpx_utils module"
+        )
+        assert "create_mcp_http_client" not in source, (
+            "adapter.py still references the private create_mcp_http_client helper"
+        )

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev7}/tests/unit/mcp/client/test_adapter_transport_lifecycle.py

@@ -17,6 +17,12 @@ from ouroboros.mcp.client.adapter import MCPClientAdapter
 from ouroboros.mcp.types import MCPServerConfig, TransportType
 
 
+@pytest.fixture(autouse=True)
+def _allow_local_transport(monkeypatch: pytest.MonkeyPatch) -> None:
+    """These tests use localhost URLs — enable the local transport escape hatch."""
+    monkeypatch.setenv("OUROBOROS_ALLOW_LOCAL_TRANSPORT", "1")
+
+
 def _make_stdio_config(name: str = "test") -> MCPServerConfig:
     return MCPServerConfig(
         name=name,
@@ -311,7 +317,7 @@ class TestHTTPTransportConnect:
         with (
             patch("mcp.client.streamable_http.streamable_http_client", return_value=transport_cm),
             patch("mcp.ClientSession", return_value=session),
-            patch("mcp.shared._httpx_utils.create_mcp_http_client"),
+            patch("httpx.AsyncClient"),
         ):
             result = await adapter.connect(_make_http_config())
 
@@ -329,7 +335,7 @@ class TestHTTPTransportConnect:
         with (
             patch("mcp.client.streamable_http.streamable_http_client", return_value=transport_cm),
             patch("mcp.ClientSession", return_value=session),
-            patch("mcp.shared._httpx_utils.create_mcp_http_client"),
+            patch("httpx.AsyncClient"),
         ):
             result = await adapter.connect(
                 _make_http_config(transport=TransportType.STREAMABLE_HTTP)
@@ -355,7 +361,7 @@ class TestHTTPTransportConnect:
         with (
             patch("mcp.client.streamable_http.streamable_http_client", return_value=transport_cm),
             patch("mcp.ClientSession", return_value=session),
-            patch("mcp.shared._httpx_utils.create_mcp_http_client"),
+            patch("httpx.AsyncClient"),
         ):
             result = await adapter.connect(_make_http_config())
 
@@ -366,7 +372,7 @@ class TestHTTPTransportConnect:
 
     @pytest.mark.asyncio
     async def test_http_connect_passes_headers(self):
-        """When config has headers, create_mcp_http_client called with them."""
+        """When config has headers, httpx.AsyncClient is called with them."""
         adapter = MCPClientAdapter()
         transport_cm = _mock_http_transport_cm()
         session = _mock_session()
@@ -383,17 +389,22 @@ class TestHTTPTransportConnect:
                 "mcp.client.streamable_http.streamable_http_client", return_value=transport_cm
             ) as mock_http,
             patch("mcp.ClientSession", return_value=session),
-            patch("mcp.shared._httpx_utils.create_mcp_http_client") as mock_factory,
+            patch("httpx.AsyncClient") as mock_async_client,
         ):
             result = await adapter.connect(config)
 
         assert result.is_ok
-        mock_factory.assert_called_once()
-        call_kwargs = mock_factory.call_args
-        assert call_kwargs.kwargs["headers"] == {"Authorization": "Bearer token123"}
+        mock_async_client.assert_called_once()
+        call_kwargs = mock_async_client.call_args
+        # Caller-supplied headers must survive merging with the default UA.
+        headers = call_kwargs.kwargs["headers"]
+        assert headers["Authorization"] == "Bearer token123"
+        assert headers["User-Agent"].startswith("ouroboros-mcp-client/")
+        # SSRF hardening: redirects disabled on the transport httpx client.
+        assert call_kwargs.kwargs["follow_redirects"] is False
         mock_http.assert_called_once_with(
             "http://localhost:3000",
-            http_client=mock_factory.return_value,
+            http_client=mock_async_client.return_value,
         )
 
     @pytest.mark.asyncio
@@ -413,7 +424,7 @@ class TestHTTPTransportConnect:
         with (
             patch("mcp.client.streamable_http.streamable_http_client", return_value=transport_cm),
             patch("mcp.ClientSession", return_value=session),
-            patch("mcp.shared._httpx_utils.create_mcp_http_client") as mock_factory,
+            patch("httpx.AsyncClient") as mock_async_client,
             patch("httpx.Timeout") as mock_timeout,
         ):
             result = await adapter.connect(config)
@@ -421,10 +432,13 @@ class TestHTTPTransportConnect:
         assert result.is_ok
         # read timeout should be max(config.timeout, 300.0) for SSE streaming
         mock_timeout.assert_called_once_with(15.0, read=300.0)
-        mock_factory.assert_called_once_with(
-            headers=None,
-            timeout=mock_timeout.return_value,
-        )
+        mock_async_client.assert_called_once()
+        call_kwargs = mock_async_client.call_args.kwargs
+        # With no caller headers, we still set a default User-Agent so
+        # MCP servers can identify the ouroboros client in their logs.
+        assert call_kwargs["headers"]["User-Agent"].startswith("ouroboros-mcp-client/")
+        assert call_kwargs["timeout"] is mock_timeout.return_value
+        assert call_kwargs["follow_redirects"] is False
 
     @pytest.mark.asyncio
     async def test_http_disconnect_cleans_transport_on_error(self):
@@ -436,7 +450,7 @@ class TestHTTPTransportConnect:
         with (
             patch("mcp.client.streamable_http.streamable_http_client", return_value=transport_cm),
             patch("mcp.ClientSession", return_value=session),
-            patch("mcp.shared._httpx_utils.create_mcp_http_client"),
+            patch("httpx.AsyncClient"),
         ):
             result = await adapter.connect(_make_http_config())
 

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev7}/tests/unit/mcp/test_types.py

@@ -71,8 +71,9 @@ class TestMCPServerConfig:
                 transport=TransportType.HTTP,
             )
 
-    def test_valid_http_config(self) -> None:
+    def test_valid_http_config(self, monkeypatch: pytest.MonkeyPatch) -> None:
         """Valid HTTP config is created successfully."""
+        monkeypatch.setenv("OUROBOROS_ALLOW_LOCAL_TRANSPORT", "1")
         config = MCPServerConfig(
             name="test",
             transport=TransportType.HTTP,
@@ -80,8 +81,9 @@ class TestMCPServerConfig:
         )
         assert config.url == "http://localhost:3000"
 
-    def test_valid_sse_config(self) -> None:
+    def test_valid_sse_config(self, monkeypatch: pytest.MonkeyPatch) -> None:
         """Valid SSE config is created successfully."""
+        monkeypatch.setenv("OUROBOROS_ALLOW_LOCAL_TRANSPORT", "1")
         config = MCPServerConfig(
             name="test",
             transport=TransportType.SSE,
@@ -111,6 +113,210 @@ class TestMCPServerConfig:
         assert config.env == {}
         assert config.headers == {}
 
+    @pytest.mark.parametrize("scheme", ["file", "gopher", "ftp"])
+    def test_rejects_non_http_url_schemes(self, scheme: str) -> None:
+        """MCPServerConfig rejects non-http(s) URL schemes to prevent SSRF."""
+        url = f"{scheme}://example.com/path"
+        with pytest.raises(ValueError, match="Only http:// and https:// URLs are supported"):
+            MCPServerConfig(
+                name="test",
+                transport=TransportType.SSE,
+                url=url,
+            )
+
+    @pytest.mark.parametrize("scheme", ["file", "gopher", "ftp"])
+    def test_rejects_non_http_url_schemes_streamable_http(self, scheme: str) -> None:
+        """MCPServerConfig rejects non-http(s) schemes for STREAMABLE_HTTP transport."""
+        url = f"{scheme}://example.com/path"
+        with pytest.raises(ValueError, match="Only http:// and https:// URLs are supported"):
+            MCPServerConfig(
+                name="test",
+                transport=TransportType.STREAMABLE_HTTP,
+                url=url,
+            )
+
+    def test_accepts_http_url(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """MCPServerConfig accepts http:// URLs."""
+        monkeypatch.setenv("OUROBOROS_ALLOW_LOCAL_TRANSPORT", "1")
+        config = MCPServerConfig(
+            name="test",
+            transport=TransportType.SSE,
+            url="http://localhost:8080/sse",
+        )
+        assert config.url == "http://localhost:8080/sse"
+
+    def test_accepts_https_url(self) -> None:
+        """MCPServerConfig accepts https:// URLs."""
+        config = MCPServerConfig(
+            name="test",
+            transport=TransportType.STREAMABLE_HTTP,
+            url="https://api.example.com/mcp",
+        )
+        assert config.url == "https://api.example.com/mcp"
+
+
+class TestMCPServerConfigSSRFHardening:
+    """SSRF hardening beyond the scheme allowlist.
+
+    These tests cover review finding #402: the prior check only validated
+    URL schemes and left obvious SSRF vectors open (loopback, link-local
+    metadata endpoints, RFC1918 ranges, credential smuggling, empty hosts).
+    """
+
+    @pytest.mark.parametrize(
+        "url",
+        [
+            "http://127.0.0.1/",
+            "http://127.0.0.1:8080/",
+            "http://[::1]/",
+            "https://[::1]:443/",
+        ],
+    )
+    def test_rejects_loopback(self, url: str, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Loopback IPv4/IPv6 literals are rejected."""
+        monkeypatch.delenv("OUROBOROS_ALLOW_LOCAL_TRANSPORT", raising=False)
+        with pytest.raises(ValueError, match="loopback/link-local/private"):
+            MCPServerConfig(
+                name="test",
+                transport=TransportType.HTTP,
+                url=url,
+            )
+
+    def test_rejects_aws_metadata(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """The AWS / GCP / Azure metadata link-local IP is rejected."""
+        monkeypatch.delenv("OUROBOROS_ALLOW_LOCAL_TRANSPORT", raising=False)
+        with pytest.raises(ValueError, match="loopback/link-local/private"):
+            MCPServerConfig(
+                name="test",
+                transport=TransportType.STREAMABLE_HTTP,
+                url="http://169.254.169.254/latest/meta-data/",
+            )
+
+    @pytest.mark.parametrize(
+        "url",
+        [
+            "http://10.0.0.1/",
+            "http://10.255.255.255/",
+            "http://172.16.0.1/",
+            "http://172.31.255.254/",
+            "http://192.168.1.1/",
+        ],
+    )
+    def test_rejects_private_ranges(self, url: str, monkeypatch: pytest.MonkeyPatch) -> None:
+        """RFC1918 private IPv4 ranges are rejected."""
+        monkeypatch.delenv("OUROBOROS_ALLOW_LOCAL_TRANSPORT", raising=False)
+        with pytest.raises(ValueError, match="loopback/link-local/private"):
+            MCPServerConfig(
+                name="test",
+                transport=TransportType.HTTP,
+                url=url,
+            )
+
+    @pytest.mark.parametrize(
+        "url",
+        [
+            "http://user:pass@example.com/",
+            "http://user@example.com/",
+            "https://admin:secret@api.example.com/mcp",
+        ],
+    )
+    def test_rejects_userinfo(self, url: str) -> None:
+        """URLs carrying userinfo (credential smuggling) are rejected."""
+        with pytest.raises(ValueError, match="userinfo"):
+            MCPServerConfig(
+                name="test",
+                transport=TransportType.HTTP,
+                url=url,
+            )
+
+    def test_rejects_empty_hostname(self) -> None:
+        """Bare scheme URLs without a hostname are rejected."""
+        with pytest.raises(ValueError, match="hostname"):
+            MCPServerConfig(
+                name="test",
+                transport=TransportType.HTTP,
+                url="http://",
+            )
+
+    def test_rejects_javascript_scheme(self) -> None:
+        """javascript: and other non-http schemes remain rejected."""
+        with pytest.raises(ValueError, match="Only http:// and https://"):
+            MCPServerConfig(
+                name="test",
+                transport=TransportType.HTTP,
+                url="javascript:alert(1)",
+            )
+
+    def test_accepts_public_hostname(self) -> None:
+        """Public DNS hostnames are still accepted."""
+        config = MCPServerConfig(
+            name="test",
+            transport=TransportType.HTTP,
+            url="http://example.com/",
+        )
+        assert config.url == "http://example.com/"
+
+    def test_accepts_public_ip(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Public IP literals (e.g. 8.8.8.8) are still accepted."""
+        monkeypatch.delenv("OUROBOROS_ALLOW_LOCAL_TRANSPORT", raising=False)
+        config = MCPServerConfig(
+            name="test",
+            transport=TransportType.HTTP,
+            url="https://8.8.8.8/mcp",
+        )
+        assert config.url == "https://8.8.8.8/mcp"
+
+    def test_local_transport_escape_hatch(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """OUROBOROS_ALLOW_LOCAL_TRANSPORT=1 permits loopback for local dev."""
+        monkeypatch.setenv("OUROBOROS_ALLOW_LOCAL_TRANSPORT", "1")
+        config = MCPServerConfig(
+            name="test",
+            transport=TransportType.HTTP,
+            url="http://127.0.0.1:3000/",
+        )
+        assert config.url == "http://127.0.0.1:3000/"
+
+    def test_local_transport_escape_hatch_off_by_default(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Without the env flag, the loopback guard still fires."""
+        monkeypatch.setenv("OUROBOROS_ALLOW_LOCAL_TRANSPORT", "0")
+        with pytest.raises(ValueError, match="loopback/link-local/private"):
+            MCPServerConfig(
+                name="test",
+                transport=TransportType.HTTP,
+                url="http://127.0.0.1/",
+            )
+
+    @pytest.mark.parametrize(
+        "url",
+        [
+            "http://localhost/",
+            "http://localhost:3000/",
+            "http://localhost:8080/sse",
+            "https://localhost/",
+        ],
+    )
+    def test_rejects_localhost(self, url: str, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Loopback hostnames (localhost) are rejected without escape hatch."""
+        monkeypatch.delenv("OUROBOROS_ALLOW_LOCAL_TRANSPORT", raising=False)
+        with pytest.raises(ValueError, match="local hostname"):
+            MCPServerConfig(
+                name="test",
+                transport=TransportType.HTTP,
+                url=url,
+            )
+
+    def test_localhost_allowed_with_escape_hatch(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """OUROBOROS_ALLOW_LOCAL_TRANSPORT=1 permits localhost for local dev."""
+        monkeypatch.setenv("OUROBOROS_ALLOW_LOCAL_TRANSPORT", "1")
+        config = MCPServerConfig(
+            name="test",
+            transport=TransportType.HTTP,
+            url="http://localhost:3000/",
+        )
+        assert config.url == "http://localhost:3000/"
+
 
 class TestMCPToolParameter:
     """Test MCPToolParameter dataclass."""