b3c32 0.0.2__tar.gz

b3c32-0.0.2/.gitignore

@@ -0,0 +1,6 @@
+# .gitignore
+__pycache__/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.hypothesis/

b3c32-0.0.2/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: b3c32
+Version: 0.0.2
+Summary: Compact, hand-writable, prefix-matchable BLAKE3 XOF hashes in Crockford Base32
+Project-URL: Homepage, https://github.com/marcus-grant/b3c32
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.12
+Requires-Dist: blake3
+Description-Content-Type: text/markdown
+
+# b3c32 (Python)
+
+Compact, hand-writable, prefix-matchable XOF hashes and identities for
+anything.
+
+This is the Python implementation of b3c32, and until otherwise stated
+it is the reference implementation: the contract artifacts at the
+project root are certified against it, and other language
+implementations are certified against the same frozen vectors. That
+status is expected to change once a native Rust implementation exists.
+
+Codes are unkeyed BLAKE3 sliced on 40-bit boundaries, encoded as
+low-pad bitstream Crockford Base32. The result is short enough to write
+by hand, unambiguous enough to read aloud, and prefix-matchable so a
+truncated code still resolves.
+
+## Use
+
+```python
+from b3c32 import hash_b32
+
+code = hash_b32(b"hello", 120)
+```
+
+Width is in bits. 120 is the current certified width. This is not a
+ceiling on usefulness: slice the returned code at any multiple of 40
+bits, which is 5 bytes or 8 characters, and the short form is a true
+string prefix of the long one. Store the full code, index a prefix.
+
+The package also exports `hash_digest` for raw digest bytes, the codec
+functions `encode_crockford_b32`, `decode_crockford_b32`, and
+`coerce_crockford_b32`, the alphabet as `CROCKFORD32_ALPHABET`, and the
+error types `UncertifiedWidthError` and `CoercionError`.
+
+## Consuming
+
+Pin an exact version. The project is pre-1.0 and no compatibility
+policy is in force, so any release may change the contract. Call
+`verify_conformance` in your own suite to learn when it does:
+
+```python
+from b3c32 import verify_conformance
+
+def test_b3c32_contract():
+    verify_conformance()
+```
+
+It raises AssertionError naming the failed claim. Its scope is drift
+detection through the public API at the certified width; deep
+certification is this project's own suite against the pinned BLAKE3
+reference vectors.
+
+## Status
+
+Pre-release. Certification hardening is in progress. The full scheme
+definition, the normative conformance contract, and the frozen vectors
+live at the project root:
+<https://github.com/marcus-grant/b3c32>
+

b3c32-0.0.2/README.md

@@ -0,0 +1,59 @@
+# b3c32 (Python)
+
+Compact, hand-writable, prefix-matchable XOF hashes and identities for
+anything.
+
+This is the Python implementation of b3c32, and until otherwise stated
+it is the reference implementation: the contract artifacts at the
+project root are certified against it, and other language
+implementations are certified against the same frozen vectors. That
+status is expected to change once a native Rust implementation exists.
+
+Codes are unkeyed BLAKE3 sliced on 40-bit boundaries, encoded as
+low-pad bitstream Crockford Base32. The result is short enough to write
+by hand, unambiguous enough to read aloud, and prefix-matchable so a
+truncated code still resolves.
+
+## Use
+
+```python
+from b3c32 import hash_b32
+
+code = hash_b32(b"hello", 120)
+```
+
+Width is in bits. 120 is the current certified width. This is not a
+ceiling on usefulness: slice the returned code at any multiple of 40
+bits, which is 5 bytes or 8 characters, and the short form is a true
+string prefix of the long one. Store the full code, index a prefix.
+
+The package also exports `hash_digest` for raw digest bytes, the codec
+functions `encode_crockford_b32`, `decode_crockford_b32`, and
+`coerce_crockford_b32`, the alphabet as `CROCKFORD32_ALPHABET`, and the
+error types `UncertifiedWidthError` and `CoercionError`.
+
+## Consuming
+
+Pin an exact version. The project is pre-1.0 and no compatibility
+policy is in force, so any release may change the contract. Call
+`verify_conformance` in your own suite to learn when it does:
+
+```python
+from b3c32 import verify_conformance
+
+def test_b3c32_contract():
+    verify_conformance()
+```
+
+It raises AssertionError naming the failed claim. Its scope is drift
+detection through the public API at the certified width; deep
+certification is this project's own suite against the pinned BLAKE3
+reference vectors.
+
+## Status
+
+Pre-release. Certification hardening is in progress. The full scheme
+definition, the normative conformance contract, and the frozen vectors
+live at the project root:
+<https://github.com/marcus-grant/b3c32>
+

b3c32-0.0.2/pyproject.toml

@@ -0,0 +1,32 @@
+# python/pyproject.toml
+[project]
+name = "b3c32"
+version = "0.0.2"
+description = "Compact, hand-writable, prefix-matchable BLAKE3 XOF hashes in Crockford Base32"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+dependencies = ["blake3"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+]
+
+[project.urls]
+Homepage = "https://github.com/marcus-grant/b3c32"
+
+[dependency-groups]
+dev = ["pytest", "hypothesis", "ruff", "pyright"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/b3c32"]
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"

b3c32-0.0.2/src/b3c32/__init__.py

@@ -0,0 +1,30 @@
+# python/src/b3c32/__init__.py
+"""
+b3c32: compact, hand-writable, prefix-matchable XOF hashes.
+Author: Marcus Grant
+Date: 2026-07-24
+License: Apache-2.0
+"""
+
+from b3c32.core import (
+    CROCKFORD32_ALPHABET,
+    coerce_crockford_b32,
+    decode_crockford_b32,
+    encode_crockford_b32,
+    hash_b32,
+    hash_digest,
+)
+from b3c32.errors import CoercionError, UncertifiedWidthError
+from b3c32.smoke import verify_conformance
+
+__all__ = [
+    "CROCKFORD32_ALPHABET",
+    "CoercionError",
+    "UncertifiedWidthError",
+    "coerce_crockford_b32",
+    "decode_crockford_b32",
+    "encode_crockford_b32",
+    "hash_b32",
+    "hash_digest",
+    "verify_conformance",
+]

b3c32-0.0.2/src/b3c32/core.py

@@ -0,0 +1,132 @@
+# python/src/b3c32/core.py
+"""
+BLAKE3 hashing and Crockford Base32 codec for b3c32 codes.
+Author: Marcus Grant
+Date: 2026-01-26
+Revisions: [2026-07-24]
+License: Apache-2.0
+"""
+
+from blake3 import blake3
+
+from b3c32.errors import CoercionError, UncertifiedWidthError
+
+_CERTIFIED_BITS = frozenset({120})
+_TRANS_CROCKFORD_AMBIG = str.maketrans({"O": "0", "I": "1", "L": "1"})
+
+CROCKFORD32_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+
+def hash_digest(data: bytes, bits: int) -> bytes:
+    """Compute the content digest at a certified width.
+
+    Unkeyed BLAKE3 XOF sliced to bits, gated on the certified set.
+
+    Args:
+        data: The bytes to hash.
+        bits: Digest width; must be in the certified set.
+
+    Returns:
+        The digest of bits // 8 bytes.
+
+    Raises:
+        UncertifiedWidthError: bits is not a certified width.
+    """
+    if bits not in _CERTIFIED_BITS:
+        raise UncertifiedWidthError(bits)
+    return blake3(data).digest(length=bits // 8)
+
+
+def encode_crockford_b32(data: bytes) -> str:
+    """Encode bytes as Crockford Base32, low-pad bitstream.
+
+    Bits are taken MSB-first as a single stream, grouped into 5-bit
+    units from the left; a final partial group is zero-extended in the
+    least-significant positions (low-pad) per the Base32-for-Humans
+    draft, Section 3.1.
+
+    Args:
+        data: The bytes to encode.
+
+    Returns:
+        Crockford Base32 string, length ceil(len(data) * 8 / 5).
+    """
+    num, bit_count = int.from_bytes(data, byteorder="big"), len(data) * 8
+    symbol_count = (bit_count + 4) // 5  # ceil(bits / 5)
+    num <<= (5 - bit_count % 5) % 5  # low-pad to next 5-bit boundary
+    symbols = []
+    for i in range(symbol_count):
+        symbol_num = (num >> (5 * (symbol_count - 1 - i))) & 0b11111
+        symbols.append(CROCKFORD32_ALPHABET[symbol_num])
+    return "".join(symbols)
+
+
+def hash_b32(data: bytes, bits: int) -> str:
+    """Compute the canonical code at a certified width.
+
+    Composes hash_digest and the Crockford encoder.
+
+    Args:
+        data: The bytes to hash.
+        bits: Digest width; must be in the certified set.
+
+    Returns:
+        Crockford Base32 code of bits // 5 characters.
+
+    Raises:
+        UncertifiedWidthError: bits is not a certified width.
+    """
+    return encode_crockford_b32(hash_digest(data, bits))
+
+
+def decode_crockford_b32(code: str) -> bytes:
+    """Decode canonical Crockford Base32 to bytes.
+
+    Symbols are taken MSB-first in 5-bit groups. Trailing bits that do
+    not complete a byte are discarded: they are pad the encoder added to
+    fill a whole symbol, never part of the input. Reference
+    implementation of the encoding's inverse.
+
+    Args:
+        code: Canonical (uppercase, alphabet-only) Crockford string.
+
+    Returns:
+        The decoded bytes.
+
+    Raises:
+        ValueError: A character is outside the Crockford alphabet.
+    """
+    accumulated_int = 0
+    for symbol in code:
+        symbol_int_value = CROCKFORD32_ALPHABET.index(symbol)
+        # Shift left 5 to make room, OR to append this symbol's bits
+        accumulated_int = (accumulated_int << 5) | symbol_int_value
+    bit_count = 5 * len(code)
+    # Trailing bits past the last whole byte are encoder pad, so drop them
+    accumulated_int >>= bit_count % 8
+    return accumulated_int.to_bytes(bit_count // 8, "big")
+
+
+def coerce_crockford_b32(code: str) -> str:
+    """Coerce user-supplied code for non-strict decodes/lookups.
+
+    Args:
+        code: User-supplied code string.
+
+    Returns:
+        Canonical uppercase string with ambiguous chars normalized.
+
+    Raises:
+        CoercionError: If code is empty or contains invalid characters.
+    """
+    s = code.strip().upper()
+    s = s.replace("-", "").replace(" ", "")
+    s = s.translate(_TRANS_CROCKFORD_AMBIG)
+
+    if not s:
+        raise CoercionError()
+
+    for ch in s:
+        if ch not in CROCKFORD32_ALPHABET:
+            raise CoercionError(ch)
+    return s

b3c32-0.0.2/src/b3c32/errors.py

@@ -0,0 +1,35 @@
+# python/src/b3c32/errors.py
+"""
+Exception types for b3c32.
+Author: Marcus Grant
+Date: 2026-07-24
+License: Apache-2.0
+"""
+
+
+class UncertifiedWidthError(ValueError):
+    """Raised when a requested digest width is not in the certified set.
+
+    Subclasses ValueError so naive callers still catch it; distinct so
+    consumer smoke tests can assert the gate survived an upgrade.
+    """
+
+    def __init__(self, bits: int) -> None:
+        self.bits = bits
+        super().__init__(f"digest width {bits} bits is not certified by contract")
+
+
+class CoercionError(ValueError):
+    """Raised when user-supplied code cannot be coerced to canonical form.
+
+    Carries the offending character, or None when the input was empty
+    after normalization.
+    """
+
+    def __init__(self, char: str | None = None) -> None:
+        self.char = char
+        if char is None:
+            msg = "cannot coerce input, empty after normalization"
+        else:
+            msg = f"cannot coerce input, offending char: {char}"
+        super().__init__(msg)

b3c32-0.0.2/src/b3c32/smoke.py

@@ -0,0 +1,65 @@
+# python/src/b3c32/smoke.py
+"""
+Consumer smoke checks for contract drift detection.
+Author: Marcus Grant
+Date: 2026-07-27
+License: Apache-2.0
+"""
+
+from b3c32 import (
+    CoercionError,
+    UncertifiedWidthError,
+    coerce_crockford_b32,
+    decode_crockford_b32,
+    encode_crockford_b32,
+    hash_b32,
+)
+
+
+def verify_conformance() -> None:
+    """Assert the installed b3c32 still honors the contract surface.
+
+    One curated assertion per contract claim a consumer depends on.
+    Raises AssertionError naming the failed claim, or the library's
+    own error types if raise behavior itself has drifted.
+
+    Scope: drift detection through the public API only. Deep
+    certification, including XOF output past the 64-byte block and
+    exhaustive codec domains, is the library's own suite against the
+    pinned reference file. A consumer build passing here is the
+    certified surface at 120 bits; it is not itself a certification.
+    """
+    code = hash_b32(bytes(i % 251 for i in range(0)), 120)
+    msg = f"smoke: pipeline vector mismatch at 120 bits, got {code}"
+    assert code == "NW9MKEFNZ6GTD8209QN3DQ69", msg
+
+    digest_wide = bytes(range(20))
+    narrow = encode_crockford_b32(digest_wide[:15])
+    wide = encode_crockford_b32(digest_wide)
+    msg = "smoke: 40-bit prefix relation broken on aligned widths"
+    assert wide.startswith(narrow), msg
+
+    encoded = encode_crockford_b32(b"foobar")
+    msg = f"smoke: non-aligned encode mismatch, got {encoded}"
+    assert encoded == "CSQPYRK1E8", msg
+
+    decoded = decode_crockford_b32("CSQPYRK1E8")
+    assert decoded == b"foobar", f"smoke: decode inversion mismatch, got {decoded!r}"
+
+    coerced = coerce_crockford_b32("oil-1")
+    msg = f"smoke: coercion mismatch, got {coerced}"
+    assert coerced == "0111", msg
+
+    try:
+        coerce_crockford_b32("!")
+    except CoercionError:
+        pass
+    else:
+        raise AssertionError("smoke: CoercionError not raised on invalid char")
+
+    try:
+        hash_b32(b"", 160)
+    except UncertifiedWidthError:
+        pass
+    else:
+        raise AssertionError("smoke: UncertifiedWidthError not raised at 160")

b3c32-0.0.2/tests/test_alphabet.py

@@ -0,0 +1,67 @@
+# python/tests/test_alphabet.py
+"""
+Tests for the Crockford alphabet contract.
+Author: Marcus Grant
+Date: 2026-08-11
+License: Apache-2.0
+"""
+
+import string
+
+from b3c32.core import CROCKFORD32_ALPHABET
+
+
+class TestCrockfordAlphabet:
+    """Contract 4.4. The alphabet is pinned two independent ways, neither
+    restating the module's literal.
+
+    The first route rebuilds the alphabet from stdlib constants and the
+    I, L, O, U exclusion rule, asserting the literal matches. The second
+    pins it from spec facts alone: the digits block, the A and Z
+    endpoints, the four skip transitions, and strict ascent. The routes
+    share no source, so a typo in the literal fails the first and a
+    wrong exclusion rule fails the second.
+    """
+
+    def test_matches_rule_construction(self):
+        """The literal equals digits followed by uppercase letters with
+        I, L, O, U removed, built from stdlib constants."""
+        alphanum = string.digits + string.ascii_uppercase
+        assert CROCKFORD32_ALPHABET == "".join(c for c in alphanum if c not in "ILOU")
+
+    def test_length_is_32(self):
+        """The alphabet is exactly 32 symbols, one per 5-bit value."""
+        assert len(CROCKFORD32_ALPHABET) == 32
+
+    def test_symbols_unique(self):
+        """No symbol repeats, every 5bit value maps to a distinct character."""
+        assert len(set(CROCKFORD32_ALPHABET)) == 32
+
+    def test_excludes_ambiguous_letters(self):
+        """No I,L,O,U appear: 1st 3 ambiguous visually to 1,0; U reserved to checksum"""
+        assert not any(c in CROCKFORD32_ALPHABET for c in "ILOU")
+
+    def test_digits_block(self):
+        """First 10 symbols are digits 0 to 9 without stdlib string helpers."""
+        assert CROCKFORD32_ALPHABET[:10] == "".join(str(n) for n in range(10))
+
+    def test_letters_start_after_digits(self):
+        """A appears at 10, after digits block, and Z at end index of 31."""
+        assert CROCKFORD32_ALPHABET[10] == "A"
+        assert CROCKFORD32_ALPHABET[31] == "Z"
+
+    def test_skip_transitions_positional(self):
+        """Skips at HJ, KM, NP, TV, pinning which are omitted in alphanum sequence."""
+        assert CROCKFORD32_ALPHABET.index("H") + 1 == CROCKFORD32_ALPHABET.index("J")
+        assert CROCKFORD32_ALPHABET.index("K") + 1 == CROCKFORD32_ALPHABET.index("M")
+        assert CROCKFORD32_ALPHABET.index("N") + 1 == CROCKFORD32_ALPHABET.index("P")
+        assert CROCKFORD32_ALPHABET.index("T") + 1 == CROCKFORD32_ALPHABET.index("V")
+
+    def test_ordering_monotonic(self):
+        """Digits 0-9 occupy indices 0-9 and letters ascend thereafter,
+        so lexical order of encoded strings matches bit order."""
+        previous_symbol = CROCKFORD32_ALPHABET[10]
+        for current_symbol in CROCKFORD32_ALPHABET[11:]:
+            msg = f"Alphabet order not monotonic: {previous_symbol} >= {current_symbol}"
+            assert current_symbol > previous_symbol, msg
+            previous_symbol = current_symbol