@stll/stdnum 2.0.1 → 2.1.0

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";