baseh 1.1.0__py3-none-any.whl

baseh/__init__.py

@@ -0,0 +1,62 @@
+"""baseH codec, Python implementation.
+
+Public API mirrors spec section 12: the Baseh codec class, BasehError with a
+stable .code attribute and the frozen profile tier helpers (baseh_medium_v1
+is the default tier; the _p variants enable feistel-v1 permutation).
+"""
+
+from .blocklist import DEFAULT_BLOCKLIST
+from .codec import CONFUSION_MAPS, Baseh, DecodeResult, generate_candidates
+from .errors import (
+    AMBIGUOUS_INPUT,
+    BLOCKED_CODE,
+    INVALID_CHARACTER,
+    INVALID_CHECKSUM,
+    INVALID_LENGTH,
+    INVALID_PROFILE,
+    OUT_OF_RANGE,
+    PERMUTATION_FAILURE,
+    TOO_MANY_CANDIDATES,
+    BasehError,
+)
+from .profiles import (
+    baseh_heavy_p_v1,
+    baseh_heavy_v1,
+    baseh_light_p_v1,
+    baseh_light_v1,
+    baseh_medium_p_v1,
+    baseh_medium_v1,
+    baseh_minimum_p_v1,
+    baseh_minimum_v1,
+)
+from .zero import from_code, to_code
+
+__all__ = [
+    "Baseh",
+    "BasehError",
+    "DecodeResult",
+    "CONFUSION_MAPS",
+    "DEFAULT_BLOCKLIST",
+    "generate_candidates",
+    "baseh_minimum_v1",
+    "baseh_minimum_p_v1",
+    "baseh_light_v1",
+    "baseh_light_p_v1",
+    "baseh_medium_v1",
+    "baseh_medium_p_v1",
+    "baseh_heavy_v1",
+    "baseh_heavy_p_v1",
+    "INVALID_PROFILE",
+    "OUT_OF_RANGE",
+    "PERMUTATION_FAILURE",
+    "INVALID_LENGTH",
+    "INVALID_CHARACTER",
+    "INVALID_CHECKSUM",
+    "AMBIGUOUS_INPUT",
+    "TOO_MANY_CANDIDATES",
+    "BLOCKED_CODE",
+    "to_code",
+    "from_code",
+]
+
+__version__ = "1.0.0"

baseh/basen.py

@@ -0,0 +1,36 @@
+"""Fixed-length base-N encode and decode, spec sections 5.1 through 5.3."""
+
+from __future__ import annotations
+
+from .errors import INVALID_CHARACTER, OUT_OF_RANGE, BasehError
+
+
+def alphabet_index(alphabet: str) -> dict:
+    return {ch: i for i, ch in enumerate(alphabet)}
+
+
+def encode_base_n(value: int, alphabet: str, length: int) -> str:
+    """Fixed-length base-N encode, most significant digit first."""
+    base = len(alphabet)
+    capacity = base ** length
+    if value < 0 or value >= capacity:
+        raise BasehError(OUT_OF_RANGE, "value is outside the fixed-length capacity")
+    out = [""] * length
+    v = value
+    for pos in range(length - 1, -1, -1):
+        out[pos] = alphabet[v % base]
+        v //= base
+    return "".join(out)
+
+
+def decode_base_n(text: str, alphabet: str, index: dict | None = None) -> int:
+    base = len(alphabet)
+    if index is None:
+        index = alphabet_index(alphabet)
+    value = 0
+    for ch in text:
+        digit = index.get(ch)
+        if digit is None:
+            raise BasehError(INVALID_CHARACTER, f"Symbol {ch!r} is not in the alphabet")
+        value = value * base + digit
+    return value

baseh/blocklist.py

@@ -0,0 +1,41 @@
+"""Profanity safety primitives, spec section 18."""
+
+from __future__ import annotations
+
+import re
+
+from .errors import INVALID_PROFILE, BasehError
+
+# Spec 18.2 default list. Deliberately small; applications extend it.
+DEFAULT_BLOCKLIST = (
+    "CRAP", "TWAT", "SHAG", "DAMN", "FCK", "FUC",
+    "SHT", "CNT", "TWT", "DCK", "AZZ", "BCH",
+)
+
+_WORD = re.compile(r"^[A-Za-z]{2,32}$")
+_VOWELS = frozenset("AEIOU")
+
+
+def effective_blocklist(profanity: dict) -> list:
+    """Spec 18.2: replacement semantics, then augmentation, uppercased and
+    deduplicated. Raises BasehError INVALID_PROFILE on a malformed entry."""
+    base = list(profanity["words"]) if "words" in profanity else list(DEFAULT_BLOCKLIST)
+    words = base + list(profanity.get("extraWords") or [])
+    out: list = []
+    for word in words:
+        if not isinstance(word, str) or not _WORD.match(word):
+            raise BasehError(
+                INVALID_PROFILE,
+                "Invalid baseH profile: blocklist entries must be 2 through 32 ASCII letters",
+                False,
+            )
+        upper = word.upper()
+        if upper not in out:
+            out.append(upper)
+    return out
+
+
+def strip_vowels(alphabet_norm: str) -> str:
+    """Spec 18.1: vowels removed for no-vowels mode, applied after case
+    normalization."""
+    return "".join(ch for ch in alphabet_norm if ch not in _VOWELS)

baseh/checksum.py

@@ -0,0 +1,36 @@
+"""Version 1 rolling polynomial checksum, spec section 6.2."""
+
+from __future__ import annotations
+
+from .basen import alphabet_index, encode_base_n
+from .errors import INVALID_CHARACTER, BasehError
+from .profile import PreparedProfile
+
+_INITIAL_STATE = 17
+_MULTIPLIER = 37
+
+
+def checksum_value(profile: PreparedProfile, body: str, body_index: dict) -> int:
+    """Return the checksum value in [0, modulus)."""
+    modulus = profile.checksum_modulus
+    state = _INITIAL_STATE
+    for byte in profile.profile_id.encode("ascii"):
+        state = (state * _MULTIPLIER + byte + 1) % modulus
+    state = (state * _MULTIPLIER) % modulus
+    for pos, ch in enumerate(body):
+        value = body_index.get(ch)
+        if value is None:
+            raise BasehError(
+                INVALID_CHARACTER, f"Symbol {ch!r} is not in the body alphabet"
+            )
+        state = (state * _MULTIPLIER + value + pos + 1) % modulus
+    return state
+
+
+def calculate_checksum(profile: PreparedProfile, body: str) -> str:
+    """Compute the expected checksum string for a normalized body."""
+    if profile.checksum_length == 0:
+        return ""
+    index = alphabet_index(profile.body_alphabet_norm)
+    value = checksum_value(profile, body, index)
+    return encode_base_n(value, profile.checksum_alphabet_norm, profile.checksum_length)

baseh/codec.py

@@ -0,0 +1,242 @@
+"""Full encode and decode flows, spec sections 8, 9, 10, 11 and 12."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .basen import alphabet_index, decode_base_n, encode_base_n
+from .checksum import calculate_checksum
+from .errors import (
+    AMBIGUOUS_INPUT,
+    BLOCKED_CODE,
+    INVALID_CHARACTER,
+    INVALID_CHECKSUM,
+    INVALID_LENGTH,
+    OUT_OF_RANGE,
+    TOO_MANY_CANDIDATES,
+    BasehError,
+)
+from .feistel import FeistelKey, inverse_permute, permute
+from .profile import PreparedProfile, prepare_profile
+
+# Built-in spoken-confusion candidate maps, spec 3.3. Body symbols only.
+CONFUSION_MAPS = {
+    "light": {"B": ["D"], "D": ["B"], "P": ["T"], "T": ["P"]},
+    "medium": {
+        "B": ["D"], "D": ["B"], "P": ["T"], "T": ["P"],
+        "M": ["N"], "N": ["M"], "V": ["W"], "W": ["V"],
+    },
+    "heavy": {
+        "B": ["D"], "D": ["B"], "P": ["T"], "T": ["P"],
+        "M": ["N"], "N": ["M"], "V": ["W"], "W": ["V"],
+        "F": ["S"], "S": ["F"], "C": ["G"], "G": ["C"],
+    },
+}
+
+_ASCII_WS = "\t\n\v\f\r "
+_MAX_CANDIDATES = 64
+
+
+@dataclass(frozen=True)
+class DecodeResult:
+    id: int
+    canonical_code: str
+    corrected: bool
+
+
+def normalize(input: str, profile: PreparedProfile, accept_spaces: bool = False) -> str:
+    """Spec 3.1 normalization, steps 1-7. Returns the raw unformatted string."""
+    if not isinstance(input, str):
+        raise BasehError(INVALID_CHARACTER, "input must be a string")
+    s = input.strip(_ASCII_WS)
+    if profile.separator:
+        s = s.replace(profile.separator, "")
+    if accept_spaces:
+        s = s.replace(" ", "")
+    if not profile.case_sensitive:
+        s = s.upper()
+    if profile.aliases_norm:
+        s = "".join(profile.aliases_norm.get(ch, ch) for ch in s)
+    allowed = set(profile.body_alphabet_norm) | set(profile.checksum_alphabet_norm)
+    for ch in s:
+        if ch not in allowed:
+            raise BasehError(INVALID_CHARACTER, f"Symbol {ch!r} is not accepted")
+    expected = profile.body_length + profile.checksum_length
+    # Spec 3.4: a code that lost leading zero body symbols is re-padded with
+    # the body zero symbol. The checksum symbols always remain, so the split
+    # point is unambiguous. A fully stripped no-checksum code would be empty
+    # and stays a length error.
+    if len(s) < expected and len(s) >= max(profile.checksum_length, 1):
+        zero = profile.body_alphabet_norm[0]
+        s = zero * (expected - len(s)) + s
+    if len(s) != expected:
+        raise BasehError(INVALID_LENGTH, f"Expected {expected} symbols, got {len(s)}")
+    return s
+
+
+def format_raw(raw: str, profile: PreparedProfile) -> str:
+    if not profile.separator:
+        return raw
+    parts = []
+    offset = 0
+    for size in profile.grouping:
+        parts.append(raw[offset : offset + size])
+        offset += size
+    return profile.separator.join(parts)
+
+
+def generate_candidates(body: str, confusion_map: dict, max_edits: int = 1) -> list:
+    """Spec 10. Substitution-only candidate generation, capped and deduplicated."""
+    if max_edits == 0:
+        return []
+    results: set = set()
+    for pos, source in enumerate(body):
+        for replacement in confusion_map.get(source, ()):
+            candidate = body[:pos] + replacement + body[pos + 1 :]
+            results.add(candidate)
+            if len(results) > _MAX_CANDIDATES:
+                raise BasehError(
+                    TOO_MANY_CANDIDATES,
+                    "Candidate generation exceeded 64 entries",
+                    False,
+                )
+    return list(results)
+
+
+class Baseh:
+    """Codec bound to one validated profile. The profile is validated once at
+    construction per spec 2.2, never per encode or decode."""
+
+    def __init__(self, profile: dict) -> None:
+        if isinstance(profile, PreparedProfile):
+            self._profile = profile
+        else:
+            self._profile = prepare_profile(profile)
+        self._body_index = alphabet_index(self._profile.body_alphabet_norm)
+
+    @property
+    def profile(self) -> PreparedProfile:
+        return self._profile
+
+    def capacity(self) -> int:
+        return self._profile.capacity
+
+    def _feistel_key(self) -> FeistelKey:
+        perm = self._profile.permutation
+        return FeistelKey(
+            profile_id=self._profile.profile_id,
+            key_bytes=perm.key_bytes,
+            rounds=perm.rounds,
+        )
+
+    def encode(self, id: int) -> str:
+        """Spec 8, including the section 18.2 blocked-substring scan."""
+        if isinstance(id, bool) or not isinstance(id, int):
+            raise BasehError(OUT_OF_RANGE, "id must be an integer")
+        value = id
+        if value < 0 or value >= self._profile.capacity:
+            raise BasehError(OUT_OF_RANGE, f"ID {value} is outside the profile capacity")
+        if self._profile.permutation.enabled:
+            value = permute(value, self._profile.capacity, self._feistel_key())
+        body = encode_base_n(
+            value, self._profile.body_alphabet_norm, self._profile.body_length
+        )
+        checksum = calculate_checksum(self._profile, body)
+        raw = body + checksum
+        # Spec 18.2: case-insensitive substring scan over the raw code.
+        if self._profile.blocklist:
+            upper = raw.upper()
+            if any(word in upper for word in self._profile.blocklist):
+                raise BasehError(
+                    BLOCKED_CODE,
+                    "The generated reference contains a blocked substring",
+                    False,
+                )
+        return format_raw(raw, self._profile)
+
+    def decode(
+        self,
+        input: str,
+        *,
+        accept_spaces: bool = False,
+        try_correction: bool = False,
+        confusion_profile: str = "none",
+        max_corrections: int = 1,
+    ) -> DecodeResult:
+        """Spec 9."""
+        raw = normalize(input, self._profile, accept_spaces)
+        body = raw[: self._profile.body_length]
+        supplied_checksum = raw[self._profile.body_length :]
+
+        # Spec 3.1 validates union membership before the split. There is no
+        # per-region membership check: a checksum-region symbol outside the
+        # checksum alphabet fails as INVALID_CHECKSUM and a body symbol
+        # outside the body alphabet fails in the checksum or base-N work as
+        # INVALID_CHARACTER.
+
+        if calculate_checksum(self._profile, body) != supplied_checksum:
+            if not try_correction or max_corrections == 0:
+                raise BasehError(
+                    INVALID_CHECKSUM, "The reference code did not pass validation"
+                )
+            if confusion_profile == "none":
+                raw_map: dict = {}
+            elif confusion_profile in CONFUSION_MAPS:
+                raw_map = CONFUSION_MAPS[confusion_profile]
+            else:
+                raise ValueError(
+                    f"unknown confusion profile: {confusion_profile!r}"
+                )
+            # Spec 10: replacements that are not body alphabet symbols are
+            # dropped before candidate generation. A suggested symbol the
+            # alphabet cannot contain (say a spoken drop on a stripped-alphabet
+            # profile) could never validate; generating it anyway would raise
+            # INVALID_CHARACTER from the checksum step instead of reporting an
+            # honest INVALID_CHECKSUM.
+            body_set = set(self._profile.body_alphabet_norm)
+            confusion_map = {}
+            for source, replacements in raw_map.items():
+                kept = [r for r in replacements if r in body_set]
+                if kept:
+                    confusion_map[source] = kept
+            valid: set = set()
+            for candidate in generate_candidates(body, confusion_map, max_corrections):
+                if calculate_checksum(self._profile, candidate) == supplied_checksum:
+                    valid.add(candidate)
+            if not valid:
+                raise BasehError(
+                    INVALID_CHECKSUM, "The reference code did not pass validation"
+                )
+            if len(valid) > 1:
+                raise BasehError(
+                    AMBIGUOUS_INPUT,
+                    "The reference code matches more than one record",
+                    False,
+                )
+            body = next(iter(valid))
+
+        value = decode_base_n(
+            body, self._profile.body_alphabet_norm, self._body_index
+        )
+        if self._profile.permutation.enabled:
+            value = inverse_permute(
+                value, self._profile.capacity, self._feistel_key()
+            )
+        canonical_code = self.encode(value)
+        if self._profile.separator:
+            canonical_raw = canonical_code.replace(self._profile.separator, "")
+        else:
+            canonical_raw = canonical_code
+        return DecodeResult(
+            id=value,
+            canonical_code=canonical_code,
+            corrected=(raw != canonical_raw),
+        )
+
+    def validate(self, input: str, **options) -> dict:
+        """Spec 12.4. Never raises on user input."""
+        try:
+            result = self.decode(input, **options)
+            return {"valid": True, "canonical_code": result.canonical_code}
+        except BasehError as err:
+            return {"valid": False, "reason": err.code}

baseh/errors.py

@@ -0,0 +1,36 @@
+"""Error type and codes defined by the baseH codec specification."""
+
+INVALID_PROFILE = "INVALID_PROFILE"
+OUT_OF_RANGE = "OUT_OF_RANGE"
+PERMUTATION_FAILURE = "PERMUTATION_FAILURE"
+INVALID_LENGTH = "INVALID_LENGTH"
+INVALID_CHARACTER = "INVALID_CHARACTER"
+INVALID_CHECKSUM = "INVALID_CHECKSUM"
+AMBIGUOUS_INPUT = "AMBIGUOUS_INPUT"
+TOO_MANY_CANDIDATES = "TOO_MANY_CANDIDATES"
+BLOCKED_CODE = "BLOCKED_CODE"
+
+ERROR_CODES = frozenset(
+    {
+        INVALID_PROFILE,
+        OUT_OF_RANGE,
+        PERMUTATION_FAILURE,
+        INVALID_LENGTH,
+        INVALID_CHARACTER,
+        INVALID_CHECKSUM,
+        AMBIGUOUS_INPUT,
+        TOO_MANY_CANDIDATES,
+        BLOCKED_CODE,
+    }
+)
+
+
+class BasehError(Exception):
+    """Codec error carrying a stable, machine-readable code."""
+
+    def __init__(self, code: str, message: str, safe_for_customer: bool = True) -> None:
+        super().__init__(message)
+        if code not in ERROR_CODES:
+            raise ValueError(f"unknown baseH error code: {code!r}")
+        self.code = code
+        self.safe_for_customer = safe_for_customer

baseh/feistel.py

@@ -0,0 +1,119 @@
+"""Feistel-v1 reversible permutation, spec section 7.3.
+
+Message bytes, half widths, low-N-bits truncation and cycle walking are
+implemented exactly as written in section 7.3. The vectors in
+vectors/feistel-vectors.json are the ground truth.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from dataclasses import dataclass
+
+from .errors import PERMUTATION_FAILURE, BasehError
+
+
+@dataclass(frozen=True)
+class FeistelKey:
+    profile_id: str
+    key_bytes: bytes
+    rounds: int
+
+
+_TAG = b"BASEH-FEISTEL-V1"
+_MAX_WALKS = 1000
+
+
+def _bit_length(capacity: int) -> int:
+    return (capacity - 1).bit_length()
+
+
+def _low_bits(digest: bytes, n: int) -> int:
+    """Interpret the first ceil(n/8) digest bytes as big-endian, mask to n bits."""
+    byte_count = (n + 7) // 8
+    value = int.from_bytes(digest[:byte_count], "big")
+    return value & ((1 << n) - 1)
+
+
+def _round_message(profile_id: str, round_number: int, right: int, wr: int) -> bytes:
+    pid_bytes = profile_id.encode("ascii")
+    right_bytes = right.to_bytes((wr + 7) // 8, "big")
+    return (
+        _TAG
+        + b"\x00"
+        + pid_bytes
+        + b"\x00"
+        + bytes([round_number])
+        + right_bytes
+    )
+
+
+def _run_rounds(left: int, right: int, key, w0: int, w1: int) -> tuple:
+    for i in range(key.rounds):
+        even = i % 2 == 0
+        wr = w1 if even else w0
+        wl = w0 if even else w1
+        digest = hmac.new(
+            key.key_bytes, _round_message(key.profile_id, i, right, wr), hashlib.sha256
+        ).digest()
+        f = _low_bits(digest, wl)
+        left, right = right, left ^ f
+    return left, right
+
+
+def _run_inverse(left: int, right: int, key, w0: int, w1: int) -> tuple:
+    for i in range(key.rounds - 1, -1, -1):
+        even = i % 2 == 0
+        wr = w1 if even else w0
+        wl = w0 if even else w1
+        digest = hmac.new(
+            key.key_bytes, _round_message(key.profile_id, i, left, wr), hashlib.sha256
+        ).digest()
+        f = _low_bits(digest, wl)
+        left, right = right ^ f, left
+    return left, right
+
+
+def _split(value: int, w1: int) -> tuple:
+    return value >> w1, value & ((1 << w1) - 1)
+
+
+def _combine(left: int, right: int, w1: int) -> int:
+    return (left << w1) | right
+
+
+def permute(value: int, capacity: int, key) -> int:
+    """Forward permutation with cycle walking, spec 7.3 steps 1-7."""
+    bits = _bit_length(capacity)
+    w1 = bits // 2
+    w0 = bits - w1
+    v = value
+    for _ in range(_MAX_WALKS):
+        left, right = _split(v, w1)
+        left, right = _run_rounds(left, right, key, w0, w1)
+        out = _combine(left, right, w1)
+        if out < capacity:
+            return out
+        v = out
+    raise BasehError(
+        PERMUTATION_FAILURE, "Feistel cycle walking exceeded 1000 iterations", False
+    )
+
+
+def inverse_permute(value: int, capacity: int, key) -> int:
+    """Inverse permutation with identical cycle walking, spec 7.3."""
+    bits = _bit_length(capacity)
+    w1 = bits // 2
+    w0 = bits - w1
+    v = value
+    for _ in range(_MAX_WALKS):
+        left, right = _split(v, w1)
+        left, right = _run_inverse(left, right, key, w0, w1)
+        out = _combine(left, right, w1)
+        if out < capacity:
+            return out
+        v = out
+    raise BasehError(
+        PERMUTATION_FAILURE, "Feistel cycle walking exceeded 1000 iterations", False
+    )

baseh/profile.py

@@ -0,0 +1,205 @@
+"""Profile validation per spec section 2.2 and derived precomputed values."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .blocklist import effective_blocklist, strip_vowels
+from .errors import INVALID_PROFILE, BasehError
+
+
+def _fail(reason: str) -> None:
+    raise BasehError(INVALID_PROFILE, f"Invalid baseH profile: {reason}", False)
+
+
+def _is_ascii_char(ch: str) -> bool:
+    return len(ch) == 1 and 0x20 <= ord(ch) <= 0x7E
+
+
+def _is_ascii(text: str) -> bool:
+    return all(0x20 <= ord(ch) <= 0x7E for ch in text)
+
+
+def _is_int(value) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+@dataclass(frozen=True)
+class PreparedPermutation:
+    enabled: bool
+    key_id: str = ""
+    key_bytes: bytes = b""
+    rounds: int = 8
+
+
+@dataclass(frozen=True)
+class PreparedProfile:
+    """Validated profile with derived case-normalized values."""
+
+    profile_id: str
+    body_alphabet_norm: str
+    checksum_alphabet_norm: str
+    body_length: int
+    checksum_length: int
+    case_sensitive: bool
+    separator: str
+    grouping: tuple
+    aliases_norm: dict
+    permutation: PreparedPermutation
+    checksum_modulus: int
+    capacity: int
+    blocklist: tuple
+
+
+def _norm(case_sensitive: bool, ch: str) -> str:
+    return ch if case_sensitive else ch.upper()
+
+
+def prepare_profile(profile) -> PreparedProfile:
+    """Validate a profile dict per spec 2.2. Raises BasehError INVALID_PROFILE."""
+    if not isinstance(profile, dict):
+        _fail("profile is required")
+
+    profile_id = profile.get("profileId")
+    if not isinstance(profile_id, str) or len(profile_id) == 0:
+        _fail("profileId must be non-empty")
+    if not _is_ascii(profile_id):
+        _fail("profileId must be ASCII")
+
+    case_sensitive = profile.get("caseSensitive") is True
+
+    body_alphabet = profile.get("bodyAlphabet")
+    if not isinstance(body_alphabet, str) or len(body_alphabet) < 2:
+        _fail("bodyAlphabet needs at least two symbols")
+    for ch in body_alphabet:
+        if not _is_ascii_char(ch):
+            _fail(f"body alphabet symbol is not single ASCII: {ch!r}")
+    body_norm = "".join(_norm(case_sensitive, ch) for ch in body_alphabet)
+    if len(set(body_norm)) != len(body_norm):
+        _fail("body alphabet symbols must be unique after case normalization")
+
+    body_length = profile.get("bodyLength")
+    if not _is_int(body_length) or body_length < 1 or body_length > 32:
+        _fail("bodyLength must be an integer from 1 through 32")
+
+    checksum_length = profile.get("checksumLength")
+    if not _is_int(checksum_length) or checksum_length < 0 or checksum_length > 8:
+        _fail("checksumLength must be an integer from 0 through 8")
+
+    checksum_alphabet = profile.get("checksumAlphabet") or ""
+    if not isinstance(checksum_alphabet, str):
+        _fail("checksumAlphabet must be a string")
+    if checksum_length > 0:
+        if len(checksum_alphabet) < 2:
+            _fail("checksumAlphabet needs at least two symbols when checksumLength is positive")
+        for ch in checksum_alphabet:
+            if not _is_ascii_char(ch):
+                _fail(f"checksum alphabet symbol is not single ASCII: {ch!r}")
+    checksum_norm = "".join(_norm(case_sensitive, ch) for ch in checksum_alphabet)
+    if len(set(checksum_norm)) != len(checksum_norm):
+        _fail("checksum alphabet symbols must be unique after case normalization")
+
+    # Spec 18. no-vowels strips vowels before every downstream rule; blocklist
+    # only arms the encode-time scan.
+    profanity = profile.get("profanity") or {"mode": "none"}
+    if not isinstance(profanity, dict) or profanity.get("mode") not in (
+        "none",
+        "no-vowels",
+        "blocklist",
+    ):
+        _fail("profanity mode must be none, no-vowels or blocklist")
+    if profanity["mode"] == "no-vowels":
+        body_norm = strip_vowels(body_norm)
+        checksum_norm = strip_vowels(checksum_norm)
+        if len(body_norm) < 2:
+            _fail("no-vowels mode leaves the body alphabet with fewer than two symbols")
+        if checksum_length > 0 and len(checksum_norm) < 2:
+            _fail("no-vowels mode leaves the checksum alphabet with fewer than two symbols")
+    blocklist = (
+        effective_blocklist(profanity) if profanity["mode"] == "blocklist" else []
+    )
+
+    separator = profile.get("separator") or ""
+    if not isinstance(separator, str):
+        _fail("separator must be a string")
+    for ch in separator:
+        if ch in body_norm or ch in checksum_norm:
+            _fail("separator must not occur in either alphabet")
+
+    aliases = profile.get("aliases") or {}
+    if not isinstance(aliases, dict):
+        _fail("aliases must be a mapping")
+    aliases_norm: dict = {}
+    canonical_set = set(body_norm) | set(checksum_norm)
+    for src, tgt in aliases.items():
+        if not isinstance(src, str) or not _is_ascii_char(src):
+            _fail(f"alias source is not single ASCII: {src!r}")
+        if not isinstance(tgt, str) or not _is_ascii_char(tgt):
+            _fail(f"alias target is not single ASCII: {tgt!r}")
+        s_norm = _norm(case_sensitive, src)
+        t_norm = _norm(case_sensitive, tgt)
+        if s_norm in canonical_set:
+            _fail(f"alias source {src!r} is already a canonical symbol")
+        if t_norm not in canonical_set:
+            _fail(f"alias target {tgt!r} is not a canonical symbol")
+        if s_norm in aliases_norm:
+            _fail(f"duplicate alias source {s_norm!r} after case normalization")
+        if any(_norm(case_sensitive, key) == t_norm for key in aliases):
+            _fail(f"alias chain forbidden: target {t_norm} is also an alias source")
+        aliases_norm[s_norm] = t_norm
+
+    grouping = profile.get("grouping")
+    if not isinstance(grouping, (list, tuple)):
+        _fail("grouping must be empty when separator is empty")
+    if separator == "":
+        if len(grouping) != 0:
+            _fail("grouping must be empty when separator is empty")
+    else:
+        group_sum = 0
+        for g in grouping:
+            if not _is_int(g) or g < 1:
+                _fail("group sizes must sum to bodyLength + checksumLength")
+            group_sum += g
+        if group_sum != body_length + checksum_length:
+            _fail("group sizes must sum to bodyLength + checksumLength")
+
+    permutation = profile.get("permutation") or {"enabled": False}
+    if not isinstance(permutation, dict):
+        _fail("permutation must be a mapping")
+    if permutation.get("enabled"):
+        if permutation.get("algorithm") != "feistel-v1":
+            _fail("unknown permutation algorithm")
+        key_id = permutation.get("keyId")
+        if not isinstance(key_id, str) or len(key_id) == 0:
+            _fail("permutation requires a keyId")
+        key_bytes = permutation.get("keyBytes")
+        if not isinstance(key_bytes, (bytes, bytearray)) or len(key_bytes) == 0:
+            _fail("permutation requires key material")
+        rounds = permutation.get("rounds")
+        if not _is_int(rounds) or rounds < 4 or rounds > 16 or rounds % 2 != 0:
+            _fail("Feistel rounds must be an even integer from 4 through 16")
+        perm = PreparedPermutation(
+            enabled=True,
+            key_id=key_id,
+            key_bytes=bytes(key_bytes),
+            rounds=rounds,
+        )
+    else:
+        perm = PreparedPermutation(enabled=False)
+
+    modulus_base = len(checksum_norm) if checksum_norm else 1
+    return PreparedProfile(
+        profile_id=profile_id,
+        body_alphabet_norm=body_norm,
+        checksum_alphabet_norm=checksum_norm,
+        body_length=body_length,
+        checksum_length=checksum_length,
+        case_sensitive=case_sensitive,
+        separator=separator,
+        grouping=tuple(grouping),
+        aliases_norm=aliases_norm,
+        permutation=perm,
+        checksum_modulus=modulus_base ** checksum_length,
+        capacity=len(body_norm) ** body_length,
+        blocklist=tuple(blocklist),
+    )

baseh/profiles.py

@@ -0,0 +1,146 @@
+"""Frozen profile tiers, spec section 17.
+
+Four tiers built from the full alphanumeric set with cumulative visual and
+spoken strips:
+
+    Minimum  36 symbols, no checksum           2,176,782,336 ids
+    Light    31 symbols, 1 checksum              887,503,681 ids
+    Medium   28 symbols, 1 checksum              481,890,304 ids (default)
+    Heavy    26 symbols, 1 checksum              308,915,776 ids
+
+All four are 6 body symbols, case-insensitive, run the default profanity
+blocklist and keep the typed O/I/L aliases where possible. Minimum also
+uses a hyphen delimiter; the rest have none. The _p variants are identical
+but enable feistel-v1 permutation and require caller-supplied key material.
+
+Each helper returns a freshly-built mutable profile dict on every call, so
+callers can load a default and modify it.
+"""
+
+from __future__ import annotations
+
+_OIL_ALIASES = {"O": "0", "I": "1", "L": "1"}
+
+_TIERS = {
+    "minimum": {
+        "profileId": "baseh-minimum",
+        "bodyAlphabet": "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+        "checksumAlphabet": "",
+        "checksumLength": 0,
+        "separator": "-",
+        "grouping": [3, 3],
+        "aliases": {},
+    },
+    "light": {
+        "profileId": "baseh-light",
+        "bodyAlphabet": "0123456789ABCEFGHJKMNPQRSUVWXYZ",
+        "checksumAlphabet": "234679ACEFGHJKMNPQRUVWXY",
+        "checksumLength": 1,
+        "separator": "",
+        "grouping": [],
+        "aliases": {**_OIL_ALIASES, "D": "B", "T": "P"},
+    },
+    "medium": {
+        "profileId": "baseh-medium",
+        "bodyAlphabet": "0123456789ACDEFGHJKMPQRUVXYZ",
+        "checksumAlphabet": "234679ACDEFGHJKMPQRUVXY",
+        "checksumLength": 1,
+        "separator": "",
+        "grouping": [],
+        # B and S are dropped for looking like 8 and 5; since they can never
+        # be issued, a typed B is always an 8 and a typed S always a 5.
+        "aliases": {**_OIL_ALIASES, "B": "8", "S": "5", "T": "P", "N": "M", "W": "V"},
+    },
+    "heavy": {
+        "profileId": "baseh-heavy",
+        "bodyAlphabet": "0123456789ABCEFHJKMPQRVXYZ",
+        "checksumAlphabet": "234679ACEFHJKMPQRUVXY",
+        "checksumLength": 1,
+        "separator": "",
+        "grouping": [],
+        "aliases": {
+            **_OIL_ALIASES,
+            "D": "B",
+            "T": "P",
+            "N": "M",
+            "W": "V",
+            "S": "F",
+            "G": "C",
+        },
+    },
+}
+
+
+def _tier(name: str, permutation: dict, p_suffix: bool) -> dict:
+    shape = _TIERS[name]
+    return {
+        "profileId": shape["profileId"] + ("-p" if p_suffix else "") + "-v1",
+        "bodyAlphabet": shape["bodyAlphabet"],
+        "bodyLength": 6,
+        "checksumAlphabet": shape["checksumAlphabet"],
+        "checksumLength": shape["checksumLength"],
+        "caseSensitive": False,
+        "separator": shape["separator"],
+        "grouping": list(shape["grouping"]),
+        "aliases": dict(shape["aliases"]),
+        "permutation": permutation,
+        "profanity": {"mode": "blocklist"},
+    }
+
+
+def _keyed_permutation(key_bytes: bytes, key_id: str, rounds: int) -> dict:
+    return {
+        "enabled": True,
+        "algorithm": "feistel-v1",
+        "keyId": key_id,
+        "keyBytes": bytes(key_bytes),
+        "rounds": rounds,
+    }
+
+
+def baseh_minimum_v1() -> dict:
+    """Alphanumeric, no safety strips, no checksum, hyphen-delimited XXX-XXX."""
+    return _tier("minimum", {"enabled": False}, False)
+
+
+def baseh_minimum_p_v1(
+    key_bytes: bytes, key_id: str = "default", rounds: int = 8
+) -> dict:
+    """baseh-minimum with feistel-v1 permutation."""
+    return _tier("minimum", _keyed_permutation(key_bytes, key_id, rounds), True)
+
+
+def baseh_light_v1() -> dict:
+    """Visual light plus spoken light, one checksum symbol."""
+    return _tier("light", {"enabled": False}, False)
+
+
+def baseh_light_p_v1(
+    key_bytes: bytes, key_id: str = "default", rounds: int = 8
+) -> dict:
+    """baseh-light with feistel-v1 permutation."""
+    return _tier("light", _keyed_permutation(key_bytes, key_id, rounds), True)
+
+
+def baseh_medium_v1() -> dict:
+    """Visual medium plus spoken medium, one checksum symbol. The default."""
+    return _tier("medium", {"enabled": False}, False)
+
+
+def baseh_medium_p_v1(
+    key_bytes: bytes, key_id: str = "default", rounds: int = 8
+) -> dict:
+    """baseh-medium with feistel-v1 permutation."""
+    return _tier("medium", _keyed_permutation(key_bytes, key_id, rounds), True)
+
+
+def baseh_heavy_v1() -> dict:
+    """Conservative alphabet plus spoken heavy, one checksum symbol."""
+    return _tier("heavy", {"enabled": False}, False)
+
+
+def baseh_heavy_p_v1(
+    key_bytes: bytes, key_id: str = "default", rounds: int = 8
+) -> dict:
+    """baseh-heavy with feistel-v1 permutation."""
+    return _tier("heavy", _keyed_permutation(key_bytes, key_id, rounds), True)

baseh/zero.py

@@ -0,0 +1,52 @@
+"""Zero-config pair over the frozen baseh-medium-v1 profile.
+
+No profile object, no key: just the two functions an application needs
+when it does not want to think about configuration.
+
+    to_code(id)    -> "7KM4Q2H"
+    from_code(code) -> id
+
+to_code accepts an int or a decimal string of digits. from_code strips
+every whitespace character (edges and internal), accepts lowercase and
+the typed aliases (O, I, L) and returns the id as an int. Any invalid
+input raises BasehError, including the rare BLOCKED_CODE identifiers
+that spell a blocklisted word; no correction attempts are ever made.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .codec import Baseh
+from .profiles import baseh_medium_v1
+
+_DECIMAL = re.compile(r"^[0-9]+$")
+_WHITESPACE = re.compile(r"\s+")
+
+_ZERO = Baseh(baseh_medium_v1())
+
+
+def _to_int(id: object) -> int:
+    if isinstance(id, bool):
+        raise TypeError(
+            "to_code expects a non-negative int or a decimal string"
+        )
+    if isinstance(id, int):
+        if id < 0:
+            raise ValueError("to_code expects a non-negative id")
+        return id
+    if isinstance(id, str) and _DECIMAL.match(id):
+        return int(id)
+    raise TypeError("to_code expects a non-negative int or a decimal string")
+
+
+def to_code(id: object) -> str:
+    """Encode an identifier with the zero-config Medium profile."""
+    return _ZERO.encode(_to_int(id))
+
+
+def from_code(code: str) -> int:
+    """Decode a code from the zero-config Medium profile back to its id."""
+    if not isinstance(code, str):
+        raise TypeError("from_code expects a string")
+    return _ZERO.decode(_WHITESPACE.sub("", code)).id

baseh-1.1.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: baseh
+Version: 1.1.0
+Summary: baseH codec: checksumed, optionally permuted human-readable identifiers
+License: AGPL-3.0-only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# baseh
+
+Python implementation of the baseH codec. Encodes an internal integer ID as
+a checksummed, optionally permuted human-readable reference code. Implements
+the normative spec in `../spec/IMPLEMENTATION_CODEC.md` and passes the
+frozen cross-language vectors in `../vectors/`.
+
+Zero runtime dependencies. HMAC-SHA-256 comes from the standard library.
+
+## Install
+
+```bash
+pip install ./python
+```
+
+Or run in place without installing:
+
+```bash
+PYTHONPATH=python/src python3 -c "import baseh"
+```
+
+## Usage
+
+```python
+from baseh import Baseh, BasehError, baseh_medium_v1
+
+codec = Baseh(baseh_medium_v1())
+
+code = codec.encode(123456789)
+print(code)                       # fixed-length, checksummed code
+
+result = codec.decode(code.lower())  # case-insensitive
+print(result.id)                  # 123456789
+print(result.canonical_code)      # canonical rendering
+print(result.corrected)           # False (input differed only in case)
+
+# Assisted correction over spoken-confusion pairs (B/D, P/T, ...):
+fixed = codec.decode(
+    code,
+    try_correction=True,
+    confusion_profile="light",
+)
+
+# Non-throwing validation for user input:
+check = codec.validate("0000000")
+print(check)                      # {"valid": False, "reason": "INVALID_CHECKSUM"}
+
+print(codec.capacity())           # 481890304
+```
+
+Errors raise `BasehError` with a `.code` attribute, one of:
+`INVALID_PROFILE`, `OUT_OF_RANGE`, `PERMUTATION_FAILURE`, `INVALID_LENGTH`,
+`INVALID_CHARACTER`, `INVALID_CHECKSUM`, `AMBIGUOUS_INPUT`,
+`TOO_MANY_CANDIDATES`, `BLOCKED_CODE`.
+
+## Frozen tiers
+
+Four frozen profiles, each 6 body symbols and case-insensitive, built from
+the full alphanumeric set with cumulative visual and spoken strips:
+
+| Tier | Helper | Symbols | Checksum | Capacity |
+|------|--------|---------|----------|----------|
+| Minimum | `baseh_minimum_v1()` | 36 | none | 2,176,782,336 |
+| Light | `baseh_light_v1()` | 31 | 1 | 887,503,681 |
+| Medium | `baseh_medium_v1()` | 28 | 1 | 481,890,304 |
+| Heavy | `baseh_heavy_v1()` | 26 | 1 | 308,915,776 |
+
+Medium is the default. All four keep the typed O/I/L aliases where possible
+and run the default profanity blocklist. Minimum also uses a hyphen
+delimiter (`XXX-XXX`); the rest have none.
+
+Each helper returns a freshly-built mutable profile dict on every call, so
+callers can load a default and modify it:
+
+```python
+profile = baseh_medium_v1()
+profile["checksumLength"] = 2
+codec = Baseh(profile)
+```
+
+### Permuted variants
+
+The `_p` variants are identical to their tier but enable feistel-v1
+permutation and require caller-supplied key material:
+
+```python
+from baseh import Baseh, baseh_medium_p_v1
+
+key = bytes.fromhex("746573742d6f6e6c792d6b65792d6d6174657269616c2d30303031")
+codec = Baseh(baseh_medium_p_v1(key, key_id="my-app-01"))  # rounds defaults to 8
+```
+
+Available as `baseh_minimum_p_v1`, `baseh_light_p_v1`, `baseh_medium_p_v1`
+and `baseh_heavy_p_v1`.
+
+## Profanity safety (spec 18)
+
+All frozen tiers run the default blocklist. Profiles accept a `profanity`
+field to change that:
+
+```python
+# Block specific words (substrings of the raw code) at encode time:
+profile = baseh_medium_v1()
+profile["profanity"] = {"mode": "blocklist", "extraWords": ["QQQQ"]}
+codec = Baseh(profile)
+# codec.encode(id) raises BasehError(code="BLOCKED_CODE") on a match.
+
+# Or remove vowels from both alphabets entirely:
+profile["profanity"] = {"mode": "no-vowels"}
+```
+
+## Tests
+
+```bash
+cd python
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```

baseh-1.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+baseh/__init__.py,sha256=xCvcyAFBCJheYW4EaB1CDxpgp19P8X7RRDQz7b-BuSk,1450
+baseh/basen.py,sha256=C7Uy9zy-nUu7DndzbN4-1BDOQn7d8fVTYWFq8hA5O_E,1152
+baseh/blocklist.py,sha256=10-PPRNseYj_8LCbnyN4Ol4k9nP-oHr3rEb8G2c1xBk,1373
+baseh/checksum.py,sha256=fU2zlu1eRTRGVFRs-dF_vK5Geby1y4Q6U8-Mrd54e64,1324
+baseh/codec.py,sha256=n1_ym6NQzLsMQtvXMWRstuyHmsYYAGzZ9k0xt7kZJbM,9299
+baseh/errors.py,sha256=qCeUAj3qGD5c05M2-kib4LJvK5H8mraO51i_dwPxKl0,1070
+baseh/feistel.py,sha256=2z2-0p7QFFGJ2Pc66Wr1F6--7MJ314qhS4wp9GK149M,3365
+baseh/profile.py,sha256=WQkLOB5MGVfbLbdNdWg2ng4mkrTmiLS-4czrEhLHydk,7961
+baseh/profiles.py,sha256=hYYX3FWycKwMzwPIoUp0rcX07Z0sS3qX3vCnFU-OuJY,4827
+baseh/zero.py,sha256=7D2yoWoHL-vCJjF4OdxOwHpgCShr2bpyZgusd3e4vm4,1655
+baseh-1.1.0.dist-info/METADATA,sha256=fUS2eFLmP2avQLSzj-POcLljP4DfkjjLowLQxlv7zXg,3700
+baseh-1.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+baseh-1.1.0.dist-info/top_level.txt,sha256=heWKFtH7f_7c9iEqeekm2zkwa3fsVdSIPzAIX1uyarI,6
+baseh-1.1.0.dist-info/RECORD,,

baseh-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

baseh-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+baseh