# SPDX-License-Identifier: Apache-2.0 # Copyright 2026 Scienting # # Source Code: https://git.scient.ing/papers/paperspec # See the LICENSE.md file for full license terms. """The transparency log: entries, signed checkpoints and tiles (paperspec.log).""" import base64 import hashlib import json import pytest from hypothesis import given, settings, strategies as st from conftest import vector_cases from helpers_lib2 import ( PROPS, RECORDS, fixture_receipts, fixture_roster, receipt, revocation, roster_key, roster_of, sealed, secret, ) from paperspec import crypto, jcs, log CHECKPOINT = vector_cases("checkpoint")[0] ORIGIN = "scient.ing/log/test" ROSTER = roster_of( roster_key("ana", role="owner"), roster_key("ben", role="owner"), roster_key("cara", role="editor"), roster_key("w1", role="guest", purposes=("witness",)), roster_key("w2", role="guest", purposes=("witness",)), ) SETTINGS = {"origin": ORIGIN, "threshold": 1, "witnesses": ["w1", "w2"]} def entries_of(n): """`n` log entries.""" return [ ["receipt", f"r{i:04d}", hashlib.sha256(str(i).encode()).hexdigest()] for i in range(n) ] def note_of(signers, entries=None, origin=ORIGIN): """A checkpoint over `entries` signed by the fixture keys named in `signers`.""" pairs = [(name, secret(name)) for name in signers] if entries is None: entries = entries_of(3) return log.sign_checkpoint(origin, entries, pairs) # --- entries --------------------------------------------------------------------------------------- def test_a_receipt_entry_names_its_kind_id_and_record_hash(): rec = sealed(receipt([("nodea", "aa" * 32)])) body = {k: v for k, v in rec.items() if k not in ("id", "signature")} assert log.entry(rec) == [ "receipt", rec["id"], hashlib.sha256(jcs.dumpb(body)).hexdigest(), ] def test_a_revocation_entry_is_of_its_own_kind(): rev = revocation("ana", receipt="abc") assert log.entry(rev)[:2] == ["revocation", rev["id"]] def test_a_roster_entry_names_the_store_and_hashes_the_whole_roster(): roster = json.loads((RECORDS / "roster.json").read_text(encoding="utf-8")) assert log.entry(roster) == [ "roster", roster.get("store", ""), hashlib.sha256(jcs.dumpb(roster)).hexdigest(), ] assert ( log.entry({"format": "scienting-roster/1", "store": "smithlab"})[1] == "smithlab" ) @pytest.mark.parametrize( "record", [{}, {"format": "scienting-policy/1", "id": "x"}, {"format": None}], ids=["no-format", "unlogged-format", "null-format"], ) def test_other_records_are_not_logged(record): with pytest.raises(ValueError, match="only receipts, revocations and rosters"): log.entry(record) def test_the_root_of_the_entries_is_the_history_root(): entries = entries_of(5) assert log.root(entries) == crypto.history_root(entries) assert log.root([]) == crypto.EMPTY_ROOT # --- checkpoints ----------------------------------------------------------------------------------- def test_checkpoint_vector_root_note_verification_and_tiles(): case = CHECKPOINT roster = fixture_roster() signers = [(name, secret(name)) for name in case["signers"]] assert log.root(case["entries"]) == case["root"] assert log.sign_checkpoint(case["origin"], case["entries"], signers) == case["note"] note, verified = log.verify_checkpoint(case["note"], roster) assert note["size"] == len(case["entries"]) assert note["root"] == case["root"] assert note["origin"] == case["origin"] assert verified == case["signers"] assert sorted(log.tiles(case["entries"])) == case["tiles"] def test_a_checkpoint_with_a_changed_origin_verifies_no_signer(): case = CHECKPOINT bad = case["note"].replace(case["origin"], case["origin"] + "x", 1) note, verified = log.verify_checkpoint(bad, fixture_roster()) assert note is not None assert verified == [] def test_the_note_body_is_the_origin_the_size_and_the_root_in_base64(): entries = entries_of(4) note = note_of([], entries) root = bytes.fromhex(log.root(entries)) assert note == f"{ORIGIN}\n4\n{base64.b64encode(root).decode()}\n\n" assert log.note_body(ORIGIN, 4, log.root(entries)) + "\n" == note def test_a_signature_line_is_the_name_and_the_key_hash_and_signature_in_base64(): note = note_of(["ana"]) line = note.rstrip("\n").split("\n")[-1] dash, name, blob = line.split(" ") raw = base64.b64decode(blob) public = crypto.ed25519_public(secret("ana")) assert (dash, name) == ("—", "ana") assert raw[:4] == log.key_hash("ana", public) body = log.note_body(ORIGIN, 3, log.root(entries_of(3))).encode() assert crypto.ed25519_verify(public, body, raw[4:]) def test_the_key_hash_binds_the_name_and_the_key(): one, other = crypto.ed25519_public(bytes(32)), crypto.ed25519_public(b"\x01" * 32) assert len(log.key_hash("ana", one)) == 4 assert log.key_hash("ana", one) != log.key_hash("ben", one) assert log.key_hash("ana", one) != log.key_hash("ana", other) expected = hashlib.sha256(b"ana\n\x01" + one).digest()[:4] assert log.key_hash("ana", one) == expected def test_a_note_parses_to_its_parts(): entries = entries_of(3) parsed = log.parse_checkpoint(note_of(["ana", "w1"], entries)) assert parsed["origin"] == ORIGIN assert parsed["size"] == 3 assert parsed["root"] == log.root(entries) assert [name for name, _, _ in parsed["signatures"]] == ["ana", "w1"] assert all(len(kh) == 4 and len(sig) == 64 for _, kh, sig in parsed["signatures"]) def test_a_note_with_no_signature_is_well_formed_and_verifies_no_signer(): note = note_of([]) assert log.parse_checkpoint(note)["signatures"] == [] parsed, verified = log.verify_checkpoint(note, ROSTER) assert parsed["size"] == 3 assert verified == [] def test_a_note_of_an_empty_log_is_well_formed(): parsed = log.parse_checkpoint(note_of(["ana"], entries=[])) assert parsed["size"] == 0 assert parsed["root"] == crypto.EMPTY_ROOT GOOD = note_of(["ana", "w1"]) BODY, _, SIGS = GOOD.partition("\n\n") LINES = SIGS.split("\n")[:-1] ROOT_B64 = BODY.split("\n")[2] FORGED_ROOT = base64.b64encode(bytes(32)).decode() def with_body(origin=ORIGIN, size="3", root=ROOT_B64, sigs=SIGS): """A note assembled from the given parts, none of them checked.""" return f"{origin}\n{size}\n{root}\n\n{sigs}" MALFORMED = { "empty": "", "no-blank-line": BODY + "\n", "two-lines": f"{ORIGIN}\n3\n\n{SIGS}", "four-lines": with_body(root=ROOT_B64 + "\nextra"), "empty-origin": with_body(origin=""), "size-with-leading-zero": with_body(size="03"), "size-negative": with_body(size="-3"), "size-not-a-number": with_body(size="three"), "size-superscript": with_body(size="²"), "size-arabic-indic": with_body(size="٣"), "size-empty": with_body(size=""), "root-not-base64": with_body(root="!!!!"), "root-too-short": with_body(root=base64.b64encode(bytes(31)).decode()), "root-too-long": with_body(root=base64.b64encode(bytes(33)).decode()), "root-not-canonical": with_body(root=ROOT_B64[:-2] + "B="), "root-unpadded": with_body(root=ROOT_B64.rstrip("=")), "signatures-without-final-newline": GOOD[:-1], "signature-line-without-dash": with_body(sigs=SIGS.replace("— ", "- ", 1)), "signature-without-name": with_body(sigs="— \n"), "signature-without-blob": with_body(sigs="— ana\n"), "signature-blob-not-base64": with_body(sigs="— ana !!!!\n"), "signature-blob-too-short": with_body( sigs=f"— ana {base64.b64encode(bytes(67)).decode()}\n" ), "signature-blob-too-long": with_body( sigs=f"— ana {base64.b64encode(bytes(69)).decode()}\n" ), "blank-line-between-signatures": with_body( sigs=LINES[0] + "\n\n" + LINES[1] + "\n" ), } @pytest.mark.parametrize("name", MALFORMED) def test_malformed_notes_do_not_parse(name): assert log.parse_checkpoint(MALFORMED[name]) is None assert log.verify_checkpoint(MALFORMED[name], ROSTER) == (None, []) def test_a_note_with_a_different_root_is_well_formed_but_signed_by_nobody(): parsed, verified = log.verify_checkpoint(with_body(root=FORGED_ROOT), ROSTER) assert parsed["root"] == "00" * 32 assert verified == [] @pytest.mark.parametrize( "separator", ["\x0b", "\x0c", "\x1c", "\x1d", "\x1e", "\x85", chr(0x2028), chr(0x2029), "\r"], ids=lambda s: f"U+{ord(s):04X}", ) def test_only_the_line_feed_ends_a_line_of_a_note(separator): assert log.parse_checkpoint(GOOD[:-1] + separator) is None assert log.parse_checkpoint(with_body(sigs=separator.join(LINES) + "\n")) is None def test_a_note_with_text_after_its_signatures_is_malformed(): assert log.parse_checkpoint(GOOD + "extra\n") is None def test_verification_checks_each_signer_against_the_roster(): note = note_of(["ana", "ben", "cara", "w1"]) _, verified = log.verify_checkpoint(note, ROSTER) assert verified == ["ana", "ben", "cara", "w1"] def test_a_signer_the_roster_does_not_hold_is_skipped(): _, verified = log.verify_checkpoint(note_of(["ana", "zed"]), ROSTER) assert verified == ["ana"] def test_a_signer_whose_key_is_not_ed25519_is_skipped(): roster = {**ROSTER, "ana": {**ROSTER["ana"], "scheme": "ml-dsa-65"}} assert log.verify_checkpoint(note_of(["ana", "ben"]), roster)[1] == ["ben"] @pytest.mark.parametrize( "public", ["not base64!", None, base64.b64encode(bytes(31)).decode()], ids=repr ) def test_a_signer_whose_public_key_is_unusable_is_skipped(public): roster = {**ROSTER, "ana": {**ROSTER["ana"], "public": public}} assert log.verify_checkpoint(note_of(["ana", "ben"]), roster)[1] == ["ben"] def test_a_signer_under_another_key_is_skipped(): roster = {**ROSTER, "ana": roster_key("ben")} assert log.verify_checkpoint(note_of(["ana", "ben"]), roster)[1] == ["ben"] def test_a_signature_line_moved_to_another_name_does_not_verify(): note = note_of(["ana", "ben"]) swapped = note.replace("— ana ", "— zed ", 1) assert log.verify_checkpoint(swapped, ROSTER)[1] == ["ben"] @pytest.mark.parametrize("position", range(0, 200, 7)) def test_an_edit_anywhere_in_a_note_costs_a_signer_or_the_whole_note(position): note = note_of(["ana", "ben"]) edited = ( note[:position] + chr((ord(note[position]) % 126) + 1) + note[position + 1 :] ) parsed, verified = log.verify_checkpoint(edited, ROSTER) assert parsed is None or len(verified) < 2 NAMES = st.text( alphabet="abcdefghijklmnopqrstuvwxyz0123456789-", min_size=1, max_size=8 ) @given( st.text(alphabet="abcdefghijklmnopqrstuvwxyz/.-_ ", min_size=1, max_size=30), st.integers(0, 12), st.lists(st.sampled_from(["ana", "ben", "cara"]), unique=True, max_size=3), ) @settings(PROPS, max_examples=30) def test_a_signed_note_parses_back_and_every_signer_verifies(origin, size, signers): entries = entries_of(size) note = note_of(signers, entries, origin=origin) parsed, verified = log.verify_checkpoint(note, ROSTER) assert parsed["origin"] == origin assert parsed["size"] == size assert parsed["root"] == log.root(entries) assert verified == signers # --- acceptance -------------------------------------------------------------------------------------- def test_the_example_projects_log_accepts_its_checkpoint(): note = (RECORDS / "log" / "checkpoint").read_text(encoding="utf-8") project = json.loads((RECORDS / "project.json").read_text(encoding="utf-8")) settings_log = project["settings"]["log"] roster = fixture_roster() assert log.accept_checkpoint(note, roster, settings_log) == (True, []) assert not log.accept_checkpoint(note, roster, dict(settings_log, threshold=2))[0] assert not log.accept_checkpoint(note, roster, dict(settings_log, origin="other"))[ 0 ] def test_a_checkpoint_from_an_owner_and_enough_witnesses_is_accepted(): note = note_of(["ana", "w1"]) assert log.accept_checkpoint(note, ROSTER, SETTINGS) == (True, []) def test_a_malformed_note_is_not_accepted(): assert log.accept_checkpoint("junk", ROSTER, SETTINGS) == ( False, ["the note is malformed"], ) def test_a_checkpoint_of_another_log_is_not_accepted(): note = note_of(["ana", "w1"], origin="scient.ing/log/other") accepted, reasons = log.accept_checkpoint(note, ROSTER, SETTINGS) assert not accepted assert reasons == ["the origin is not the project's log"] @pytest.mark.parametrize( "signers", [["w1"], ["cara", "w1"]], ids=["witness-only", "editor-only"] ) def test_a_checkpoint_without_an_owner_key_is_not_accepted(signers): accepted, reasons = log.accept_checkpoint(note_of(signers), ROSTER, SETTINGS) assert not accepted assert reasons == ["no owner key with the sign purpose signed it"] def test_an_owner_key_without_the_sign_purpose_does_not_count(): roster = { **ROSTER, "ana": roster_key("ana", role="owner", purposes=("spot-check",)), } accepted, reasons = log.accept_checkpoint(note_of(["ana", "w1"]), roster, SETTINGS) assert not accepted assert reasons == ["no owner key with the sign purpose signed it"] def test_witnesses_must_reach_the_threshold_and_be_the_projects_own(): settings_two = dict(SETTINGS, threshold=2) one = log.accept_checkpoint(note_of(["ana", "w1"]), ROSTER, settings_two) assert one[0] is False assert one[1] == ["1 of 2 witnesses cosigned"] assert log.accept_checkpoint( note_of(["ana", "w1", "w2"]), ROSTER, settings_two ) == (True, []) unlisted = dict(SETTINGS, witnesses=["w2"]) assert not log.accept_checkpoint(note_of(["ana", "w1"]), ROSTER, unlisted)[0] def test_a_witness_key_needs_the_witness_purpose(): roster = {**ROSTER, "w1": roster_key("w1", role="guest", purposes=("sign",))} accepted, reasons = log.accept_checkpoint(note_of(["ana", "w1"]), roster, SETTINGS) assert not accepted assert reasons == ["0 of 1 witnesses cosigned"] def test_settings_without_witnesses_or_a_threshold_ask_for_none(): assert log.accept_checkpoint(note_of(["ana"]), ROSTER, {"origin": ORIGIN}) == ( True, [], ) def test_every_failing_condition_is_reported(): note = note_of(["cara"], origin="scient.ing/log/other") accepted, reasons = log.accept_checkpoint(note, ROSTER, SETTINGS) assert not accepted assert len(reasons) == 3 # --- tile paths -------------------------------------------------------------------------------------- @pytest.mark.parametrize( ("level", "index", "width", "path"), [ (0, 0, None, "tile/0/000"), (0, 7, None, "tile/0/007"), (0, 1234067, None, "tile/0/x001/x234/067"), (3, 1000, None, "tile/3/x001/000"), ("entries", 5, 9, "tile/entries/005.p/9"), (1, 999, 255, "tile/1/999.p/255"), (0, 1000000, None, "tile/0/x001/x000/000"), ], ) def test_tile_paths_group_the_index_in_threes(level, index, width, path): assert log.tile_path(level, index, width) == path # --- tiles --------------------------------------------------------------------------------------------- def test_a_log_of_nine_entries_has_one_partial_hash_tile_and_one_of_entries(): entries = entries_of(9) tiles = log.tiles(entries) assert sorted(tiles) == ["tile/0/000.p/9", "tile/entries/000.p/9"] leaves = [crypto.leaf_hash(e) for e in entries] assert tiles["tile/0/000.p/9"] == bytes.fromhex("".join(leaves)) assert tiles["tile/entries/000.p/9"] == b"".join( jcs.dumpb(e) + b"\n" for e in entries ) def test_a_log_of_nothing_has_no_tiles(): assert log.tiles([]) == {} def test_a_log_of_two_tiles_and_a_bit_has_full_partial_and_upper_tiles(): entries = entries_of(2 * log.TILE_WIDTH + 44) tiles = log.tiles(entries) assert sorted(tiles) == [ "tile/0/000", "tile/0/001", "tile/0/002.p/44", "tile/1/000.p/2", "tile/entries/000", "tile/entries/001", "tile/entries/002.p/44", ] assert len(tiles["tile/0/000"]) == 32 * log.TILE_WIDTH assert len(tiles["tile/1/000.p/2"]) == 64 first = crypto.history_root(entries[: log.TILE_WIDTH]) second = crypto.history_root(entries[log.TILE_WIDTH : 2 * log.TILE_WIDTH]) assert tiles["tile/1/000.p/2"] == bytes.fromhex(first + second) assert tiles["tile/entries/001"].count(b"\n") == log.TILE_WIDTH def test_a_log_of_exactly_one_tile_has_no_partial_tiles(): tiles = log.tiles(entries_of(log.TILE_WIDTH)) assert sorted(tiles) == ["tile/0/000", "tile/1/000.p/1", "tile/entries/000"] def test_the_example_logs_tiles_are_those_the_oracle_writes(): entries, note = log.read_log(str(RECORDS / "log")) on_disk = { p.relative_to(RECORDS / "log").as_posix(): p.read_bytes() for p in (RECORDS / "log").rglob("*") if p.is_file() and p.name != "checkpoint" } assert log.tiles(entries) == on_disk want = [log.entry(r) for r in fixture_receipts()] want.append( log.entry(json.loads((RECORDS / "roster.json").read_text(encoding="utf-8"))) ) assert entries == want assert log.verify_checkpoint(note, fixture_roster())[1] == ["ana", "wit"] # --- writing and reading a log ------------------------------------------------------------------------- @pytest.mark.parametrize( "size", [0, 1, 9, 255, 256, 257, 600], ids=lambda n: f"{n}-entries" ) def test_a_written_log_reads_back(tmp_path, size): entries = entries_of(size) signers = [("ana", secret("ana"))] note = log.write_log(entries, ORIGIN, signers, str(tmp_path)) assert (tmp_path / "checkpoint").read_text(encoding="utf-8") == note read, read_note = log.read_log(str(tmp_path)) assert read == entries assert read_note == note assert log.verify_checkpoint(read_note, ROSTER) == ( log.parse_checkpoint(note), ["ana"], ) def test_a_written_log_holds_every_tile_and_the_checkpoint(tmp_path): entries = entries_of(300) log.write_log(entries, ORIGIN, [("ana", secret("ana"))], str(tmp_path)) written = { p.relative_to(tmp_path).as_posix() for p in tmp_path.rglob("*") if p.is_file() } assert written == set(log.tiles(entries)) | {"checkpoint"} def test_reading_a_log_with_a_malformed_checkpoint_is_refused(tmp_path): (tmp_path / "checkpoint").write_text("junk\n", encoding="utf-8") with pytest.raises(ValueError, match="checkpoint is malformed"): log.read_log(str(tmp_path)) def test_reading_a_log_with_a_missing_tile_fails(tmp_path): log.write_log(entries_of(9), ORIGIN, [("ana", secret("ana"))], str(tmp_path)) (tmp_path / "tile" / "entries" / "000.p" / "9").unlink() with pytest.raises(FileNotFoundError): log.read_log(str(tmp_path))