373 unit tests, up from 266. Three files, split the way the modules are: `test_mcp_authorizations.py` is standard library and touches no SDK, `test_mcp_http.py` drives a real ASGI stack, and the additions to `test_mcp_server.py` are about the command line now that it has subcommands. Four of these exist for properties that a refactor breaks silently rather than loudly, which is the only reason they are worth their length: * **the file never holds a token.** A store that started writing the secret instead of its digest would pass every functional test here, so one test reads the bytes on disk and looks for the token and for a usable prefix of it. * **a concurrent mint is not lost.** Thirty threads mint into one table and all thirty tokens must still verify. The atomic replace stops a torn read; it does nothing about two writers loading the same table and the second replacing the first's addition. Without the flock this fails. * **`--toolsets` before the subcommand survives it.** argparse copies a subparser's namespace over the top-level one, so an ordinary default on the subcommand's copy would overwrite the value with `None` and `hhstream-mcp --toolsets=frames serve` would quietly serve all twenty-one tools. `SUPPRESS` prevents it and this test notices if it goes. * **a token verb never claims the transport.** `mint` prints a secret on stdout, which on stdio *is* the transport, so `claim_transport` is monkeypatched to fail the test if it is ever reached. The refusal tests assert the absence of information as much as the status code: an empty body, no echo of the token in body or headers, and unknown/revoked/expired arriving as one answer byte for byte -- telling them apart would tell someone who guessed a real id that they had. An unknown path is a 401 before a 404, so an unauthenticated caller does not learn what is mounted; the token is checked before the Host, so it does not learn the allowlist either. `test_resources_are_not_narrowed_by_a_token` asserts a *limit*, on purpose: a token scoped to `frames` can still read `hhstream://sessions`, and that is written down rather than left for someone to discover. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
474 lines
18 KiB
Python
474 lines
18 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 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
|