Files
hyprland-headless-stream-pl…/tests/unit/test_mcp_http.py
T
HermenixandClaude Opus 5 f83717ba71 Merge feat/mcp-server (9708154) into feat/mcp-auth
The base branch moved twelve commits while this work was in flight --
including the per-session live stream and its own contract bump -- so this
integrates rather than leaving a PR nobody can merge.  Six files
conflicted; the interesting resolutions are the two that were not
textual.

**The contract is mcp-v3.1, not v2.1.**  This branch bumped v2 -> v2.1 for
an additive change; `feat/mcp-server` bumped v2 -> v3 for the live stream,
also additive.  Both point releases, both correct, and they cannot both be
the same document.  So v3 stands as written and the HTTP transport is the
point release on top of it, by the same rule each of us applied
independently: v2 is still the only major bump, because it is still the
only one that removed anything.

**The counts are no longer literals.**  This branch asserted `21 tools` and
`5 resources` in `checks/vm-mcp-http.nix` and `5` in `test_mcp_http.py`;
the stream added two tools and one fixed resource, so the surface is 23
and 6.  Rather than re-hardcode numbers that will go stale again, the
check now counts against `--list-tools` and `--list-resources` -- the
server's own table -- and the unit test against `resources.FIXED`.  That
is the lesson 9708154 ("count the unnarrowed resources against the
listing, not a literal") had already learned on the other side of this
merge, arrived at twice.  A stale number here would have failed in a way
indistinguishable from the HTTP transport dropping tools, which is the
one thing those subtests exist to catch.

The rest were additive on both sides and both halves are kept: the TODO
table, the checks wiring, the README check rows, the architecture diagram
(their 23/10 counts with this branch's two-transport annotation).
`nix/module.nix` needed reconstructing -- git interleaved the bodies of
`hhstream-live` and `hhstream-mcp` because both units land between the
same surrounding lines -- so the live unit is taken verbatim and the MCP
unit placed after it, with this branch's options, tmpfiles entry,
firewall rule, two assertions and two warnings re-applied on top.

One thing deliberately NOT touched: the v3 change table cites `§6` for the
idle-clock exception, but the rule it means is `§8`. That is the other
branch's prose and its author's call, not something to quietly rewrite in
a merge.

Verified after resolution: 394 unit tests pass, and the module evaluates
with both units, the right ExecStart, one firewall port and both
warnings.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
2026-10-12 00:47:14 +00:00

505 lines
19 KiB
Python

"""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