# 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. """Claim references and pins (spec/18 ยง18.4).""" import json import re import pytest from hypothesis import given, settings, strategies as st from conftest import FIXTURES, ROOT from paperspec import claims PROPERTIES = settings(derandomize=True, max_examples=200, database=None, deadline=None) SCHEMA = json.loads((ROOT / "schemas" / "common.schema.json").read_text("utf-8")) # ECMAScript `$` matches only at the end; Python's also matches before a final newline. REF_PATTERN = SCHEMA["$defs"]["claimRef"]["pattern"].removesuffix("$") + r"\Z" PIN_PATTERN = SCHEMA["$defs"]["claimPin"]["pattern"].removesuffix("$") + r"\Z" TAGS = st.text(alphabet="0123456789ABCDEFGHJKMNPQRSTVWXYZ", min_size=8, max_size=8) HOSTS = st.one_of( st.none(), st.from_regex(r"[a-z0-9][a-z0-9-]{0,8}\.[a-z]{2,6}", fullmatch=True), ) HASHES = st.text(alphabet="0123456789abcdef", min_size=64, max_size=64) def _fixture_texts() -> list[str]: found = set() for path in FIXTURES.rglob("*"): if path.is_file(): text = path.read_text("utf-8", errors="ignore") found.update(re.findall(r"claim:[A-Za-z0-9./@_-]+", text)) return sorted(found) def test_the_patterns_are_those_of_the_schema(): schema_ref, schema_pin = re.compile(REF_PATTERN), re.compile(PIN_PATTERN) samples = [ "claim:272XTX7C", "claim:272XTX7C@02f47b", "claim:example.org/272XTX7C", "claim:example.org/272XTX7C@02f47b", "claim:272XTX7I", "claim:272xtx7c", "claim:272XTX7", "claim:272XTX7C@02F47B", "claim:localhost/272XTX7C", "claim:a.b/272XTX7C@02f47", "claim:272XTX7C ", "claim:272XTX7C\n", ] for s in samples: assert bool(claims.CLAIM_REF_RE.match(s)) == bool(schema_ref.match(s)), s assert bool(claims.CLAIM_PIN_RE.match(s)) == bool(schema_pin.match(s)), s @given(st.from_regex(REF_PATTERN) | st.from_regex(PIN_PATTERN) | st.text(max_size=30)) @PROPERTIES def test_the_patterns_agree_with_the_schema_on_any_text(s): assert bool(claims.CLAIM_REF_RE.match(s)) == bool(re.match(REF_PATTERN, s)) assert bool(claims.CLAIM_PIN_RE.match(s)) == bool(re.match(PIN_PATTERN, s)) def test_the_fixtures_hold_claim_references_and_pins(): texts = _fixture_texts() assert any("@" in t for t in texts) assert any("@" not in t for t in texts) @pytest.mark.parametrize("text", _fixture_texts()) def test_a_fixture_claim_parses_and_formats_back(text): pin = claims.parse_pin(text) if "@" in text: assert pin is not None assert claims.parse_ref(text) is None assert pin["ref"] + "@" + pin["pin"] == text else: ref = claims.parse_ref(text) assert ref is not None assert claims.format_ref(ref["tag"], ref["host"]) == text assert pin is None def test_a_reference_has_a_tag_and_no_host_for_the_local_store(): assert claims.parse_ref("claim:272XTX7C") == {"host": None, "tag": "272XTX7C"} def test_a_reference_to_another_store_has_its_host(): assert claims.parse_ref("claim:claims.example.org/272XTX7C") == { "host": "claims.example.org", "tag": "272XTX7C", } def test_a_pin_splits_into_reference_tag_and_pin(): assert claims.parse_pin("claim:a.org/272XTX7C@02f47b") == { "ref": "claim:a.org/272XTX7C", "host": "a.org", "tag": "272XTX7C", "pin": "02f47b", } @pytest.mark.parametrize( "text", [ "", "272XTX7C", "claim:", "claim:272XTX7", "claim:272XTX7CC", "claim:272xtx7c", "claim:272XTX7U", "claim:272XTX7L", "claim:272XTX7I", "claim:272XTX7O", "claim:localhost/272XTX7C", "claim:Example.org/272XTX7C", "claim:amber/k-bond", "claim:272XTX7C@02f47b ", "claim:272XTX7C\n", ], ) def test_text_that_is_not_a_reference_does_not_parse(text): assert claims.parse_ref(text) is None @pytest.mark.parametrize( "text", [ "claim:272XTX7C", "claim:272XTX7C@", "claim:272XTX7C@02f47", "claim:272XTX7C@02f47b0", "claim:272XTX7C@02F47B", "claim:272XTX7C@02f47g", "272XTX7C@02f47b", "claim:272XTX7C@02f47b\n", ], ) def test_text_that_is_not_a_pin_does_not_parse(text): assert claims.parse_pin(text) is None def test_a_reference_is_not_a_pin_and_a_pin_is_not_a_reference(): assert claims.parse_pin("claim:272XTX7C") is None assert claims.parse_ref("claim:272XTX7C@02f47b") is None def test_format_ref_writes_the_local_and_the_hosted_form(): assert claims.format_ref("272XTX7C") == "claim:272XTX7C" assert claims.format_ref("272XTX7C", "a.org") == "claim:a.org/272XTX7C" assert claims.format_ref("272XTX7C", host="") == "claim:272XTX7C" @pytest.mark.parametrize( ("tag", "host"), [("short", None), ("272xtx7c", None), ("272XTX7C", "nodot")] ) def test_format_ref_refuses_what_is_not_a_reference(tag, host): with pytest.raises(ValueError, match="not a claim reference"): claims.format_ref(tag, host) def test_format_pin_keeps_the_first_six_digits_of_the_hash(): digest = "02f47b" + "0" * 58 assert claims.format_pin("claim:272XTX7C", digest) == "claim:272XTX7C@02f47b" def test_format_pin_refuses_a_bad_reference_or_hash(): with pytest.raises(ValueError, match="not a claim reference"): claims.format_pin("claim:nope", "0" * 64) with pytest.raises(ValueError, match="64 lowercase hex"): claims.format_pin("claim:272XTX7C", "02f47b") with pytest.raises(ValueError, match="64 lowercase hex"): claims.format_pin("claim:272XTX7C", "A" * 64) @given(TAGS, HOSTS) @PROPERTIES def test_a_formatted_reference_parses_back(tag, host): ref = claims.format_ref(tag, host) assert claims.parse_ref(ref) == {"host": host, "tag": tag} assert re.match(REF_PATTERN, ref) @given(TAGS, HOSTS, HASHES) @PROPERTIES def test_a_formatted_pin_parses_back(tag, host, digest): ref = claims.format_ref(tag, host) pin = claims.format_pin(ref, digest) assert claims.parse_pin(pin) == { "ref": ref, "host": host, "tag": tag, "pin": digest[:6], } assert re.match(PIN_PATTERN, pin)