@cloudyventures/baseh 1.1.0

package/dist/basen.d.ts

@@ -0,0 +1,5 @@
+/** Spec 5.1. Fixed-length base-N encode, most significant digit first. */
+export declare function encodeBaseN(value: bigint, alphabet: string, length: number): string;
+/** Spec 5.2. */
+export declare function decodeBaseN(text: string, alphabet: string, index: Map<string, bigint>): bigint;
+export declare function alphabetIndex(alphabet: string): Map<string, bigint>;

package/dist/basen.js

@@ -0,0 +1,34 @@
+import { BasehError } from "./errors.js";
+/** Spec 5.1. Fixed-length base-N encode, most significant digit first. */
+export function encodeBaseN(value, alphabet, length) {
+    const base = BigInt(alphabet.length);
+    const out = new Array(length);
+    let v = value;
+    for (let pos = length - 1; pos >= 0; pos -= 1) {
+        const digit = Number(v % base);
+        const ch = alphabet[digit];
+        if (ch === undefined)
+            throw new BasehError("OUT_OF_RANGE", "digit outside alphabet");
+        out[pos] = ch;
+        v = v / base;
+    }
+    return out.join("");
+}
+/** Spec 5.2. */
+export function decodeBaseN(text, alphabet, index) {
+    const base = BigInt(alphabet.length);
+    let value = 0n;
+    for (const ch of text) {
+        const digit = index.get(ch);
+        if (digit === undefined) {
+            throw new BasehError("INVALID_CHARACTER", `Symbol ${JSON.stringify(ch)} is not in the alphabet`);
+        }
+        value = value * base + digit;
+    }
+    return value;
+}
+export function alphabetIndex(alphabet) {
+    const m = new Map();
+    [...alphabet].forEach((ch, i) => m.set(ch, BigInt(i)));
+    return m;
+}

package/dist/blocklist.d.ts

@@ -0,0 +1,15 @@
+export type BasehProfanityMode = "none" | "no-vowels" | "blocklist";
+/** Spec 18. Optional profanity safety configuration. */
+export interface BasehProfanity {
+    mode: BasehProfanityMode;
+    /** Replaces the default list when present (mode "blocklist" only). */
+    words?: string[];
+    /** Appended to the effective list (mode "blocklist" only). */
+    extraWords?: string[];
+}
+/** Spec 18.2 default list. Deliberately small; applications extend it. */
+export declare const DEFAULT_BLOCKLIST: readonly string[];
+/** Spec 18.2: replacement semantics, then augmentation, uppercased and deduplicated. */
+export declare function effectiveBlocklist(profanity: BasehProfanity): string[];
+/** Spec 18.1: vowels removed for no-vowels mode, applied after case normalization. */
+export declare function stripVowels(alphabetNorm: string): string;

package/dist/blocklist.js

@@ -0,0 +1,29 @@
+import { BasehError } from "./errors.js";
+/** Spec 18.2 default list. Deliberately small; applications extend it. */
+export const DEFAULT_BLOCKLIST = [
+    "CRAP", "TWAT", "SHAG", "DAMN", "FCK", "FUC",
+    "SHT", "CNT", "TWT", "DCK", "AZZ", "BCH"
+];
+const WORD = /^[A-Za-z]{2,32}$/;
+function fail(reason) {
+    throw new BasehError("INVALID_PROFILE", `Invalid baseH profile: ${reason}`, false);
+}
+/** Spec 18.2: replacement semantics, then augmentation, uppercased and deduplicated. */
+export function effectiveBlocklist(profanity) {
+    const base = profanity.words ? [...profanity.words] : [...DEFAULT_BLOCKLIST];
+    const list = [...base, ...(profanity.extraWords ?? [])];
+    const out = [];
+    for (const word of list) {
+        if (typeof word !== "string" || !WORD.test(word)) {
+            fail("blocklist entries must be 2 through 32 ASCII letters");
+        }
+        const upper = word.toUpperCase();
+        if (!out.includes(upper))
+            out.push(upper);
+    }
+    return out;
+}
+/** Spec 18.1: vowels removed for no-vowels mode, applied after case normalization. */
+export function stripVowels(alphabetNorm) {
+    return [...alphabetNorm].filter((c) => !"AEIOU".includes(c)).join("");
+}

package/dist/checksum.d.ts

@@ -0,0 +1,8 @@
+import type { PreparedProfile } from "./profile.js";
+/**
+ * Spec 6.2. Rolling polynomial checksum over symbol values.
+ * Returns the checksum value in [0, modulus).
+ */
+export declare function checksumValue(profile: PreparedProfile, body: string, bodyIndex: Map<string, bigint>): bigint;
+/** Compute the expected checksum string for a normalized body. */
+export declare function calculateChecksum(profile: PreparedProfile, body: string): string;

package/dist/checksum.js

@@ -0,0 +1,30 @@
+import { BasehError } from "./errors.js";
+import { alphabetIndex, encodeBaseN } from "./basen.js";
+/**
+ * Spec 6.2. Rolling polynomial checksum over symbol values.
+ * Returns the checksum value in [0, modulus).
+ */
+export function checksumValue(profile, body, bodyIndex) {
+    const modulus = profile.checksumModulus;
+    let state = 17n;
+    for (let i = 0; i < profile.profileId.length; i += 1) {
+        state = (state * 37n + BigInt(profile.profileId.charCodeAt(i)) + 1n) % modulus;
+    }
+    state = (state * 37n) % modulus;
+    for (let pos = 0; pos < body.length; pos += 1) {
+        const symValue = bodyIndex.get(body[pos]);
+        if (symValue === undefined) {
+            throw new BasehError("INVALID_CHARACTER", `Body symbol ${JSON.stringify(body[pos])} is not in the body alphabet`);
+        }
+        state = (state * 37n + symValue + BigInt(pos + 1)) % modulus;
+    }
+    return state;
+}
+/** Compute the expected checksum string for a normalized body. */
+export function calculateChecksum(profile, body) {
+    if (profile.checksumLength === 0)
+        return "";
+    const index = alphabetIndex(profile.bodyAlphabetNorm);
+    const value = checksumValue(profile, body, index);
+    return encodeBaseN(value, profile.checksumAlphabetNorm, profile.checksumLength);
+}

package/dist/codec.d.ts

@@ -0,0 +1,38 @@
+import { type BasehErrorCode } from "./errors.js";
+import { type BasehProfile, type PreparedProfile } from "./profile.js";
+export type ConfusionProfileName = "none" | "light" | "medium" | "heavy";
+/** Built-in spoken-confusion candidate maps. Spec 3.3; pairs apply to body symbols only. */
+export declare const CONFUSION_MAPS: Record<Exclude<ConfusionProfileName, "none">, Record<string, string[]>>;
+export interface DecodeOptions {
+    acceptSpaces?: boolean;
+    tryCorrection?: boolean;
+    confusionProfile?: ConfusionProfileName;
+    maxCorrections?: 0 | 1;
+}
+export interface DecodeResult {
+    id: bigint;
+    canonicalCode: string;
+    corrected: boolean;
+}
+export interface ValidateResult {
+    valid: boolean;
+    canonicalCode?: string;
+    reason?: BasehErrorCode;
+}
+/** Spec 3.1 normalization, steps 1-7. Returns the raw unformatted string. */
+export declare function normalize(input: string, profile: PreparedProfile, acceptSpaces?: boolean): string;
+export declare function formatRaw(raw: string, profile: PreparedProfile): string;
+/** Spec 10. Substitution-only candidate generation, capped and deduplicated. */
+export declare function generateCandidates(body: string, confusionMap: Record<string, string[]>, maxEdits?: number): string[];
+export declare class Baseh {
+    readonly profile: PreparedProfile;
+    private readonly bodyIndex;
+    constructor(profile: BasehProfile);
+    capacity(): bigint;
+    /** Spec 8. */
+    encode(id: bigint | number): string;
+    /** Spec 9. */
+    decode(input: string, options?: DecodeOptions): DecodeResult;
+    /** Spec 12.4. Never throws on user input. */
+    validate(input: string, options?: DecodeOptions): ValidateResult;
+}

package/dist/codec.js

@@ -0,0 +1,185 @@
+import { BasehError } from "./errors.js";
+import { decodeBaseN, encodeBaseN, alphabetIndex } from "./basen.js";
+import { calculateChecksum } from "./checksum.js";
+import { inversePermute, permute } from "./feistel.js";
+import { prepareProfile } from "./profile.js";
+/** Built-in spoken-confusion candidate maps. Spec 3.3; pairs apply to body symbols only. */
+export const 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"]
+    }
+};
+const ASCII_WS = /^[\t\n\v\f\r ]+|[\t\n\v\f\r ]+$/g;
+const MAX_CANDIDATES = 64;
+/** Spec 3.1 normalization, steps 1-7. Returns the raw unformatted string. */
+export function normalize(input, profile, acceptSpaces = false) {
+    let s = input.replace(ASCII_WS, "");
+    if (profile.separator.length > 0) {
+        s = s.split(profile.separator).join("");
+    }
+    if (acceptSpaces) {
+        s = s.replace(/ /g, "");
+    }
+    if (!profile.caseSensitive) {
+        s = s.toUpperCase();
+    }
+    s = [...s].map((ch) => profile.aliasesNorm[ch] ?? ch).join("");
+    const allowed = new Set([...profile.bodyAlphabetNorm, ...profile.checksumAlphabetNorm]);
+    for (const ch of s) {
+        if (!allowed.has(ch)) {
+            throw new BasehError("INVALID_CHARACTER", `Symbol ${JSON.stringify(ch)} is not accepted`);
+        }
+    }
+    const expected = profile.bodyLength + profile.checksumLength;
+    // 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 (s.length < expected && s.length >= Math.max(profile.checksumLength, 1)) {
+        const zero = profile.bodyAlphabetNorm[0];
+        s = zero.repeat(expected - s.length) + s;
+    }
+    if (s.length !== expected) {
+        throw new BasehError("INVALID_LENGTH", `Expected ${expected} symbols, got ${s.length}`);
+    }
+    return s;
+}
+export function formatRaw(raw, profile) {
+    if (profile.separator.length === 0)
+        return raw;
+    const parts = [];
+    let o = 0;
+    for (const size of profile.grouping) {
+        parts.push(raw.slice(o, o + size));
+        o += size;
+    }
+    return parts.join(profile.separator);
+}
+/** Spec 10. Substitution-only candidate generation, capped and deduplicated. */
+export function generateCandidates(body, confusionMap, maxEdits = 1) {
+    if (maxEdits === 0)
+        return [];
+    const results = new Set();
+    const chars = [...body];
+    for (let pos = 0; pos < chars.length; pos += 1) {
+        const source = chars[pos];
+        for (const replacement of confusionMap[source] ?? []) {
+            const candidate = [...chars];
+            candidate[pos] = replacement;
+            results.add(candidate.join(""));
+            if (results.size > MAX_CANDIDATES) {
+                throw new BasehError("TOO_MANY_CANDIDATES", "Candidate generation exceeded 64 entries", false);
+            }
+        }
+    }
+    return [...results];
+}
+export class Baseh {
+    profile;
+    bodyIndex;
+    constructor(profile) {
+        this.profile = prepareProfile(profile);
+        this.bodyIndex = alphabetIndex(this.profile.bodyAlphabetNorm);
+    }
+    capacity() {
+        return this.profile.capacity;
+    }
+    /** Spec 8. */
+    encode(id) {
+        let value = BigInt(id);
+        if (value < 0n || value >= this.profile.capacity) {
+            throw new BasehError("OUT_OF_RANGE", `ID ${value} is outside the profile capacity`);
+        }
+        const perm = this.profile.permutation;
+        if (perm.enabled) {
+            value = permute(value, this.profile.capacity, {
+                profileId: this.profile.profileId,
+                keyBytes: perm.keyBytes,
+                rounds: perm.rounds
+            });
+        }
+        const body = encodeBaseN(value, this.profile.bodyAlphabetNorm, this.profile.bodyLength);
+        const checksum = calculateChecksum(this.profile, body);
+        const raw = body + checksum;
+        // Spec 18.2: case-insensitive substring scan over the raw code.
+        if (this.profile.blocklist.length > 0) {
+            const upper = raw.toUpperCase();
+            for (const word of this.profile.blocklist) {
+                if (upper.includes(word)) {
+                    throw new BasehError("BLOCKED_CODE", "The generated reference contains a blocked substring", false);
+                }
+            }
+        }
+        return formatRaw(raw, this.profile);
+    }
+    /** Spec 9. */
+    decode(input, options = {}) {
+        const raw = normalize(input, this.profile, options.acceptSpaces === true);
+        let body = raw.slice(0, this.profile.bodyLength);
+        const suppliedChecksum = raw.slice(this.profile.bodyLength);
+        // Spec 3.1 validates union membership before the split. There is no
+        // per-region membership check: a checksum-region symbol outside the
+        // checksum alphabet simply fails as INVALID_CHECKSUM, and a body symbol
+        // outside the body alphabet fails later in decodeBaseN as INVALID_CHARACTER.
+        if (calculateChecksum(this.profile, body) !== suppliedChecksum) {
+            if (!options.tryCorrection || (options.maxCorrections ?? 1) === 0) {
+                throw new BasehError("INVALID_CHECKSUM", "The reference code did not pass validation");
+            }
+            const mapName = options.confusionProfile ?? "none";
+            // 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 throw
+            // INVALID_CHARACTER from the checksum step instead of reporting an
+            // honest INVALID_CHECKSUM.
+            const bodySet = new Set(this.profile.bodyAlphabetNorm);
+            const rawMap = mapName === "none" ? {} : CONFUSION_MAPS[mapName];
+            const map = {};
+            for (const [source, replacements] of Object.entries(rawMap)) {
+                const kept = replacements.filter((r) => bodySet.has(r));
+                if (kept.length > 0)
+                    map[source] = kept;
+            }
+            const valid = new Set();
+            for (const candidate of generateCandidates(body, map, options.maxCorrections ?? 1)) {
+                if (calculateChecksum(this.profile, candidate) === suppliedChecksum) {
+                    valid.add(candidate);
+                }
+            }
+            if (valid.size === 0) {
+                throw new BasehError("INVALID_CHECKSUM", "The reference code did not pass validation");
+            }
+            if (valid.size > 1) {
+                throw new BasehError("AMBIGUOUS_INPUT", "The reference code matches more than one record", false);
+            }
+            body = [...valid][0];
+        }
+        let value = decodeBaseN(body, this.profile.bodyAlphabetNorm, this.bodyIndex);
+        const perm = this.profile.permutation;
+        if (perm.enabled) {
+            value = inversePermute(value, this.profile.capacity, {
+                profileId: this.profile.profileId,
+                keyBytes: perm.keyBytes,
+                rounds: perm.rounds
+            });
+        }
+        const canonicalCode = this.encode(value);
+        const canonicalRaw = canonicalCode.split(this.profile.separator).join("");
+        return { id: value, canonicalCode, corrected: raw !== canonicalRaw };
+    }
+    /** Spec 12.4. Never throws on user input. */
+    validate(input, options = {}) {
+        try {
+            const result = this.decode(input, options);
+            return { valid: true, canonicalCode: result.canonicalCode };
+        }
+        catch (err) {
+            if (err instanceof BasehError)
+                return { valid: false, reason: err.code };
+            throw err;
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+/** Error codes defined by the baseH codec specification. */
+export type BasehErrorCode = "INVALID_PROFILE" | "OUT_OF_RANGE" | "PERMUTATION_FAILURE" | "INVALID_LENGTH" | "INVALID_CHARACTER" | "INVALID_CHECKSUM" | "AMBIGUOUS_INPUT" | "TOO_MANY_CANDIDATES" | "BLOCKED_CODE";
+export declare class BasehError extends Error {
+    readonly code: BasehErrorCode;
+    /** True when the message may be shown to an end user unchanged. */
+    readonly safeForCustomer: boolean;
+    constructor(code: BasehErrorCode, message: string, safeForCustomer?: boolean);
+}

package/dist/errors.js

@@ -0,0 +1,11 @@
+export class BasehError extends Error {
+    code;
+    /** True when the message may be shown to an end user unchanged. */
+    safeForCustomer;
+    constructor(code, message, safeForCustomer = true) {
+        super(message);
+        this.name = "BasehError";
+        this.code = code;
+        this.safeForCustomer = safeForCustomer;
+    }
+}

package/dist/feistel.d.ts

@@ -0,0 +1,10 @@
+interface FeistelKey {
+    profileId: string;
+    keyBytes: Uint8Array;
+    rounds: number;
+}
+/** Spec 7.3 forward permutation with cycle walking. */
+export declare function permute(value: bigint, capacity: bigint, key: FeistelKey): bigint;
+/** Spec 7.3 inverse permutation with cycle walking. */
+export declare function inversePermute(value: bigint, capacity: bigint, key: FeistelKey): bigint;
+export {};

package/dist/feistel.js

@@ -0,0 +1,108 @@
+import { hmac } from "@noble/hashes/hmac";
+import { sha256 } from "@noble/hashes/sha256";
+import { BasehError } from "./errors.js";
+const TAG = new TextEncoder().encode("BASEH-FEISTEL-V1");
+const MAX_WALKS = 1000;
+function bitLength(capacity) {
+    return (capacity - 1n).toString(2).length;
+}
+/** Low n bits of the HMAC-SHA-256 digest, per spec 7.3. */
+function lowBits(digest, n) {
+    const byteCount = Math.ceil(n / 8);
+    let v = 0n;
+    for (let i = 0; i < byteCount; i += 1) {
+        v = (v << 8n) | BigInt(digest[i]);
+    }
+    return v & ((1n << BigInt(n)) - 1n);
+}
+function toBe(value, byteCount) {
+    const out = new Uint8Array(byteCount);
+    let v = value;
+    for (let i = byteCount - 1; i >= 0; i -= 1) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return out;
+}
+function roundMessage(profileId, round, right, wr) {
+    const pidBytes = new TextEncoder().encode(profileId);
+    const rightBytes = toBe(right, Math.ceil(wr / 8));
+    const msg = new Uint8Array(TAG.length + 1 + pidBytes.length + 1 + 1 + rightBytes.length);
+    let o = 0;
+    msg.set(TAG, o);
+    o += TAG.length;
+    msg[o] = 0;
+    o += 1;
+    msg.set(pidBytes, o);
+    o += pidBytes.length;
+    msg[o] = 0;
+    o += 1;
+    msg[o] = round;
+    o += 1;
+    msg.set(rightBytes, o);
+    return msg;
+}
+function runRounds(h, key, w0, w1) {
+    let { left, right } = h;
+    for (let i = 0; i < key.rounds; i += 1) {
+        const even = i % 2 === 0;
+        const wr = even ? w1 : w0;
+        const wl = even ? w0 : w1;
+        const digest = hmac(sha256, key.keyBytes, roundMessage(key.profileId, i, right, wr));
+        const f = lowBits(digest, wl);
+        const newLeft = right;
+        const newRight = left ^ f;
+        left = newLeft;
+        right = newRight;
+    }
+    return { left, right };
+}
+function runInverse(h, key, w0, w1) {
+    let { left, right } = h;
+    for (let i = key.rounds - 1; i >= 0; i -= 1) {
+        const even = i % 2 === 0;
+        const wr = even ? w1 : w0;
+        const wl = even ? w0 : w1;
+        const digest = hmac(sha256, key.keyBytes, roundMessage(key.profileId, i, left, wr));
+        const f = lowBits(digest, wl);
+        const prevRight = left;
+        const prevLeft = right ^ f;
+        left = prevLeft;
+        right = prevRight;
+    }
+    return { left, right };
+}
+function combine(h, w1) {
+    return (h.left << BigInt(w1)) | h.right;
+}
+function split(value, w1) {
+    return { left: value >> BigInt(w1), right: value & ((1n << BigInt(w1)) - 1n) };
+}
+/** Spec 7.3 forward permutation with cycle walking. */
+export function permute(value, capacity, key) {
+    const bits = bitLength(capacity);
+    const w1 = Math.floor(bits / 2);
+    const w0 = bits - w1;
+    let v = value;
+    for (let walk = 0; walk < MAX_WALKS; walk += 1) {
+        const out = combine(runRounds(split(v, w1), key, w0, w1), w1);
+        if (out < capacity)
+            return out;
+        v = out;
+    }
+    throw new BasehError("PERMUTATION_FAILURE", "Feistel cycle walking exceeded 1000 iterations", false);
+}
+/** Spec 7.3 inverse permutation with cycle walking. */
+export function inversePermute(value, capacity, key) {
+    const bits = bitLength(capacity);
+    const w1 = Math.floor(bits / 2);
+    const w0 = bits - w1;
+    let v = value;
+    for (let walk = 0; walk < MAX_WALKS; walk += 1) {
+        const out = combine(runInverse(split(v, w1), key, w0, w1), w1);
+        if (out < capacity)
+            return out;
+        v = out;
+    }
+    throw new BasehError("PERMUTATION_FAILURE", "Feistel cycle walking exceeded 1000 iterations", false);
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { BasehError } from "./errors.js";
+export type { BasehErrorCode } from "./errors.js";
+export type { BasehProfile, BasehPermutation, PreparedProfile } from "./profile.js";
+export { prepareProfile } from "./profile.js";
+export { Baseh, normalize, formatRaw, generateCandidates, CONFUSION_MAPS } from "./codec.js";
+export type { DecodeOptions, DecodeResult, ValidateResult, ConfusionProfileName } from "./codec.js";
+export { encodeBaseN, decodeBaseN, alphabetIndex } from "./basen.js";
+export { calculateChecksum, checksumValue } from "./checksum.js";
+export { permute, inversePermute } from "./feistel.js";
+export { basehMinimumV1, basehLightV1, basehMediumV1, basehHeavyV1, basehMinimumPV1, basehLightPV1, basehMediumPV1, basehHeavyPV1, type FrozenKeyOptions } from "./profiles.js";
+export { toCode, fromCode } from "./zero.js";
+export { DEFAULT_BLOCKLIST, effectiveBlocklist, stripVowels } from "./blocklist.js";
+export type { BasehProfanity, BasehProfanityMode } from "./blocklist.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { BasehError } from "./errors.js";
+export { prepareProfile } from "./profile.js";
+export { Baseh, normalize, formatRaw, generateCandidates, CONFUSION_MAPS } from "./codec.js";
+export { encodeBaseN, decodeBaseN, alphabetIndex } from "./basen.js";
+export { calculateChecksum, checksumValue } from "./checksum.js";
+export { permute, inversePermute } from "./feistel.js";
+export { basehMinimumV1, basehLightV1, basehMediumV1, basehHeavyV1, basehMinimumPV1, basehLightPV1, basehMediumPV1, basehHeavyPV1 } from "./profiles.js";
+export { toCode, fromCode } from "./zero.js";
+export { DEFAULT_BLOCKLIST, effectiveBlocklist, stripVowels } from "./blocklist.js";

package/dist/profile.d.ts

@@ -0,0 +1,40 @@
+import { type BasehProfanity } from "./blocklist.js";
+export type BasehPermutation = {
+    enabled: false;
+} | {
+    enabled: true;
+    algorithm: "feistel-v1";
+    keyId: string;
+    keyBytes: Uint8Array;
+    rounds: number;
+};
+export interface BasehProfile {
+    profileId: string;
+    bodyAlphabet: string;
+    bodyLength: number;
+    checksumAlphabet: string;
+    checksumLength: number;
+    caseSensitive: boolean;
+    separator: string;
+    grouping: number[];
+    aliases: Record<string, string>;
+    permutation: BasehPermutation;
+    /** Spec 18. Defaults to mode "none". */
+    profanity?: BasehProfanity;
+}
+/** Case-prepared derived data, computed once at construction. */
+export interface PreparedProfile extends BasehProfile {
+    readonly bodyAlphabetNorm: string;
+    readonly checksumAlphabetNorm: string;
+    readonly aliasesNorm: Record<string, string>;
+    readonly checksumModulus: bigint;
+    readonly capacity: bigint;
+    /** Spec 18. Empty unless the profile uses mode "blocklist". */
+    readonly blocklist: string[];
+}
+/**
+ * Validates a profile per spec section 2.2 and returns it with derived,
+ * pre-computed values. Throws BasehError INVALID_PROFILE on any violation.
+ * Call once at construction, never per encode/decode.
+ */
+export declare function prepareProfile(profile: BasehProfile): PreparedProfile;

package/dist/profile.js

@@ -0,0 +1,167 @@
+import { BasehError } from "./errors.js";
+import { effectiveBlocklist, stripVowels } from "./blocklist.js";
+const ASCII_ONLY = /^[\x20-\x7e]*$/;
+function fail(reason) {
+    throw new BasehError("INVALID_PROFILE", `Invalid baseH profile: ${reason}`, false);
+}
+function isAsciiChar(ch) {
+    return ch.length === 1 && ASCII_ONLY.test(ch);
+}
+function norm(profile, ch) {
+    return profile.caseSensitive ? ch : ch.toUpperCase();
+}
+function powBigInt(base, exp) {
+    let result = 1n;
+    for (let i = 0; i < exp; i += 1)
+        result *= base;
+    return result;
+}
+/**
+ * Validates a profile per spec section 2.2 and returns it with derived,
+ * pre-computed values. Throws BasehError INVALID_PROFILE on any violation.
+ * Call once at construction, never per encode/decode.
+ */
+export function prepareProfile(profile) {
+    if (!profile || typeof profile !== "object")
+        fail("profile is required");
+    if (typeof profile.profileId !== "string" || profile.profileId.length === 0) {
+        fail("profileId must be non-empty");
+    }
+    if (!ASCII_ONLY.test(profile.profileId))
+        fail("profileId must be ASCII");
+    const caseSensitive = profile.caseSensitive === true;
+    const bodyAlphabet = profile.bodyAlphabet;
+    if (typeof bodyAlphabet !== "string" || bodyAlphabet.length < 2) {
+        fail("bodyAlphabet needs at least two symbols");
+    }
+    for (const ch of bodyAlphabet) {
+        if (!isAsciiChar(ch))
+            fail(`body alphabet symbol is not single ASCII: ${JSON.stringify(ch)}`);
+    }
+    const view = { caseSensitive };
+    let bodyNorm = [...bodyAlphabet].map((c) => norm(view, c)).join("");
+    if (new Set(bodyNorm).size !== bodyNorm.length) {
+        fail("body alphabet symbols must be unique after case normalization");
+    }
+    if (!Number.isInteger(profile.bodyLength) ||
+        profile.bodyLength < 1 ||
+        profile.bodyLength > 32) {
+        fail("bodyLength must be an integer from 1 through 32");
+    }
+    if (!Number.isInteger(profile.checksumLength) ||
+        profile.checksumLength < 0 ||
+        profile.checksumLength > 8) {
+        fail("checksumLength must be an integer from 0 through 8");
+    }
+    const checksumAlphabet = profile.checksumAlphabet ?? "";
+    if (profile.checksumLength > 0) {
+        if (typeof checksumAlphabet !== "string" || checksumAlphabet.length < 2) {
+            fail("checksumAlphabet needs at least two symbols when checksumLength is positive");
+        }
+        for (const ch of checksumAlphabet) {
+            if (!isAsciiChar(ch))
+                fail(`checksum alphabet symbol is not single ASCII: ${JSON.stringify(ch)}`);
+        }
+    }
+    let checksumNorm = [...checksumAlphabet].map((c) => norm(view, c)).join("");
+    if (new Set(checksumNorm).size !== checksumNorm.length) {
+        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.
+    const profanity = profile.profanity ?? { mode: "none" };
+    if (!["none", "no-vowels", "blocklist"].includes(profanity.mode)) {
+        fail("profanity mode must be none, no-vowels or blocklist");
+    }
+    if (profanity.mode === "no-vowels") {
+        bodyNorm = stripVowels(bodyNorm);
+        checksumNorm = stripVowels(checksumNorm);
+        if (bodyNorm.length < 2) {
+            fail("no-vowels mode leaves the body alphabet with fewer than two symbols");
+        }
+        if (profile.checksumLength > 0 && checksumNorm.length < 2) {
+            fail("no-vowels mode leaves the checksum alphabet with fewer than two symbols");
+        }
+    }
+    const blocklist = profanity.mode === "blocklist" ? effectiveBlocklist(profanity) : [];
+    const separator = profile.separator ?? "";
+    for (const ch of separator) {
+        if (bodyNorm.includes(ch) || checksumNorm.includes(ch)) {
+            fail("separator must not occur in either alphabet");
+        }
+    }
+    const aliases = profile.aliases ?? {};
+    const aliasesNorm = {};
+    const canonicalSet = new Set([...bodyNorm, ...checksumNorm]);
+    for (const [src, tgt] of Object.entries(aliases)) {
+        if (!isAsciiChar(src))
+            fail(`alias source is not single ASCII: ${JSON.stringify(src)}`);
+        if (!isAsciiChar(tgt))
+            fail(`alias target is not single ASCII: ${JSON.stringify(tgt)}`);
+        const sNorm = norm(view, src);
+        const tNorm = norm(view, tgt);
+        if (canonicalSet.has(sNorm)) {
+            fail(`alias source ${JSON.stringify(src)} is already a canonical symbol`);
+        }
+        if (!canonicalSet.has(tNorm)) {
+            fail(`alias target ${JSON.stringify(tgt)} is not a canonical symbol`);
+        }
+        if (sNorm in aliasesNorm)
+            fail(`duplicate alias source ${JSON.stringify(sNorm)} after case normalization`);
+        if (tNorm in aliases || [...Object.keys(aliases)].some((k) => norm(view, k) === tNorm)) {
+            fail(`alias chain forbidden: target ${tNorm} is also an alias source`);
+        }
+        aliasesNorm[sNorm] = tNorm;
+    }
+    const total = bodySum(profile.grouping);
+    if (separator.length === 0) {
+        if (profile.grouping.length !== 0)
+            fail("grouping must be empty when separator is empty");
+    }
+    else if (total !== profile.bodyLength + profile.checksumLength) {
+        fail("group sizes must sum to bodyLength + checksumLength");
+    }
+    const permutation = profile.permutation ?? { enabled: false };
+    if (permutation.enabled) {
+        if (permutation.algorithm !== "feistel-v1")
+            fail("unknown permutation algorithm");
+        if (typeof permutation.keyId !== "string" || permutation.keyId.length === 0) {
+            fail("permutation requires a keyId");
+        }
+        if (!(permutation.keyBytes instanceof Uint8Array) || permutation.keyBytes.length === 0) {
+            fail("permutation requires key material");
+        }
+        if (!Number.isInteger(permutation.rounds) ||
+            permutation.rounds < 4 ||
+            permutation.rounds > 16 ||
+            permutation.rounds % 2 !== 0) {
+            fail("Feistel rounds must be an even integer from 4 through 16");
+        }
+    }
+    return {
+        ...profile,
+        caseSensitive,
+        checksumAlphabet,
+        separator,
+        grouping: [...profile.grouping],
+        aliases: { ...aliases },
+        permutation,
+        bodyAlphabetNorm: bodyNorm,
+        checksumAlphabetNorm: checksumNorm,
+        aliasesNorm,
+        checksumModulus: powBigInt(BigInt(checksumNorm.length || 1), profile.checksumLength),
+        capacity: powBigInt(BigInt(bodyNorm.length), profile.bodyLength),
+        blocklist
+    };
+}
+function bodySum(grouping) {
+    if (!Array.isArray(grouping))
+        return -1;
+    let sum = 0;
+    for (const g of grouping) {
+        if (!Number.isInteger(g) || g < 1)
+            return -1;
+        sum += g;
+    }
+    return sum;
+}

package/dist/profiles.d.ts

@@ -0,0 +1,22 @@
+import type { BasehProfile } from "./profile.js";
+export interface FrozenKeyOptions {
+    keyBytes: Uint8Array;
+    keyId?: string;
+    rounds?: number;
+}
+/** Alphanumeric, no safety strips, no checksum, hyphen-delimited XXX-XXX. */
+export declare function basehMinimumV1(): BasehProfile;
+/** baseh-minimum with feistel-v1 permutation. */
+export declare function basehMinimumPV1(options: FrozenKeyOptions): BasehProfile;
+/** Visual light plus spoken light, one checksum symbol. */
+export declare function basehLightV1(): BasehProfile;
+/** baseh-light with feistel-v1 permutation. */
+export declare function basehLightPV1(options: FrozenKeyOptions): BasehProfile;
+/** Visual medium plus spoken medium, one checksum symbol. The default. */
+export declare function basehMediumV1(): BasehProfile;
+/** baseh-medium with feistel-v1 permutation. */
+export declare function basehMediumPV1(options: FrozenKeyOptions): BasehProfile;
+/** Conservative alphabet plus spoken heavy, one checksum symbol. */
+export declare function basehHeavyV1(): BasehProfile;
+/** baseh-heavy with feistel-v1 permutation. */
+export declare function basehHeavyPV1(options: FrozenKeyOptions): BasehProfile;

package/dist/profiles.js

@@ -0,0 +1,117 @@
+/**
+ * Frozen tiers. Each is built from the full alphanumeric set with cumulative
+ * visual and spoken strips; the spoken strips interact with the visual ones
+ * exactly as the web tools derive them, so the tool capacities match.
+ *
+ *   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 keep the typed O/I/L aliases where possible and run the default
+ * profanity blocklist. Minimum also uses a hyphen delimiter; the rest have
+ * none. The -p variants are identical but with feistel-v1 permutation and
+ * require caller-supplied key material.
+ */
+const OIL_ALIASES = { O: "0", I: "1", L: "1" };
+const MINIMUM_BODY = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const LIGHT_BODY = "0123456789ABCEFGHJKMNPQRSUVWXYZ";
+const MEDIUM_BODY = "0123456789ACDEFGHJKMPQRUVXYZ";
+const HEAVY_BODY = "0123456789ABCEFHJKMPQRVXYZ";
+const LIGHT_CHECK = "234679ACEFGHJKMNPQRUVWXY";
+const MEDIUM_CHECK = "234679ACDEFGHJKMPQRUVXY";
+const HEAVY_CHECK = "234679ACEFHJKMPQRUVXY";
+function keyedPermutation(options) {
+    return {
+        enabled: true,
+        algorithm: "feistel-v1",
+        keyId: options.keyId ?? "default",
+        keyBytes: options.keyBytes,
+        rounds: options.rounds ?? 8
+    };
+}
+function tier(shape, permutation, pSuffix) {
+    return {
+        profileId: shape.profileId + (pSuffix ? "-p" : "") + "-v1",
+        bodyAlphabet: shape.bodyAlphabet,
+        bodyLength: 6,
+        checksumAlphabet: shape.checksumAlphabet,
+        checksumLength: shape.checksumLength,
+        caseSensitive: false,
+        separator: shape.separator,
+        grouping: shape.grouping,
+        aliases: { ...shape.aliases },
+        permutation,
+        profanity: { mode: "blocklist" }
+    };
+}
+const MINIMUM = {
+    profileId: "baseh-minimum",
+    bodyAlphabet: MINIMUM_BODY,
+    checksumAlphabet: "",
+    checksumLength: 0,
+    separator: "-",
+    grouping: [3, 3],
+    aliases: {}
+};
+const LIGHT = {
+    profileId: "baseh-light",
+    bodyAlphabet: LIGHT_BODY,
+    checksumAlphabet: LIGHT_CHECK,
+    checksumLength: 1,
+    separator: "",
+    grouping: [],
+    aliases: { ...OIL_ALIASES, D: "B", T: "P" }
+};
+const MEDIUM = {
+    profileId: "baseh-medium",
+    bodyAlphabet: MEDIUM_BODY,
+    checksumAlphabet: MEDIUM_CHECK,
+    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" }
+};
+const HEAVY = {
+    profileId: "baseh-heavy",
+    bodyAlphabet: HEAVY_BODY,
+    checksumAlphabet: HEAVY_CHECK,
+    checksumLength: 1,
+    separator: "",
+    grouping: [],
+    aliases: { ...OIL_ALIASES, D: "B", T: "P", N: "M", W: "V", S: "F", G: "C" }
+};
+/** Alphanumeric, no safety strips, no checksum, hyphen-delimited XXX-XXX. */
+export function basehMinimumV1() {
+    return tier(MINIMUM, { enabled: false }, false);
+}
+/** baseh-minimum with feistel-v1 permutation. */
+export function basehMinimumPV1(options) {
+    return tier(MINIMUM, keyedPermutation(options), true);
+}
+/** Visual light plus spoken light, one checksum symbol. */
+export function basehLightV1() {
+    return tier(LIGHT, { enabled: false }, false);
+}
+/** baseh-light with feistel-v1 permutation. */
+export function basehLightPV1(options) {
+    return tier(LIGHT, keyedPermutation(options), true);
+}
+/** Visual medium plus spoken medium, one checksum symbol. The default. */
+export function basehMediumV1() {
+    return tier(MEDIUM, { enabled: false }, false);
+}
+/** baseh-medium with feistel-v1 permutation. */
+export function basehMediumPV1(options) {
+    return tier(MEDIUM, keyedPermutation(options), true);
+}
+/** Conservative alphabet plus spoken heavy, one checksum symbol. */
+export function basehHeavyV1() {
+    return tier(HEAVY, { enabled: false }, false);
+}
+/** baseh-heavy with feistel-v1 permutation. */
+export function basehHeavyPV1(options) {
+    return tier(HEAVY, keyedPermutation(options), true);
+}

package/dist/zero.d.ts

@@ -0,0 +1,4 @@
+/** Encode an identifier with the zero-config Medium profile. */
+export declare function toCode(id: bigint | number | string): string;
+/** Decode a code from the zero-config Medium profile back to its identifier. */
+export declare function fromCode(code: string): bigint;

package/dist/zero.js

@@ -0,0 +1,39 @@
+import { Baseh } from "./codec.js";
+import { basehMediumV1 } from "./profiles.js";
+/**
+ * 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.
+ *
+ *   toCode(id)   -> "7KM4Q2H"
+ *   fromCode(code) -> id
+ *
+ * toCode accepts a bigint, a safe integer number or a decimal string.
+ * fromCode strips every whitespace character (edges and internal),
+ * accepts lowercase and the typed aliases (O, I, L) and returns the id
+ * as a bigint. Any invalid input throws BasehError, including the rare
+ * BLOCKED_CODE identifiers that spell a blocklisted word; no correction
+ * attempts are ever made.
+ */
+const ZERO = new Baseh(basehMediumV1());
+function toBigInt(id) {
+    if (typeof id === "bigint")
+        return id;
+    if (typeof id === "number") {
+        if (!Number.isSafeInteger(id) || id < 0) {
+            throw new TypeError("toCode expects a non-negative safe integer, bigint or decimal string");
+        }
+        return BigInt(id);
+    }
+    if (typeof id === "string" && /^[0-9]+$/.test(id))
+        return BigInt(id);
+    throw new TypeError("toCode expects a non-negative safe integer, bigint or decimal string");
+}
+/** Encode an identifier with the zero-config Medium profile. */
+export function toCode(id) {
+    return ZERO.encode(toBigInt(id));
+}
+/** Decode a code from the zero-config Medium profile back to its identifier. */
+export function fromCode(code) {
+    return ZERO.decode(code.replace(/\s+/g, "")).id;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@cloudyventures/baseh",
+  "version": "1.1.0",
+  "description": "baseH: reversible, checksummed, human-safe short references for integers.",
+  "repository": "github:cloudyventures/baseh",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "tsx --test test/*.test.ts",
+    "vectors": "tsx scripts/generate-vectors.ts"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "fast-check": "^4.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "license": "AGPL-3.0-only"
+}