diff --git a/checks/default.nix b/checks/default.nix index cab711d..cdba964 100644 --- a/checks/default.nix +++ b/checks/default.nix @@ -2,6 +2,7 @@ # # unit -- pytest over tests/, against the nix/package.nix build # vm-mcp -- the MCP server over stdio, against a live broker +# vm-mcp-http -- the MCP server's HTTP transport, its token, and its unit # vm-stream -- the per-session live stream, with a real HTTP viewer # vm-basic -- nixosTest with a fake capture backend: module + wire contract # vm-hyprland -- nixosTest with the real compositor and grim @@ -82,6 +83,15 @@ in # the others have no reason to carry. vm-mcp = pkgs.callPackage ./vm-mcp.nix (sessionArgs // { inherit hhstream-mcp; }); + # The same machine again with `mcp.http.enable`. A separate check and not a + # subtest of `vm-mcp`, because it proves a different thing: that one is about + # the surface over a pipe, this one is about a unit systemd supervises and a + # credential on the way in. Sharing a guest would also mean one failure + # hiding the other, and the first subtest here deliberately waits for a unit + # to FAIL -- which is not something to do in the middle of a check whose + # other assertions need it up. + vm-mcp-http = pkgs.callPackage ./vm-mcp-http.nix (sessionArgs // { inherit hhstream-mcp; }); + # The live stream: `stream enable`, a real HTTP viewer inside the guest, and # the one thing no in-process test can say -- that a connected viewer moves # the idle clock. Spends real time on purpose; see the file's header. diff --git a/checks/lib/mcp_http_client.py b/checks/lib/mcp_http_client.py new file mode 100644 index 0000000..6d63702 --- /dev/null +++ b/checks/lib/mcp_http_client.py @@ -0,0 +1,224 @@ +#!/usr/bin/env python3 +"""``hhs-mcp-http`` -- drive an MCP server over Streamable HTTP from a shell. + +What ``checks/vm-mcp-http.nix`` uses, and the sibling of +``checks/lib/mcp_client.py``: the same deliberate choice not to use the MCP +SDK's own client, for the same reason. 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 check is about. + +Standard library only -- ``urllib.request`` and ``json``. One process per +invocation, which re-does the ``initialize`` handshake every time; that is a +feature here, because the handshake behind a bearer token is one of the things +under test. + + hhs-mcp-http --token T --initialize + hhs-mcp-http --token T --list + hhs-mcp-http --token T --resources + hhs-mcp-http --token T --read hhstream://sessions + hhs-mcp-http --token T session_gc + hhs-mcp-http --token T session_touch '{"id": "s-1"}' + hhs-mcp-http --initialize (no token: expect exit 4) + +Exit codes, chosen so no assertion can mistake one failure for another: + +==== =============================================================== +0 the server answered; whatever it said is on stdout as JSON +2 the server did not answer -- unreachable, timed out, or not JSON +3 the server answered with a JSON-RPC *error* object +4 an HTTP status other than 200 or 202; the status and the headers + the check cares about are on stdout as JSON +==== =============================================================== + +Exit 4 is the interesting one and the reason this program exists rather than a +``curl`` pipeline: a 401 has an empty body, so the thing to assert is a status +code and a ``WWW-Authenticate`` header, and both have to come back in a shape a +test script can read without parsing curl's header dump. +""" + +from __future__ import annotations + +import argparse +import json +import sys +import urllib.error +import urllib.request + +PROTOCOL_VERSION = "2025-06-18" +#: Both, in this order, because the specification requires a client to accept +#: either an immediate JSON body or an SSE stream. The server under test is run +#: with `--json-response`, so the body comes back as JSON -- but a client that +#: advertised only `application/json` would be testing a narrower contract than +#: the one a real client has to satisfy. +ACCEPT = "application/json, text/event-stream" + + +class NoAnswer(Exception): + """The server did not answer in a way this client can read.""" + + +class HttpStatus(Exception): + """The server answered with a status other than 200.""" + + def __init__(self, status: int, headers: dict[str, str], body: bytes) -> None: + super().__init__(f"HTTP {status}") + self.status = status + self.headers = headers + self.body = body + + def report(self) -> dict[str, object]: + """What a test script needs, and deliberately not the body's bytes. + + A refusal's body is empty and must stay empty; reporting its *length* + lets a check assert that without this program being the thing that + decides what "empty" means. + """ + + return { + "http_status": self.status, + "www_authenticate": self.headers.get("www-authenticate"), + "cache_control": self.headers.get("cache-control"), + "body_len": len(self.body), + "body_prefix": self.body[:200].decode("utf-8", "replace"), + } + + +class Client: + """One connection's worth of state: the token and the session id.""" + + def __init__(self, url: str, token: str | None, timeout: float) -> None: + self.url = url + self.token = token + self.timeout = timeout + self.session_id: str | None = None + + def send(self, body: dict[str, object]) -> dict[str, object] | None: + payload = json.dumps(body).encode("utf-8") + headers = {"Content-Type": "application/json", "Accept": ACCEPT} + if self.token: + headers["Authorization"] = f"Bearer {self.token}" + if self.session_id: + headers["Mcp-Session-Id"] = self.session_id + request = urllib.request.Request( + self.url, data=payload, headers=headers, method="POST" + ) + try: + with urllib.request.urlopen(request, timeout=self.timeout) as response: + raw = response.read() + lowered = {k.lower(): v for k, v in response.headers.items()} + status = response.status + except urllib.error.HTTPError as exc: + # The refusals arrive here: urllib raises on 4xx and 5xx, and the + # headers are on the exception. + raise HttpStatus( + exc.code, + {k.lower(): v for k, v in (exc.headers or {}).items()}, + exc.read() or b"", + ) from None + except (urllib.error.URLError, OSError, TimeoutError) as exc: + raise NoAnswer(f"no answer from {self.url}: {exc!r}") from None + + # 200 for a request, 202 for a notification -- the specification's own + # answer to a message with no id, and it carries no body. Treating it + # as a refusal is a mistake worth naming here, because it looks exactly + # like one: the `notifications/initialized` that every handshake sends + # is answered 202, so a client that only accepts 200 fails on its + # second message with something that reads like an auth problem. + if status not in (200, 202): + raise HttpStatus(status, lowered, raw) + # Remembered from the `initialize` response and sent on every request + # after it; a stateful server refuses the second request without it. + if "mcp-session-id" in lowered: + self.session_id = lowered["mcp-session-id"] + # A notification is answered with 202 and no body. + if not raw: + return None + try: + return json.loads(raw) + except json.JSONDecodeError: + raise NoAnswer(f"not JSON-RPC from {self.url}: {raw[:400]!r}") from None + + def request(self, method: str, params: dict[str, object] | None, request_id: int): + body: dict[str, object] = {"jsonrpc": "2.0", "id": request_id, "method": method} + if params is not None: + body["params"] = params + answer = self.send(body) + if answer is None: + raise NoAnswer(f"empty answer to {method}") + if "error" in answer: + raise SystemExit(_print_and(3, answer["error"])) + return answer.get("result") + + def notify(self, method: str) -> None: + self.send({"jsonrpc": "2.0", "method": method}) + + def handshake(self) -> dict[str, object]: + result = self.request( + "initialize", + { + "protocolVersion": PROTOCOL_VERSION, + "capabilities": {}, + "clientInfo": {"name": "hhs-mcp-http", "version": "0"}, + }, + 1, + ) + self.notify("notifications/initialized") + return result + + +def _print_and(code: int, obj: object) -> int: + print(json.dumps(obj, indent=2, sort_keys=True)) + return code + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser( + prog="hhs-mcp-http", + description="Drive an MCP server over Streamable HTTP. Raw JSON-RPC, " + "standard library only; not the MCP SDK's client.", + ) + parser.add_argument("--url", default="http://127.0.0.1:9989/mcp") + parser.add_argument("--token", default=None, help="the bearer token; omitted, none is sent") + parser.add_argument("--timeout", type=float, default=60.0) + parser.add_argument("--initialize", action="store_true", help="the handshake's own result") + parser.add_argument("--list", action="store_true", help="tools/list") + parser.add_argument("--resources", action="store_true", help="resources/list") + parser.add_argument("--read", metavar="URI", help="one resources/read") + parser.add_argument("tool", nargs="?", help="a tool name for one tools/call") + parser.add_argument("arguments", nargs="?", default="{}", help="its arguments, as JSON") + return parser + + +def main(argv: list[str] | None = None) -> int: + parser = build_parser() + args = parser.parse_args(argv) + client = Client(args.url, args.token, args.timeout) + try: + handshake = client.handshake() + if args.initialize: + return _print_and(0, handshake) + if args.list: + return _print_and(0, client.request("tools/list", None, 2)) + if args.resources: + return _print_and(0, client.request("resources/list", None, 2)) + if args.read: + return _print_and(0, client.request("resources/read", {"uri": args.read}, 2)) + if args.tool: + try: + arguments = json.loads(args.arguments) + except json.JSONDecodeError as exc: + parser.error(f"arguments are not JSON: {exc}") + return _print_and( + 0, client.request("tools/call", {"name": args.tool, "arguments": arguments}, 2) + ) + except HttpStatus as refused: + return _print_and(4, refused.report()) + except NoAnswer as exc: + print(str(exc), file=sys.stderr) + return 2 + parser.error("nothing to do: give --initialize, --list, --resources, --read or a tool name") + return 2 # pragma: no cover -- parser.error exits + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/checks/vm-mcp-http.nix b/checks/vm-mcp-http.nix new file mode 100644 index 0000000..1fec72a --- /dev/null +++ b/checks/vm-mcp-http.nix @@ -0,0 +1,352 @@ +# checks..vm-mcp-http -- the HTTP transport, its token, and the unit, in +# a guest with a live broker and a real compositor. +# +# The sibling of `vm-mcp.nix`, which proves the *surface* over stdio. This one +# proves nothing about the surface and everything about the two things stdio +# does not have: a unit that systemd supervises, and a credential on the way +# in. So the tool and resource assertions here are one of each -- just enough +# to show the request reached the broker through an authenticated HTTP session +# -- and the weight is on the refusals, on the state directory's permissions, +# and on the lifecycle of the unit itself. +# +# THE ONE THAT MATTERS MOST is the first subtest. The server exits 2 while the +# authorization table is empty, which puts a freshly provisioned machine in a +# failed state: that is the deliberate trade (a `systemctl status` naming the +# remedy beats a listener that 401s every request), and it is only a *good* +# trade because the unit retries rather than giving up, so minting the first +# token brings it up with no `systemctl start`. That self-heal is a property of +# `StartLimitIntervalSec = 0` in the module and nothing in the Python can test +# it. If it ever regresses, every machine that enables this option comes up +# dead and stays dead, and this is the only thing that would notice. +# +# The client is `lib/mcp_http_client.py`: raw JSON-RPC over `urllib`, not the +# MCP 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. +# +# Habits copied from the other session checks: every wait is bounded, each +# subtest asserts once, and a failure dumps diagnostics before it propagates. +{ + testers, + hhstream, + hhstream-mcp, + hhsModule, + testTools, + hyprland, + foot, + jq, + grim, + procps, + coreutils, + dejavu_fonts, + width ? 1280, + height ? 720, + sessionUser ? "hermes", + port ? 9989, +}: +testers.runNixOSTest ( + { pkgs, ... }: + let + tools = pkgs.callPackage ./lib/session-tools.nix { inherit hhstream; }; + guest = import ./lib/session-machine.nix { + inherit + hhsModule + hhstream + hyprland + testTools + foot + jq + procps + grim + coreutils + dejavu_fonts + ; + sessionTools = tools; + }; + prelude = import ./lib/session-prelude.nix { + inherit hhstream coreutils sessionUser; + }; + + client = pkgs.runCommandLocal "hhs-mcp-http" { } '' + install -Dm755 ${./lib/mcp_http_client.py} $out/bin/hhs-mcp-http + sed -i '1s|.*|#!${pkgs.python3}/bin/python3|' $out/bin/hhs-mcp-http + $out/bin/hhs-mcp-http --help > /dev/null + # It must refuse to invent a request rather than printing nothing: a + # client that exits 0 having done nothing would make every subtest below + # vacuous. + if $out/bin/hhs-mcp-http --url http://127.0.0.1:1/mcp --initialize; then + echo "hhs-mcp-http succeeded against a port nothing is listening on" >&2 + exit 1 + fi + ''; + in + { + name = "hhstream-vm-mcp-http"; + + globalTimeout = 1800; + + nodes.machine = { + imports = [ + (guest { + inherit width height sessionUser; + pointer = true; + apps.foot = { + exec = "${foot}/bin/foot"; + argsAllow = [ ]; + }; + }) + ]; + + services.hyprland-headless-stream.mcp = { + enable = true; + package = hhstream-mcp; + http = { + enable = true; + inherit port; + # Left at the default loopback, and asserted to be loopback: a check + # that bound the wildcard would stop being able to prove the default + # is the safe one. + # + # `openFirewall` is left off, also deliberately, and also asserted: + # the option exists so that opening the port is an explicit act, and + # a check that opened it would never notice if it became implied. + + # `--json-response` so the client reads one JSON body instead of + # parsing SSE. The client's convenience, not the server's default. + extraArgs = [ "--json-response" ]; + }; + }; + + environment.systemPackages = [ client ]; + }; + + testScript = + prelude + + '' + import shlex + + HTTP = "${client}/bin/hhs-mcp-http" + URL = "http://127.0.0.1:${toString port}/mcp" + UNIT = "hhstream-mcp.service" + STATE = "/var/lib/hhstream-mcp" + TABLE = f"{STATE}/authorizations.json" + MCP = "${hhstream-mcp}/bin/hhstream-mcp" + + + def http(argv, token=None, timeout=120): + """One `hhs-mcp-http` call that must succeed. Returns its JSON.""" + + auth = f"--token {shlex.quote(token)} " if token else "" + out = machine.succeed( + f"{HTTP} --url {URL} {auth}{argv}", timeout=timeout + ) + try: + return json.loads(out) + except json.JSONDecodeError: + raise AssertionError(f"not JSON from `hhs-mcp-http {argv}`: {out!r}") + + + def refused(argv, token=None, timeout=120): + """One call that must come back as an HTTP refusal (exit 4). + + Exit 4 and not merely "it failed": the client uses 2 for "the + server did not answer", so this cannot pass because the unit died. + """ + + auth = f"--token {shlex.quote(token)} " if token else "" + status, out = machine.execute( + f"{HTTP} --url {URL} {auth}{argv}", timeout=timeout + ) + assert status == 4, ( + f"expected an HTTP refusal (4) for `{argv}`, got {status}: {out}" + ) + return json.loads(out) + + + def mint(label, extra=""): + """`hhstream-mcp token mint` as the broker's user, as an operator would. + + As that user and not as root, because the state directory is 0700 + owned by it -- which means this is also the assertion that an + operator can actually issue a token on a machine configured this + way. + """ + + out = machine.succeed( + as_user(f"{MCP} token mint --label {shlex.quote(label)} {extra}"), + timeout=120, + ) + token = out.strip().splitlines()[-1] + assert token.startswith("hhsmcp_"), f"not a token: {out!r}" + return token + + + start_all() + bring_up("the compositor and broker") + + with subtest("the unit refuses to run while no token exists"): + # The deliberate failure. `wait_until_fails` rather than a single + # check, because systemd restarts it every five seconds and the + # instant sampled matters otherwise. + machine.wait_until_fails(f"systemctl is-active {UNIT}", timeout=180) + status = machine.execute(f"systemctl status {UNIT}")[1] + journal = machine.succeed(f"journalctl -u {UNIT} --no-pager | tail -40") + assert "no tokens" in journal, ( + "the unit did not say why it refused to start; an operator has " + f"nothing to act on. status was:\n{status}\njournal:\n{journal}" + ) + # And nothing is listening, which is the point of refusing. + machine.fail("ss -ltn | grep -q ':${toString port}'") + + with subtest("the state directory is the operator's and nobody else's"): + machine.wait_for_file(STATE, timeout=120) + mode = machine.succeed(f"stat -c %a {STATE}").strip() + owner = machine.succeed(f"stat -c %U {STATE}").strip() + assert mode == "700", f"{STATE} is {mode}, not 700" + assert owner == USER, f"{STATE} is owned by {owner}, not {USER}" + # The group is `sessions.group` and is deliberately not asserted + # here: at 0700 it grants nothing, and pinning it would make this + # subtest fail for a machine that merely named its group something + # else. What matters is that the owner is the account that mints + # tokens, and that nobody else can read the table at all. + + with subtest("minting the first token brings the unit up by itself"): + # The self-heal. No `systemctl start` anywhere in this subtest, on + # purpose: if this needs one, the option is a trap on every freshly + # provisioned machine. + token = mint("the check") + machine.wait_for_unit(UNIT, timeout=180) + machine.wait_for_open_port(${toString port}, addr="127.0.0.1", timeout=120) + + with subtest("the table is private and holds no token"): + mode = machine.succeed(f"stat -c %a {TABLE}").strip() + assert mode == "600", f"{TABLE} is {mode}, not 600" + raw = machine.succeed(f"cat {TABLE}") + assert token not in raw, "the authorization table contains the token itself" + assert '"hash"' in raw, f"no digest in the table: {raw!r}" + + with subtest("the port is loopback only"): + listening = machine.succeed("ss -ltnH | grep ':${toString port}' || true") + assert "127.0.0.1:${toString port}" in listening, ( + f"not bound on loopback: {listening!r}" + ) + assert "0.0.0.0:${toString port}" not in listening, ( + f"bound on every interface, which the default must never do: {listening!r}" + ) + + with subtest("the firewall does not open the port"): + # `openFirewall` is off by default and must not be implied by + # `http.enable`; this asserts it against the guest's own running + # rule set, the way vm-stream-firewall does. + machine.fail("iptables -C nixos-fw -p tcp --dport ${toString port} -j nixos-fw-accept") + + with subtest("an unauthenticated request is refused and says nothing"): + report = refused("--initialize") + assert report["http_status"] == 401, report + assert report["body_len"] == 0, f"a refusal with a body: {report}" + assert (report["www_authenticate"] or "").startswith("Bearer"), report + + with subtest("a wrong token is refused the same way"): + report = refused("--initialize", token="hhsmcp_not-a-real-token") + assert report["http_status"] == 401, report + assert report["body_len"] == 0, report + # And the token is not echoed anywhere in what came back. + assert "not-a-real-token" not in json.dumps(report), report + + with subtest("the handshake completes with a good token"): + result = http("--initialize", token=token) + assert result["serverInfo"]["name"] == "hhstream", result + assert result["protocolVersion"], result + + with subtest("the whole surface is offered to an unscoped token"): + listed = http("--list", token=token)["tools"] + assert len(listed) == 23, f"{len(listed)} tools, expected 23" + fixed = http("--resources", token=token)["resources"] + assert len(fixed) == 6, f"{len(fixed)} resources, expected 6" + + with subtest("a resource read reaches the broker"): + contents = http("--read hhstream://sessions", token=token)["contents"] + payload = json.loads(contents[0]["text"]) + assert payload.get("ok") is True, payload + + with subtest("a tool call reaches the broker"): + result = http("session_gc", token=token) + assert not result.get("isError"), result + + with subtest("a scoped token is offered only its toolsets"): + scoped = mint("frames only", "--toolsets frames") + listed = http("--list", token=scoped)["tools"] + names = sorted(tool["name"] for tool in listed) + assert names == ["record", "run", "shot"], names + + with subtest("a scoped token cannot call outside its toolsets"): + result = http("session_gc", token=scoped) + assert result.get("isError"), result + text = result["content"][0]["text"] + assert "session_gc" in text, text + + with subtest("the unscoped token still sees everything"): + # The two tokens are served by ONE process, which is the whole + # argument for putting toolsets on the token rather than only on + # the command line: a launch-time flag cannot do this. + assert len(http("--list", token=token)["tools"]) == 23 + + with subtest("token list shows both and neither secret"): + out = machine.succeed(as_user(f"{MCP} token list"), timeout=120) + assert "the check" in out, out + assert "frames only" in out, out + assert token not in out, "`token list` printed a token" + assert scoped not in out, "`token list` printed a token" + + with subtest("using a token stamps it"): + records = json.loads( + machine.succeed(as_user(f"{MCP} token list --json"), timeout=120) + ) + stamped = [r for r in records if r["last_used"]] + assert len(stamped) == 2, records + + with subtest("revoking a token refuses it immediately"): + # No restart of the unit: the table is read per request, so a + # revocation takes effect on the next one. An operator who has to + # restart a service to lock someone out does not have revocation. + records = json.loads( + machine.succeed(as_user(f"{MCP} token list --json"), timeout=120) + ) + doomed = next(r["id"] for r in records if r["label"] == "frames only") + machine.succeed(as_user(f"{MCP} token revoke {doomed}"), timeout=120) + report = refused("--initialize", token=scoped) + assert report["http_status"] == 401, report + # And the other token is untouched. + assert http("--initialize", token=token)["serverInfo"]["name"] == "hhstream" + + with subtest("the unit survives a restart and the token still works"): + machine.succeed(f"systemctl restart {UNIT}") + machine.wait_for_unit(UNIT, timeout=180) + machine.wait_for_open_port(${toString port}, addr="127.0.0.1", timeout=120) + assert http("--initialize", token=token)["serverInfo"]["name"] == "hhstream" + restarts = machine.succeed( + f"systemctl show -p NRestarts --value {UNIT}" + ).strip() + # It restarted while the table was empty, so this is not zero -- + # what matters is that it is not still climbing now that it is up. + machine.succeed("sleep 12") + again = machine.succeed( + f"systemctl show -p NRestarts --value {UNIT}" + ).strip() + assert restarts == again, ( + f"the unit is still restarting ({restarts} -> {again}): it is " + "crash-looping, not running" + ) + + with subtest("revoking every token does not take the unit down"): + # The running process keeps its port; it simply refuses everyone. + # Stopping on an empty table would mean a revocation could not be + # undone without a `systemctl start`, and the refusal at startup + # exists to catch a *forgotten* mint, not to police a deliberate one. + machine.succeed(as_user(f"{MCP} token revoke --all"), timeout=120) + machine.succeed(f"systemctl is-active {UNIT}") + report = refused("--initialize", token=token) + assert report["http_status"] == 401, report + ''; + } +) diff --git a/tests/unit/test_mcp_http.py b/tests/unit/test_mcp_http.py index c549ab6..1e8969f 100644 --- a/tests/unit/test_mcp_http.py +++ b/tests/unit/test_mcp_http.py @@ -23,6 +23,7 @@ would 421 them, which is the behaviour ``test_rebinding_protection_*`` asserts. from __future__ import annotations import json +import pathlib import pytest @@ -471,3 +472,35 @@ def test_offered_for_returns_everything_without_a_grant(): 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