@discretion/core 0.1.0

package/src/checksums/digits.ts

@@ -0,0 +1,108 @@
+/**
+ * Digit and character helpers shared by every checksum implementation.
+ *
+ * These exist so that the algorithm modules (luhn, mod97, verhoeff, …) deal
+ * only in `number[]` and never re-implement parsing. Every function here is
+ * total: it returns `null` on malformed input rather than throwing, because
+ * checksum code runs on arbitrary user text where malformed input is the
+ * common case, not an exceptional one.
+ */
+
+/** ASCII '0'–'9'. */
+const ZERO = 0x30;
+const NINE = 0x39;
+
+/**
+ * Parse a string of ASCII digits into numeric digit values.
+ *
+ * Returns `null` if the string is empty or contains any non-digit character.
+ * Deliberately rejects non-ASCII digits (Arabic-Indic ٤, fullwidth ４, …):
+ * Stage 0 normalization already folds fullwidth forms to ASCII, and a
+ * genuinely non-ASCII digit run is not an identifier in any scheme we
+ * validate.
+ */
+export function toDigits(value: string): number[] | null {
+  if (value.length === 0) return null;
+  const digits: number[] = new Array<number>(value.length);
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code < ZERO || code > NINE) return null;
+    digits[i] = code - ZERO;
+  }
+  return digits;
+}
+
+/**
+ * Remove every character in `separators` from `value`.
+ *
+ * Identifiers are routinely written with grouping punctuation (`4111 1111
+ * 1111 1111`, `123-45-6789`, `AB-12-CD`). Detectors strip before validating
+ * and keep the raw span for offset reporting.
+ */
+export function stripSeparators(value: string, separators = ' \t-.–—/'): string {
+  let out = '';
+  for (const ch of value) {
+    if (!separators.includes(ch)) out += ch;
+  }
+  return out;
+}
+
+/**
+ * Value of an alphanumeric character in base 36: '0'–'9' → 0–9,
+ * 'A'/'a'–'Z'/'z' → 10–35. Returns `null` for anything else.
+ *
+ * This is the mapping IBAN's mod-97 and several VAT schemes use to fold
+ * letters into the numeric checksum.
+ */
+export function alphanumericValue(ch: string): number | null {
+  if (ch.length !== 1) return null;
+  const code = ch.charCodeAt(0);
+  if (code >= ZERO && code <= NINE) return code - ZERO;
+  if (code >= 0x41 && code <= 0x5a) return code - 0x41 + 10; // A-Z
+  if (code >= 0x61 && code <= 0x7a) return code - 0x61 + 10; // a-z
+  return null;
+}
+
+/**
+ * Expand every character of `value` to its base-36 value and concatenate the
+ * decimal representations, the transformation IBAN mod-97 requires.
+ *
+ * "GB82" → "161182"  (G=16, B=11, 8, 2)
+ *
+ * Returns `null` if any character is not alphanumeric.
+ */
+export function toNumericString(value: string): string | null {
+  let out = '';
+  for (const ch of value) {
+    const v = alphanumericValue(ch);
+    if (v === null) return null;
+    out += v.toString(10);
+  }
+  return out;
+}
+
+/** True when every character is an ASCII digit and the string is non-empty. */
+export function isAllDigits(value: string): boolean {
+  if (value.length === 0) return false;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code < ZERO || code > NINE) return false;
+  }
+  return true;
+}
+
+/**
+ * True when every digit is identical ("0000000000", "1111111111").
+ *
+ * Repdigits pass several national checksums by construction (a weighted sum
+ * of identical digits often lands on a valid remainder) yet are never issued.
+ * Schemes that exclude them say so in their own validator.
+ */
+export function isRepdigit(digits: readonly number[]): boolean {
+  if (digits.length === 0) return false;
+  const first = digits[0]!;
+  for (let i = 1; i < digits.length; i++) {
+    if (digits[i] !== first) return false;
+  }
+  return true;
+}

package/src/checksums/icao9303.ts

@@ -0,0 +1,53 @@
+/**
+ * ICAO 9303 machine-readable-zone check digits.
+ *
+ * One weighting for every MRZ field on every document type: cycle the
+ * weights 7, 3, 1 across the field, mapping '0'–'9' to their value, 'A'–'Z'
+ * to 10–35, and the filler '<' to 0; the check digit is the sum mod 10.
+ *
+ * Lives in the checksum library rather than in the MRZ detector because
+ * SPEC.md wants each algorithm implemented and tested once, and TD1, TD2,
+ * TD3 and the composite check all call it with different slices.
+ */
+
+const WEIGHTS: readonly number[] = [7, 3, 1];
+
+/**
+ * Character value under the MRZ scheme: digits are themselves, letters are
+ * 10 + their alphabet position, '<' is 0. Returns null for anything else.
+ */
+export function mrzCharValue(ch: string): number | null {
+  if (ch === '<') return 0;
+  const code = ch.charCodeAt(0);
+  if (code >= 0x30 && code <= 0x39) return code - 0x30;
+  if (code >= 0x41 && code <= 0x5a) return code - 0x41 + 10;
+  return null;
+}
+
+/**
+ * The ICAO check digit for a field. Returns null if the field contains a
+ * character outside the MRZ alphabet.
+ */
+export function mrzCheckDigit(field: string): number | null {
+  let sum = 0;
+  for (let i = 0; i < field.length; i++) {
+    const v = mrzCharValue(field[i]!);
+    if (v === null) return null;
+    sum += v * WEIGHTS[i % 3]!;
+  }
+  return sum % 10;
+}
+
+/**
+ * Verify a field against its trailing check character.
+ *
+ * The check character may itself be '<' in the optional-data field of some
+ * documents, which ICAO treats as zero — handled by `mrzCharValue`.
+ */
+export function mrzCheckValid(field: string, check: string): boolean {
+  if (check.length !== 1) return false;
+  const expected = mrzCheckDigit(field);
+  if (expected === null) return false;
+  const actual = mrzCharValue(check);
+  return actual !== null && actual === expected;
+}

package/src/checksums/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared checksum library.
+ *
+ * SPEC.md, Stage 1: "implement with full checksum validation, not pattern
+ * matching". These are the algorithms the identifier validators are built
+ * from — each implemented once here, tested once in
+ * `test/checksums.test.ts`, and reused by every detector that needs it.
+ *
+ * Nothing in this directory knows what a detector or an entity type is. These
+ * are pure functions over strings and digit arrays, which is what makes them
+ * cheap to property-test exhaustively.
+ */
+
+export { toDigits, stripSeparators, alphanumericValue, toNumericString, isAllDigits, isRepdigit } from './digits.js';
+
+export { weightedSum, weightedMod, weightedModBy, cyclicWeightedMod, complement } from './weighted.js';
+
+export { luhnValid, luhnCheckDigit } from './luhn.js';
+
+export { verhoeffValid, verhoeffCheckDigit } from './verhoeff.js';
+
+export { modString, ibanMod97Valid, ibanCheckDigits, mod97Key } from './mod97.js';
+
+export {
+  iso7064PureCheckValue,
+  iso7064PureValid,
+  mod11_2Valid,
+  mod11_2CheckChar,
+  mod37_36Valid,
+  mod11_10CheckDigit,
+  mod11_10Valid,
+} from './iso7064.js';
+
+export { abaValid, abaCheckDigit } from './aba.js';
+
+export { mrzCharValue, mrzCheckDigit, mrzCheckValid } from './icao9303.js';

package/src/checksums/iso7064.ts

@@ -0,0 +1,168 @@
+/**
+ * ISO/IEC 7064 check character systems.
+ *
+ * A family of standardized checksums, of which Stage 1 needs several:
+ *   • MOD 11-2  — China's Resident Identity Card (check char 0-9 or 'X')
+ *   • MOD 97-10 — the system underlying IBAN and several VAT schemes
+ *   • MOD 37-36 — alphanumeric identifiers
+ *   • MOD 11-10 — a hybrid system used by some national registries
+ *
+ * The "pure" systems (MOD M-R, where R is a power used as a multiplier) all
+ * share one recurrence, so it is written once here and parameterized by
+ * modulus and radix. That is exactly the reuse SPEC.md asks for: these are
+ * the same algorithm with different constants, and implementing MOD 11-2 by
+ * hand per country is how transcription bugs get in.
+ *
+ * Pure system recurrence, over the payload characters:
+ *     P ← ((P + aᵢ) × R) mod M
+ * The check value is then (M + 1 − P) mod M. Verification appends the check
+ * value with a final addition instead of a multiplication and requires the
+ * result to be 1.
+ */
+
+import { alphanumericValue } from './digits.js';
+
+/** Character set for MOD 37-36: 0-9, A-Z, then '*' for the value 36. */
+const MOD37_ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ*';
+
+/**
+ * Run the pure-system recurrence over a sequence of character values.
+ * Returns the interim value P after the final multiplication.
+ */
+function pureInterim(values: readonly number[], modulus: number, radix: number): number {
+  let p = 0;
+  for (const v of values) {
+    p = ((p + v) * radix) % modulus;
+  }
+  return p;
+}
+
+/**
+ * The check value for a payload under a pure ISO 7064 system.
+ *
+ * Returns a number in `[0, modulus)`. Callers map it to a character according
+ * to their scheme's alphabet (10 → 'X' for MOD 11-2, for instance).
+ */
+export function iso7064PureCheckValue(
+  values: readonly number[],
+  modulus: number,
+  radix: number,
+): number {
+  return (modulus + 1 - pureInterim(values, modulus, radix)) % modulus;
+}
+
+/**
+ * Verify a payload plus its check value under a pure ISO 7064 system.
+ *
+ * The standard verification processes the payload with the multiplying
+ * recurrence, then adds the check value once and requires a result of 1.
+ */
+export function iso7064PureValid(
+  payloadValues: readonly number[],
+  checkValue: number,
+  modulus: number,
+  radix: number,
+): boolean {
+  const p = pureInterim(payloadValues, modulus, radix);
+  return (p + checkValue) % modulus === 1;
+}
+
+/**
+ * ISO 7064 MOD 11-2 over a decimal payload.
+ *
+ * `payload` must be all ASCII digits; `check` is the trailing check character,
+ * either a digit or 'X'/'x' representing 10. This is China's Resident
+ * Identity Card checksum.
+ */
+export function mod11_2Valid(payload: string, check: string): boolean {
+  const values: number[] = [];
+  for (const ch of payload) {
+    const v = alphanumericValue(ch);
+    if (v === null || v > 9) return false; // digits only
+    values.push(v);
+  }
+  if (values.length === 0) return false;
+
+  const checkValue = parseCheckChar(check, 11);
+  if (checkValue === null) return false;
+
+  return iso7064PureValid(values, checkValue, 11, 2);
+}
+
+/**
+ * The MOD 11-2 check character for a decimal payload: '0'–'9' or 'X'.
+ * Returns `null` if the payload contains a non-digit.
+ */
+export function mod11_2CheckChar(payload: string): string | null {
+  const values: number[] = [];
+  for (const ch of payload) {
+    const v = alphanumericValue(ch);
+    if (v === null || v > 9) return null;
+    values.push(v);
+  }
+  if (values.length === 0) return null;
+  const check = iso7064PureCheckValue(values, 11, 2);
+  return check === 10 ? 'X' : check.toString(10);
+}
+
+/**
+ * ISO 7064 MOD 37-36 over an alphanumeric payload, with a check character
+ * drawn from 0-9, A-Z, '*'.
+ */
+export function mod37_36Valid(payload: string, check: string): boolean {
+  const values: number[] = [];
+  for (const ch of payload) {
+    const v = alphanumericValue(ch);
+    if (v === null) return false;
+    values.push(v);
+  }
+  if (values.length === 0) return false;
+
+  const checkValue = MOD37_ALPHABET.indexOf(check.toUpperCase());
+  if (checkValue < 0) return false;
+
+  return iso7064PureValid(values, checkValue, 37, 36);
+}
+
+/**
+ * ISO 7064 MOD 11-10, a hybrid system. Unlike the pure systems this carries
+ * the running value through a different recurrence and closes with a single
+ * decimal check digit.
+ *
+ *     P ← 10  (seed)
+ *     for each digit d:  P ← ((P mod 11) + d) mod 10, folding 0 to 10, ×2 mod 11
+ *
+ * Expressed in the standard's own terms below.
+ */
+export function mod11_10CheckDigit(payload: string): number | null {
+  let p = 10;
+  for (const ch of payload) {
+    const v = alphanumericValue(ch);
+    if (v === null || v > 9) return null;
+    let sum = (p + v) % 10;
+    if (sum === 0) sum = 10;
+    p = (sum * 2) % 11;
+  }
+  const check = (11 - p) % 10;
+  return check;
+}
+
+/** Verify a decimal payload plus trailing check digit under MOD 11-10. */
+export function mod11_10Valid(payload: string, check: string): boolean {
+  const expected = mod11_10CheckDigit(payload);
+  if (expected === null) return false;
+  const actual = parseCheckChar(check, 10);
+  return actual !== null && actual === expected;
+}
+
+/**
+ * Parse a single check character to its numeric value.
+ * 'X'/'x' maps to 10 only when the modulus admits it (MOD 11-2).
+ */
+function parseCheckChar(check: string, modulus: number): number | null {
+  if (check.length !== 1) return null;
+  if (modulus === 11 && (check === 'X' || check === 'x')) return 10;
+  const v = alphanumericValue(check);
+  if (v === null || v >= modulus || v > 9) return null;
+  return v;
+}

package/src/checksums/luhn.ts

@@ -0,0 +1,66 @@
+/**
+ * The Luhn algorithm (ISO/IEC 7812-1), also called mod-10 double-add-double.
+ *
+ * Used by far more than credit cards: Canada's SIN, Sweden's Personnummer,
+ * South Africa's ID number, Israel's Teudat Zehut, the US NPI (over a
+ * prefixed string), Greece's AFM and IMEI all close with a Luhn digit.
+ *
+ * The algorithm, right to left over the FULL number including its check
+ * digit: double every second digit, subtract 9 from any result above 9, sum
+ * everything. The number is valid when that total is divisible by 10.
+ *
+ * Luhn catches every single-digit error and every adjacent transposition
+ * except 09↔90 — a property the tests assert directly rather than trusting.
+ */
+
+import { toDigits } from './digits.js';
+
+/**
+ * Validate a digit string against Luhn.
+ *
+ * `value` must already be stripped of separators and contain only ASCII
+ * digits; anything else returns `false`. A single digit is rejected: a
+ * one-character "identifier" carries no payload, and accepting "0" would make
+ * every scheme that closes with Luhn match a bare zero.
+ */
+export function luhnValid(value: string): boolean {
+  const digits = toDigits(value);
+  if (digits === null || digits.length < 2) return false;
+  return luhnSum(digits) % 10 === 0;
+}
+
+/**
+ * The Luhn check digit for a payload that does NOT yet include one.
+ *
+ * Returns `null` if the payload is not all digits. Used by the test-vector
+ * generators — and later by M4's surrogate substitution, which must emit
+ * replacement values that still pass the validator.
+ */
+export function luhnCheckDigit(payload: string): number | null {
+  const digits = toDigits(payload);
+  if (digits === null) return null;
+  // Append a placeholder 0, compute the sum, and take the complement.
+  const sum = luhnSum([...digits, 0]);
+  return (10 - (sum % 10)) % 10;
+}
+
+/**
+ * Sum the Luhn-transformed digits of a complete number.
+ *
+ * Doubling starts at the second digit from the right, i.e. positions of the
+ * same parity as the check digit are NOT doubled.
+ */
+function luhnSum(digits: readonly number[]): number {
+  let sum = 0;
+  let double = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let d = digits[i]!;
+    if (double) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    double = !double;
+  }
+  return sum;
+}

package/src/checksums/mod97.ts

@@ -0,0 +1,91 @@
+/**
+ * Mod-97 checksums.
+ *
+ * Two distinct users in Stage 1:
+ *   • IBAN (ISO 13616) — rearrange, transliterate, remainder must be 1.
+ *   • France's NIR and Belgium's Rijksregisternummer — a two-digit key that
+ *     is the complement of the payload mod 97.
+ *
+ * Both need modular arithmetic over numbers far wider than a JS `number`: a
+ * 34-character IBAN transliterates to as many as 68 decimal digits. Rather
+ * than reach for BigInt — which allocates per operation and is markedly
+ * slower in the hot path of scanning arbitrary text — this computes the
+ * remainder by streaming the digit string in chunks that always stay inside
+ * the 2^53 safe-integer range.
+ */
+
+import { isAllDigits, toNumericString } from './digits.js';
+
+/**
+ * Remainder of a decimal string modulo `modulus`, for arbitrarily long input.
+ *
+ * Processes at most 13 new digits per step. The running remainder is below
+ * `modulus` (≤ 97 here, but the bound holds for any modulus under 10^4), so
+ * `remainder × 10^13 + chunk` stays well under Number.MAX_SAFE_INTEGER.
+ *
+ * Returns `null` if the string is empty or contains a non-digit.
+ */
+export function modString(numeric: string, modulus: number): number | null {
+  if (modulus <= 0 || modulus > 10_000) return null;
+  if (!isAllDigits(numeric)) return null;
+
+  const CHUNK = 13;
+  let remainder = 0;
+  let i = 0;
+  while (i < numeric.length) {
+    const slice = numeric.slice(i, i + CHUNK);
+    remainder = Number(`${remainder}${slice}`) % modulus;
+    i += slice.length;
+  }
+  return remainder;
+}
+
+/**
+ * Validate an IBAN's mod-97 checksum (ISO 13616 / ISO 7064 MOD 97-10).
+ *
+ * Expects an IBAN already stripped of spaces and uppercased. Country-specific
+ * length and structure rules are NOT checked here — that is the IBAN
+ * detector's per-country table. This function answers exactly one question:
+ * does the checksum close?
+ *
+ * Procedure: move the first four characters (country code + check digits) to
+ * the end, replace each letter with its base-36 value, and take mod 97. A
+ * valid IBAN yields 1.
+ */
+export function ibanMod97Valid(iban: string): boolean {
+  if (iban.length < 5) return false;
+  const rearranged = iban.slice(4) + iban.slice(0, 4);
+  const numeric = toNumericString(rearranged);
+  if (numeric === null) return false;
+  return modString(numeric, 97) === 1;
+}
+
+/**
+ * The two IBAN check digits for a country code and BBAN with no check digits
+ * yet. Returns a zero-padded two-character string, or `null` on bad input.
+ *
+ * Used by the test-vector generators and, from M4, by IBAN surrogate
+ * substitution — SPEC.md requires a substituted IBAN to have a "valid
+ * checksum, same country".
+ */
+export function ibanCheckDigits(countryCode: string, bban: string): string | null {
+  if (countryCode.length !== 2) return null;
+  const numeric = toNumericString(`${bban}${countryCode}00`);
+  if (numeric === null) return null;
+  const remainder = modString(numeric, 97);
+  if (remainder === null) return null;
+  const check = 98 - remainder;
+  return check.toString(10).padStart(2, '0');
+}
+
+/**
+ * The "97 minus remainder" key used by France's NIR and Belgium's national
+ * register number: `97 − (payload mod 97)`, in the range 1..97.
+ *
+ * Returns `null` if the payload is not a decimal string.
+ */
+export function mod97Key(payload: string): number | null {
+  const remainder = modString(payload, 97);
+  if (remainder === null) return null;
+  return 97 - remainder;
+}

package/src/checksums/verhoeff.ts

@@ -0,0 +1,84 @@
+/**
+ * The Verhoeff check digit algorithm.
+ *
+ * Required by India's Aadhaar. Unlike Luhn it is built on the dihedral group
+ * D₅ rather than modular arithmetic, which is why it catches ALL single-digit
+ * errors and ALL adjacent transpositions — including 09↔90, the one case Luhn
+ * misses. That completeness is the whole reason Aadhaar chose it, so the
+ * tests assert both properties exhaustively over generated inputs rather than
+ * spot-checking a few vectors.
+ *
+ * The three tables below are the standard published ones:
+ *   d — the D₅ Cayley (multiplication) table
+ *   p — the permutation table, applied position-dependently
+ *   inv — the multiplicative inverse used to derive a check digit
+ */
+
+import { toDigits } from './digits.js';
+
+/** D₅ multiplication table. */
+const D: readonly (readonly number[])[] = [
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+  [1, 2, 3, 4, 0, 6, 7, 8, 9, 5],
+  [2, 3, 4, 0, 1, 7, 8, 9, 5, 6],
+  [3, 4, 0, 1, 2, 8, 9, 5, 6, 7],
+  [4, 0, 1, 2, 3, 9, 5, 6, 7, 8],
+  [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
+  [6, 5, 9, 8, 7, 1, 0, 4, 3, 2],
+  [7, 6, 5, 9, 8, 2, 1, 0, 4, 3],
+  [8, 7, 6, 5, 9, 3, 2, 1, 0, 4],
+  [9, 8, 7, 6, 5, 4, 3, 2, 1, 0],
+];
+
+/** Permutation table; row index is position mod 8. */
+const P: readonly (readonly number[])[] = [
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+  [1, 5, 7, 6, 2, 8, 3, 0, 9, 4],
+  [5, 8, 0, 3, 7, 9, 6, 1, 4, 2],
+  [8, 9, 1, 6, 0, 4, 3, 5, 2, 7],
+  [9, 4, 5, 3, 1, 2, 6, 8, 7, 0],
+  [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
+  [2, 7, 9, 3, 8, 0, 6, 4, 1, 5],
+  [7, 0, 4, 6, 9, 1, 3, 2, 5, 8],
+];
+
+/** Multiplicative inverse in D₅. */
+const INV: readonly number[] = [0, 4, 3, 2, 1, 5, 6, 7, 8, 9];
+
+/**
+ * Validate a complete digit string (payload plus trailing check digit).
+ *
+ * Returns `false` for non-digit input or fewer than two digits.
+ */
+export function verhoeffValid(value: string): boolean {
+  const digits = toDigits(value);
+  if (digits === null || digits.length < 2) return false;
+  return verhoeffInterim(digits) === 0;
+}
+
+/**
+ * The Verhoeff check digit for a payload that does NOT include one.
+ *
+ * Returns `null` if the payload is not all digits.
+ */
+export function verhoeffCheckDigit(payload: string): number | null {
+  const digits = toDigits(payload);
+  if (digits === null) return null;
+  // Shift by one position by appending a zero, then invert the interim value.
+  const c = verhoeffInterim([...digits, 0]);
+  return INV[c]!;
+}
+
+/**
+ * Fold the digits right-to-left through the permutation and D₅ tables.
+ * The result is 0 exactly when the number carries a correct check digit.
+ */
+function verhoeffInterim(digits: readonly number[]): number {
+  let c = 0;
+  const reversed = [...digits].reverse();
+  for (let i = 0; i < reversed.length; i++) {
+    const permuted = P[i % 8]![reversed[i]!]!;
+    c = D[c]![permuted]!;
+  }
+  return c;
+}