Merge reviewability-v1 into dependency cleanup

Refresh the dependency-removal branch onto the current reviewability-v1 base. Preserve Python 3.10-3.15 support from #36 and the MIT/BSD license metadata from #15.

Author: BenWestgate

MANIFEST.in

@@ -1,4 +1,5 @@
 include LICENSE README.md SECURITY.md
+recursive-include LICENSES *
 recursive-include docs *.html *.md
 prune docs/planning
 exclude docs/developer/provenance.md

docs/developer/api.md

@@ -62,6 +62,9 @@ generic parse-length failure.
   modules. Labels, lengths, padding, diagnostics, and S types stay with their
   application; unknown HRPs remain opaque and there is no runtime registration.
 - Headers and artifacts are immutable; shares expose symbols, not bytes.
+- Artifact `str()` and `repr()` render redacted placeholders. Code that
+  intentionally serializes a validated `Share` or `Secret` must use its explicit
+  `.text` attribute.
 - Sharing interpolates payload and checksum together, explicitly constructs the
   target header, and reparses the result.
 - `generation.py` is the only entropy owner and generates only `ms` and `cl`.

docs/security/model.md

@@ -90,6 +90,10 @@ lengths or interpret payload semantics.
 
 Only parsers and profile-specific factories construct immutable validated
 artifacts. A share has symbol semantics and cannot be converted to bytes.
+Default `str()` and `repr()` rendering of artifacts is redacted; callers must
+use `.text` explicitly when they intentionally need the serialized recovery
+string. This reduces accidental disclosure through logs and interpolation but
+does not make `.text` safe to expose.
 Registration adds semantics but is not required for generic parsing, recovery,
 derivation, or correction. Wallet and profile-specific generation APIs do not
 accept opaque artifacts or raw strings.

pyproject.toml

@@ -11,8 +11,8 @@ authors = [
 description = "Python reference implementation for codex32 (BIP93) and codex32-encoded master seeds."
 readme = "README.md"
 requires-python = ">=3.10,<3.16"
-license = "MIT"
-license-files = ["LICENSE*"]
+license = "MIT AND BSD-3-Clause"
+license-files = ["LICENSE*", "LICENSES/*"]
 maintainers = [
   { name = "Ben Westgate", email = "benwestgate@protonmail.com" },
 ]

src/codex32/bip93.py

@@ -134,17 +134,32 @@ def __init__(
         object.__setattr__(self, "payload_symbols", payload_symbols)
 
     def __str__(self) -> str:
-        return self.text
+        return f"<{type(self).__name__}: redacted>"
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(<redacted>)"
 
     def __len__(self) -> int:
         return len(self.text)
 
 
 class Share(_Artifact):
+    """Validated codex32 share; use ``.text`` for the explicit serialized value.
+
+    ``str(share)`` and ``repr(share)`` are deliberately redacted so accidental
+    logging or interpolation does not disclose recovery material.
+    """
+
     __slots__ = ()
 
 
 class Secret(_Artifact):
+    """Validated codex32 secret; use ``.text`` for the explicit serialized value.
+
+    ``str(secret)`` and ``repr(secret)`` are deliberately redacted so accidental
+    logging or interpolation does not disclose recovery material.
+    """
+
     __slots__ = ()
 
 

src/codex32/correction.py

@@ -23,7 +23,7 @@
 
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass, replace
-from functools import cache
+from functools import cache, lru_cache
 from math import comb
 from time import monotonic
 from typing import Literal
@@ -250,6 +250,10 @@ class _Spec:
     1023,
 )
 
+# Keep every target length from one generic unknown-length search hot without
+# letting arbitrary HRPs create process-lifetime state.
+_ALIGNMENT_CACHE_SIZE = 11
+
 
 def _spec_for_checksum(checksum: _Checksum) -> _Spec:
     if checksum is _CODEX32:
@@ -276,7 +280,7 @@ def _pack_syndromes(values: tuple[int, ...]) -> int:
     return sum(value << (10 * index) for index, value in enumerate(values))
 
 
-@cache
+@lru_cache(maxsize=_ALIGNMENT_CACHE_SIZE)
 def _syndrome_alignment(spec: _Spec, hrp: str, length: int) -> tuple[int, tuple[tuple[int, ...], ...]]:
     base = _pack_syndromes(_syndromes(spec, _residue(spec, hrp, [0] * length), target=True))
     powers = _poly_powers(spec.generator, length)

tests/test_alignment.py

@@ -6,6 +6,7 @@
 
 from codex32._alignment import _IncrementalSyndromes, _View
 from codex32.correction import (
+    _ALIGNMENT_CACHE_SIZE,
     _LONG_SPEC,
     _SHORT_SPEC,
     _pack_syndromes,
@@ -15,6 +16,45 @@
 )
 
 
+def test_syndrome_alignment_cache_is_bounded_for_untrusted_hrps():
+    _syndrome_alignment.cache_clear()
+
+    for index in range(_ALIGNMENT_CACHE_SIZE + 5):
+        _syndrome_alignment(_SHORT_SPEC, f"attacker{index}", 45)
+
+    info = _syndrome_alignment.cache_info()
+    assert info.maxsize == _ALIGNMENT_CACHE_SIZE
+    assert info.currsize == _ALIGNMENT_CACHE_SIZE
+
+
+def test_syndrome_alignment_cache_fits_one_unknown_length_search():
+    observed = 50
+    targets = sorted({observed + delta for delta in (*range(-4, 5), -8, 8)})
+    _syndrome_alignment.cache_clear()
+
+    first = [_syndrome_alignment(_SHORT_SPEC, "generic", target) for target in targets]
+    before = _syndrome_alignment.cache_info()
+    second = [_syndrome_alignment(_SHORT_SPEC, "generic", target) for target in targets]
+    after = _syndrome_alignment.cache_info()
+
+    assert len(targets) == _ALIGNMENT_CACHE_SIZE
+    assert all(left is right for left, right in zip(first, second, strict=True))
+    assert after.misses == before.misses
+    assert after.hits == before.hits + len(targets)
+
+
+def test_syndrome_alignment_cache_still_reuses_recent_entries():
+    _syndrome_alignment.cache_clear()
+    first = _syndrome_alignment(_SHORT_SPEC, "ms", 45)
+    before = _syndrome_alignment.cache_info()
+
+    second = _syndrome_alignment(_SHORT_SPEC, "ms", 45)
+
+    after = _syndrome_alignment.cache_info()
+    assert first is second
+    assert after.hits == before.hits + 1
+
+
 @pytest.mark.parametrize(
     ("hrp", "length", "spec"),
     (

tests/test_public_api.py

@@ -11,7 +11,7 @@
 from data.bip93_vectors import VECTOR_2
 
 import codex32
-from codex32 import Header, MasterSeed, Share, parse_codex32
+from codex32 import CorrectionCandidate, Header, MasterSeed, Share, parse_codex32
 from codex32.errors import InvalidIdentifier, InvalidShareIndex, InvalidThreshold
 
 
@@ -84,6 +84,27 @@ def test_artifacts_cannot_be_directly_constructed_or_mutated() -> None:
         share.header.identifier = "leak"  # type: ignore[misc]
 
 
+def test_artifact_default_rendering_does_not_disclose_recovery_text() -> None:
+    share = parse_codex32(VECTOR_2["share_A"])
+    candidate = CorrectionCandidate(share, (), 1, 0, 0, None)
+
+    assert share.text not in str(share)
+    assert share.text not in repr(share)
+    assert share.text not in repr(candidate)
+    assert str(share) == "<Share: redacted>"
+    assert repr(share) == "Share(<redacted>)"
+
+
+def test_master_seed_default_rendering_does_not_disclose_seed_material() -> None:
+    secret = MasterSeed.from_seed(bytes(range(16)), identifier="test")
+
+    assert secret.text not in str(secret)
+    assert secret.text not in repr(secret)
+    assert "payload_symbols" not in repr(secret)
+    assert str(secret) == "<MasterSeed: redacted>"
+    assert repr(secret) == "MasterSeed(<redacted>)"
+
+
 def test_master_seed_factory_can_only_construct_index_s() -> None:
     secret = MasterSeed.from_seed(bytes(16), identifier="test", threshold=2)
     assert secret.header.index == "s"