@cloudyventures/baseh 1.1.0 → 2.0.1

package/dist/cjs/codec.js

@@ -0,0 +1,408 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Baseh = exports.CONFUSION_MAPS = void 0;
+exports.normalize = normalize;
+exports.formatRaw = formatRaw;
+exports.expandableGrouping = expandableGrouping;
+exports.generationBase = generationBase;
+exports.generationCapacity = generationCapacity;
+exports.generationForId = generationForId;
+exports.generateCandidates = generateCandidates;
+const errors_js_1 = require("./errors.js");
+const basen_js_1 = require("./basen.js");
+const checksum_js_1 = require("./checksum.js");
+const feistel_js_1 = require("./feistel.js");
+const profile_js_1 = require("./profile.js");
+/** Built-in spoken-confusion candidate maps. Spec 3.3; pairs apply to body symbols only. */
+exports.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 INSPECT_WS = /[\t\n\v\f\r ]/;
+const MAX_CANDIDATES = 64;
+/** Spec 3.1 normalization, steps 1-7. Returns the raw unformatted string. */
+function normalize(input, profile, acceptSpaces = false) {
+    let s = input.replace(ASCII_WS, "");
+    const hadSeparator = profile.separator.length > 0 && s.includes(profile.separator);
+    if (profile.separator.length > 0) {
+        s = s.split(profile.separator).join("");
+    }
+    if (acceptSpaces) {
+        s = s.replace(/ /g, "");
+    }
+    if (!profile.caseSensitive) {
+        s = s.toUpperCase();
+    }
+    const allowed = new Set([...profile.bodyAlphabetNorm, ...profile.checksumAlphabetNorm]);
+    // Spec 3.2: an alias never maps two distinct canonical symbols into one
+    // value, so a symbol that is already canonical stays as-is and only
+    // non-canonical symbols are aliased. (In fixed tiers alias sources are
+    // never canonical, so this changes nothing there.)
+    s = [...s].map((ch) => (allowed.has(ch) ? ch : (profile.aliasesNorm[ch] ?? ch))).join("");
+    for (const ch of s) {
+        if (!allowed.has(ch)) {
+            throw new errors_js_1.BasehError("INVALID_CHARACTER", `Symbol ${JSON.stringify(ch)} is not accepted`);
+        }
+    }
+    if (profile.mode === "expandable") {
+        // Spec 19.2/19.7: no left-padding and no stripped-zero leniency. Input
+        // shorter than minLength or longer than 32 fails INVALID_LENGTH, and a
+        // separator below separatorMinLength is rejected (spec 19.5: the decoder
+        // expects no separators there).
+        if (s.length < profile.minLength) {
+            throw new errors_js_1.BasehError("INVALID_LENGTH", `Expected at least ${profile.minLength} symbols, got ${s.length}`);
+        }
+        if (s.length > 32) {
+            throw new errors_js_1.BasehError("INVALID_LENGTH", `Expected at most 32 symbols, got ${s.length}`);
+        }
+        if (hadSeparator && s.length < profile.separatorMinLength) {
+            throw new errors_js_1.BasehError("INVALID_CHARACTER", `Separators do not appear below ${profile.separatorMinLength} symbols`);
+        }
+        return s;
+    }
+    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 errors_js_1.BasehError("INVALID_LENGTH", `Expected ${expected} symbols, got ${s.length}`);
+    }
+    return s;
+}
+function formatWith(raw, sizes, separator) {
+    if (separator.length === 0)
+        return raw;
+    const parts = [];
+    let o = 0;
+    for (const size of sizes) {
+        parts.push(raw.slice(o, o + size));
+        o += size;
+    }
+    return parts.join(separator);
+}
+function formatRaw(raw, profile) {
+    if (profile.mode === "expandable") {
+        if (raw.length < profile.separatorMinLength)
+            return raw;
+        return formatWith(raw, expandableGrouping(raw.length), profile.separator);
+    }
+    return formatWith(raw, profile.grouping, profile.separator);
+}
+/**
+ * Spec 19.5. Balanced grouping: the split is a pure function of the total
+ * length — `g = max(2, ceil(L / 5))` groups differing in size by at most
+ * one, larger groups to the left. There is no configurable pattern in
+ * expandable mode (`grouping` must be empty, section 2.2).
+ */
+function expandableGrouping(length) {
+    const g = Math.max(2, Math.ceil(length / 5));
+    const base = Math.floor(length / g);
+    if (base < 1)
+        return [length];
+    const rem = length % g;
+    return [
+        ...Array(rem).fill(base + 1),
+        ...Array(g - rem).fill(base)
+    ];
+}
+/**
+ * Spec 19.1/22.3. First id of generation L: the sum of each generation's
+ * capacity A^(k - effectiveK(k)) for k from minLength through L-1. The
+ * effective checksum length is per-generation (spec 22), so the sum is not
+ * a single geometric series when the short checksum is on.
+ */
+function generationBase(profile, length) {
+    let base = 0n;
+    for (let l = profile.minLength; l < length; l += 1) {
+        base += generationCapacity(profile, l);
+    }
+    return base;
+}
+/** Spec 19.1/22.3. Ids held by generation L: A^(L - effectiveK(L)). */
+function generationCapacity(profile, length) {
+    return (0, basen_js_1.powBigInt)(BigInt(profile.bodyAlphabetNorm.length), length - (0, profile_js_1.effectiveChecksumLength)(profile, length));
+}
+/** Smallest generation whose range holds id, per spec 19.6. */
+function generationForId(profile, id) {
+    let l = profile.minLength;
+    let base = 0n;
+    let cap = generationCapacity(profile, l);
+    while (id >= base + cap) {
+        // Codes cap at 32 symbols, so generation 33 is the hard ceiling.
+        // Throwing from inside keeps an adversarial huge id from spinning the
+        // loop (and its bigint multiplications) without bound.
+        if (l >= 32) {
+            throw new errors_js_1.BasehError("OUT_OF_RANGE", "ID requires a code longer than 32 symbols");
+        }
+        base += cap;
+        l += 1;
+        cap = generationCapacity(profile, l);
+    }
+    return l;
+}
+/** Spec 10. Substitution-only candidate generation, capped and deduplicated. */
+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 errors_js_1.BasehError("TOO_MANY_CANDIDATES", "Candidate generation exceeded 64 entries", false);
+            }
+        }
+    }
+    return [...results];
+}
+class Baseh {
+    profile;
+    bodyIndex;
+    constructor(profile) {
+        this.profile = (0, profile_js_1.prepareProfile)(profile);
+        this.bodyIndex = (0, basen_js_1.alphabetIndex)(this.profile.bodyAlphabetNorm);
+    }
+    capacity() {
+        // Spec 12.3: fixed mode only. Expandable profiles have no single
+        // capacity; use the per-generation formulas of spec 19.1.
+        if (this.profile.mode !== "fixed") {
+            throw new errors_js_1.BasehError("INVALID_PROFILE", "capacity() is only defined for fixed-mode profiles", false);
+        }
+        return this.profile.capacity;
+    }
+    permKey(length) {
+        const perm = this.profile.permutation;
+        if (!perm.enabled)
+            throw new errors_js_1.BasehError("INVALID_PROFILE", "permutation is disabled", false);
+        return { profileId: this.profile.profileId, keyBytes: perm.keyBytes, rounds: perm.rounds, ...(length === undefined ? {} : { length }) };
+    }
+    checkBlocked(raw) {
+        // 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 errors_js_1.BasehError("BLOCKED_CODE", "The generated reference contains a blocked substring", false);
+                }
+            }
+        }
+        // Spec 21.2: a run of the same symbol at or above maxRepetition blocks
+        // the code. Runs are measured on the raw string, so a separator never
+        // breaks a run.
+        const max = this.profile.maxRepetition;
+        if (max > 0 && new RegExp(`(.)\\1{${max - 1},}`).test(raw)) {
+            throw new errors_js_1.BasehError("BLOCKED_CODE", "The generated reference repeats a symbol beyond the profile limit", false);
+        }
+    }
+    /** Spec 8 (fixed mode). */
+    encodeFixed(id) {
+        let value = id;
+        if (value < 0n || value >= this.profile.capacity) {
+            throw new errors_js_1.BasehError("OUT_OF_RANGE", `ID ${value} is outside the profile capacity`);
+        }
+        const perm = this.profile.permutation;
+        if (perm.enabled) {
+            value = (0, feistel_js_1.permute)(value, this.profile.capacity, this.permKey());
+        }
+        const body = (0, basen_js_1.encodeBaseN)(value, this.profile.bodyAlphabetNorm, this.profile.bodyLength);
+        const raw = body + (0, checksum_js_1.calculateChecksum)(this.profile, body, this.profile.checksumLength, this.bodyIndex);
+        this.checkBlocked(raw);
+        return formatRaw(raw, this.profile);
+    }
+    /** Spec 19.6. */
+    encodeExpandable(id) {
+        if (id < 0n) {
+            throw new errors_js_1.BasehError("OUT_OF_RANGE", `ID ${id} is negative`);
+        }
+        // generationForId throws OUT_OF_RANGE for ids beyond the 32-symbol ceiling.
+        const l = generationForId(this.profile, id);
+        let value = id - generationBase(this.profile, l);
+        const domain = generationCapacity(this.profile, l);
+        const perm = this.profile.permutation;
+        if (perm.enabled) {
+            value = (0, feistel_js_1.permute)(value, domain, this.permKey(l));
+        }
+        const k = (0, profile_js_1.effectiveChecksumLength)(this.profile, l);
+        const body = (0, basen_js_1.encodeBaseN)(value, this.profile.bodyAlphabetNorm, l - k);
+        const raw = body + (0, checksum_js_1.calculateChecksum)(this.profile, body, k, this.bodyIndex);
+        this.checkBlocked(raw);
+        return formatRaw(raw, this.profile);
+    }
+    /** Spec 8/19.6. */
+    encode(id) {
+        const value = BigInt(id);
+        return this.profile.mode === "expandable" ? this.encodeExpandable(value) : this.encodeFixed(value);
+    }
+    /** Spec 9/19.7. */
+    decode(input, options = {}) {
+        // Spec API is maxCorrections?: 0 | 1; anything else is a caller bug and
+        // is rejected at the boundary instead of silently coerced.
+        if (options.maxCorrections !== undefined && options.maxCorrections !== 0 && options.maxCorrections !== 1) {
+            throw new errors_js_1.BasehError("INVALID_PROFILE", "maxCorrections must be 0 or 1", false);
+        }
+        const raw = normalize(input, this.profile, options.acceptSpaces === true);
+        // Spec 22: the generation is selected by the presented total length, so
+        // the effective checksum length is a deterministic function of it.
+        const effectiveK = this.profile.mode === "expandable"
+            ? (0, profile_js_1.effectiveChecksumLength)(this.profile, raw.length)
+            : this.profile.checksumLength;
+        const bodyLength = this.profile.mode === "expandable"
+            ? raw.length - effectiveK
+            : this.profile.bodyLength;
+        let body = raw.slice(0, bodyLength);
+        const suppliedChecksum = raw.slice(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 ((0, checksum_js_1.calculateChecksum)(this.profile, body, effectiveK, this.bodyIndex) !== suppliedChecksum) {
+            if (!options.tryCorrection || (options.maxCorrections ?? 1) === 0) {
+                throw new errors_js_1.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" ? {} : exports.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 ((0, checksum_js_1.calculateChecksum)(this.profile, candidate, effectiveK, this.bodyIndex) === suppliedChecksum) {
+                    valid.add(candidate);
+                }
+            }
+            if (valid.size === 0) {
+                throw new errors_js_1.BasehError("INVALID_CHECKSUM", "The reference code did not pass validation");
+            }
+            if (valid.size > 1) {
+                throw new errors_js_1.BasehError("AMBIGUOUS_INPUT", "The reference code matches more than one record", false);
+            }
+            body = [...valid][0];
+        }
+        let value = (0, basen_js_1.decodeBaseN)(body, this.profile.bodyAlphabetNorm, this.bodyIndex);
+        const perm = this.profile.permutation;
+        if (this.profile.mode === "expandable") {
+            // Spec 19.7: the offset is de-permuted within the generation's own
+            // domain, then the generation base is added back.
+            const l = raw.length;
+            if (perm.enabled) {
+                value = (0, feistel_js_1.inversePermute)(value, generationCapacity(this.profile, l), this.permKey(l));
+            }
+            value = generationBase(this.profile, l) + value;
+        }
+        else if (perm.enabled) {
+            value = (0, feistel_js_1.inversePermute)(value, this.profile.capacity, this.permKey());
+        }
+        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 errors_js_1.BasehError)
+                return { valid: false, reason: err.code };
+            throw err;
+        }
+    }
+    /**
+     * Spec 12.5. Live as-you-type inspection. Gates on the typed length before
+     * validating, so spec 3.4 re-padding can never paint an incomplete fixed-mode
+     * code `valid` (or `invalid`): a short fixed input is `typing`, never
+     * checked. Never throws on user input.
+     */
+    inspect(input) {
+        const p = this.profile;
+        // Remove every occurrence of the separator string, then drop ASCII
+        // whitespace anywhere (a paste can carry either inside the code).
+        const noSep = p.separator.length > 0 ? input.split(p.separator).join("") : input;
+        const cleaned = [...noSep].filter((ch) => !INSPECT_WS.test(ch));
+        const typedCount = cleaned.length;
+        if (typedCount === 0)
+            return { state: "empty" };
+        const fixed = p.mode === "fixed";
+        const expected = fixed ? p.bodyLength + p.checksumLength : 32;
+        if (typedCount > expected)
+            return { state: "too-long" };
+        // Spec 3.1 steps 4-6, without the length checks: case normalization,
+        // aliases, then union membership. A symbol outside both alphabets is
+        // bad-char; a symbol valid only in the other region (say a checksum-only
+        // symbol typed into the body) passes here and fails later under validate.
+        const allowed = new Set([...p.bodyAlphabetNorm, ...p.checksumAlphabetNorm]);
+        let s = cleaned.join("");
+        if (!p.caseSensitive)
+            s = s.toUpperCase();
+        const raw = [...s].map((ch) => (allowed.has(ch) ? ch : (p.aliasesNorm[ch] ?? ch))).join("");
+        if ([...raw].some((ch) => !allowed.has(ch)))
+            return { state: "bad-char" };
+        // Fixed mode: complete means exactly bodyLength + checksumLength symbols.
+        // Expandable mode: every length from minLength through 32 is a complete
+        // code (the length selects the generation), so typing is only below
+        // minLength.
+        const complete = fixed ? typedCount === expected : typedCount >= p.minLength;
+        if (!complete) {
+            return {
+                state: "typing",
+                typed: formatPartial(raw, p),
+                progress: typedCount / (fixed ? expected : p.minLength)
+            };
+        }
+        const result = this.validate(raw);
+        if (!result.valid)
+            return { state: "invalid", reason: result.reason ?? "INVALID_CHECKSUM" };
+        const decoded = this.decode(raw);
+        return { state: "valid", id: decoded.id, canonicalCode: decoded.canonicalCode };
+    }
+}
+exports.Baseh = Baseh;
+/**
+ * Spec 12.5. Separators inserted into a partially typed code, as far as the
+ * groups go. Fixed mode walks the configured grouping; expandable mode uses
+ * the balanced grouping rule of spec 19.5 for the typed length, bare below
+ * separatorMinLength.
+ */
+function formatPartial(raw, profile) {
+    if (profile.separator.length === 0)
+        return raw;
+    if (profile.mode === "expandable") {
+        if (raw.length < profile.separatorMinLength)
+            return raw;
+        return formatWith(raw, expandableGrouping(raw.length), profile.separator);
+    }
+    const parts = [];
+    let offset = 0;
+    for (const size of profile.grouping) {
+        if (offset >= raw.length)
+            break;
+        parts.push(raw.slice(offset, offset + size));
+        offset += size;
+    }
+    return parts.join(profile.separator);
+}

package/dist/cjs/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/cjs/errors.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BasehError = void 0;
+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;
+    }
+}
+exports.BasehError = BasehError;

package/dist/cjs/facade.d.ts

@@ -0,0 +1,9 @@
+import { type DecodeOptions, type DecodeResult, type InspectResult, type ValidateResult } from "./codec.js";
+/** Encode an id with the default expandable v1 profile. */
+export declare function encode(id: bigint | number): string;
+/** Decode a code with the default expandable v1 profile. Throws BasehError like the instance API. */
+export declare function decode(input: string, options?: DecodeOptions): DecodeResult;
+/** Validate a code with the default expandable v1 profile. Never throws on user input. */
+export declare function validate(input: string, options?: DecodeOptions): ValidateResult;
+/** Live as-you-type inspection with the default expandable v1 profile. Never throws on user input. */
+export declare function inspect(input: string): InspectResult;

package/dist/cjs/facade.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encode = encode;
+exports.decode = decode;
+exports.validate = validate;
+exports.inspect = inspect;
+const codec_js_1 = require("./codec.js");
+const profiles_js_1 = require("./profiles.js");
+/**
+ * Zero-config facade over the shipped expandable v1 default profile. Most
+ * callers never need to touch a profile object: `encode(id)` and
+ * `decode(code)` here behave exactly like the same methods on a
+ * `new Baseh(basehExpandableV1())` instance, sharing one lazily constructed
+ * instance for the process.
+ */
+let shared;
+function sharedInstance() {
+    shared ??= new codec_js_1.Baseh((0, profiles_js_1.basehExpandableV1)());
+    return shared;
+}
+/** Encode an id with the default expandable v1 profile. */
+function encode(id) {
+    return sharedInstance().encode(id);
+}
+/** Decode a code with the default expandable v1 profile. Throws BasehError like the instance API. */
+function decode(input, options = {}) {
+    return sharedInstance().decode(input, options);
+}
+/** Validate a code with the default expandable v1 profile. Never throws on user input. */
+function validate(input, options = {}) {
+    return sharedInstance().validate(input, options);
+}
+/** Live as-you-type inspection with the default expandable v1 profile. Never throws on user input. */
+function inspect(input) {
+    return sharedInstance().inspect(input);
+}

package/dist/cjs/feistel.d.ts

@@ -0,0 +1,16 @@
+interface FeistelKey {
+    profileId: string;
+    keyBytes: Uint8Array;
+    rounds: number;
+    /**
+     * Expandable mode only (spec 7.3/19.4): the total code length L of the
+     * generation, mixed into the round message. Absent in fixed mode, where
+     * the message stays byte-for-byte unchanged.
+     */
+    length?: 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/cjs/feistel.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.permute = permute;
+exports.inversePermute = inversePermute;
+const hmac_1 = require("@noble/hashes/hmac");
+const sha256_1 = require("@noble/hashes/sha256");
+const errors_js_1 = require("./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, length) {
+    const pidBytes = new TextEncoder().encode(profileId);
+    const lenBytes = length === undefined ? new Uint8Array(0) : new TextEncoder().encode(String(length));
+    const rightBytes = toBe(right, Math.ceil(wr / 8));
+    const msg = new Uint8Array(TAG.length + 1 + pidBytes.length + 1 + lenBytes.length + (length === undefined ? 0 : 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;
+    if (length !== undefined) {
+        msg.set(lenBytes, o);
+        o += lenBytes.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 = (0, hmac_1.hmac)(sha256_1.sha256, key.keyBytes, roundMessage(key.profileId, i, right, wr, key.length));
+        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 = (0, hmac_1.hmac)(sha256_1.sha256, key.keyBytes, roundMessage(key.profileId, i, left, wr, key.length));
+        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. */
+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 errors_js_1.BasehError("PERMUTATION_FAILURE", "Feistel cycle walking exceeded 1000 iterations", false);
+}
+/** Spec 7.3 inverse permutation with cycle walking. */
+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 errors_js_1.BasehError("PERMUTATION_FAILURE", "Feistel cycle walking exceeded 1000 iterations", false);
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,14 @@
+export { BasehError } from "./errors.js";
+export type { BasehErrorCode } from "./errors.js";
+export type { BasehProfile, BasehPermutation, PreparedProfile } from "./profile.js";
+export { prepareProfile, effectiveChecksumLength } from "./profile.js";
+export { Baseh, normalize, formatRaw, generateCandidates, CONFUSION_MAPS } from "./codec.js";
+export type { DecodeOptions, DecodeResult, ValidateResult, InspectResult, 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, basehExpandableV1, basehExpandablePV1, FROZEN_KEY_BYTES, type FrozenKeyOptions } from "./profiles.js";
+export { generationBase, generationCapacity, generationForId, expandableGrouping } from "./codec.js";
+export { encode, decode, validate, inspect } from "./facade.js";
+export { DEFAULT_BLOCKLIST, effectiveBlocklist, stripVowels } from "./blocklist.js";
+export type { BasehProfanity, BasehProfanityMode } from "./blocklist.js";