"""The HTTP transport: every way a request is refused, and the one way it is not. This file imports Starlette as well as the SDK, **unconditionally**, for the reason ``test_mcp_server.py`` imports the SDK that way: the thing under test is the wiring, only a real ASGI stack can judge it, and a file that skipped when its dependency was missing would be green in precisely the build where that mattered. The store itself is standard library and tested without any of this (``test_mcp_authorizations.py``). The app is driven through ``starlette.testclient``, which speaks to it over ASGI with no socket. That is enough for everything here -- a status code, a header, an empty body, which tools a session is shown -- and it is deliberately *not* enough for "the unit comes up and answers on a port", which is ``checks/vm-mcp.nix``' job. ``Host: testserver`` is what the test client sends, so every app built here names it in ``allowed_hosts``. That is not a workaround: DNS-rebinding protection is on by default and an app that did not name its clients' host would 421 them, which is the behaviour ``test_rebinding_protection_*`` asserts. """ from __future__ import annotations import json import pathlib import pytest from hhstream_mcp import authorizations as auth from hhstream_mcp import http as http_transport from hhstream_mcp import resources as mcp_resources from hhstream_mcp import tools from hhstream_mcp.invoke import Runner # Imported unconditionally, and not through `importorskip`, for the reason # `test_mcp_server.py` imports the SDK unconditionally: a file that skipped # when its dependency was absent would be green in exactly the build where # that mattered. `checks/unit.nix` declares `starlette` and `httpx` so this # cannot become a skip, and proves them importable before pytest runs. from starlette.testclient import TestClient #: The test client's Host, plus what a loopback deployment derives. TEST_HOSTS = ["testserver", *http_transport.default_allowed_hosts("127.0.0.1", 9989)] HEADERS = { "Accept": "application/json, text/event-stream", "Content-Type": "application/json", } INITIALIZE = { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test", "version": "0"}, }, } @pytest.fixture def store(tmp_path): return auth.Store.at(tmp_path / "state") def make_app(store, **kwargs): """The app, with a Runner that never reaches a CLI. ``entry`` returns 0 without doing anything: nothing in this file calls a tool for its effect, and a Runner that could reach `hhstream.cli` would make these tests depend on a broker socket. """ kwargs.setdefault("allowed_hosts", TEST_HOSTS) kwargs.setdefault("json_response", True) return http_transport.build_app(Runner(entry=lambda argv: 0), store, **kwargs) def post(client, body, token=None, headers=None, path="/mcp"): """One POST, and **never** following a redirect. `follow_redirects=False` is load-bearing, not tidiness. The test client follows redirects by default, which is how a `Mount`-shaped 307 on the exact path `/mcp` passed this whole file once while failing a real client: a redirected POST has to be re-sent with its body, and `urllib` will not do that at all. See `test_the_exact_path_does_not_redirect`. """ sent = dict(HEADERS) if token is not None: sent["Authorization"] = f"Bearer {token}" sent.update(headers or {}) return client.post( path, content=json.dumps(body), headers=sent, follow_redirects=False ) def session(client, token): """Initialize and return the headers that carry the session on.""" response = post(client, INITIALIZE, token=token) assert response.status_code == 200, response.content extra = {} sid = response.headers.get("mcp-session-id") if sid: extra["mcp-session-id"] = sid post(client, {"jsonrpc": "2.0", "method": "notifications/initialized"}, token=token, headers=extra) return extra def call(client, token, method, params=None, headers=None, request_id=2): body = {"jsonrpc": "2.0", "id": request_id, "method": method} if params is not None: body["params"] = params response = post(client, body, token=token, headers=headers) assert response.status_code == 200, response.content return json.loads(response.content) # ── parsing the header ───────────────────────────────────────────────────── @pytest.mark.parametrize( ("header", "expected"), [ ("Bearer abc", "abc"), ("bearer abc", "abc"), # RFC 9110: the scheme is case-insensitive ("BEARER abc", "abc"), ("Bearer abc ", "abc"), ("", None), ("abc", None), # no scheme ("Basic abc", None), # wrong scheme ("Bearer", None), # no token ("Bearer ", None), ], ) def test_bearer_token_parsing(header, expected): assert http_transport.bearer_token(header) == expected # ── the refusals ─────────────────────────────────────────────────────────── def test_no_header_is_401_with_an_empty_body(store): store.mint() with TestClient(make_app(store)) as client: response = post(client, INITIALIZE) assert response.status_code == 401 assert response.content == b"" assert response.headers["www-authenticate"].startswith("Bearer ") assert response.headers["cache-control"] == "no-store" def test_a_wrong_token_is_401_and_is_not_echoed(store): store.mint() wrong = "hhsmcp_definitely-not-a-real-token" with TestClient(make_app(store)) as client: response = post(client, INITIALIZE, token=wrong) assert response.status_code == 401 assert response.content == b"" # Not in the body, and not in any header either. assert wrong not in "".join(f"{k}{v}" for k, v in response.headers.items()) def test_a_revoked_token_is_401(store): grant, token = store.mint() store.revoke(grant.id) with TestClient(make_app(store)) as client: assert post(client, INITIALIZE, token=token).status_code == 401 def test_an_expired_token_is_401(store): from hhstreamd.clock import ManualClock clock = ManualClock() store.clock = clock _, token = store.mint(ttl=60) clock.advance(61) with TestClient(make_app(store)) as client: assert post(client, INITIALIZE, token=token).status_code == 401 def test_the_wrong_scheme_is_401(store): _, token = store.mint() with TestClient(make_app(store)) as client: response = post(client, INITIALIZE, headers={"Authorization": f"Basic {token}"}) assert response.status_code == 401 def test_an_empty_table_refuses_everything(store): with TestClient(make_app(store)) as client: assert post(client, INITIALIZE, token="hhsmcp_anything").status_code == 401 def test_the_refusal_does_not_say_which_kind_it_was(store): """Unknown, revoked and expired are one answer, byte for byte. Telling them apart would tell someone who guessed a real id that they had. """ grant, revoked = store.mint() store.revoke(grant.id) _, live = store.mint() responses = [] with TestClient(make_app(store)) as client: for token in ("hhsmcp_unknown", revoked, live[:-1] + "x"): response = post(client, INITIALIZE, token=token) responses.append((response.status_code, response.content, response.headers.get("www-authenticate"))) assert len(set(responses)) == 1 @pytest.mark.parametrize("path", ["/mcp", "/mcp/"]) def test_the_exact_path_does_not_redirect(store, path): """Both spellings are the endpoint, and neither is a redirect to the other. The regression this exists for: `Starlette(routes=[Mount("/mcp", ...)])` serves `/mcp/` and answers `/mcp` with a 307 — and every MCP client configuration spells the URL without the trailing slash. The redirect is invisible to a client that follows it on a POST and fatal to one that does not, which is why the endpoint matches the path itself instead. """ _, token = store.mint() with TestClient(make_app(store)) as client: response = post(client, INITIALIZE, token=token, path=path) assert response.status_code == 200, ( f"{path} answered {response.status_code} " f"(location: {response.headers.get('location')!r})" ) def test_a_custom_path_is_honoured(store): _, token = store.mint() with TestClient(make_app(store, path="/agent/mcp")) as client: assert post(client, INITIALIZE, token=token, path="/agent/mcp").status_code == 200 assert post(client, INITIALIZE, token=token, path="/mcp").status_code == 404 def test_an_unknown_path_leaks_nothing_without_a_token(store): store.mint() with TestClient(make_app(store)) as client: # 401 and not 404: an unauthenticated caller does not learn what is # mounted here, or that anything is. assert client.get("/elsewhere").status_code == 401 def test_an_unknown_path_is_a_404_once_authenticated(store): _, token = store.mint() with TestClient(make_app(store)) as client: response = client.get( "/elsewhere", headers={"Authorization": f"Bearer {token}"}, follow_redirects=False, ) assert response.status_code == 404 def test_repeated_failures_are_rate_limited(store): from hhstream_live.server import RateLimiter store.mint() app = make_app(store) app.limiter = RateLimiter(limit=3) with TestClient(app) as client: codes = [post(client, INITIALIZE).status_code for _ in range(5)] assert codes[:3] == [401, 401, 401] assert codes[3:] == [429, 429] def test_a_good_token_is_not_rate_limited(store): from hhstream_live.server import RateLimiter _, token = store.mint() app = make_app(store) app.limiter = RateLimiter(limit=2) with TestClient(app) as client: for _ in range(5): assert post(client, INITIALIZE, token=token).status_code == 200 # ── the one way through ──────────────────────────────────────────────────── def test_a_good_token_completes_the_handshake(store): _, token = store.mint() with TestClient(make_app(store)) as client: response = post(client, INITIALIZE, token=token) assert response.status_code == 200 result = json.loads(response.content)["result"] assert result["serverInfo"]["name"] == "hhstream" assert "instructions" in result def test_the_full_surface_is_offered_to_an_unrestricted_token(store): _, token = store.mint() with TestClient(make_app(store)) as client: extra = session(client, token) listed = call(client, token, "tools/list", headers=extra)["result"]["tools"] listed_resources = call(client, token, "resources/list", headers=extra, request_id=3)["result"]["resources"] assert len(listed) == len(tools.TOOLS) assert len(listed_resources) == len(mcp_resources.FIXED) def test_using_a_token_stamps_it(store): grant, token = store.mint() with TestClient(make_app(store)) as client: session(client, token) assert store.load()[0].last_used is not None assert store.load()[0].id == grant.id # ── what a token's toolsets do ───────────────────────────────────────────── def test_a_scoped_token_is_offered_only_its_toolsets(store): _, token = store.mint(toolsets=["frames"]) with TestClient(make_app(store)) as client: extra = session(client, token) listed = call(client, token, "tools/list", headers=extra)["result"]["tools"] assert {tool["name"] for tool in listed} == set(tools.TOOLSETS["frames"]) def test_a_scoped_token_cannot_call_outside_its_toolsets(store): _, token = store.mint(toolsets=["frames"]) with TestClient(make_app(store)) as client: extra = session(client, token) result = call( client, token, "tools/call", {"name": "session_gc", "arguments": {}}, headers=extra, )["result"] assert result["isError"] is True text = result["content"][0]["text"] assert "session_gc" in text # The message names both possible narrowings, because the agent cannot tell # them apart and neither is its to change. assert "--toolsets" in text assert "authorization" in text def test_a_token_cannot_widen_the_processs_own_toolsets(store): """The intersection, not the token's list. A unit started with `--toolsets frames` must not be talked into serving `session_start` by a token that names `sessions`. """ _, token = store.mint(toolsets=["frames", "sessions"]) with TestClient(make_app(store, toolsets=["frames"])) as client: extra = session(client, token) listed = call(client, token, "tools/list", headers=extra)["result"]["tools"] assert {tool["name"] for tool in listed} == set(tools.TOOLSETS["frames"]) def test_two_tokens_on_one_server_see_different_surfaces(store): """The property the per-token narrowing exists for. One process, two callers, two tool budgets. A launch-time flag cannot do this, which is the whole argument for putting toolsets on the token. """ _, broad = store.mint(label="broad") _, narrow = store.mint(label="narrow", toolsets=["frames"]) with TestClient(make_app(store)) as client: broad_extra = session(client, broad) narrow_extra = session(client, narrow) broad_tools = call(client, broad, "tools/list", headers=broad_extra)["result"]["tools"] narrow_tools = call(client, narrow, "tools/list", headers=narrow_extra, request_id=3)["result"]["tools"] assert len(broad_tools) == len(tools.TOOLS) assert {tool["name"] for tool in narrow_tools} == set(tools.TOOLSETS["frames"]) def test_resources_are_not_narrowed_by_a_token(store): """A stated limit, not an oversight. `docs/CONTRACT-mcp.md` keeps resources out of `--toolsets` because they are the host's context rather than the model's budget. A token is an authorization rather than a budget, so this is a real gap and it is written down in `docs/TODO/mcp-tokens-do-not-scope-resources.md` rather than quietly implied by the tests. """ _, token = store.mint(toolsets=["frames"]) with TestClient(make_app(store)) as client: extra = session(client, token) listed = call(client, token, "resources/list", headers=extra)["result"]["resources"] assert any(entry["uri"] == "hhstream://sessions" for entry in listed) def test_a_token_naming_an_unknown_toolset_offers_nothing(store): """A grant from a future build: refuse everything rather than widen.""" grant, token = store.mint() grant.toolsets = ("a-family-this-build-has-never-heard-of",) store._write([grant]) with TestClient(make_app(store)) as client: extra = session(client, token) listed = call(client, token, "tools/list", headers=extra)["result"]["tools"] assert listed == [] # ── DNS-rebinding protection ─────────────────────────────────────────────── def test_rebinding_protection_refuses_an_unnamed_host(store): _, token = store.mint() app = make_app(store, allowed_hosts=["somewhere.else"]) with TestClient(app) as client: response = post(client, INITIALIZE, token=token) # The token was good; the Host was not. 421 Misdirected Request. assert response.status_code == 421 def test_the_token_is_checked_before_the_host(store): """Order matters: an unauthenticated caller learns nothing about the host allowlist, which is itself a hint about how this server is deployed.""" store.mint() app = make_app(store, allowed_hosts=["somewhere.else"]) with TestClient(app) as client: assert post(client, INITIALIZE).status_code == 401 @pytest.mark.parametrize("address", ["127.0.0.1", "::1", "localhost"]) def test_loopback_derives_a_working_allowlist(address): hosts = http_transport.default_allowed_hosts(address, 9989) assert "127.0.0.1:9989" in hosts assert "localhost:9989" in hosts assert "[::1]:9989" in hosts # The SDK's wildcard-port form, for a client that reached a proxy on # another port and was forwarded here. assert "127.0.0.1:*" in hosts def test_a_named_address_derives_itself_and_not_loopback(): hosts = http_transport.default_allowed_hosts("10.0.0.5", 9989) assert hosts == ["10.0.0.5:9989", "10.0.0.5:*", "10.0.0.5"] @pytest.mark.parametrize("address", ["0.0.0.0", "::", "*"]) def test_a_wildcard_bind_derives_nothing(address): """Which is what makes the launch path refuse it. Nothing can be guessed about the Host a client will send, and an empty allowlist with protection on refuses every request. So the operator is made to name the hostnames instead. """ assert http_transport.default_allowed_hosts(address, 9989) == [] # ── the grant on the request ─────────────────────────────────────────────── def test_current_grant_is_none_off_a_request(): """The stdio case: no request context at all, and no restriction either.""" from mcp.server.lowlevel import Server assert http_transport.current_grant(Server("probe")) is None def test_offered_for_returns_everything_without_a_grant(): from mcp.server.lowlevel import Server chooser = http_transport.offered_for(Server("probe"), tools.TOOLS) assert chooser() == tools.TOOLS # ── the dependencies this transport needs declared ───────────────────────── #: `src/hhstream_mcp/pyproject.toml`, when the suite is run from a checkout. #: Absent in the build sandbox, which copies only `tests/`. MCP_PYPROJECT = ( pathlib.Path(__file__).resolve().parents[2] / "src" / "hhstream_mcp" / "pyproject.toml" ) @pytest.mark.skipif(not MCP_PYPROJECT.is_file(), reason="not running from a checkout") def test_the_distribution_declares_what_this_module_imports(): """`starlette` and `uvicorn` by name, not by way of the SDK. The same assertion `tests/pointer/test_vendored_protocol.py` makes about `pywayland` and `xkbcommon`, and for the same kind of reason. The MCP SDK propagates both of these today, so leaving them out of the metadata would *work* — which is exactly what makes it worth pinning. `http.py` imports `uvicorn` by name and the SDK's `TransportSecuritySettings` sits on Starlette's `Request`, so an SDK release that moved its HTTP transport behind an optional extra would break `serve --http` with an ImportError naming somebody else's package. """ pyproject = MCP_PYPROJECT.read_text() assert "starlette" in pyproject assert "uvicorn" in pyproject # And `anyio`, which was already declared on this argument before the HTTP # transport existed — the precedent this follows. assert "anyio" in pyproject