@cloudyventures/baseh 1.1.0 → 2.0.1

package/README.md

@@ -0,0 +1,168 @@
+# @cloudyventures/baseh
+
+TypeScript implementation of the baseH (Human Reference Code) codec. Encodes
+integer IDs as checksummed, human-friendly reference codes — short codes that
+grow automatically in expandable mode (recommended), or fixed-length codes on
+the classic tiers — with a feistel-v1 permutation on every tier and profanity
+safety. The normative spec is `spec/IMPLEMENTATION_CODEC.md` in the
+[monorepo](https://github.com/cloudyventures/baseh).
+
+## Install
+
+```sh
+npm install @cloudyventures/baseh
+```
+
+One runtime dependency (`@noble/hashes`, auditable and dependency-free itself). Requires Node 18 or later (native `BigInt`).
+
+## Expandable mode (recommended)
+
+Every profile carries a `mode` field: `"expandable"` or `"fixed"`. Expandable
+is the recommended default for new users: codes start short (minimum 4
+characters, profile field `minLength`) and grow automatically as the ID
+sequence climbs past each length's capacity — transparently, with no
+migration and no re-issue. Shorter codes already issued keep decoding
+forever; the code's length selects the generation on decode.
+
+The recommended starting tier is `baseh-expandable-v1`:
+
+```typescript
+import { Baseh, basehExpandableV1 } from "@cloudyventures/baseh";
+
+const codec = new Baseh(basehExpandableV1());
+
+const code = codec.encode(123456n); // short code; grows as ids climb
+
+const result = codec.decode(code);
+result.id;                          // 123456n
+```
+
+Expandable mode differs from the fixed tiers as follows:
+
+- The default body alphabet is the 27 symbols left after the medium visual
+  and spoken safety strips and the `0`/`O` zero ban, so an issued code
+  never emits a visual or spoken confusable. A custom alphabet that includes
+  `0`/`O` has those symbols silently removed during profile preparation.
+- The checksum alphabet is the body alphabet plus `0` (28 symbols by
+  default). The `O -> 0` input alias remains, so a misread `O` in a checksum
+  position resolves to `0`; a `0` or `O` in a body position is simply an
+  invalid character.
+- The short checksum is on by default (codec spec 22): one checksum symbol
+  through 5 characters, two beyond; generation 4 holds 19,683 ids (3 body +
+  1 checksum) instead of 729. Configure with `shortChecksumLength` and
+  `shortChecksumUntil`; `shortChecksumUntil: 0` turns it off.
+- There is no left-padding; codes use exactly the length of the current
+  generation.
+- The Feistel permutation stays on, applied per generation with the code
+  length mixed into the key derivation alongside the profile id. Codes within
+  each length look random even though issuance is a sequential counter.
+  Presentation only, not encryption — same caveat as the fixed tiers.
+- Separators only appear once codes reach `separatorMinLength` characters
+  (6 in the shipped tier). Below that threshold there is no separator and no
+  grouping. Above it the split is the balanced rule of codec spec 19.5 —
+  a pure function of the code length (`XXX-XXX` at 6, `XXXX-XXX` at 7,
+  `XXXX-XXXX` at 8) — so expandable profiles carry no `grouping` field.
+- All other profile options — visual/spoken safety levels, profanity modes,
+  blocklists — compose with expandable unchanged.
+- The repetition filter is on by default here too: the tier ships
+  `maxRepetition: 4`, so a code with a run of four or more identical symbols
+  is never issued (any floor of 3 or more is configurable; 0 turns it off).
+
+A keyed private-mapping variant `baseh-expandable-p-v1` mirrors the `-p`
+fixed tiers:
+
+```typescript
+import { basehExpandablePV1 } from "@cloudyventures/baseh";
+
+const codec = new Baseh(
+  basehExpandablePV1({ keyBytes, keyId: "prod-01" })
+);
+```
+
+Security posture is unchanged: a code is a reference alias, never an
+authorization token. The smallest expandable generations are a small
+namespace, so rate-limit public lookups and enforce authorization after
+decode.
+
+## Frozen tiers (fixed mode)
+
+The classic frozen tiers are all `mode: "fixed"`: constant-width codes for
+when you need a stable printed length. Four frozen tiers ship with the
+package, built from the full alphanumeric set with cumulative visual and
+spoken strips. All four encode 6 body symbols, are case-insensitive,
+hyphen-delimit at the midpoint, run the default profanity blocklist, block
+runs of four or more identical symbols (the repetition filter,
+`maxRepetition: 4` — configurable to any floor of 3 or more, or 0 to turn it
+off) and permute with the published frozen key.
+
+| Tier | Helper | Body symbols | Checksum | Format | Capacity |
+| ---- | ------ | ------------ | -------- | ------ | -------- |
+| Minimum | `basehMinimumV1` | 36 | none | `XXX-XXX` | 2,176,782,336 |
+| Light | `basehLightV1` | 31 | 2 | `XXXX-XXXX` | 887,503,681 |
+| Medium | `basehMediumV1` | 28 | 2 | `XXXX-XXXX` | 481,890,304 |
+| Heavy | `basehHeavyV1` | 26 | 2 | `XXXX-XXXX` | 308,915,776 |
+
+Medium is the default fixed tier. The frozen key is public by design: it
+hides sequence, not records. See the spec, section 7.5.
+
+## Usage
+
+```typescript
+import { Baseh, basehExpandableV1 } from "@cloudyventures/baseh";
+
+const codec = new Baseh(basehExpandableV1());
+
+const code = codec.encode(123456n);        // short code; grows as ids climb
+
+const result = codec.decode(code);
+result.id;                                 // 123456n
+result.canonicalCode;                      // canonical form
+result.corrected;                          // true when input needed correction
+
+codec.capacity;                            // capacity of the current generation
+
+const check = codec.validate("00000000");
+check.valid;                               // false
+check.reason;                              // "INVALID_CHECKSUM"
+
+// Spoken-confusion correction
+codec.decode("TB14QDFU", { tryCorrection: true, confusionProfile: "light" });
+```
+
+Fixed mode works the same way, through a fixed tier helper:
+
+```typescript
+import { basehMediumV1 } from "@cloudyventures/baseh";
+
+const fixed = new Baseh(basehMediumV1());
+const code = fixed.encode(123456n);        // fixed-width hyphenated code
+```
+
+IDs are `bigint`, so every capacity and ID operation is exact at any size.
+
+## Permutation
+
+The plain tiers permute with `FROZEN_KEY_BYTES` (the published frozen key).
+The `P` variants take a caller-supplied key instead; keep that key in a
+secret manager and never change it for a live profile:
+
+```typescript
+import { basehMediumPV1 } from "@cloudyventures/baseh";
+
+const codec = new Baseh(
+  basehMediumPV1({ keyBytes, keyId: "prod-01" })
+);
+```
+
+## Errors
+
+All failures raise `BasehError` with a `code` from the spec:
+`INVALID_PROFILE`, `OUT_OF_RANGE`, `PERMUTATION_FAILURE`, `INVALID_LENGTH`,
+`INVALID_CHARACTER`, `INVALID_CHECKSUM`, `AMBIGUOUS_INPUT`,
+`TOO_MANY_CANDIDATES` and `BLOCKED_CODE`. `validate` never raises on user
+input.
+
+## License
+
+AGPL-3.0. Commercial licensing available; see
+[COMMERCIAL.md](https://github.com/cloudyventures/baseh/blob/main/COMMERCIAL.md).

package/dist/basen.d.ts

@@ -3,3 +3,5 @@ export declare function encodeBaseN(value: bigint, alphabet: string, length: num
 /** 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>;
+/** Integer power for bigint bases; shared by profile, codec and checksum. */
+export declare function powBigInt(base: bigint, exp: number): bigint;

package/dist/basen.js

@@ -32,3 +32,10 @@ export function alphabetIndex(alphabet) {
     [...alphabet].forEach((ch, i) => m.set(ch, BigInt(i)));
     return m;
 }
+/** Integer power for bigint bases; shared by profile, codec and checksum. */
+export function powBigInt(base, exp) {
+    let result = 1n;
+    for (let i = 0; i < exp; i += 1)
+        result *= base;
+    return result;
+}

package/dist/blocklist.js

@@ -5,6 +5,9 @@ export const DEFAULT_BLOCKLIST = [
     "SHT", "CNT", "TWT", "DCK", "AZZ", "BCH"
 ];
 const WORD = /^[A-Za-z]{2,32}$/;
+// JS `$` also matches before a trailing newline, so the charset test alone
+// accepts "abc\n"; an explicit newline check restores Ruby's \A...\z strictness.
+const NEWLINE = /[\r\n]/;
 function fail(reason) {
     throw new BasehError("INVALID_PROFILE", `Invalid baseH profile: ${reason}`, false);
 }
@@ -14,7 +17,7 @@ export function effectiveBlocklist(profanity) {
     const list = [...base, ...(profanity.extraWords ?? [])];
     const out = [];
     for (const word of list) {
-        if (typeof word !== "string" || !WORD.test(word)) {
+        if (typeof word !== "string" || !WORD.test(word) || NEWLINE.test(word)) {
             fail("blocklist entries must be 2 through 32 ASCII letters");
         }
         const upper = word.toUpperCase();

package/dist/checksum.d.ts

@@ -2,7 +2,9 @@ import type { PreparedProfile } from "./profile.js";
 /**
  * Spec 6.2. Rolling polynomial checksum over symbol values.
  * Returns the checksum value in [0, modulus).
+ * Spec 22: expandable generations may pass a shorter effective checksum
+ * length; the modulus is then S^length instead of the profile default.
  */
-export declare function checksumValue(profile: PreparedProfile, body: string, bodyIndex: Map<string, bigint>): bigint;
+export declare function checksumValue(profile: PreparedProfile, body: string, bodyIndex: Map<string, bigint>, checksumLength?: number): bigint;
 /** Compute the expected checksum string for a normalized body. */
-export declare function calculateChecksum(profile: PreparedProfile, body: string): string;
+export declare function calculateChecksum(profile: PreparedProfile, body: string, checksumLength?: number, bodyIndex?: Map<string, bigint>): string;

package/dist/checksum.js

@@ -1,11 +1,15 @@
 import { BasehError } from "./errors.js";
-import { alphabetIndex, encodeBaseN } from "./basen.js";
+import { alphabetIndex, encodeBaseN, powBigInt } from "./basen.js";
 /**
  * Spec 6.2. Rolling polynomial checksum over symbol values.
  * Returns the checksum value in [0, modulus).
+ * Spec 22: expandable generations may pass a shorter effective checksum
+ * length; the modulus is then S^length instead of the profile default.
  */
-export function checksumValue(profile, body, bodyIndex) {
-    const modulus = profile.checksumModulus;
+export function checksumValue(profile, body, bodyIndex, checksumLength = profile.checksumLength) {
+    const modulus = checksumLength === profile.checksumLength
+        ? profile.checksumModulus
+        : powBigInt(BigInt(profile.checksumAlphabetNorm.length || 1), checksumLength);
     let state = 17n;
     for (let i = 0; i < profile.profileId.length; i += 1) {
         state = (state * 37n + BigInt(profile.profileId.charCodeAt(i)) + 1n) % modulus;
@@ -21,10 +25,12 @@ export function checksumValue(profile, body, bodyIndex) {
     return state;
 }
 /** Compute the expected checksum string for a normalized body. */
-export function calculateChecksum(profile, body) {
-    if (profile.checksumLength === 0)
+export function calculateChecksum(profile, body, checksumLength = profile.checksumLength, bodyIndex) {
+    if (checksumLength === 0)
         return "";
-    const index = alphabetIndex(profile.bodyAlphabetNorm);
-    const value = checksumValue(profile, body, index);
-    return encodeBaseN(value, profile.checksumAlphabetNorm, profile.checksumLength);
+    // Correction loops call this up to 64 times; callers with a prepared index
+    // pass it in rather than rebuilding one per call.
+    const index = bodyIndex ?? alphabetIndex(profile.bodyAlphabetNorm);
+    const value = checksumValue(profile, body, index, checksumLength);
+    return encodeBaseN(value, profile.checksumAlphabetNorm, checksumLength);
 }

package/dist/cjs/basen.d.ts

@@ -0,0 +1,7 @@
+/** 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>;
+/** Integer power for bigint bases; shared by profile, codec and checksum. */
+export declare function powBigInt(base: bigint, exp: number): bigint;

package/dist/cjs/basen.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeBaseN = encodeBaseN;
+exports.decodeBaseN = decodeBaseN;
+exports.alphabetIndex = alphabetIndex;
+exports.powBigInt = powBigInt;
+const errors_js_1 = require("./errors.js");
+/** Spec 5.1. Fixed-length base-N encode, most significant digit first. */
+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 errors_js_1.BasehError("OUT_OF_RANGE", "digit outside alphabet");
+        out[pos] = ch;
+        v = v / base;
+    }
+    return out.join("");
+}
+/** Spec 5.2. */
+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 errors_js_1.BasehError("INVALID_CHARACTER", `Symbol ${JSON.stringify(ch)} is not in the alphabet`);
+        }
+        value = value * base + digit;
+    }
+    return value;
+}
+function alphabetIndex(alphabet) {
+    const m = new Map();
+    [...alphabet].forEach((ch, i) => m.set(ch, BigInt(i)));
+    return m;
+}
+/** Integer power for bigint bases; shared by profile, codec and checksum. */
+function powBigInt(base, exp) {
+    let result = 1n;
+    for (let i = 0; i < exp; i += 1)
+        result *= base;
+    return result;
+}

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

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BLOCKLIST = void 0;
+exports.effectiveBlocklist = effectiveBlocklist;
+exports.stripVowels = stripVowels;
+const errors_js_1 = require("./errors.js");
+/** Spec 18.2 default list. Deliberately small; applications extend it. */
+exports.DEFAULT_BLOCKLIST = [
+    "CRAP", "TWAT", "SHAG", "DAMN", "FCK", "FUC",
+    "SHT", "CNT", "TWT", "DCK", "AZZ", "BCH"
+];
+const WORD = /^[A-Za-z]{2,32}$/;
+// JS `$` also matches before a trailing newline, so the charset test alone
+// accepts "abc\n"; an explicit newline check restores Ruby's \A...\z strictness.
+const NEWLINE = /[\r\n]/;
+function fail(reason) {
+    throw new errors_js_1.BasehError("INVALID_PROFILE", `Invalid baseH profile: ${reason}`, false);
+}
+/** Spec 18.2: replacement semantics, then augmentation, uppercased and deduplicated. */
+function effectiveBlocklist(profanity) {
+    const base = profanity.words ? [...profanity.words] : [...exports.DEFAULT_BLOCKLIST];
+    const list = [...base, ...(profanity.extraWords ?? [])];
+    const out = [];
+    for (const word of list) {
+        if (typeof word !== "string" || !WORD.test(word) || NEWLINE.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. */
+function stripVowels(alphabetNorm) {
+    return [...alphabetNorm].filter((c) => !"AEIOU".includes(c)).join("");
+}

package/dist/cjs/checksum.d.ts

@@ -0,0 +1,10 @@
+import type { PreparedProfile } from "./profile.js";
+/**
+ * Spec 6.2. Rolling polynomial checksum over symbol values.
+ * Returns the checksum value in [0, modulus).
+ * Spec 22: expandable generations may pass a shorter effective checksum
+ * length; the modulus is then S^length instead of the profile default.
+ */
+export declare function checksumValue(profile: PreparedProfile, body: string, bodyIndex: Map<string, bigint>, checksumLength?: number): bigint;
+/** Compute the expected checksum string for a normalized body. */
+export declare function calculateChecksum(profile: PreparedProfile, body: string, checksumLength?: number, bodyIndex?: Map<string, bigint>): string;

package/dist/cjs/checksum.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checksumValue = checksumValue;
+exports.calculateChecksum = calculateChecksum;
+const errors_js_1 = require("./errors.js");
+const basen_js_1 = require("./basen.js");
+/**
+ * Spec 6.2. Rolling polynomial checksum over symbol values.
+ * Returns the checksum value in [0, modulus).
+ * Spec 22: expandable generations may pass a shorter effective checksum
+ * length; the modulus is then S^length instead of the profile default.
+ */
+function checksumValue(profile, body, bodyIndex, checksumLength = profile.checksumLength) {
+    const modulus = checksumLength === profile.checksumLength
+        ? profile.checksumModulus
+        : (0, basen_js_1.powBigInt)(BigInt(profile.checksumAlphabetNorm.length || 1), checksumLength);
+    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 errors_js_1.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. */
+function calculateChecksum(profile, body, checksumLength = profile.checksumLength, bodyIndex) {
+    if (checksumLength === 0)
+        return "";
+    // Correction loops call this up to 64 times; callers with a prepared index
+    // pass it in rather than rebuilding one per call.
+    const index = bodyIndex ?? (0, basen_js_1.alphabetIndex)(profile.bodyAlphabetNorm);
+    const value = checksumValue(profile, body, index, checksumLength);
+    return (0, basen_js_1.encodeBaseN)(value, profile.checksumAlphabetNorm, checksumLength);
+}

package/dist/cjs/codec.d.ts

@@ -0,0 +1,94 @@
+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 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 {
+    readonly profile: PreparedProfile;
+    private readonly bodyIndex;
+    constructor(profile: BasehProfile);
+    capacity(): bigint;
+    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/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;
+}