"""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)