b3c32 0.0.2__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+b3c32/__init__.py,sha256=jQItlLbASG-f3Nki5wVStNy0aAufFbDAFvCttjQBHn8,663
+b3c32/core.py,sha256=V2jwI32F_wig3NZ4GaYsafqiViy8WkpJwAYh4Xzuw1w,3938
+b3c32/errors.py,sha256=Hdmda5peD4Ih-ZKENh36iDcr3-rnaAIO-ulXZbRLlrA,1034
+b3c32/smoke.py,sha256=bNl-8oLgOwg74ZgmiZG1skE1IR6P5LUzZ7teufFRktY,2129
+b3c32-0.0.2.dist-info/METADATA,sha256=J-qXbOOLT5wC9Nc2tzRnylSa-uFjUyT5Qc9bfdMR5PY,2544
+b3c32-0.0.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+b3c32-0.0.2.dist-info/RECORD,,

b3c32-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any