@stll/stdnum 2.0.1 → 2.1.1

package/src/crypto/btcbech32.ts

@@ -0,0 +1,210 @@
+/**
+ * Bitcoin Bech32/Bech32m address.
+ *
+ * Validates mainnet SegWit addresses with the
+ * Bech32 checksum for v0 and Bech32m for v1+.
+ */
+
+import type {
+  GlobalValidator,
+  ValidateResult,
+} from "../types";
+
+import { clean } from "#util/clean";
+import { err } from "#util/result";
+
+const CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
+const GENERATORS = [
+  0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd,
+  0x2a1462b3,
+] as const;
+const BECH32_CONST = 1;
+const BECH32M_CONST = 0x2bc830a3;
+const CHECKSUM_LENGTH = 6;
+const MIN_DATA_LENGTH = 11;
+const MAX_DATA_LENGTH = 71;
+const BC_HRP_EXPANSION = [3, 3, 0, 2, 3] as const;
+
+const compact = (value: string): string =>
+  clean(value, " ").toLowerCase();
+
+const polymod = (values: readonly number[]): number => {
+  let chk = 1;
+  for (const value of values) {
+    const top = chk >>> 25;
+    chk = (((chk & 0x1ffffff) << 5) ^ value) >>> 0;
+    for (let i = 0; i < GENERATORS.length; i += 1) {
+      const generator = GENERATORS[i] ?? 0;
+      if (((top >>> i) & 1) === 1) {
+        chk = (chk ^ generator) >>> 0;
+      }
+    }
+  }
+  return chk >>> 0;
+};
+
+const dataValues = (data: string): number[] | null => {
+  const values: number[] = [];
+  for (const ch of data) {
+    const value = CHARSET.indexOf(ch);
+    if (value === -1) return null;
+    values.push(value);
+  }
+  return values;
+};
+
+const convertBits = (
+  values: readonly number[],
+  fromBits: number,
+  toBits: number,
+): number[] | null => {
+  let accumulator = 0;
+  let bits = 0;
+  const maxValue = (1 << toBits) - 1;
+  const result: number[] = [];
+
+  for (const value of values) {
+    if (value < 0 || value >>> fromBits !== 0) return null;
+    accumulator = (accumulator << fromBits) | value;
+    bits += fromBits;
+    while (bits >= toBits) {
+      bits -= toBits;
+      result.push((accumulator >>> bits) & maxValue);
+    }
+  }
+
+  if (bits >= fromBits) return null;
+  if (((accumulator << (toBits - bits)) & maxValue) !== 0) {
+    return null;
+  }
+
+  return result;
+};
+
+type Bech32Validation =
+  | { valid: true }
+  | {
+      valid: false;
+      code: "format" | "checksum" | "component";
+    };
+
+const validateBech32 = (
+  rawValue: string,
+): Bech32Validation => {
+  const hasLower = /[a-z]/.test(rawValue);
+  const hasUpper = /[A-Z]/.test(rawValue);
+  if (hasLower && hasUpper)
+    return { valid: false, code: "format" };
+
+  const v = rawValue.toLowerCase();
+  if (!v.startsWith("bc1"))
+    return { valid: false, code: "component" };
+
+  const data = v.slice(3);
+  if (
+    data.length < MIN_DATA_LENGTH ||
+    data.length > MAX_DATA_LENGTH
+  ) {
+    return { valid: false, code: "format" };
+  }
+
+  const values = dataValues(data);
+  if (values === null)
+    return { valid: false, code: "format" };
+
+  const expanded: number[] = Array.from(BC_HRP_EXPANSION);
+  for (const value of values) {
+    expanded.push(value);
+  }
+  const check = polymod(expanded);
+
+  const version = values[0];
+  if (version === undefined || version > 16) {
+    return { valid: false, code: "component" };
+  }
+
+  if (version === 0 && check !== BECH32_CONST) {
+    return { valid: false, code: "checksum" };
+  }
+  if (version > 0 && check !== BECH32M_CONST) {
+    return { valid: false, code: "checksum" };
+  }
+
+  const programValues = values.slice(1, -CHECKSUM_LENGTH);
+  const program = convertBits(programValues, 5, 8);
+  if (
+    program === null ||
+    program.length < 2 ||
+    program.length > 40
+  ) {
+    return { valid: false, code: "component" };
+  }
+
+  if (
+    version === 0 &&
+    program.length !== 20 &&
+    program.length !== 32
+  ) {
+    return { valid: false, code: "component" };
+  }
+
+  return { valid: true };
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  const result = validateBech32(clean(value, " "));
+  if (result.valid) return { valid: true, compact: v };
+
+  if (result.code === "component") {
+    return err(
+      "INVALID_COMPONENT",
+      "Bitcoin Bech32 address has an unsupported component",
+    );
+  }
+  if (result.code === "checksum") {
+    return err(
+      "INVALID_CHECKSUM",
+      "Bitcoin Bech32 address fails checksum validation",
+    );
+  }
+  return err(
+    "INVALID_FORMAT",
+    "Bitcoin Bech32 address has an invalid format",
+  );
+};
+
+const format = (value: string): string => compact(value);
+
+const btcBech32: GlobalValidator = {
+  scope: "global",
+  name: "Bitcoin Bech32 Address",
+  localName: "Bitcoin Bech32 Address",
+  abbreviation: "BTC",
+  aliases: [
+    "Bitcoin address",
+    "Bitcoin SegWit address",
+    "Bech32 address",
+    "Bech32m address",
+  ] as const,
+  candidatePattern:
+    "(?:bc1[ac-hj-np-z02-9]{11,71}|BC1[AC-HJ-NP-Z02-9]{11,71})",
+  entityType: "any",
+  examples: [
+    "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
+    "bc1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3qccfmv3",
+  ] as const,
+  compact,
+  format,
+  validate,
+};
+
+export default btcBech32;
+export {
+  compact,
+  convertBits,
+  format,
+  polymod,
+  validate,
+  validateBech32,
+};

package/src/crypto/eth.ts

@@ -0,0 +1,114 @@
+/**
+ * Ethereum address.
+ *
+ * Validates the canonical 0x-prefixed 20-byte
+ * hexadecimal address shape. The compact form is
+ * lowercased so checksummed and non-checksummed
+ * variants of the same address compare equal.
+ */
+
+import type {
+  GlobalValidator,
+  ValidateResult,
+} from "../types";
+
+import { keccak256 } from "#checksums/keccak";
+import { clean } from "#util/clean";
+import { err } from "#util/result";
+
+const ETH_ADDRESS_LENGTH = 42;
+const HEX_PREFIX_LENGTH = 2;
+
+const compact = (value: string): string =>
+  clean(value, " ").toLowerCase();
+
+const asciiBytes = (value: string): Uint8Array => {
+  const bytes = new Uint8Array(value.length);
+  for (let i = 0; i < value.length; i += 1) {
+    bytes[i] = value.charCodeAt(i);
+  }
+  return bytes;
+};
+
+const hexBytes = (bytes: Uint8Array): string => {
+  let result = "";
+  for (const byte of bytes) {
+    result += byte.toString(16).padStart(2, "0");
+  }
+  return result;
+};
+
+const isMixedCase = (value: string): boolean =>
+  /[a-f]/.test(value) && /[A-F]/.test(value);
+
+const hasValidEip55Checksum = (
+  address: string,
+): boolean => {
+  const body = address.slice(HEX_PREFIX_LENGTH);
+  if (!isMixedCase(body)) return true;
+
+  const lower = body.toLowerCase();
+  const hash = hexBytes(keccak256(asciiBytes(lower)));
+
+  for (let i = 0; i < body.length; i += 1) {
+    const ch = body.charAt(i);
+    if (/\d/.test(ch)) continue;
+
+    const nibble = Number.parseInt(hash.charAt(i), 16);
+    const expected =
+      nibble >= 8 ? ch.toUpperCase() : ch.toLowerCase();
+    if (ch !== expected) return false;
+  }
+
+  return true;
+};
+
+const validate = (value: string): ValidateResult => {
+  const raw = clean(value, " ");
+  const v = raw.toLowerCase();
+  if (v.length !== ETH_ADDRESS_LENGTH) {
+    return err(
+      "INVALID_LENGTH",
+      "Ethereum address must be 42 characters",
+    );
+  }
+  if (!/^0x[0-9a-f]{40}$/i.test(raw)) {
+    return err(
+      "INVALID_FORMAT",
+      "Ethereum address must be 0x followed by 40 hexadecimal characters",
+    );
+  }
+  if (!hasValidEip55Checksum(raw)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Ethereum address fails EIP-55 checksum validation",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+const eth: GlobalValidator = {
+  scope: "global",
+  name: "Ethereum Address",
+  localName: "Ethereum Address",
+  abbreviation: "ETH",
+  aliases: [
+    "Ethereum address",
+    "EVM address",
+    "crypto wallet",
+  ] as const,
+  candidatePattern: "0x[0-9A-Fa-f]{40}",
+  entityType: "any",
+  examples: [
+    "0xde709f2102306220921060314715629080e2fb77",
+  ] as const,
+  lengths: [ETH_ADDRESS_LENGTH] as const,
+  compact,
+  format,
+  validate,
+};
+
+export default eth;
+export { compact, format, hasValidEip55Checksum, validate };

package/src/crypto/mod.ts

@@ -0,0 +1,4 @@
+export { default as btcbase58 } from "./btcbase58";
+export { default as btcbech32 } from "./btcbech32";
+export { default as eth } from "./eth";
+export { default as wallet } from "./wallet";

package/src/crypto/wallet.ts

@@ -0,0 +1,67 @@
+/**
+ * Cryptocurrency wallet address.
+ *
+ * Convenience validator for supported wallet address
+ * families. Use the specific validators when the
+ * network or format must be known.
+ */
+
+import type {
+  GlobalValidator,
+  ValidateResult,
+} from "../types";
+import btcBase58 from "./btcbase58";
+import btcBech32 from "./btcbech32";
+import eth from "./eth";
+
+const validators = [eth, btcBech32, btcBase58] as const;
+
+const compact = (value: string): string => {
+  for (const validator of validators) {
+    const result = validator.validate(value);
+    if (result.valid) return result.compact;
+  }
+  return value.trim();
+};
+
+const validate = (value: string): ValidateResult => {
+  for (const validator of validators) {
+    const result = validator.validate(value);
+    if (result.valid) return result;
+  }
+  return {
+    valid: false,
+    error: {
+      code: "INVALID_FORMAT",
+      message: "Unsupported cryptocurrency wallet address",
+    },
+  };
+};
+
+const format = (value: string): string => compact(value);
+
+const wallet: GlobalValidator = {
+  scope: "global",
+  name: "Cryptocurrency Wallet Address",
+  localName: "Cryptocurrency Wallet Address",
+  abbreviation: "crypto",
+  aliases: [
+    "crypto address",
+    "wallet address",
+    "cryptocurrency wallet",
+  ] as const,
+  candidatePattern:
+    "(?:0x[0-9A-Fa-f]{40}|[13][1-9A-HJ-NP-Za-km-z]{25,34}|bc1[ac-hj-np-z02-9]{11,71}|BC1[AC-HJ-NP-Z02-9]{11,71})",
+  entityType: "any",
+  examples: [
+    "0xde709f2102306220921060314715629080e2fb77",
+    "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
+    "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
+  ] as const,
+  compact,
+  format,
+  validate,
+};
+
+export default wallet;
+export { compact, format, validate };

package/src/gb/mod.ts

@@ -1,3 +1,4 @@
+export { default as nhs } from "./nhs";
 export { default as nino } from "./nino";
 export { default as sedol } from "./sedol";
 export { default as utr } from "./utr";

package/src/gb/nhs.ts

@@ -0,0 +1,92 @@
+/**
+ * UK NHS Number.
+ *
+ * Validates the 10-digit NHS number using the
+ * modulus 11 checksum used by NHS England.
+ */
+
+import type {
+  CountryValidator,
+  ValidateResult,
+} from "../types";
+
+import { clean } from "#util/clean";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
+const NHS_NUMBER_LENGTH = 10;
+const CHECK_DIGIT_INDEX = 9;
+
+const compact = (value: string): string =>
+  clean(value, " ");
+
+const calcCheckDigit = (value: string): number | null => {
+  if (value.length !== NHS_NUMBER_LENGTH) return null;
+  if (!isdigits(value)) return null;
+
+  let total = 0;
+  for (let i = 0; i < CHECK_DIGIT_INDEX; i += 1) {
+    total += Number(value.charAt(i)) * (10 - i);
+  }
+
+  const check = 11 - (total % 11);
+  if (check === 10) return null;
+  return check === 11 ? 0 : check;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== NHS_NUMBER_LENGTH) {
+    return err(
+      "INVALID_LENGTH",
+      "NHS number must be 10 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "NHS number must contain only digits",
+    );
+  }
+
+  const check = calcCheckDigit(v);
+  if (
+    check === null ||
+    check !== Number(v.charAt(CHECK_DIGIT_INDEX))
+  ) {
+    return err(
+      "INVALID_CHECKSUM",
+      "NHS number fails modulus 11 check",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  if (v.length !== NHS_NUMBER_LENGTH) return v;
+  return `${v.slice(0, 3)} ${v.slice(3, 6)} ${v.slice(6)}`;
+};
+
+const nhs: CountryValidator<"GB"> = {
+  scope: "country",
+  country: "GB",
+  name: "UK NHS Number",
+  localName: "NHS number",
+  abbreviation: "NHS",
+  aliases: [
+    "NHS number",
+    "National Health Service number",
+  ] as const,
+  candidatePattern: "\\d{3}\\s?\\d{3}\\s?\\d{4}",
+  entityType: "person",
+  lengths: [NHS_NUMBER_LENGTH] as const,
+  examples: ["4010232137"] as const,
+  compact,
+  format,
+  validate,
+};
+
+export default nhs;
+export { calcCheckDigit, compact, format, validate };

package/src/index.ts

@@ -23,6 +23,7 @@ export { default as isin } from "./isin";
 export { default as lei } from "./lei";
 export { default as luhn } from "./luhn";
 
+export * as crypto from "./crypto/mod";
 export * as ad from "./ad/mod";
 export * as ae from "./ae/mod";
 export * as ai from "./ai/mod";