@cloudyventures/baseh 1.1.0 → 2.0.1

package/dist/codec.d.ts

@@ -19,9 +19,52 @@ export interface ValidateResult {
     canonicalCode?: string;
     reason?: BasehErrorCode;
 }
+/**
+ * Spec 12.5. Live as-you-type feedback for a code entry field. `typing`
+ * carries the normalized typed symbols with separators inserted as far as
+ * the groups go, plus a progress fraction; `invalid` carries the
+ * BasehErrorCode from validate; `valid` is only ever reported for a
+ * complete code.
+ */
+export type InspectResult = {
+    state: "empty";
+} | {
+    state: "typing";
+    typed: string;
+    progress: number;
+} | {
+    state: "bad-char";
+} | {
+    state: "too-long";
+} | {
+    state: "invalid";
+    reason: BasehErrorCode;
+} | {
+    state: "valid";
+    id: bigint;
+    canonicalCode: string;
+};
 /** 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 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).
+ */
+export declare function expandableGrouping(length: number): number[];
+/**
+ * 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.
+ */
+export declare function generationBase(profile: PreparedProfile, length: number): bigint;
+/** Spec 19.1/22.3. Ids held by generation L: A^(L - effectiveK(L)). */
+export declare function generationCapacity(profile: PreparedProfile, length: number): bigint;
+/** Smallest generation whose range holds id, per spec 19.6. */
+export declare function generationForId(profile: PreparedProfile, id: bigint): number;
 /** 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 {
@@ -29,10 +72,23 @@ export declare class Baseh {
     private readonly bodyIndex;
     constructor(profile: BasehProfile);
     capacity(): bigint;
-    /** Spec 8. */
+    private permKey;
+    private checkBlocked;
+    /** Spec 8 (fixed mode). */
+    private encodeFixed;
+    /** Spec 19.6. */
+    private encodeExpandable;
+    /** Spec 8/19.6. */
     encode(id: bigint | number): string;
-    /** Spec 9. */
+    /** Spec 9/19.7. */
     decode(input: string, options?: DecodeOptions): DecodeResult;
     /** Spec 12.4. Never throws on user input. */
     validate(input: string, options?: DecodeOptions): ValidateResult;
+    /**
+     * 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: string): InspectResult;
 }

package/dist/codec.js

@@ -1,8 +1,8 @@
 import { BasehError } from "./errors.js";
-import { decodeBaseN, encodeBaseN, alphabetIndex } from "./basen.js";
+import { decodeBaseN, encodeBaseN, alphabetIndex, powBigInt } from "./basen.js";
 import { calculateChecksum } from "./checksum.js";
 import { inversePermute, permute } from "./feistel.js";
-import { prepareProfile } from "./profile.js";
+import { prepareProfile, effectiveChecksumLength } 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"] },
@@ -13,10 +13,12 @@ export const CONFUSION_MAPS = {
     }
 };
 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. */
 export 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("");
     }
@@ -26,13 +28,33 @@ export function normalize(input, profile, acceptSpaces = false) {
     if (!profile.caseSensitive) {
         s = s.toUpperCase();
     }
-    s = [...s].map((ch) => profile.aliasesNorm[ch] ?? ch).join("");
     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 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 BasehError("INVALID_LENGTH", `Expected at least ${profile.minLength} symbols, got ${s.length}`);
+        }
+        if (s.length > 32) {
+            throw new BasehError("INVALID_LENGTH", `Expected at most 32 symbols, got ${s.length}`);
+        }
+        if (hadSeparator && s.length < profile.separatorMinLength) {
+            throw new 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
@@ -47,16 +69,76 @@ export function normalize(input, profile, acceptSpaces = false) {
     }
     return s;
 }
-export function formatRaw(raw, profile) {
-    if (profile.separator.length === 0)
+function formatWith(raw, sizes, separator) {
+    if (separator.length === 0)
         return raw;
     const parts = [];
     let o = 0;
-    for (const size of profile.grouping) {
+    for (const size of sizes) {
         parts.push(raw.slice(o, o + size));
         o += size;
     }
-    return parts.join(profile.separator);
+    return parts.join(separator);
+}
+export 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).
+ */
+export 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.
+ */
+export 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)). */
+export function generationCapacity(profile, length) {
+    return powBigInt(BigInt(profile.bodyAlphabetNorm.length), length - effectiveChecksumLength(profile, length));
+}
+/** Smallest generation whose range holds id, per spec 19.6. */
+export 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 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. */
 export function generateCandidates(body, confusionMap, maxEdits = 1) {
@@ -85,25 +167,20 @@ export class Baseh {
         this.bodyIndex = 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 BasehError("INVALID_PROFILE", "capacity() is only defined for fixed-mode profiles", false);
+        }
         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`);
-        }
+    permKey(length) {
         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;
+        if (!perm.enabled)
+            throw new 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();
@@ -113,18 +190,76 @@ export class Baseh {
                 }
             }
         }
+        // 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 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 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, this.permKey());
+        }
+        const body = encodeBaseN(value, this.profile.bodyAlphabetNorm, this.profile.bodyLength);
+        const raw = body + calculateChecksum(this.profile, body, this.profile.checksumLength, this.bodyIndex);
+        this.checkBlocked(raw);
         return formatRaw(raw, this.profile);
     }
-    /** Spec 9. */
+    /** Spec 19.6. */
+    encodeExpandable(id) {
+        if (id < 0n) {
+            throw new 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 = permute(value, domain, this.permKey(l));
+        }
+        const k = effectiveChecksumLength(this.profile, l);
+        const body = encodeBaseN(value, this.profile.bodyAlphabetNorm, l - k);
+        const raw = body + 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 BasehError("INVALID_PROFILE", "maxCorrections must be 0 or 1", false);
+        }
         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 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"
+            ? 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 (calculateChecksum(this.profile, body) !== suppliedChecksum) {
+        if (calculateChecksum(this.profile, body, effectiveK, this.bodyIndex) !== suppliedChecksum) {
             if (!options.tryCorrection || (options.maxCorrections ?? 1) === 0) {
                 throw new BasehError("INVALID_CHECKSUM", "The reference code did not pass validation");
             }
@@ -145,7 +280,7 @@ export class Baseh {
             }
             const valid = new Set();
             for (const candidate of generateCandidates(body, map, options.maxCorrections ?? 1)) {
-                if (calculateChecksum(this.profile, candidate) === suppliedChecksum) {
+                if (calculateChecksum(this.profile, candidate, effectiveK, this.bodyIndex) === suppliedChecksum) {
                     valid.add(candidate);
                 }
             }
@@ -159,12 +294,17 @@ export class Baseh {
         }
         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
-            });
+        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 = inversePermute(value, generationCapacity(this.profile, l), this.permKey(l));
+            }
+            value = generationBase(this.profile, l) + value;
+        }
+        else if (perm.enabled) {
+            value = inversePermute(value, this.profile.capacity, this.permKey());
         }
         const canonicalCode = this.encode(value);
         const canonicalRaw = canonicalCode.split(this.profile.separator).join("");
@@ -182,4 +322,76 @@ export class Baseh {
             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 };
+    }
+}
+/**
+ * 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/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/facade.js

@@ -0,0 +1,30 @@
+import { Baseh } from "./codec.js";
+import { basehExpandableV1 } from "./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 Baseh(basehExpandableV1());
+    return shared;
+}
+/** Encode an id with the default expandable v1 profile. */
+export function encode(id) {
+    return sharedInstance().encode(id);
+}
+/** Decode a code with the default expandable v1 profile. Throws BasehError like the instance API. */
+export function decode(input, options = {}) {
+    return sharedInstance().decode(input, options);
+}
+/** Validate a code with the default expandable v1 profile. Never throws on user input. */
+export 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. */
+export function inspect(input) {
+    return sharedInstance().inspect(input);
+}

package/dist/feistel.d.ts

@@ -2,6 +2,12 @@ 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;

package/dist/feistel.js

@@ -24,10 +24,11 @@ function toBe(value, byteCount) {
     }
     return out;
 }
-function roundMessage(profileId, round, right, wr) {
+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 + 1 + rightBytes.length);
+    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;
@@ -37,6 +38,12 @@ function roundMessage(profileId, round, right, wr) {
     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);
@@ -48,7 +55,7 @@ function runRounds(h, key, w0, w1) {
         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 digest = hmac(sha256, key.keyBytes, roundMessage(key.profileId, i, right, wr, key.length));
         const f = lowBits(digest, wl);
         const newLeft = right;
         const newRight = left ^ f;
@@ -63,7 +70,7 @@ function runInverse(h, key, w0, w1) {
         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 digest = hmac(sha256, key.keyBytes, roundMessage(key.profileId, i, left, wr, key.length));
         const f = lowBits(digest, wl);
         const prevRight = left;
         const prevLeft = right ^ f;

package/dist/index.d.ts

@@ -1,13 +1,14 @@
 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 { prepareProfile, effectiveChecksumLength } from "./profile.js";
 export { Baseh, normalize, formatRaw, generateCandidates, CONFUSION_MAPS } from "./codec.js";
-export type { DecodeOptions, DecodeResult, ValidateResult, ConfusionProfileName } 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, type FrozenKeyOptions } from "./profiles.js";
-export { toCode, fromCode } from "./zero.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";

package/dist/index.js

@@ -1,9 +1,10 @@
 export { BasehError } from "./errors.js";
-export { prepareProfile } from "./profile.js";
+export { prepareProfile, effectiveChecksumLength } 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 { basehMinimumV1, basehLightV1, basehMediumV1, basehHeavyV1, basehMinimumPV1, basehLightPV1, basehMediumPV1, basehHeavyPV1, basehExpandableV1, basehExpandablePV1, FROZEN_KEY_BYTES } 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";

package/dist/profile.d.ts

@@ -10,28 +10,79 @@ export type BasehPermutation = {
 };
 export interface BasehProfile {
     profileId: string;
+    /**
+     * Spec 2.1/19.9. "fixed" keeps the classic constant-width behaviour;
+     * "expandable" gives variable-length codes driven by id magnitude
+     * (spec 19). Profiles that predate the mode field are fixed: the shared
+     * frozen vectors pin their byte-for-byte behaviour, so a missing mode is
+     * prepared as "fixed".
+     */
+    mode?: "fixed" | "expandable";
     bodyAlphabet: string;
-    bodyLength: number;
+    /** Fixed mode only; ignored in expandable mode. */
+    bodyLength?: number;
+    /** Expandable mode only; default 4. Must exceed checksumLength. */
+    minLength?: number;
     checksumAlphabet: string;
     checksumLength: number;
+    /**
+     * Spec 22. Expandable mode only. The checksum width used by generations at
+     * or below `shortChecksumUntil`; may be 0 (a zero-checksum window: those
+     * generations carry no checksum symbols and no typo detection). Without a
+     * window (`shortChecksumUntil` absent or 0) this must be absent or 0.
+     */
+    shortChecksumLength?: number;
+    /**
+     * Spec 22. The last generation (total length) that uses the short
+     * checksum; 0 or absent turns the feature off (the codebase convention,
+     * like maxRepetition). When set it must be an integer from `minLength`
+     * through 8.
+     */
+    shortChecksumUntil?: number;
     caseSensitive: boolean;
     separator: string;
+    /** Expandable mode only; default 0 (separator always applies). */
+    separatorMinLength?: number;
     grouping: number[];
     aliases: Record<string, string>;
     permutation: BasehPermutation;
     /** Spec 18. Defaults to mode "none". */
     profanity?: BasehProfanity;
+    /**
+     * Spec 21. Maximum allowed run of the same symbol in a raw code. 0 (the
+     * default) disables the filter; otherwise it must be an integer of at
+     * least 3. A value above the code length is a legal no-op.
+     */
+    maxRepetition?: number;
 }
 /** Case-prepared derived data, computed once at construction. */
 export interface PreparedProfile extends BasehProfile {
+    readonly mode: "fixed" | "expandable";
+    readonly minLength: number;
+    readonly separatorMinLength: number;
     readonly bodyAlphabetNorm: string;
     readonly checksumAlphabetNorm: string;
     readonly aliasesNorm: Record<string, string>;
     readonly checksumModulus: bigint;
+    /** Fixed-mode capacity A^bodyLength. Meaningless in expandable mode. */
     readonly capacity: bigint;
     /** Spec 18. Empty unless the profile uses mode "blocklist". */
     readonly blocklist: string[];
+    /** Spec 21. 0 disables the repetition filter. */
+    readonly maxRepetition: number;
+    /** Spec 22. 0 disables the short checksum. */
+    readonly shortChecksumLength: number;
+    /** Spec 22. Last short-checksum generation; 0 when the feature is off. */
+    readonly shortChecksumUntil: number;
 }
+/**
+ * Spec 22. The checksum length that applies to a generation of the given
+ * total length: `shortChecksumLength` at or below `shortChecksumUntil`,
+ * `checksumLength` above it (and always in fixed mode). The feature is on
+ * exactly when `shortChecksumUntil` is non-zero; a `shortChecksumLength` of
+ * 0 then means the window's generations carry no checksum symbols at all.
+ */
+export declare function effectiveChecksumLength(profile: PreparedProfile, length: number): number;
 /**
  * Validates a profile per spec section 2.2 and returns it with derived,
  * pre-computed values. Throws BasehError INVALID_PROFILE on any violation.