baseh 2.0.4

baseH codec: fixed-length, checksummed, optionally permuted human-readable identifiers
Documentation

baseh

Rust implementation of the baseH codec: checksummed, optionally permuted human-readable identifiers for internal integer IDs. Codes are expandable by default — they start short and grow as the id sequence climbs — with fixed-length tiers available for constant-width needs. The normative specification is ../spec/IMPLEMENTATION_CODEC.md and cross-language conformance vectors live in ../vectors/.

Usage

Expandable mode is the recommended default for new users: codes start at 4 characters and grow one character at a time as ids climb past each length's capacity — transparently, with no migration and no re-issue. Old shorter codes keep decoding forever.

use baseh::{baseh_expandable_v1, Baseh, DecodeOptions};
use num_bigint::BigUint;

let baseh = Baseh::new(baseh_expandable_v1())?;

let code = baseh.encode(&BigUint::from(48_284_291u64))?;
// a few characters long at this namespace size; grows as ids climb.
let result = baseh.decode(&code, &DecodeOptions::default())?;
assert_eq!(result.id, BigUint::from(48_284_291u64));
# Ok::<(), baseh::BasehError>(())

The expandable body alphabet applies the medium visual and spoken safety strips and the 0/O zero ban (27 symbols by default; any 0/O in a custom alphabet are silently removed during profile preparation). The checksum alphabet adds 0 back (28 symbols), and the existing O -> 0 input alias still repairs a misread checksum character. There is no left-padding, the Feistel permutation stays on (applied per code length, so codes within each length look random even though issuance is sequential), and separators only appear once codes reach separator_min_length (6 in the shipped tier). All existing profile options — visual/spoken safety levels, profanity modes, blocklists — compose with expandable unchanged. For private scrambling use baseh_expandable_p_v1 with your own key material, exactly like the fixed *_p_v1 tiers below.

For validation, spoken-typo correction and the rest of the codec surface see the fixed-mode example below and the API summary; they work identically in expandable mode. Security posture is unchanged: a code is a reference alias, never an authorization token — expandable codes in the smallest generations are a small namespace, so rate-limit public lookups and enforce authorization after decode.

Fixed mode

Fixed mode keeps codes at one constant width, left-padding as today, for layouts that need a stable shape. Medium is the default fixed tier.

use baseh::{baseh_medium_v1, Baseh, ConfusionProfile, DecodeOptions};
use num_bigint::BigUint;

// Medium is the default tier; it permutes with the frozen public key and
// needs no key material.
let baseh = Baseh::new(baseh_medium_v1())?;

let code = baseh.encode(&BigUint::from(48_284_291u64))?;
let result = baseh.decode(&code, &DecodeOptions::default())?;
assert_eq!(result.id, BigUint::from(48_284_291u64));
assert!(!result.corrected);

// Validation without a returned id (for customer-facing checks).
let outcome = baseh.validate("vcs pq2 g", &DecodeOptions {
    accept_spaces: true,
    ..DecodeOptions::default()
});

// Spoken-confusion correction after a checksum failure: here a G misheard
// as a C is repaired and the amended canonical code is returned.
let fixed = baseh.decode("MGV3-JKDJ", &DecodeOptions {
    try_correction: true,
    confusion_profile: ConfusionProfile::Heavy,
    max_corrections: 1,
    ..DecodeOptions::default()
});
assert_eq!(fixed?.canonical_code, "MCV3-JKDJ");
# Ok::<(), baseh::BasehError>(())

Frozen tiers

All frozen tiers below are mode: "fixed" and behave exactly as they always have. Four frozen tiers trade alphabet safety for capacity. All are 6 body symbols, case-insensitive, hyphen-delimited at the midpoint, run the default profanity blocklist and keep the typed O/I/L aliases where possible. Medium is the default fixed tier.

Tier Symbols Checksums Shape Capacity
baseh_minimum_v1 36 0 XXX-XXX 2,176,782,336
baseh_light_v1 31 2 XXXX-XXXX 887,503,681
baseh_medium_v1 28 2 XXXX-XXXX 481,890,304
baseh_heavy_v1 26 2 XXXX-XXXX 308,915,776

Every helper returns a freshly-built profile value, so callers can load a default and modify it before constructing the codec.

Permutation (always on, frozen key)

Every plain tier permutes with feistel-v1 under the frozen published key FROZEN_KEY_BYTES (key id "frozen", 8 rounds). The key is public by design: it makes issued codes look non-sequential but offers no secrecy, since anyone can read it here. Never swap it on a live namespace; codes only decode with the key they were issued under.

For private scrambling use the *_p_v1 variants and supply your own key material, key id and round count (pass an empty key id or 0 rounds for the defaults "default" and 8). Keep both immutable for the life of the profile and out of frontend code.

use baseh::{baseh_medium_p_v1, Baseh};
# fn f() -> Result<(), baseh::BasehError> {
let baseh = Baseh::new(baseh_medium_p_v1(b"application-key-material", "app-key-1", 8))?;
# Ok(())
# }

Profanity safety (spec 18)

Profiles accept an optional profanity object with three modes:

  • None (default): no filtering.
  • NoVowels: strips A E I O U from both alphabets before any other profile-derived computation. Capacity, checksums and every downstream rule then run on the stripped alphabets.
  • Blocklist: the encoder refuses (new error BLOCKED_CODE) any code whose raw string contains a blocked substring. words replaces the small built-in default list and extra_words appends to it. Decode may also raise BLOCKED_CODE, since a blocked code could never have been issued.

API summary

  • Baseh::new(profile) validates the profile once (specs 2.2 and 18).
  • encode(&BigUint) -> Result<String, BasehError>.
  • decode(&str, &DecodeOptions) -> Result<DecodeResult, BasehError> returning the id, the canonical code and a corrected flag.
  • capacity() -> Result<&BigUint, BasehError> (arbitrary precision, may exceed u64). Fixed mode only; expandable profiles fail INVALID_PROFILE.
  • validate(input, options) -> ValidateOutcome never fails on user input and never exposes an internal id on failure.
  • inspect(input) -> InspectResult (spec 12.5) gives live as-you-type feedback: an enum with per-state variants (Empty, Typing { typed, progress }, BadChar, TooLong, Invalid { reason }, Valid { id, canonical_code }); InspectResult::state() renders the cross-language state name. It never panics on user input and never reports Valid for an incomplete code. baseh::inspect applies it to the default profile.
  • baseh_expandable_v1 builds the recommended expandable tier profile (mode: "expandable", min_length 4, separator_min_length 6), permuting per code length with the public frozen key; baseh_expandable_p_v1 takes caller-supplied key material instead. min_length is an Option<usize>: None selects the default of 4 and an explicit Some(0) is rejected.
  • baseh_minimum_v1 / baseh_light_v1 / baseh_medium_v1 / baseh_heavy_v1 build the frozen fixed-mode tier profiles, each permuting with the public frozen key. The *_p_v1 variants permute with caller-supplied key material instead.
  • feistel::permute / feistel::inverse_permute are public for conformance testing against ../vectors/feistel-vectors.json.

Errors

Every fallible call returns BasehError { code, message, safe_for_customer }. code.to_string() renders the serialized spec form (INVALID_CHECKSUM and so on). safe_for_customer marks messages that may be shown to end users unchanged; BLOCKED_CODE is never customer-safe since it is an issuance decision. Applications should advance their sequence by one and re-encode.

Testing

cargo test runs:

  • tests/vectors.rs: every frozen encode, decode, error, encode-error, correction, inspect and Feistel vector from ../vectors/, with profiles (including profanity modes) rebuilt from the embedded definitions.
  • tests/inspect.rs: the spec 12.5 state machine in both modes — every state, partial-prefix rendering, aliases while typing and the spec 3.4 padded-prefix false-green case.
  • tests/codec.rs: profile-validation rejections, boundary round trips, normalization, aliases, correction, blocklist and no-vowels behavior, a 10k sequential-id round-trip smoke and a fixed-seed fuzz smoke.

Also gated on cargo clippy --all-targets (clean) and cargo fmt --check.

License

Apache-2.0