Files
hyprland-headless-stream-pl…/checks/vm-mcp-http.nix
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

372 lines
16 KiB
Nix

# checks.<system>.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"):
# Against the server's **own** table rather than a literal. A
# number here would have to be edited every time the surface grows
# -- and the failure that produces is indistinguishable from the
# HTTP transport dropping tools, which is what this subtest is for.
# `--list-tools` is the same table `tools/list` serves, printed by
# the binary without opening a transport.
expected_tools = len(machine.succeed(
as_user(f"{MCP} --list-tools"), timeout=120
).strip().splitlines())
listed = http("--list", token=token)["tools"]
assert len(listed) == expected_tools, (
f"{len(listed)} tools over http, {expected_tools} in the table"
)
# The fixed resources only: `--list-resources` prints the templates
# beside them, and `resources/list` is the fixed ones by protocol.
printed = machine.succeed(
as_user(f"{MCP} --list-resources"), timeout=120
).strip().splitlines()
expected_fixed = len([line for line in printed if "{" not in line])
fixed = http("--resources", token=token)["resources"]
assert len(fixed) == expected_fixed, (
f"{len(fixed)} resources over http, {expected_fixed} fixed in the table"
)
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"]) == expected_tools
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
'';
}
)