@pezkuwi/util-crypto 14.0.21 → 14.0.23

package/src/address/setSS58Format.ts

@@ -0,0 +1,20 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Prefix } from './types.js';
+
+import { logger } from '@pezkuwi/util';
+
+import { defaults } from './defaults.js';
+
+const l = logger('setSS58Format');
+
+/**
+ * @description Sets the global SS58 format to use for address encoding
+ * @deprecated Use keyring.setSS58Format
+ */
+export function setSS58Format (prefix: Prefix): void {
+  l.warn('Global setting of the ss58Format is deprecated and not recommended. Set format on the keyring (if used) or as part of the address encode function');
+
+  defaults.prefix = prefix;
+}

package/src/address/sort.spec.ts

@@ -0,0 +1,22 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { sortAddresses } from './index.js';
+
+describe('sortAddresses', (): void => {
+  it('sorts addresses by the publicKeys', (): void => {
+    expect(
+      sortAddresses([
+        '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY',
+        '5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty',
+        '5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y'
+      ])
+    ).toEqual([
+      '5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty',
+      '5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y',
+      '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY'
+    ]);
+  });
+});

package/src/address/sort.ts

@@ -0,0 +1,17 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Prefix } from './types.js';
+
+import { u8aSorted } from '@pezkuwi/util';
+
+import { encodeAddress } from './encode.js';
+import { addressToU8a } from './util.js';
+
+export function sortAddresses (addresses: (string | Uint8Array)[], ss58Format?: Prefix): string[] {
+  const u8aToAddress = (u8a: Uint8Array) => encodeAddress(u8a, ss58Format);
+
+  return u8aSorted(
+    addresses.map(addressToU8a)
+  ).map(u8aToAddress);
+}

package/src/address/sshash.ts

@@ -0,0 +1,12 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { stringToU8a, u8aConcat } from '@pezkuwi/util';
+
+import { blake2AsU8a } from '../blake2/asU8a.js';
+
+const SS58_PREFIX = stringToU8a('SS58PRE');
+
+export function sshash (key: Uint8Array): Uint8Array {
+  return blake2AsU8a(u8aConcat(SS58_PREFIX, key), 512);
+}

package/src/address/types.ts

@@ -0,0 +1,6 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// FIXME we really want this to map with what is in the allowedSS58 array... i.e. the
+// values there. As of now, we just map to number.
+export type Prefix = number;

package/src/address/util.ts

@@ -0,0 +1,8 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { decodeAddress } from './decode.js';
+
+export function addressToU8a (who: string | Uint8Array): Uint8Array {
+  return decodeAddress(who);
+}

package/src/address/validate.spec.ts

@@ -0,0 +1,113 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { validateAddress } from './index.js';
+
+describe('validateAddress', (): void => {
+  it('decodes an address', (): void => {
+    expect(
+      validateAddress('5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY')
+    ).toEqual(true);
+  });
+
+  it('decodes the council address', (): void => {
+    expect(
+      validateAddress('F3opxRbN5ZbjJNU511Kj2TLuzFcDq9BGduA9TgiECafpg29')
+    ).toEqual(true);
+  });
+
+  it('converts a publicKey (hex) as-is', (): void => {
+    expect(
+      validateAddress('0x01020304')
+    ).toEqual(true);
+  });
+
+  it('decodes a short address', (): void => {
+    expect(
+      validateAddress('F7NZ')
+    ).toEqual(true);
+  });
+
+  it('decodes a 1-byte accountId (with prefix)', (): void => {
+    expect(
+      validateAddress('g4b', false, 2)
+    ).toEqual(true);
+  });
+
+  it('decodes a 2-byte accountId', (): void => {
+    expect(
+      validateAddress('3xygo', false, 2)
+    ).toEqual(true);
+  });
+
+  it('encodes a 4-byte address', (): void => {
+    expect(
+      validateAddress('zswfoZa', false, 2)
+    ).toEqual(true);
+  });
+
+  it('decodes a 8-byte address', (): void => {
+    expect(
+      validateAddress('848Gh2GcGaZia', false, 2)
+    ).toEqual(true);
+  });
+
+  it('decodes a 33-byte address', (): void => {
+    expect(
+      validateAddress('KWCv1L3QX9LDPwY4VzvLmarEmXjVJidUzZcinvVnmxAJJCBou')
+    ).toEqual(true);
+  });
+
+  it('decodes a 2-byte prefix (65)', (): void => {
+    expect(
+      validateAddress('cLtA6nCDyvwKcEHH4QkZDSHMhS9s78BvUJUsKUbUAn1Jc2SCF')
+    ).toEqual(true);
+  });
+
+  it('decodes a 2-byte prefix (69)', (): void => {
+    expect(
+      validateAddress('cnUaoo5wodnTVA4bnr4woSweto8hWZADUvLFXkR9Q6U7BRsbF')
+    ).toEqual(true);
+  });
+
+  it('decodes a 2-byte prefix (252)', (): void => {
+    expect(
+      validateAddress('xw9Hca4RJTmBRgzJT4ieJBh7XCK9gE3NXBDSEmgGHd4TCrbnG')
+    ).toEqual(true);
+  });
+
+  it('decodes a 2-byte prefix (255)', (): void => {
+    expect(
+      validateAddress('yGHU8YKprxHbHdEv7oUK4rzMZXtsdhcXVG2CAMyC9WhzhjH2k')
+    ).toEqual(true);
+  });
+
+  it('decodes a 2-byte prefix (ecdsa, from Substrate)', (): void => {
+    expect(
+      validateAddress('4pbsSkWcBaYoFHrKJZp5fDVUKbqSYD9dhZZGvpp3vQ5ysVs5ybV')
+    ).toEqual(true);
+  });
+
+  it('fails when length is invalid', (): void => {
+    expect(
+      () => validateAddress('y9EMHt34JJo4rWLSaxoLGdYXvjgSXEd4zHUnQgfNzwES8b')
+    ).toThrow(/address length/);
+  });
+
+  it('fails when the checksum does not match', (): void => {
+    expect(
+      () => validateAddress('5GoKvZWG5ZPYL1WUovuHW3zJBWBP5eT8CbqjdRY4Q6iMa9cj')
+    ).toThrow(/address checksum/);
+    expect(
+      () => validateAddress('5GoKvZWG5ZPYL1WUovuHW3zJBWBP5eT8CbqjdRY4Q6iMaDwU')
+    ).toThrow(/address checksum/);
+  });
+
+  it('fails when invalid base58 encoded address is found', (): void => {
+    expect(
+      () => validateAddress('F3opIRbN5ZbjJNU511Kj2TLuzFcDq9BGduA9TgiECafpg29')
+    ).toThrow(/Decoding F3opIRbN5ZbjJNU511Kj2TLuzFcDq9BGduA9TgiECafpg29: Invalid base58 character "I" \(0x49\) at index 4/);
+  });
+});

package/src/address/validate.ts

@@ -0,0 +1,10 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Prefix } from './types.js';
+
+import { decodeAddress } from './decode.js';
+
+export function validateAddress (encoded?: string | null, ignoreChecksum?: boolean, ss58Format?: Prefix): encoded is string {
+  return !!decodeAddress(encoded, ignoreChecksum, ss58Format);
+}

package/src/base32/bs32.ts

@@ -0,0 +1,53 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { utils } from '@scure/base';
+
+import { createDecode, createEncode, createIs, createValidate } from './helpers.js';
+
+const chars = 'abcdefghijklmnopqrstuvwxyz234567';
+
+const config = {
+  chars,
+  coder: utils.chain(
+    // We define our own chain, the default base32 has padding
+    utils.radix2(5),
+    utils.alphabet(chars),
+    {
+      decode: (input: string) => input.split(''),
+      encode: (input: string[]) => input.join('')
+    }
+  ),
+  ipfs: 'b',
+  type: 'base32'
+};
+
+/**
+ * @name base32Validate
+ * @summary Validates a base32 value.
+ * @description
+ * Validates that the supplied value is valid base32, throwing exceptions if not
+ */
+export const base32Validate = /*#__PURE__*/ createValidate(config);
+
+/**
+* @name isBase32
+* @description Checks if the input is in base32, returning true/false
+*/
+export const isBase32 = /*#__PURE__*/ createIs(base32Validate);
+
+/**
+ * @name base32Decode
+ * @summary Delookup a base32 value.
+ * @description
+ * From the provided input, decode the base32 and return the result as an `Uint8Array`.
+ */
+export const base32Decode = /*#__PURE__*/ createDecode(config, base32Validate);
+
+/**
+* @name base32Encode
+* @summary Creates a base32 value.
+* @description
+* From the provided input, create the base32 and return the result as a string.
+*/
+export const base32Encode = /*#__PURE__*/ createEncode(config);

package/src/base32/decode.spec.ts

@@ -0,0 +1,34 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { u8aToString } from '@pezkuwi/util';
+
+import { base32Decode } from './index.js';
+
+describe('base32Decode', (): void => {
+  it('decodes an empty string)', (): void => {
+    expect(
+      u8aToString(
+        base32Decode('')
+      )
+    ).toEqual('');
+  });
+
+  it('decodes a base32', (): void => {
+    expect(
+      u8aToString(
+        base32Decode('irswgzloorzgc3djpjssazlwmvzhs5dinfxgoijb')
+      )
+    ).toEqual('Decentralize everything!!');
+  });
+
+  it('decodes a base32 (ipfsCompat)', (): void => {
+    expect(
+      u8aToString(
+        base32Decode('birswgzloorzgc3djpjssazlwmvzhs5dinfxgoijb', true)
+      )
+    ).toEqual('Decentralize everything!!');
+  });
+});

package/src/base32/encode.spec.ts

@@ -0,0 +1,30 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { base58Decode } from '../base58/index.js';
+import { base32Encode } from './index.js';
+
+describe('base32Encode', (): void => {
+  it('encodes to a base32', (): void => {
+    expect(
+      base32Encode('Decentralize everything!!')
+    ).toEqual('irswgzloorzgc3djpjssazlwmvzhs5dinfxgoijb');
+  });
+
+  it('encodes to a base32 (ipfs-compat)', (): void => {
+    expect(
+      base32Encode('Decentralize everything!!', true)
+    ).toEqual('birswgzloorzgc3djpjssazlwmvzhs5dinfxgoijb');
+  });
+
+  it('encodes a base58 to a base32', (): void => {
+    expect(
+      base32Encode(
+        base58Decode('zb2rhk6GMPQF3hfzwXTaNYFLKomMeC6UXdUt6jZKPpeVirLtV', true),
+        true
+      )
+    ).toEqual('bafkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy');
+  });
+});

package/src/base32/helpers.ts

@@ -0,0 +1,93 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { U8aLike } from '@pezkuwi/util/types';
+
+import { u8aToU8a } from '@pezkuwi/util';
+
+// re-export the type so *.d.ts files don't have ../src imports
+export type { U8aLike } from '@pezkuwi/util/types';
+
+interface Coder {
+  decode: (value: string) => Uint8Array;
+  encode: (value: Uint8Array) => string;
+}
+
+interface Config {
+  chars: string;
+  coder: Coder;
+  ipfs?: string;
+  regex?: RegExp;
+  type: string;
+  withPadding?: boolean;
+}
+
+type DecodeFn = (value: string, ipfsCompat?: boolean) => Uint8Array;
+
+type EncodeFn = (value: U8aLike, ipfsCompat?: boolean) => string;
+
+type ValidateFn = (value?: unknown, ipfsCompat?: boolean) => value is string;
+
+/** @internal */
+export function createDecode ({ coder, ipfs }: Config, validate: ValidateFn): DecodeFn {
+  return (value: string, ipfsCompat?: boolean): Uint8Array => {
+    validate(value, ipfsCompat);
+
+    return coder.decode(
+      ipfs && ipfsCompat
+        ? value.substring(1)
+        : value
+    );
+  };
+}
+
+/** @internal */
+export function createEncode ({ coder, ipfs }: Config): EncodeFn {
+  return (value: U8aLike, ipfsCompat?: boolean): string => {
+    const out = coder.encode(u8aToU8a(value));
+
+    return ipfs && ipfsCompat
+      ? `${ipfs}${out}`
+      : out;
+  };
+}
+
+/** @internal */
+export function createIs (validate: ValidateFn): ValidateFn {
+  return (value?: unknown, ipfsCompat?: boolean): value is string => {
+    try {
+      return validate(value, ipfsCompat);
+    } catch {
+      return false;
+    }
+  };
+}
+
+/** @internal */
+export function createValidate ({ chars, ipfs, type, withPadding }: Config): ValidateFn {
+  return (value?: unknown, ipfsCompat?: boolean): value is string => {
+    if (typeof value !== 'string') {
+      throw new Error(`Expected ${type} string input`);
+    } else if (ipfs && ipfsCompat && !value.startsWith(ipfs)) {
+      throw new Error(`Expected ipfs-compatible ${type} to start with '${ipfs}'`);
+    }
+
+    for (let i = (ipfsCompat ? 1 : 0), count = value.length; i < count; i++) {
+      if (chars.includes(value[i])) {
+        // all ok, character found
+      } else if (withPadding && value[i] === '=') {
+        if (i === count - 1) {
+          // last character, everything ok
+        } else if (value[i + 1] === '=') {
+          // next one is also padding, sequence ok
+        } else {
+          throw new Error(`Invalid ${type} padding sequence "${value[i]}${value[i + 1]}" at index ${i}`);
+        }
+      } else {
+        throw new Error(`Invalid ${type} character "${value[i]}" (0x${value.charCodeAt(i).toString(16)}) at index ${i}`);
+      }
+    }
+
+    return true;
+  };
+}

package/src/base32/index.ts

@@ -0,0 +1,8 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @summary Encode and decode base32 values
+ */
+
+export { base32Decode, base32Encode, base32Validate, isBase32 } from './bs32.js';

package/src/base32/is.spec.ts

@@ -0,0 +1,32 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { isBase32 } from './index.js';
+
+describe('isBase32', (): void => {
+  it('validates encoded', (): void => {
+    expect(
+      isBase32('afkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy', false)
+    ).toEqual(true);
+  });
+
+  it('validates ipfs-compat encoded', (): void => {
+    expect(
+      isBase32('bafkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy', false)
+    ).toEqual(true);
+  });
+
+  it('fails on invalid', (): void => {
+    expect(
+      isBase32('not in base32')
+    ).toEqual(false);
+  });
+
+  it('fails on non-ipfs', (): void => {
+    expect(
+      isBase32('afkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy', true)
+    ).toEqual(false);
+  });
+});

package/src/base32/validate.spec.ts

@@ -0,0 +1,44 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { base32Validate } from './index.js';
+
+describe('base32Validate', (): void => {
+  it('validates encoded', (): void => {
+    expect(
+      base32Validate('afkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy', false)
+    ).toEqual(true);
+  });
+
+  it('validates ipfs-compat encoded', (): void => {
+    expect(
+      base32Validate('bafkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy', true)
+    ).toEqual(true);
+  });
+
+  it('does not fail on empty', (): void => {
+    expect(
+      base32Validate('')
+    ).toEqual(true);
+  });
+
+  it('fails on non-string', (): void => {
+    expect(
+      () => base32Validate(true)
+    ).toThrow(/Expected/);
+  });
+
+  it('fails on invalid', (): void => {
+    expect(
+      () => base32Validate('not in base32')
+    ).toThrow(/Invalid/);
+  });
+
+  it('fails on non-ipfs', (): void => {
+    expect(
+      () => base32Validate('afkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy', true)
+    ).toThrow(/Expected/);
+  });
+});

package/src/base58/bs58.ts

@@ -0,0 +1,43 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { base58 } from '@scure/base';
+
+import { createDecode, createEncode, createIs, createValidate } from '../base32/helpers.js';
+
+const config = {
+  chars: '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz',
+  coder: base58,
+  ipfs: 'z',
+  type: 'base58'
+};
+
+/**
+ * @name base58Validate
+ * @summary Validates a base58 value.
+ * @description
+ * Validates that the supplied value is valid base58, throwing exceptions if not
+ */
+export const base58Validate = /*#__PURE__*/ createValidate(config);
+
+/**
+ * @name base58Decode
+ * @summary Decodes a base58 value.
+ * @description
+ * From the provided input, decode the base58 and return the result as an `Uint8Array`.
+ */
+export const base58Decode = /*#__PURE__*/ createDecode(config, base58Validate);
+
+/**
+* @name base58Encode
+* @summary Creates a base58 value.
+* @description
+* From the provided input, create the base58 and return the result as a string.
+*/
+export const base58Encode = /*#__PURE__*/ createEncode(config);
+
+/**
+* @name isBase58
+* @description Checks if the input is in base58, returning true/false
+*/
+export const isBase58 = /*#__PURE__*/ createIs(base58Validate);

package/src/base58/decode.spec.ts

@@ -0,0 +1,31 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { base32Decode } from '../base32/index.js';
+import { base58Decode } from './index.js';
+
+describe('base58Encode', (): void => {
+  it('decodes an empty string)', (): void => {
+    expect(
+      base58Decode('')
+    ).toEqual(new Uint8Array());
+  });
+
+  it('encodes a base58 to a base32', (): void => {
+    expect(
+      base58Decode('b2rhk6GMPQF3hfzwXTaNYFLKomMeC6UXdUt6jZKPpeVirLtV')
+    ).toEqual(
+      base32Decode('afkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy')
+    );
+  });
+
+  it('encodes a base58 to a base32 (ipfs-compat)', (): void => {
+    expect(
+      base58Decode('zb2rhk6GMPQF3hfzwXTaNYFLKomMeC6UXdUt6jZKPpeVirLtV', true)
+    ).toEqual(
+      base32Decode('bafkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy', true)
+    );
+  });
+});

package/src/base58/encode.spec.ts

@@ -0,0 +1,26 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { base32Decode } from '../base32/index.js';
+import { base58Encode } from './index.js';
+
+describe('base58Encode', (): void => {
+  it('encodes a base32 to a base58', (): void => {
+    expect(
+      base58Encode(
+        base32Decode('bafkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy', true)
+      )
+    ).toEqual('b2rhk6GMPQF3hfzwXTaNYFLKomMeC6UXdUt6jZKPpeVirLtV');
+  });
+
+  it('encodes a base32 to a base58 (ipfs-compat)', (): void => {
+    expect(
+      base58Encode(
+        base32Decode('bafkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy', true),
+        true
+      )
+    ).toEqual('zb2rhk6GMPQF3hfzwXTaNYFLKomMeC6UXdUt6jZKPpeVirLtV');
+  });
+});

package/src/base58/index.ts

@@ -0,0 +1,8 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @summary Encode and decode base58 values
+ */
+
+export { base58Decode, base58Encode, base58Validate, isBase58 } from './bs58.js';

package/src/base58/validate.spec.ts

@@ -0,0 +1,20 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { base58Validate } from './index.js';
+
+describe('base58Validate', (): void => {
+  it('validates encoded', (): void => {
+    expect(
+      base58Validate('a1UbyspTdnyZXLUQaQbciCxrCWWxz24kgSwGXSQnkbs', false)
+    ).toEqual(true);
+  });
+
+  it('fails on string with extra padding', (): void => {
+    expect(
+      () => base58Validate('a1UbyspTdnyZXLUQaQbciCxrCWWxz24kgSwGXSQnkbs=', false)
+    ).toThrow(/Invalid base58 character "="/);
+  });
+});