Files
hyprland-headless-stream-pl…/tests/unit/test_mcp_authorizations.py
T
HermenixandClaude Opus 5 fd6d48099b test(mcp): the store, the token verbs, and every way a request is refused
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
2026-10-11 20:45:53 +00:00

484 lines
16 KiB
Python

"""The token store, and the token verbs on top of it.
Standard library only, like the module under test: no SDK, no socket, no
Starlette. The HTTP transport that consumes these tokens is
``test_mcp_http.py``.
Two properties get most of the attention here, because both are the kind that
a refactor breaks silently:
* **the file never holds a token.** A store that quietly started writing the
secret would pass every functional test in this file, so there is an explicit
one that reads the bytes on disk and looks for it.
* **a lost update is impossible.** Two processes write this file, and the
atomic replace alone does not prevent one from overwriting a table the other
just added to. The concurrency test does the interleaving by hand.
"""
from __future__ import annotations
import json
import os
import threading
from pathlib import Path
import pytest
from hhstreamd.clock import ManualClock
from hhstream_mcp import authorizations as auth
from hhstream_mcp import server, tokencli
@pytest.fixture
def store(tmp_path):
return auth.Store.at(tmp_path / "state")
# ── the token itself ───────────────────────────────────────────────────────
def test_mint_token_is_prefixed_and_long():
token = auth.mint_token()
assert token.startswith(auth.TOKEN_PREFIX)
# The prefix is for recognising a leak on sight; the rest carries the
# entropy. 32 bytes base64url is 43 characters.
assert len(token) - len(auth.TOKEN_PREFIX) >= 43
def test_mint_token_never_repeats():
assert len({auth.mint_token() for _ in range(200)}) == 200
def test_hash_is_stable_and_not_the_token():
token = auth.mint_token()
digest = auth.hash_token(token)
assert digest == auth.hash_token(token)
assert len(digest) == 64
assert token not in digest
# ── the table ──────────────────────────────────────────────────────────────
def test_missing_file_is_an_empty_table(store):
assert store.load() == []
assert not store.path.exists()
def test_mint_then_load_round_trips_every_field(store):
grant, token = store.mint(label="laptop", ttl=3600, toolsets=["frames", "pointer"])
(loaded,) = store.load()
assert loaded.id == grant.id
assert loaded.label == "laptop"
assert loaded.toolsets == ("frames", "pointer")
assert loaded.expires_at == pytest.approx(grant.expires_at)
assert loaded.hash == auth.hash_token(token)
def test_the_file_does_not_contain_the_token(store):
_, token = store.mint(label="secret-bearing")
raw = store.path.read_bytes()
assert token.encode() not in raw
# Nor any usable prefix of it: a truncated write would be just as bad.
assert token[len(auth.TOKEN_PREFIX) : len(auth.TOKEN_PREFIX) + 20].encode() not in raw
def test_the_file_is_private_and_so_is_its_directory(store):
store.mint()
assert os.stat(store.path).st_mode & 0o777 == 0o600
assert os.stat(store.state_dir).st_mode & 0o777 == 0o700
def test_the_file_is_json_with_a_version(store):
store.mint()
data = json.loads(store.path.read_text())
assert data["version"] == auth.FORMAT_VERSION
assert len(data["grants"]) == 1
def test_ids_are_unique_across_many_mints(store):
for _ in range(50):
store.mint()
ids = [g.id for g in store.load()]
assert len(set(ids)) == 50
# ── verify ─────────────────────────────────────────────────────────────────
def test_verify_accepts_the_minted_token(store):
grant, token = store.mint(label="good")
found = store.verify(token)
assert found is not None
assert found.id == grant.id
@pytest.mark.parametrize(
"bad",
[
"",
"hhsmcp_not-a-real-token",
"completely wrong",
auth.TOKEN_PREFIX,
],
)
def test_verify_refuses_anything_else(store, bad):
store.mint()
assert store.verify(bad) is None
def test_verify_refuses_a_revoked_token(store):
grant, token = store.mint()
store.revoke(grant.id)
assert store.verify(token) is None
def test_verify_refuses_an_expired_token(store):
clock = ManualClock()
store.clock = clock
_, token = store.mint(ttl=60)
assert store.verify(token) is not None
clock.advance(61)
assert store.verify(token) is None
def test_verify_refuses_everything_when_the_table_is_corrupt(store):
_, token = store.mint()
store.path.write_text("{ not json")
# Deny, never allow: a store that cannot be read is not a store that lets
# everyone in.
assert store.verify(token) is None
def test_verify_refuses_a_table_from_a_future_version(store):
_, token = store.mint()
data = json.loads(store.path.read_text())
data["version"] = auth.FORMAT_VERSION + 1
store.path.write_text(json.dumps(data))
assert store.verify(token) is None
with pytest.raises(auth.StoreError, match="format version"):
store.load()
def test_one_token_does_not_verify_as_another(store):
_, first = store.mint(label="a")
second_grant, second = store.mint(label="b")
assert store.verify(first).id != second_grant.id
assert store.verify(second).id == second_grant.id
# ── last_used ──────────────────────────────────────────────────────────────
def test_verify_stamps_last_used(store):
grant, token = store.mint()
assert grant.last_used is None
store.verify(token)
(loaded,) = store.load()
assert loaded.last_used is not None
def test_the_stamp_is_throttled(store):
clock = ManualClock()
store.clock = clock
_, token = store.mint()
store.verify(token)
first = store.load()[0].last_used
clock.advance(auth.LAST_USED_FLUSH_S / 2)
store.verify(token)
assert store.load()[0].last_used == first
clock.advance(auth.LAST_USED_FLUSH_S)
store.verify(token)
assert store.load()[0].last_used != first
def test_stamp_does_not_resurrect_a_token_revoked_underneath_it(store):
grant, token = store.mint()
# The grant object the caller is holding, after it has been removed: this
# is the real interleaving, where a `verify` and a `revoke` race.
store.revoke(grant.id)
store._stamp(grant, store.clock.wall())
assert store.load() == []
def test_verify_can_be_asked_not_to_stamp(store):
_, token = store.mint()
assert store.verify(token, stamp=False) is not None
assert store.load()[0].last_used is None
# ── revoke and prune ───────────────────────────────────────────────────────
def test_revoke_removes_only_the_named_grant(store):
first, _ = store.mint(label="a")
second, _ = store.mint(label="b")
store.revoke(first.id)
assert [g.id for g in store.load()] == [second.id]
def test_revoke_an_unknown_id_raises(store):
store.mint()
with pytest.raises(auth.NoSuchGrant, match="no token with id"):
store.revoke("zzzzzz")
assert len(store.load()) == 1
def test_revoke_all_empties_the_table(store):
for _ in range(3):
store.mint()
gone = store.revoke_all()
assert len(gone) == 3
assert store.load() == []
def test_prune_drops_only_what_expired(store):
clock = ManualClock()
store.clock = clock
store.mint(label="short", ttl=10)
keeper, _ = store.mint(label="forever")
clock.advance(11)
dropped = store.prune()
assert [g.label for g in dropped] == ["short"]
assert [g.id for g in store.load()] == [keeper.id]
def test_prune_is_housekeeping_not_enforcement(store):
"""An expired token is refused whether or not `prune` has run."""
clock = ManualClock()
store.clock = clock
_, token = store.mint(ttl=10)
clock.advance(11)
assert store.verify(token) is None
assert len(store.load()) == 1 # still on disk, and still refused
# ── the lock ───────────────────────────────────────────────────────────────
def test_a_concurrent_mint_is_not_lost(tmp_path):
"""Thirty threads minting into one table; every token must survive.
The atomic replace stops a reader seeing half a file. It does **not** stop
two writers from each loading the same table and the second replacing the
first's addition -- which is why the store takes a flock, and why this test
would fail without it.
"""
store = auth.Store.at(tmp_path / "state")
tokens: list[str] = []
lock = threading.Lock()
errors: list[BaseException] = []
def mint() -> None:
try:
_, token = store.mint()
with lock:
tokens.append(token)
except BaseException as exc: # recorded, asserted below
with lock:
errors.append(exc)
threads = [threading.Thread(target=mint) for _ in range(30)]
for thread in threads:
thread.start()
for thread in threads:
thread.join(30)
assert errors == []
assert len(store.load()) == 30
# And every one of them still works, which is the property that matters.
for token in tokens:
assert store.verify(token, stamp=False) is not None
def test_separate_store_objects_see_each_others_writes(tmp_path):
"""Two `Store` instances on one path, as a unit and a shell would be."""
root = tmp_path / "state"
unit = auth.Store.at(root)
operator = auth.Store.at(root)
_, token = operator.mint(label="minted by the operator")
assert unit.verify(token) is not None
# ── where the store lives ──────────────────────────────────────────────────
def test_the_default_is_not_the_brokers_state_dir():
"""The broker's state dir is 0700 and holds its audit trail; stay out."""
assert auth.DEFAULT_STATE_DIR == "/var/lib/hhstream-mcp"
assert not auth.DEFAULT_STATE_DIR.startswith("/var/lib/hhstream/")
def test_the_environment_names_the_state_dir(tmp_path, monkeypatch):
monkeypatch.setenv(auth.ENV_STATE_DIR, str(tmp_path / "from-env"))
assert auth.Store.at().state_dir == tmp_path / "from-env"
def test_an_explicit_dir_beats_the_environment(tmp_path, monkeypatch):
monkeypatch.setenv(auth.ENV_STATE_DIR, str(tmp_path / "from-env"))
assert auth.Store.at(tmp_path / "explicit").state_dir == tmp_path / "explicit"
# ── the CLI verbs ──────────────────────────────────────────────────────────
@pytest.fixture
def state_dir(tmp_path, monkeypatch):
root = tmp_path / "state"
monkeypatch.setenv(auth.ENV_STATE_DIR, str(root))
return root
def test_mint_prints_the_token_on_stdout_and_nothing_else(state_dir, capsys):
assert server.main(["token", "mint"]) == tokencli.EXIT_OK
captured = capsys.readouterr()
token = captured.out.strip()
# Exactly the token on stdout, so `token mint | ...` is usable.
assert token.startswith(auth.TOKEN_PREFIX)
assert "\n" not in token
# And the prose for the human is on stderr, beside it.
assert "only time the token is shown" in captured.err
assert auth.Store.at(state_dir).verify(token) is not None
def test_mint_accepts_a_label_an_expiry_and_toolsets(state_dir, capsys):
rc = server.main(
["token", "mint", "--label", "laptop", "--expires-in", "30d",
"--toolsets", "frames,pointer"]
)
assert rc == tokencli.EXIT_OK
capsys.readouterr()
(grant,) = auth.Store.at(state_dir).load()
assert grant.label == "laptop"
assert grant.toolsets == ("frames", "pointer")
assert grant.expires_at is not None
@pytest.mark.parametrize(
"argv",
[
["token", "mint", "--expires-in", "not-a-duration"],
["token", "mint", "--expires-in", "0"],
["token", "mint", "--toolsets", "nonesuch"],
["token", "mint", "--toolsets", ","],
],
)
def test_mint_refuses_a_bad_argument(state_dir, argv):
with pytest.raises(SystemExit) as exit_info:
server.main(argv)
assert exit_info.value.code == tokencli.EXIT_USAGE
assert auth.Store.at(state_dir).load() == []
def test_list_shows_the_ids_but_never_a_token(state_dir, capsys):
server.main(["token", "mint", "--label", "one"])
token = capsys.readouterr().out.strip()
assert server.main(["token", "list"]) == tokencli.EXIT_OK
out = capsys.readouterr().out
assert "one" in out
assert auth.Store.at(state_dir).load()[0].id in out
assert token not in out
def test_list_json_is_the_records(state_dir, capsys):
server.main(["token", "mint", "--label", "one"])
capsys.readouterr()
assert server.main(["token", "list", "--json"]) == tokencli.EXIT_OK
records = json.loads(capsys.readouterr().out)
assert [r["label"] for r in records] == ["one"]
assert "hash" in records[0]
def test_list_on_an_empty_table_says_so_and_succeeds(state_dir, capsys):
assert server.main(["token", "list"]) == tokencli.EXIT_OK
assert "no tokens" in capsys.readouterr().err
def test_revoke_by_id(state_dir, capsys):
server.main(["token", "mint"])
capsys.readouterr()
grant_id = auth.Store.at(state_dir).load()[0].id
assert server.main(["token", "revoke", grant_id]) == tokencli.EXIT_OK
assert auth.Store.at(state_dir).load() == []
def test_revoke_an_unknown_id_is_exit_3(state_dir, capsys):
assert server.main(["token", "revoke", "zzzzzz"]) == tokencli.EXIT_NO_SUCH_TOKEN
assert "no token with id" in capsys.readouterr().err
def test_revoke_all(state_dir, capsys):
for _ in range(3):
server.main(["token", "mint"])
capsys.readouterr()
assert server.main(["token", "revoke", "--all"]) == tokencli.EXIT_OK
assert auth.Store.at(state_dir).load() == []
def test_revoke_needs_an_id_or_all(state_dir):
with pytest.raises(SystemExit) as exit_info:
server.main(["token", "revoke"])
assert exit_info.value.code == tokencli.EXIT_USAGE
def test_revoke_refuses_an_id_and_all_together(state_dir):
with pytest.raises(SystemExit) as exit_info:
server.main(["token", "revoke", "abc123", "--all"])
assert exit_info.value.code == tokencli.EXIT_USAGE
def test_prune_through_the_cli(state_dir, capsys):
assert server.main(["token", "prune"]) == tokencli.EXIT_OK
assert "nothing expired" in capsys.readouterr().err
def test_token_with_no_verb_prints_help(state_dir, capsys):
assert server.main(["token"]) == tokencli.EXIT_USAGE
assert "mint" in capsys.readouterr().out
def test_an_unreadable_table_is_exit_4(state_dir, capsys):
state_dir.mkdir(parents=True)
(state_dir / auth.STORE_NAME).write_text("{ not json")
assert server.main(["token", "list"]) == tokencli.EXIT_STORE
assert "not valid JSON" in capsys.readouterr().err
def test_state_dir_flag_overrides_the_environment(state_dir, tmp_path, capsys):
elsewhere = tmp_path / "elsewhere"
assert server.main(["token", "--state-dir", str(elsewhere), "mint"]) == 0
capsys.readouterr()
assert len(auth.Store.at(elsewhere).load()) == 1
assert auth.Store.at(state_dir).load() == []
def test_the_token_verbs_never_claim_the_transport(state_dir, monkeypatch, capsys):
"""`mint` prints a secret on stdout, which on stdio *is* the transport.
So the verb has to return before anything moves file descriptor 1. A fake
`claim_transport` that fails the test if it is called is the only way to
assert that from here.
"""
def forbidden():
raise AssertionError("a token verb claimed the stdio transport")
monkeypatch.setattr(server, "claim_transport", forbidden)
assert server.main(["token", "mint"]) == tokencli.EXIT_OK
assert server.main(["token", "list"]) == tokencli.EXIT_OK
capsys.readouterr()
def test_row_for_renders_the_honest_gaps():
grant = auth.Grant(id="abc123", hash="x" * 64)
row = tokencli.row_for(grant)
assert row[0] == "abc123"
assert row[3] == "never" # expires
assert row[4] == "never" # last used
assert row[5] == "all" # toolsets
assert len(row) == len(tokencli.HEADERS)