`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
353 lines
15 KiB
Nix
353 lines
15 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"):
|
|
listed = http("--list", token=token)["tools"]
|
|
assert len(listed) == 21, f"{len(listed)} tools, expected 21"
|
|
fixed = http("--resources", token=token)["resources"]
|
|
assert len(fixed) == 5, f"{len(fixed)} resources, expected 5"
|
|
|
|
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"]) == 21
|
|
|
|
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
|
|
'';
|
|
}
|
|
)
|