@stll/stdnum 2.0.1 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/stdnum",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "description": "Validate, compact, and format standard identifiers for Node.js and Bun. Pure TypeScript, zero dependencies, tree-shakeable per identifier.",
   "keywords": [
     "credit-card",
@@ -247,6 +247,26 @@
       "import": "./dist/creditcard.js",
       "default": "./dist/creditcard.js"
     },
+    "./crypto/btcbase58": {
+      "types": "./dist/crypto/btcbase58.d.ts",
+      "import": "./dist/crypto/btcbase58.js",
+      "default": "./dist/crypto/btcbase58.js"
+    },
+    "./crypto/btcbech32": {
+      "types": "./dist/crypto/btcbech32.d.ts",
+      "import": "./dist/crypto/btcbech32.js",
+      "default": "./dist/crypto/btcbech32.js"
+    },
+    "./crypto/eth": {
+      "types": "./dist/crypto/eth.d.ts",
+      "import": "./dist/crypto/eth.js",
+      "default": "./dist/crypto/eth.js"
+    },
+    "./crypto/wallet": {
+      "types": "./dist/crypto/wallet.d.ts",
+      "import": "./dist/crypto/wallet.js",
+      "default": "./dist/crypto/wallet.js"
+    },
     "./cu/ni": {
       "types": "./dist/cu/ni.d.ts",
       "import": "./dist/cu/ni.js",
@@ -412,6 +432,11 @@
       "import": "./dist/fr/tva.js",
       "default": "./dist/fr/tva.js"
     },
+    "./gb/nhs": {
+      "types": "./dist/gb/nhs.d.ts",
+      "import": "./dist/gb/nhs.js",
+      "default": "./dist/gb/nhs.js"
+    },
     "./gb/nino": {
       "types": "./dist/gb/nino.d.ts",
       "import": "./dist/gb/nino.js",
@@ -925,7 +950,7 @@
     "@brazilian-utils/brazilian-utils": "^2.3.0",
     "@stll/oxlint-config": "^0.3.0",
     "@stll/typescript-config": "^0.3.0",
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.2",
     "bun-types": "^1.3.14",
     "fast-check": "^4.8.0",
     "fast-luhn": "^2.0.2",
@@ -933,13 +958,13 @@
     "ibantools": "^4.5.4",
     "jsvat": "^2.5.4",
     "luhn": "^2.4.1",
-    "oxfmt": "^0.52.0",
+    "oxfmt": "^0.53.0",
     "oxlint": "^1.67.0",
     "oxlint-tsgolint": "^0.23.0",
     "rut.js": "^2.1.0",
-    "stdnum": "^1.11.14",
-    "tsdown": "0.22.1",
-    "typescript": "^5.9.3",
+    "stdnum": "^1.12.0",
+    "tsdown": "0.22.2",
+    "typescript": "^6.0.3",
     "validate-polish": "^2.1.40"
   },
   "engines": {

package/src/_checksums/keccak.ts

@@ -0,0 +1,145 @@
+const MASK_64 = (1n << 64n) - 1n;
+
+const ROUND_CONSTANTS = [
+  0x0000000000000001n,
+  0x0000000000008082n,
+  0x800000000000808an,
+  0x8000000080008000n,
+  0x000000000000808bn,
+  0x0000000080000001n,
+  0x8000000080008081n,
+  0x8000000000008009n,
+  0x000000000000008an,
+  0x0000000000000088n,
+  0x0000000080008009n,
+  0x000000008000000an,
+  0x000000008000808bn,
+  0x800000000000008bn,
+  0x8000000000008089n,
+  0x8000000000008003n,
+  0x8000000000008002n,
+  0x8000000000000080n,
+  0x000000000000800an,
+  0x800000008000000an,
+  0x8000000080008081n,
+  0x8000000000008080n,
+  0x0000000080000001n,
+  0x8000000080008008n,
+] as const;
+
+const ROTATION_OFFSETS = [
+  0, 1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39,
+  41, 45, 15, 21, 8, 18, 2, 61, 56, 14,
+] as const;
+
+const RATE_BYTES = 136;
+
+const rotl64 = (value: bigint, shift: number): bigint => {
+  if (shift === 0) return value & MASK_64;
+  const bigShift = BigInt(shift);
+  return (
+    ((value << bigShift) | (value >> (64n - bigShift))) &
+    MASK_64
+  );
+};
+
+const keccakF1600 = (state: bigint[]): void => {
+  const c = Array.from({ length: 5 }, () => 0n);
+  const d = Array.from({ length: 5 }, () => 0n);
+  const b = Array.from({ length: 25 }, () => 0n);
+
+  for (const roundConstant of ROUND_CONSTANTS) {
+    for (let x = 0; x < 5; x += 1) {
+      c[x] =
+        (state[x] ?? 0n) ^
+        (state[x + 5] ?? 0n) ^
+        (state[x + 10] ?? 0n) ^
+        (state[x + 15] ?? 0n) ^
+        (state[x + 20] ?? 0n);
+    }
+
+    for (let x = 0; x < 5; x += 1) {
+      d[x] =
+        (c[(x + 4) % 5] ?? 0n) ^
+        rotl64(c[(x + 1) % 5] ?? 0n, 1);
+    }
+
+    for (let y = 0; y < 5; y += 1) {
+      for (let x = 0; x < 5; x += 1) {
+        const index = x + 5 * y;
+        state[index] =
+          ((state[index] ?? 0n) ^ (d[x] ?? 0n)) & MASK_64;
+      }
+    }
+
+    for (let y = 0; y < 5; y += 1) {
+      for (let x = 0; x < 5; x += 1) {
+        const sourceIndex = x + 5 * y;
+        const targetIndex = y + 5 * ((2 * x + 3 * y) % 5);
+        b[targetIndex] = rotl64(
+          state[sourceIndex] ?? 0n,
+          ROTATION_OFFSETS[sourceIndex] ?? 0,
+        );
+      }
+    }
+
+    for (let y = 0; y < 5; y += 1) {
+      for (let x = 0; x < 5; x += 1) {
+        const index = x + 5 * y;
+        state[index] =
+          ((b[index] ?? 0n) ^
+            (~(b[((x + 1) % 5) + 5 * y] ?? 0n) &
+              (b[((x + 2) % 5) + 5 * y] ?? 0n))) &
+          MASK_64;
+      }
+    }
+
+    state[0] = ((state[0] ?? 0n) ^ roundConstant) & MASK_64;
+  }
+};
+
+export const keccak256 = (
+  bytes: Uint8Array,
+): Uint8Array => {
+  const state = Array.from({ length: 25 }, () => 0n);
+  let offset = 0;
+
+  while (offset + RATE_BYTES <= bytes.length) {
+    for (let i = 0; i < RATE_BYTES; i += 1) {
+      const lane = Math.floor(i / 8);
+      const shift = BigInt((i % 8) * 8);
+      state[lane] =
+        ((state[lane] ?? 0n) ^
+          (BigInt(bytes[offset + i] ?? 0) << shift)) &
+        MASK_64;
+    }
+    keccakF1600(state);
+    offset += RATE_BYTES;
+  }
+
+  const block = new Uint8Array(RATE_BYTES);
+  block.set(bytes.slice(offset));
+  block[bytes.length - offset] = 0x01;
+  block[RATE_BYTES - 1] =
+    (block[RATE_BYTES - 1] ?? 0) ^ 0x80;
+
+  for (let i = 0; i < RATE_BYTES; i += 1) {
+    const lane = Math.floor(i / 8);
+    const shift = BigInt((i % 8) * 8);
+    state[lane] =
+      ((state[lane] ?? 0n) ^
+        (BigInt(block[i] ?? 0) << shift)) &
+      MASK_64;
+  }
+  keccakF1600(state);
+
+  const digest = new Uint8Array(32);
+  for (let i = 0; i < digest.length; i += 1) {
+    const lane = Math.floor(i / 8);
+    const shift = BigInt((i % 8) * 8);
+    digest[i] = Number(
+      ((state[lane] ?? 0n) >> shift) & 0xffn,
+    );
+  }
+  return digest;
+};

package/src/_checksums/sha256.ts

@@ -0,0 +1,125 @@
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5,
+  0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+  0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc,
+  0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
+  0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3,
+  0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5,
+  0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+  0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+const rotr = (value: number, bits: number): number =>
+  (value >>> bits) | (value << (32 - bits));
+
+export const sha256 = (bytes: Uint8Array): Uint8Array => {
+  const bitLength = bytes.length * 8;
+  const messageLength = bytes.length + 1;
+  const paddingLength =
+    (64 - ((messageLength + 8) % 64)) % 64;
+  const totalLength = messageLength + paddingLength + 8;
+  const message = new Uint8Array(totalLength);
+  message.set(bytes);
+  message[bytes.length] = 0x80;
+
+  const high = Math.floor(bitLength / 0x1_0000_0000);
+  const low = bitLength >>> 0;
+  message[totalLength - 8] = high >>> 24;
+  message[totalLength - 7] = high >>> 16;
+  message[totalLength - 6] = high >>> 8;
+  message[totalLength - 5] = high;
+  message[totalLength - 4] = low >>> 24;
+  message[totalLength - 3] = low >>> 16;
+  message[totalLength - 2] = low >>> 8;
+  message[totalLength - 1] = low;
+
+  let h0 = 0x6a09e667;
+  let h1 = 0xbb67ae85;
+  let h2 = 0x3c6ef372;
+  let h3 = 0xa54ff53a;
+  let h4 = 0x510e527f;
+  let h5 = 0x9b05688c;
+  let h6 = 0x1f83d9ab;
+  let h7 = 0x5be0cd19;
+
+  const words = new Uint32Array(64);
+
+  for (let offset = 0; offset < totalLength; offset += 64) {
+    for (let i = 0; i < 16; i += 1) {
+      const j = offset + i * 4;
+      words[i] =
+        ((message[j] ?? 0) << 24) |
+        ((message[j + 1] ?? 0) << 16) |
+        ((message[j + 2] ?? 0) << 8) |
+        (message[j + 3] ?? 0);
+    }
+
+    for (let i = 16; i < 64; i += 1) {
+      const w2 = words[i - 2] ?? 0;
+      const w7 = words[i - 7] ?? 0;
+      const w15 = words[i - 15] ?? 0;
+      const w16 = words[i - 16] ?? 0;
+      const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ (w15 >>> 3);
+      const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ (w2 >>> 10);
+      words[i] = (w16 + s0 + w7 + s1) >>> 0;
+    }
+
+    let a = h0;
+    let b = h1;
+    let c = h2;
+    let d = h3;
+    let e = h4;
+    let f = h5;
+    let g = h6;
+    let h = h7;
+
+    for (let i = 0; i < 64; i += 1) {
+      const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const temp1 =
+        (h + s1 + ch + (K[i] ?? 0) + (words[i] ?? 0)) >>> 0;
+      const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const temp2 = (s0 + maj) >>> 0;
+
+      h = g;
+      g = f;
+      f = e;
+      e = (d + temp1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (temp1 + temp2) >>> 0;
+    }
+
+    h0 = (h0 + a) >>> 0;
+    h1 = (h1 + b) >>> 0;
+    h2 = (h2 + c) >>> 0;
+    h3 = (h3 + d) >>> 0;
+    h4 = (h4 + e) >>> 0;
+    h5 = (h5 + f) >>> 0;
+    h6 = (h6 + g) >>> 0;
+    h7 = (h7 + h) >>> 0;
+  }
+
+  const digest = new Uint8Array(32);
+  const hash = [h0, h1, h2, h3, h4, h5, h6, h7];
+  for (let i = 0; i < hash.length; i += 1) {
+    const value = hash[i] ?? 0;
+    const j = i * 4;
+    digest[j] = value >>> 24;
+    digest[j + 1] = value >>> 16;
+    digest[j + 2] = value >>> 8;
+    digest[j + 3] = value;
+  }
+
+  return digest;
+};

package/src/_util/clean.ts

@@ -63,7 +63,12 @@ const CHAR_REGEX = new RegExp(
 
 /**
  * Normalize Unicode artifacts to ASCII
- * equivalents and strip the given characters.
+ * equivalents, strip the given characters, and
+ * remove surrounding whitespace.
+ *
+ * The trailing trim removes whitespace outside the
+ * separator set (newlines, tabs) so validators
+ * accept copy-pasted input.
  *
  * @param value - The input string
  * @param strip - Characters to remove
@@ -82,5 +87,5 @@ export const clean = (
       result = result.replaceAll(ch, "");
     }
   }
-  return result;
+  return result.trim();
 };

package/src/crypto/btcbase58.ts

@@ -0,0 +1,144 @@
+/**
+ * Bitcoin Base58Check address.
+ *
+ * Validates legacy mainnet P2PKH and P2SH Bitcoin
+ * addresses, including the double-SHA-256 checksum.
+ */
+
+import type {
+  GlobalValidator,
+  ValidateResult,
+} from "../types";
+
+import { sha256 } from "#checksums/sha256";
+import { clean } from "#util/clean";
+import { err } from "#util/result";
+
+const BASE58_ALPHABET =
+  "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+
+const MIN_LENGTH = 26;
+const MAX_LENGTH = 35;
+const DECODED_ADDRESS_LENGTH = 25;
+const CHECKSUM_LENGTH = 4;
+const MAINNET_P2PKH_VERSION = 0x00;
+const MAINNET_P2SH_VERSION = 0x05;
+
+const compact = (value: string): string =>
+  clean(value, " ");
+
+const decodeBase58 = (value: string): Uint8Array | null => {
+  let decoded = 0n;
+  for (const ch of value) {
+    const digit = BASE58_ALPHABET.indexOf(ch);
+    if (digit === -1) return null;
+    decoded = decoded * 58n + BigInt(digit);
+  }
+
+  const bytes: number[] = [];
+  while (decoded > 0n) {
+    bytes.push(Number(decoded & 0xffn));
+    decoded >>= 8n;
+  }
+  bytes.reverse();
+
+  let leadingZeros = 0;
+  while (value.charAt(leadingZeros) === "1") {
+    leadingZeros += 1;
+  }
+
+  const result = new Uint8Array(
+    leadingZeros + bytes.length,
+  );
+  result.set(bytes, leadingZeros);
+  return result;
+};
+
+const hasValidChecksum = (decoded: Uint8Array): boolean => {
+  if (decoded.length <= CHECKSUM_LENGTH) return false;
+
+  const payload = decoded.slice(0, -CHECKSUM_LENGTH);
+  const checksum = decoded.slice(-CHECKSUM_LENGTH);
+  const digest = sha256(sha256(payload));
+
+  for (let i = 0; i < CHECKSUM_LENGTH; i += 1) {
+    if (checksum[i] !== digest[i]) return false;
+  }
+  return true;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length < MIN_LENGTH || v.length > MAX_LENGTH) {
+    return err(
+      "INVALID_LENGTH",
+      "Bitcoin Base58Check address must be 26-35 characters",
+    );
+  }
+  if (!/^[13]/.test(v)) {
+    return err(
+      "INVALID_COMPONENT",
+      "Bitcoin Base58Check address must start with 1 or 3",
+    );
+  }
+
+  const decoded = decodeBase58(v);
+  if (decoded === null) {
+    return err(
+      "INVALID_FORMAT",
+      "Bitcoin Base58Check address contains invalid characters",
+    );
+  }
+  if (decoded.length !== DECODED_ADDRESS_LENGTH) {
+    return err(
+      "INVALID_LENGTH",
+      "Bitcoin Base58Check address decoded payload must be 25 bytes",
+    );
+  }
+
+  const version = decoded[0];
+  if (
+    version !== MAINNET_P2PKH_VERSION &&
+    version !== MAINNET_P2SH_VERSION
+  ) {
+    return err(
+      "INVALID_COMPONENT",
+      "Bitcoin Base58Check address has an unsupported version",
+    );
+  }
+
+  if (!hasValidChecksum(decoded)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Bitcoin Base58Check address fails checksum validation",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+const btcBase58: GlobalValidator = {
+  scope: "global",
+  name: "Bitcoin Base58Check Address",
+  localName: "Bitcoin Base58Check Address",
+  abbreviation: "BTC",
+  aliases: [
+    "Bitcoin address",
+    "Bitcoin legacy address",
+    "Base58Check address",
+  ] as const,
+  candidatePattern: "[13][1-9A-HJ-NP-Za-km-z]{25,34}",
+  entityType: "any",
+  examples: [
+    "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
+    "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",
+  ] as const,
+  compact,
+  format,
+  validate,
+};
+
+export default btcBase58;
+export { compact, decodeBase58, format, validate };