Files
hyprland-headless-stream-pl…/tests/unit/test_mcp_http.py
T
HermenixandClaude Opus 5 0e810ac99b test(mcp): the http transport, its unit and its token, in a guest
`checks.vm-mcp-http` -- the sibling of `vm-mcp`, on the same session
machine.  That one proves the *surface* over a pipe; this one proves the
two things stdio does not have: a unit systemd supervises, and a
credential on the way in.  So there is one tool call and one resource
read here, just enough to show a request reached the broker through an
authenticated session, and the weight is on the refusals, the state
directory's permissions, and the unit's lifecycle.

**The first subtest is the one that justifies the file.** The server
exits 2 while the authorization table is empty, which leaves a freshly
provisioned machine in a failed state on purpose -- and that trade is
only sound because the unit retries, so the first `token mint` brings it
up with no `systemctl start`. That self-heal lives in
`StartLimitIntervalSec = 0` and nothing in Python can test it. If it
regresses, every machine that enables the option comes up dead and stays
dead, and this is the only thing that would notice.

Also asserted, and each for a reason rather than for coverage: the state
directory is 0700 and owned by the account that mints tokens (which is
also the proof an operator *can* mint one on a machine configured this
way); the table is 0600 and does not contain the token; the port is on
loopback and **not** in the firewall, because neither default may become
implied; the refusals are 401 with an empty body and no echo; two tokens
served by one process see different tool budgets, which is the whole
argument for putting toolsets on a token; a revocation takes effect on
the next request with no restart, because an operator who must restart a
service to lock someone out does not have revocation; and revoking
*every* token does not stop the process, since the startup refusal exists
to catch a forgotten mint rather than to police a deliberate one.

`lib/mcp_http_client.py` is raw JSON-RPC over `urllib` and deliberately
not the SDK's client, for the reason `lib/mcp_client.py` is not either --
the SDK on both ends would agree with itself about a framing and a header
neither side had to get right, and the header is half of what this file
is about. It earned that choice immediately: it is what caught the 307 on
the exact path that the SDK-shaped test client had been following
silently.

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

507 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, 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"]
offered = call(client, token, "resources/list", headers=extra,
request_id=3)["result"]["resources"]
assert len(listed) == len(tools.TOOLS)
# Counted against the server's own table, never a literal: a resource added
# by a later contract version must not have to be counted here as well. The
# sibling stdio check learned this the hard way.
assert len(offered) == len(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