diff --git a/src/agent_env/env/gateway/gateway.py b/src/agent_env/env/gateway/gateway.py index 20ae28735..a7322b676 100644 --- a/src/agent_env/env/gateway/gateway.py +++ b/src/agent_env/env/gateway/gateway.py @@ -83,15 +83,18 @@ UpstreamResponse, WebsiteRoute, declared_site_names, + called_tools, fetch_child_card, forward, listed_url, lowered, operations, + reaches_child_mcp, refuse_websocket, relay_websocket, rewrite_child_card, route_name, + tool_call_refusal, upstream_url, website_routes, ) @@ -773,7 +776,8 @@ def _query_changelog_id(self) -> int | None: async def _proxy_rest_request(self, request: Request, url_map: dict[str, str] | None = None, site_names: tuple[str, ...] = ()) -> Response: """Reverse-proxy an HTTP request to an internal service, streaming the response through; a site reached at one - of its `site_names` takes it as its ``Host``.""" + of its `site_names` takes it as its ``Host``. A call to a backing server's own MCP endpoint that the caller's + role may not make is refused here, as ``/mcp`` refuses it.""" url_map = self.rest_proxy_urls if url_map is None else url_map service_name = request.path_params["service_name"] base_url = url_map.get(service_name) @@ -785,6 +789,9 @@ async def _proxy_rest_request(self, request: Request, url_map: dict[str, str] | mcp_endpoint = site_mcp or "mcp" if url_map is self.rest_proxy_urls and (cdp := await self._browsers.cdp_answer(request, base_url, role)) is not None: return cdp + if mcp_server and request.method == "POST" and reaches_child_mcp(request, mcp_endpoint): + if (refusal := await self._refuse_disabled_calls(await request.body(), role)) is not None: + return refusal if request.method in _SAFE_METHODS: return await forward(request, base_url, role=role, timeout=self.REST_PROXY_TIMEOUT, mcp_server=mcp_server, withheld=self._withheld, mcp_endpoint=mcp_endpoint, site_names=site_names) @@ -1176,15 +1183,8 @@ async def _handle_role_mutation(self, request: Request, action: str) -> Response return self._json_response({"role": role, **snapshot}, 200) async def _handle_step(self, request: Request) -> Response: - try: - await self._ensure_tools_discovered() - except ToolNameClash as e: - return self._json_response({"error": f"{e}, so the env serves none of its servers' tools."}, 503) - except Exception: - return self._json_response( - {"error": "Tool discovery has not completed. Internal MCP servers may be unavailable."}, - 503, - ) + if (unavailable := await self._discovery_unavailable()) is not None: + return unavailable try: body = await request.json() except Exception: @@ -1614,6 +1614,30 @@ def _iter(): return StreamingResponse(_iter(), media_type="application/jsonl", headers={"X-Trajectory-Total-Bytes": str(total)}) + async def _discovery_unavailable(self) -> Response | None: + """The 503 for a request that needs the servers' tools while their discovery can't complete; None once it has.""" + try: + await self._ensure_tools_discovered() + except ToolNameClash as e: + return self._json_response({"error": f"{e}, so the env serves none of its servers' tools."}, 503) + except Exception: + return self._json_response( + {"error": "Tool discovery has not completed. Internal MCP servers may be unavailable."}, + 503, + ) + return None + + async def _refuse_disabled_calls(self, body: bytes, role: str) -> Response | None: + """The refusal for a child MCP POST through ``/svc`` calling a tool `role` may not call; None to forward it.""" + if (names := called_tools(body)) is None: # unread, it could carry a call a lenient server parses (gzip) + return tool_call_refusal(body, "The request body is not JSON") + if not names: + return None + if (unavailable := await self._discovery_unavailable()) is not None: + return unavailable # a tool hidden by default is known only once discovery has listed it + disabled = next((name for name in names if self._is_disabled(role, name)), None) + return None if disabled is None else tool_call_refusal(body, f"Tool '{disabled}' is disabled for role '{role}'") + class _ProxyArgModelBase(ArgModelBase): """ArgModelBase subclass that excludes unset fields from model_dump_one_level(). diff --git a/src/agent_env/env/gateway/rest_proxy.py b/src/agent_env/env/gateway/rest_proxy.py index 73d783374..5a12faab3 100644 --- a/src/agent_env/env/gateway/rest_proxy.py +++ b/src/agent_env/env/gateway/rest_proxy.py @@ -42,6 +42,7 @@ from urllib.parse import unquote, urlsplit, urlunsplit import httpx +from mcp.types import INVALID_REQUEST from starlette.requests import HTTPConnection, Request from starlette.responses import Response, StreamingResponse from starlette.types import Receive, Scope, Send @@ -104,7 +105,7 @@ async def forward(request: Request, base_url: str, *, role: str, timeout: httpx. return await _done(_json_response({"error": str(e)}, 400), on_done) content = await request.body() # /svc and /website request bodies are small (JSON-RPC, forms) headers = upstream_headers(request, role, withheld=withheld, site_names=site_names) - if mcp_server and request.method == "POST" and is_child_mcp_path(request.path_params.get("path", ""), mcp_endpoint): + if mcp_server and request.method == "POST" and reaches_child_mcp(request, mcp_endpoint): # The gateway is the trust boundary for identity: a child's proxied MCP endpoint stays reachable, but the # role in its JSON-RPC `_meta` is the gateway's to write, like the header above. content = stamp_jsonrpc_role(content, role) @@ -261,18 +262,31 @@ def route_prefix(request: HTTPConnection) -> str: def is_child_mcp_path(decoded_rest: str, endpoint: str = "mcp") -> bool: """Whether a /svc/{service}/{path} remainder reaches the backing server's MCP endpoint (`endpoint`, `mcp` unless its card declares another, or anything under it), judged after dot-segment normalisation, since httpx collapses - `x/../mcp` to `/mcp` on the way upstream. + `x/../mcp` to `/mcp` on the way upstream, and ignoring case, as some servers' routing does. - >>> [is_child_mcp_path(p) for p in ("mcp", "mcp/", "mcp/x", "x/../mcp", "./mcp", "/mcp", "mcpx", "agentenv", "")] - [True, True, True, True, True, True, False, False, False] - >>> [is_child_mcp_path(p, "/tools/mcp/") for p in ("tools/mcp", "tools/x/../mcp", "mcp")] - [True, True, False] + >>> [is_child_mcp_path(p) for p in ("mcp", "mcp/", "mcp/x", "x/../mcp", "./mcp", "/mcp", "MCP", "mcpx", "agentenv", "")] + [True, True, True, True, True, True, True, False, False, False] + >>> [is_child_mcp_path(p, "/tools/mcp/") for p in ("tools/mcp", "tools/x/../mcp", "Tools/Mcp", "mcp")] + [True, True, True, False] """ - normalized = posixpath.normpath("/" + decoded_rest.lstrip("/")) - at = posixpath.normpath("/" + endpoint.strip("/")) + normalized = posixpath.normpath("/" + decoded_rest.lstrip("/")).lower() + at = posixpath.normpath("/" + endpoint.strip("/")).lower() return normalized == at or normalized.startswith(at + "/") +def reaches_child_mcp(request: HTTPConnection, endpoint: str = "mcp") -> bool: + """Whether a /svc request reaches the backing server's MCP endpoint (:func:`is_child_mcp_path`), by the path as + routed here or by the one the server receives: the raw path forwarded, its dot segments removed by httpx and then + decoded, which differ when an encoded slash sits beside a dot segment (``public%2Fx/../mcp`` reaches ``/mcp``).""" + if is_child_mcp_path(request.path_params.get("path", ""), endpoint): + return True + try: + sent = httpx.URL(upstream_url("http://child", request)).path + except (ValueError, httpx.InvalidURL): + return False # forward() refuses a request-target it can't build a URL for + return is_child_mcp_path(sent, endpoint) + + def stamp_jsonrpc_role(body: bytes, role: str) -> bytes: """A JSON-RPC body (one request or a batch) with every request's `params._meta` carrying the gateway's role stamp in place of whatever the client wrote there; a body that is not JSON-RPC is returned as it came. @@ -298,6 +312,37 @@ def stamp_jsonrpc_role(body: bytes, role: str) -> bytes: return json.dumps(parsed).encode() if stamped else body +def called_tools(body: bytes) -> list[str] | None: + """The tool each JSON-RPC ``tools/call`` request in `body` (one request or a batch) names; None for a body that is + not JSON. + + >>> called_tools(b'[{"method": "tools/call", "params": {"name": "a"}}, {"method": "tools/list", "params": {}}]') + ['a'] + >>> called_tools(b"not json") is None + True + """ + try: + parsed = json.loads(body) + except ValueError: + return None + return [item["params"]["name"] for item in (parsed if isinstance(parsed, list) else [parsed]) + if isinstance(item, dict) and item.get("method") == "tools/call" and isinstance(item.get("params"), dict) + and isinstance(item["params"].get("name"), str)] + + +def tool_call_refusal(body: bytes, message: str) -> Response: + """The gateway's answer to a child MCP POST it won't forward: one request gets the tool error the gateway's own + ``/mcp`` gives, and a batch, or a body that is not JSON, is refused whole as an invalid request.""" + try: + parsed = json.loads(body) + except ValueError: + parsed = None + if isinstance(parsed, dict): + return _json_response({"jsonrpc": "2.0", "id": parsed.get("id"), + "result": {"content": [{"type": "text", "text": message}], "isError": True}}, 200) + return _json_response({"jsonrpc": "2.0", "id": None, "error": {"code": INVALID_REQUEST, "message": message}}, 400) + + def raw_remainder(raw_path: bytes, decoded_path: str, decoded_rest: str) -> bytes: """The still-encoded tail of `raw_path` that Starlette's decoded `{path}` param came from. diff --git a/tst/integration/env/gateway/gateway_test.py b/tst/integration/env/gateway/gateway_test.py index f381bba7c..2cee30a98 100644 --- a/tst/integration/env/gateway/gateway_test.py +++ b/tst/integration/env/gateway/gateway_test.py @@ -1932,6 +1932,44 @@ async def test_gateway_changes_name_the_request_behind_a_write_through_the_rest_ await email_env.close() +@pytest.mark.asyncio +@pytest.mark.integration +async def test_a_tool_disabled_for_a_role_is_refused_through_svc_as_on_the_gateway_s_mcp(mcp_server_envs, + email_service_artifact): + """A tool disabled for a role is refused on the child's own MCP endpoint through /svc as on /mcp, before it + reaches the server, while another role still calls it there.""" + email_ref = mcp_server_envs["email"] + email_env = Env.get(email_ref.id, version=email_ref.version) + try: + result = await email_env.deploy() + await email_env.load_environment_artifact(email_service_artifact) + gw = result.gateway_url + async with httpx.AsyncClient(headers=result.control_headers) as client: + resp = await client.post(f"{gw}/tools/{TOOL_DISABLE_ACTION}", timeout=30, + json={"role": "carol@example.com", "tools": ["send_email"]}) + assert resp.status_code == 200, resp.text + seen = (await client.get(f"{gw}/changes", params={"limit": 10000}, timeout=30)).json()["changes"] + after_id = seen[-1]["id"] if seen else 0 + answers = {} + for role in ("carol@example.com", "dana@example.com"): + async with httpx.AsyncClient(headers={AGENT_ENV_ROLE_HEADER: role}, timeout=60) as as_role: + for path in ("/mcp", "/svc/mcp-email/mcp"): + async with streamable_http_client(f"{gw}{path}", http_client=as_role) as (read, write, _): + async with ClientSession(read, write) as session: + await session.initialize() + answers[role, path] = await session.call_tool("send_email", { + "recipients": ["erin@example.com"], "subject": f"via {path}", "content": "noon"}) + refused = [answers["carol@example.com", path] for path in ("/mcp", "/svc/mcp-email/mcp")] + assert all(a.isError for a in refused) and refused[0].content[0].text == refused[1].content[0].text, refused + assert "disabled for role 'carol@example.com'" in refused[1].content[0].text, refused + assert not any(answers["dana@example.com", path].isError for path in ("/mcp", "/svc/mcp-email/mcp")), answers + async with httpx.AsyncClient() as client: + changes = (await client.get(f"{gw}/changes", params={"after_id": after_id}, timeout=30)).json()["changes"] + assert {a["role"] for c in changes for a in c["actors"]} == {"dana@example.com"}, changes # carol wrote nothing + finally: + await email_env.close() + + @pytest.mark.asyncio @pytest.mark.integration @skip_without_model_endpoint() diff --git a/tst/unit/env/gateway/rest_proxy_stream_test.py b/tst/unit/env/gateway/rest_proxy_stream_test.py index 921187199..2ed6ac102 100644 --- a/tst/unit/env/gateway/rest_proxy_stream_test.py +++ b/tst/unit/env/gateway/rest_proxy_stream_test.py @@ -8,16 +8,22 @@ import asyncio import doctest +import gzip import json +from types import SimpleNamespace from urllib.parse import unquote, urlsplit import httpx import pytest +from mcp.server.fastmcp.exceptions import ToolError +from mcp.types import Tool as MCPTool from starlette.testclient import TestClient from agentenv_protocol.website import ApiContext, WebsiteEnvironment, api, website -from agent_env.env.gateway import AGENT_ENV_ROLE_META_KEY, AGENT_ENV_SESSION_META_KEY +from agent_env.env.gateway import (AGENT_ENV_HIDDEN_BY_DEFAULT_META_KEY, AGENT_ENV_ROLE_META_KEY, + AGENT_ENV_SESSION_META_KEY, InternalMCPServer) from agent_env.env.gateway import gateway as gateway_module +from agent_env.env.gateway.caller import Caller from agent_env.env.gateway import rest_proxy as rest_proxy_module from agent_env.env.gateway.gateway import Gateway @@ -449,7 +455,8 @@ async def test_a_proxied_child_mcp_post_carries_the_gateway_s_role_in_every_requ forged = {AGENT_ENV_ROLE_META_KEY: "victim@example.com", AGENT_ENV_SESSION_META_KEY: "forged"} one = json.dumps(_rpc(name="t", arguments={}, _meta=forged)).encode() batch = json.dumps([_rpc(name="t", arguments={}), {"jsonrpc": "2.0", "method": "notifications/initialized"}]).encode() - for path, body in [("/svc/mcp-svc/mcp", one), ("/svc/mcp-svc/mcp/", batch), ("/svc/mcp-svc/x/../mcp", one)]: + for path, body in [("/svc/mcp-svc/mcp", one), ("/svc/mcp-svc/mcp/", batch), ("/svc/mcp-svc/x/../mcp", one), + ("/svc/mcp-svc/public%2Fx/../mcp", one)]: status, _, _ = await _call(gw, path, method="POST", body=body, headers={ "AgentEnv-Role": "alice@example.com", "content-type": "application/json", "content-length": str(len(body))}) assert status == 200 @@ -458,6 +465,7 @@ async def test_a_proxied_child_mcp_post_carries_the_gateway_s_role_in_every_requ assert sent[0]["params"]["_meta"] == stamp # the forged role and session key are gone assert sent[1][0]["params"]["_meta"] == stamp and "params" not in sent[1][1] # each request of a batch assert sent[2]["params"]["_meta"] == stamp and up.requests[2].url.path == "/mcp" # dot segments collapse upstream + assert sent[3]["params"]["_meta"] == stamp and up.requests[3].url.path == "/mcp" # routed as /public/mcp, sent to /mcp assert all(r.headers["content-length"] == str(len(r.content)) for r in up.requests) # re-serialised, re-measured assert all(r.headers.get_list("agentenv-role") == ["alice@example.com"] for r in up.requests) @@ -470,19 +478,147 @@ async def test_bodies_that_are_not_a_child_mcp_request_are_forwarded_untouched(m rest_proxy_urls={"mcp-svc": UPSTREAM, "backend": UPSTREAM}) rpc = json.dumps(_rpc(name="t", arguments={}, _meta={AGENT_ENV_ROLE_META_KEY: "x"})).encode() cases = [ - ("/svc/mcp-svc/mcp", "POST", b"not json"), # unparsable: as it came ("/svc/mcp-svc/mcp", "GET", b""), # not a POST ("/svc/mcp-svc/mcpx", "POST", rpc), # not the MCP endpoint ("/svc/mcp-svc/agentenv", "POST", rpc), # the data plane keeps its body ("/svc/backend/mcp", "POST", rpc), # not an mcp-* service ("/svc/mcp-svc/mcp", "POST", b'{"jsonrpc": "2.0", "id": 1, "result": {}}'), # no params: nothing to stamp ] + gw._apply_rule("alice@example.com", "t", True) # the tool gate reads only a child's MCP endpoint for path, method, body in cases: status, _, _ = await _call(gw, path, method=method, body=body, headers={"AgentEnv-Role": "alice@example.com"}) assert status == 200, path assert [r.content for r in up.requests] == [body for _, _, body in cases] +# --- A call to a child's MCP endpoint through /svc meets the tool rules /mcp applies --- + + +class _Listing: + """A child session as discovery reads it: the tools the child lists.""" + + def __init__(self, tools: list[MCPTool]): + self.tools = tools + + async def list_tools(self): + return SimpleNamespace(tools=self.tools) + + +def _tool(name: str, meta: dict | None = None) -> MCPTool: + return MCPTool(name=name, description="", inputSchema={"type": "object", "properties": {}}, _meta=meta) + + +def _gated(*tools: MCPTool, servers=None, **kw) -> Gateway: + kw.setdefault("rest_proxy_urls", {"mcp-svc": UPSTREAM}) + gw = Gateway(host="127.0.0.1", port=0, server_name="t", + internal_mcp_servers=servers or [InternalMCPServer("svc", f"{UPSTREAM}/mcp")], **kw) + + async def open_session(server, stack, report): + return _Listing(list(tools)) + + gw._sessions.open_session = open_session # type: ignore[method-assign] + return gw + + +async def _post_rpc(gw: Gateway, payload, role: str, path: str = "/svc/mcp-svc/mcp") -> tuple[int, dict]: + body = json.dumps(payload).encode() + try: + status, _, chunks = await _call(gw, path, method="POST", body=body, headers={ + "AgentEnv-Role": role, "content-type": "application/json", "content-length": str(len(body))}) + finally: + await gw._close_child_sessions() + return status, json.loads(b"".join(chunks)) + + +@pytest.mark.asyncio +async def test_a_tool_disabled_for_the_caller_is_refused_as_mcp_refuses_it_and_never_reaches_the_child(monkeypatch): + up = _Upstream([b"{}"]) + up.install(monkeypatch) + gw = _gated(_tool("read"), _tool("list")) + gw._apply_rule("alice@example.com", "read", True) + refused = await _post_rpc(gw, _rpc(name="read", arguments={}), "alice@example.com") + respelled = [await _post_rpc(gw, _rpc(name="read", arguments={}), "alice@example.com", path=path) + for path in ("/svc/mcp-svc/MCP/", "/svc/mcp-svc/public%2Fx/../mcp")] + allowed = [await _post_rpc(gw, _rpc(name="list", arguments={}), "alice@example.com"), + await _post_rpc(gw, _rpc(name="read", arguments={}), "carol@example.com")] + token = Caller(role="alice@example.com").bind() + try: + with pytest.raises(ToolError) as on_mcp: + await gw._mcp._tool_manager.call_tool("read", {}) + finally: + Caller.reset(token) + assert [refused, *respelled] == [(200, {"jsonrpc": "2.0", "id": 1, "result": { + "content": [{"type": "text", "text": str(on_mcp.value)}], "isError": True}})] * 3 + assert allowed == [(200, {}), (200, {})] + assert [json.loads(r.content)["params"]["name"] for r in up.requests] == ["list", "read"] + + +@pytest.mark.asyncio +async def test_a_tool_hidden_by_default_is_refused_until_a_rule_names_it(monkeypatch): + up = _Upstream([b"{}"]) + up.install(monkeypatch) + gw = _gated(_tool("insert", {AGENT_ENV_HIDDEN_BY_DEFAULT_META_KEY: True})) + call = _rpc(name="insert", arguments={}) + unnamed = await _post_rpc(gw, call, "default") # the first call discovers what is hidden + gw._apply_rule("*", "*", False) # a rule for every tool never reaches a hidden one + wildcard = await _post_rpc(gw, call, "default") + gw._apply_rule("*", "insert", False) + named = await _post_rpc(gw, call, "default") + assert unnamed[1]["result"]["isError"] and wildcard[1]["result"]["isError"] + assert named == (200, {}) and len(up.requests) == 1 + + +@pytest.mark.asyncio +async def test_a_batch_with_a_disabled_call_is_refused_whole(monkeypatch): + up = _Upstream([b"{}"]) + up.install(monkeypatch) + gw = _gated(_tool("read"), _tool("list")) + gw._apply_rule("alice@example.com", "read", True) + batch = [_rpc(name="list", arguments={}), {**_rpc(name="read", arguments={}), "id": 2}] + status, body = await _post_rpc(gw, batch, "alice@example.com") + assert status == 400 and body["error"]["message"] == "Tool 'read' is disabled for role 'alice@example.com'" + assert up.requests == [] + + +@pytest.mark.asyncio +async def test_a_body_the_gateway_cannot_read_is_refused_not_forwarded(monkeypatch): + up = _Upstream([b"{}"]) + up.install(monkeypatch) + gw = _gated(_tool("read")) + gw._apply_rule("alice@example.com", "read", True) + for body, headers in [(b"not json", {}), + (gzip.compress(json.dumps(_rpc(name="read", arguments={})).encode()), {"content-encoding": "gzip"})]: + status, _, chunks = await _call(gw, "/svc/mcp-svc/mcp", method="POST", body=body, + headers={"AgentEnv-Role": "alice@example.com", **headers}) + assert status == 400 and json.loads(b"".join(chunks))["error"]["message"] == "The request body is not JSON" + assert up.requests == [] + + +@pytest.mark.asyncio +async def test_a_site_s_own_mcp_endpoint_is_gated_the_same_way(monkeypatch): + up = _Upstream([b"{}"]) + up.install(monkeypatch) + gw = _gated(_tool("checkout"), servers=[InternalMCPServer("shop", f"{UPSTREAM}/tools/mcp")], + rest_proxy_urls={"shop": UPSTREAM}, website_urls={"shop": UPSTREAM}) + gw._apply_rule("default", "checkout", True) + status, body = await _post_rpc(gw, _rpc(name="checkout", arguments={}), "default", path="/svc/shop/tools/mcp") + assert status == 200 and body["result"]["isError"] and up.forwarded == [] + + +@pytest.mark.asyncio +async def test_a_call_is_refused_while_discovery_cannot_complete(monkeypatch): + up = _Upstream([b"{}"]) + up.install(monkeypatch) + gw = _gated() + + async def unreachable(server, stack, report): + raise httpx.ConnectError("down") + + gw._sessions.open_session = unreachable # type: ignore[method-assign] + status, body = await _post_rpc(gw, _rpc(name="read", arguments={}), "default") + assert status == 503 and "discovery" in body["error"] and up.requests == [] + + def _forwarded(request: httpx.Request) -> tuple[list[str], list[str], list[str]]: return tuple(request.headers.get_list(name) for name in ("x-forwarded-host", "x-forwarded-proto", "x-forwarded-prefix"))