@pezkuwi/util-crypto 14.0.7 → 14.0.11

package/src/hd/ledger/index.ts

@@ -0,0 +1,42 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Keypair } from '../../types.js';
+
+import { ed25519PairFromSeed } from '../../ed25519/index.js';
+import { mnemonicValidate } from '../../mnemonic/index.js';
+import { HARDENED, hdValidatePath } from '../validatePath.js';
+import { ledgerDerivePrivate } from './derivePrivate.js';
+import { ledgerMaster } from './master.js';
+
+export function hdLedger (_mnemonic: string, path: string): Keypair {
+  const words = _mnemonic
+    .split(' ')
+    .map((s) => s.trim())
+    .filter((s) => s);
+
+  if (![12, 24, 25].includes(words.length)) {
+    throw new Error('Expected a mnemonic with 24 words (or 25 including a password)');
+  }
+
+  const [mnemonic, password] = words.length === 25
+    ? [words.slice(0, 24).join(' '), words[24]]
+    : [words.join(' '), ''];
+
+  if (!mnemonicValidate(mnemonic)) {
+    throw new Error('Invalid mnemonic passed to ledger derivation');
+  } else if (!hdValidatePath(path)) {
+    throw new Error('Invalid derivation path');
+  }
+
+  const parts = path.split('/').slice(1);
+  let seed = ledgerMaster(mnemonic, password);
+
+  for (const p of parts) {
+    const n = parseInt(p.replace(/'$/, ''), 10);
+
+    seed = ledgerDerivePrivate(seed, (n < HARDENED) ? (n + HARDENED) : n);
+  }
+
+  return ed25519PairFromSeed(seed.slice(0, 32));
+}

package/src/hd/ledger/master.spec.ts

@@ -0,0 +1,19 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { u8aToHex } from '@pezkuwi/util';
+
+import { ledgerMaster } from './master.js';
+
+const MNEMONIC = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
+const XPRV = '0x402b03cd9c8bed9ba9f9bd6cd9c315ce9fcc59c7c25d37c85a36096617e69d418e35cb4a3b737afd007f0688618f21a8831643c0e6c77fc33c06026d2a0fc93832596435e70647d7d98ef102a32ea40319ca8fb6c851d7346d3bd8f9d1492658';
+
+describe('ledgerDerive', (): void => {
+  it('derives a known master xprv', (): void => {
+    expect(u8aToHex(
+      ledgerMaster(MNEMONIC)
+    )).toEqual(XPRV);
+  });
+});

package/src/hd/ledger/master.ts

@@ -0,0 +1,26 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { u8aConcat } from '@pezkuwi/util';
+
+import { hmacShaAsU8a } from '../../hmac/index.js';
+import { mnemonicToSeedSync } from '../../mnemonic/bip39.js';
+
+const ED25519_CRYPTO = 'ed25519 seed';
+
+// gets an xprv from a mnemonic
+export function ledgerMaster (mnemonic: string, password?: string): Uint8Array {
+  const seed = mnemonicToSeedSync(mnemonic, password);
+  const chainCode = hmacShaAsU8a(ED25519_CRYPTO, new Uint8Array([1, ...seed]), 256);
+  let priv;
+
+  while (!priv || (priv[31] & 0b0010_0000)) {
+    priv = hmacShaAsU8a(ED25519_CRYPTO, priv || seed, 512);
+  }
+
+  priv[0] &= 0b1111_1000;
+  priv[31] &= 0b0111_1111;
+  priv[31] |= 0b0100_0000;
+
+  return u8aConcat(priv, chainCode);
+}

package/src/hd/validatePath.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 { hdValidatePath } from './index.js';
+
+const VECTORS: [string, boolean][] = [
+  ["m/44'/60'/0'/0/0", true],
+  ['m/0', true],
+  ["m/123'", true],
+  ["n/44'/60'/0'/0/0", false],
+  ['m', false],
+  ['m/', false],
+  ["m/xyz'", false],
+  ['m/123x', false],
+  ['m/123"', false],
+  ["m/123''", false],
+  ["m/123'0'", false],
+  [`m/${0x80000000}`, false],
+  ['m/-1', false]
+];
+
+describe('hdValidatePath', (): void => {
+  VECTORS.forEach(([path, result]): void => {
+    it(`validates ${path} as ${result.toString()}`, (): void => {
+      expect(hdValidatePath(path)).toEqual(result);
+    });
+  });
+});

package/src/hd/validatePath.ts

@@ -0,0 +1,24 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export const HARDENED = 0x80000000;
+
+export function hdValidatePath (path: string): boolean {
+  if (!path.startsWith('m/')) {
+    return false;
+  }
+
+  const parts = path.split('/').slice(1);
+
+  for (const p of parts) {
+    const n = /^\d+'?$/.test(p)
+      ? parseInt(p.replace(/'$/, ''), 10)
+      : Number.NaN;
+
+    if (isNaN(n) || (n >= HARDENED) || (n < 0)) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/helpers.ts

@@ -0,0 +1,38 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '@pezkuwi/util/types';
+
+import { hasBigInt, u8aToHex, u8aToU8a } from '@pezkuwi/util';
+import { isReady } from '@pezkuwi/wasm-crypto';
+
+// re-export so TS *.d.ts generation is correct
+export type { HexString } from '@pezkuwi/util/types';
+
+interface DualHash {
+  256: (u8a: Uint8Array) => Uint8Array;
+  512: (u8a: Uint8Array) => Uint8Array;
+}
+
+/** @internal */
+export function createAsHex <T extends (...args: never[]) => Uint8Array> (fn: T): (...args: Parameters<T>) => HexString {
+  return (...args: Parameters<T>): HexString =>
+    u8aToHex(fn(...args));
+}
+
+/** @internal */
+export function createBitHasher (bitLength: 256 | 512, fn: (data: string | Uint8Array, bitLength: 256 | 512, onlyJs?: boolean) => Uint8Array): (data: string | Uint8Array, onlyJs?: boolean) => Uint8Array {
+  return (data: string | Uint8Array, onlyJs?: boolean): Uint8Array =>
+    fn(data, bitLength, onlyJs);
+}
+
+/** @internal */
+export function createDualHasher (wa: DualHash, js: DualHash): (value: string | Uint8Array, bitLength?: 256 | 512, onlyJs?: boolean) => Uint8Array {
+  return (value: string | Uint8Array, bitLength: 256 | 512 = 256, onlyJs?: boolean): Uint8Array => {
+    const u8a = u8aToU8a(value);
+
+    return !hasBigInt || (!onlyJs && isReady())
+      ? wa[bitLength](u8a)
+      : js[bitLength](u8a);
+  };
+}

package/src/hmac/index.ts

@@ -0,0 +1,4 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export { hmacSha256AsU8a, hmacSha512AsU8a, hmacShaAsU8a } from './shaAsU8a.js';

package/src/hmac/shaAsU8a.spec.ts

@@ -0,0 +1,45 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { hexToU8a, stringToU8a } from '@pezkuwi/util';
+import { waitReady } from '@pezkuwi/wasm-crypto';
+
+import { perfWasm } from '../test/index.js';
+import { hmacShaAsU8a } from './index.js';
+
+describe('hmacShaAsU8a', (): void => {
+  beforeEach(async (): Promise<void> => {
+    await waitReady();
+  });
+
+  const key = stringToU8a('secret');
+  const data = stringToU8a('some message');
+  const output = {
+    256: hexToU8a(
+      '0xf28a70b41263840e5c059a0a733336e0957efba87902aa8cca11441d4b0c96d7'
+    ),
+    512: hexToU8a(
+      '0x295832e97ed77be75a9fa98029497e4a722c4b9a2f21b39d34f1befa931a39ec520fd24711d6f5c03501384ea66b83066a01a82c57a0460f8cd1f471fcce5841'
+    )
+  };
+
+  for (const bitLength of [256, 512] as const) {
+    describe(`bitLength=${bitLength}`, (): void => {
+      for (const onlyJs of [false, true]) {
+        describe(`onlyJs=${(onlyJs && 'true') || 'false'}`, (): void => {
+          it('returns an hex representation (string)', (): void => {
+            expect(
+              hmacShaAsU8a(key, data, bitLength, onlyJs)
+            ).toEqual(output[bitLength]);
+          });
+        });
+      }
+    });
+
+    perfWasm(`hmacShaAsU8a, bitLength=${bitLength}`, 16000, (input, onlyJs) =>
+      hmacShaAsU8a(input, input, bitLength, onlyJs)
+    );
+  }
+});

package/src/hmac/shaAsU8a.ts

@@ -0,0 +1,48 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { hmac } from '@noble/hashes/hmac';
+import { sha256 } from '@noble/hashes/sha256';
+import { sha512 } from '@noble/hashes/sha512';
+
+import { hasBigInt, u8aToU8a } from '@pezkuwi/util';
+import { hmacSha256, hmacSha512, isReady } from '@pezkuwi/wasm-crypto';
+
+const JS_HASH = {
+  256: sha256,
+  512: sha512
+};
+
+const WA_MHAC = {
+  256: hmacSha256,
+  512: hmacSha512
+};
+
+function createSha (bitLength: 256 | 512): (key: Uint8Array | string, data: Uint8Array, onlyJs?: boolean) => Uint8Array {
+  return (key: Uint8Array | string, data: Uint8Array, onlyJs?: boolean): Uint8Array =>
+    hmacShaAsU8a(key, data, bitLength, onlyJs);
+}
+
+/**
+ * @name hmacShaAsU8a
+ * @description creates a Hmac Sha (256/512) Uint8Array from the key & data
+ */
+export function hmacShaAsU8a (key: Uint8Array | string, data: Uint8Array, bitLength: 256 | 512 = 256, onlyJs?: boolean): Uint8Array {
+  const u8aKey = u8aToU8a(key);
+
+  return !hasBigInt || (!onlyJs && isReady())
+    ? WA_MHAC[bitLength](u8aKey, data)
+    : hmac(JS_HASH[bitLength], u8aKey, data);
+}
+
+/**
+ * @name hmacSha256AsU8a
+ * @description creates a Hmac Sha256 Uint8Array from the key & data
+ */
+export const hmacSha256AsU8a = /*#__PURE__*/ createSha(256);
+
+/**
+ * @name hmacSha512AsU8a
+ * @description creates a Hmac Sha512 Uint8Array from the key & data
+ */
+export const hmacSha512AsU8a = /*#__PURE__*/ createSha(512);

package/src/index.ts

@@ -0,0 +1,6 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import './packageDetect.js';
+
+export * from './bundle.js';

package/src/json/constants.ts

@@ -0,0 +1,11 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { EncryptedJsonEncoding, EncryptedJsonVersion } from './types.js';
+
+export const ENCODING: EncryptedJsonEncoding[] = ['scrypt', 'xsalsa20-poly1305'];
+export const ENCODING_NONE: EncryptedJsonEncoding[] = ['none'];
+export const ENCODING_VERSION: EncryptedJsonVersion = '3';
+
+export const NONCE_LENGTH = 24;
+export const SCRYPT_LENGTH = 32 + (3 * 4);

package/src/json/decrypt.ts

@@ -0,0 +1,25 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { EncryptedJson } from './types.js';
+
+import { hexToU8a, isHex } from '@pezkuwi/util';
+
+import { base64Decode } from '../base64/index.js';
+import { jsonDecryptData } from './decryptData.js';
+
+export function jsonDecrypt ({ encoded, encoding }: EncryptedJson, passphrase?: string | null): Uint8Array {
+  if (!encoded) {
+    throw new Error('No encrypted data available to decode');
+  }
+
+  return jsonDecryptData(
+    isHex(encoded)
+      ? hexToU8a(encoded)
+      : base64Decode(encoded),
+    passphrase,
+    Array.isArray(encoding.type)
+      ? encoding.type
+      : [encoding.type]
+  );
+}

package/src/json/decryptData.ts

@@ -0,0 +1,45 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { EncryptedJsonEncoding } from './types.js';
+
+import { stringToU8a, u8aFixLength } from '@pezkuwi/util';
+
+import { naclDecrypt } from '../nacl/index.js';
+import { scryptEncode, scryptFromU8a } from '../scrypt/index.js';
+import { ENCODING, NONCE_LENGTH, SCRYPT_LENGTH } from './constants.js';
+
+export function jsonDecryptData (encrypted?: Uint8Array | null, passphrase?: string | null, encType: EncryptedJsonEncoding[] = ENCODING): Uint8Array {
+  if (!encrypted) {
+    throw new Error('No encrypted data available to decode');
+  } else if (encType.includes('xsalsa20-poly1305') && !passphrase) {
+    throw new Error('Password required to decode encrypted data');
+  }
+
+  let encoded: Uint8Array | null = encrypted;
+
+  if (passphrase) {
+    let password: Uint8Array;
+
+    if (encType.includes('scrypt')) {
+      const { params, salt } = scryptFromU8a(encrypted);
+
+      password = scryptEncode(passphrase, salt, params).password;
+      encrypted = encrypted.subarray(SCRYPT_LENGTH);
+    } else {
+      password = stringToU8a(passphrase);
+    }
+
+    encoded = naclDecrypt(
+      encrypted.subarray(NONCE_LENGTH),
+      encrypted.subarray(0, NONCE_LENGTH),
+      u8aFixLength(password, 256, true)
+    );
+  }
+
+  if (!encoded) {
+    throw new Error('Unable to decode using the supplied passphrase');
+  }
+
+  return encoded;
+}

package/src/json/encrypt.ts

@@ -0,0 +1,25 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { EncryptedJson } from './types.js';
+
+import { u8aConcat } from '@pezkuwi/util';
+
+import { naclEncrypt } from '../nacl/index.js';
+import { scryptEncode, scryptToU8a } from '../scrypt/index.js';
+import { jsonEncryptFormat } from './encryptFormat.js';
+
+export function jsonEncrypt (data: Uint8Array, contentType: string[], passphrase?: string | null): EncryptedJson {
+  let isEncrypted = false;
+  let encoded = data;
+
+  if (passphrase) {
+    const { params, password, salt } = scryptEncode(passphrase);
+    const { encrypted, nonce } = naclEncrypt(encoded, password.subarray(0, 32));
+
+    isEncrypted = true;
+    encoded = u8aConcat(scryptToU8a(salt, params), nonce, encrypted);
+  }
+
+  return jsonEncryptFormat(encoded, contentType, isEncrypted);
+}

package/src/json/encryptFormat.ts

@@ -0,0 +1,20 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { EncryptedJson } from './types.js';
+
+import { base64Encode } from '../base64/index.js';
+import { ENCODING, ENCODING_NONE, ENCODING_VERSION } from './constants.js';
+
+export function jsonEncryptFormat (encoded: Uint8Array, contentType: string[], isEncrypted: boolean): EncryptedJson {
+  return {
+    encoded: base64Encode(encoded),
+    encoding: {
+      content: contentType,
+      type: isEncrypted
+        ? ENCODING
+        : ENCODING_NONE,
+      version: ENCODING_VERSION
+    }
+  };
+}

package/src/json/index.ts

@@ -0,0 +1,7 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export { jsonDecrypt } from './decrypt.js';
+export { jsonDecryptData } from './decryptData.js';
+export { jsonEncrypt } from './encrypt.js';
+export { jsonEncryptFormat } from './encryptFormat.js';

package/src/json/types.ts

@@ -0,0 +1,22 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export type EncryptedJsonVersion = '0' | '1' | '2' | '3';
+
+export type EncryptedJsonEncoding = 'none' | 'scrypt' | 'xsalsa20-poly1305';
+
+export interface EncryptedJsonDescriptor {
+  /** Descriptor for the content */
+  content: string[];
+  /** The encoding (in current/latest versions this is always an array) */
+  type: EncryptedJsonEncoding | EncryptedJsonEncoding[];
+  /** The version of encoding applied */
+  version: EncryptedJsonVersion;
+}
+
+export interface EncryptedJson {
+  /** The encoded string */
+  encoded: string;
+  /** The encoding used */
+  encoding: EncryptedJsonDescriptor;
+}

package/src/keccak/asHex.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 { waitReady } from '@pezkuwi/wasm-crypto';
+
+import { keccakAsHex } from './index.js';
+
+const BITS: (256 | 512)[] = [256, 512];
+
+const value = 'test';
+const result = {
+  256: '9c22ff5f21f0b81b113e63f7db6da94fedef11b2119b4088b89664fb9a3cb658',
+  512: '1e2e9fc2002b002d75198b7503210c05a1baac4560916a3c6d93bcce3a50d7f00fd395bf1647b9abb8d1afcc9c76c289b0c9383ba386a956da4b38934417789e'
+};
+
+describe('keccakAsHex', (): void => {
+  beforeEach(async (): Promise<void> => {
+    await waitReady();
+  });
+
+  BITS.forEach((bitLength): void => {
+    it('returns a prefixed hex representation', (): void => {
+      expect(
+        keccakAsHex(value, bitLength)
+      ).toEqual(`0x${result[bitLength]}`);
+    });
+  });
+});

package/src/keccak/asU8a.spec.ts

@@ -0,0 +1,56 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { hexToU8a, stringToU8a } from '@pezkuwi/util';
+import { waitReady } from '@pezkuwi/wasm-crypto';
+
+import { perfWasm } from '../test/index.js';
+import { keccakAsU8a } from './index.js';
+
+describe('keccakAsU8a', (): void => {
+  beforeEach(async (): Promise<void> => {
+    await waitReady();
+  });
+
+  const input = 'test value';
+  const output = {
+    256: hexToU8a(
+      '0x2d07364b5c231c56ce63d49430e085ea3033c750688ba532b24029124c26ca5e'
+    ),
+    512: hexToU8a(
+      '0xc1b50cc57f85ccd968a9d7c7a809dcebd140a548c8e0b67f3afcdd6fc14cca2b1d04187aef24ba0081b74f2ec362431e425760febe94a5607790854cafe5b197'
+    )
+  };
+
+  for (const bitLength of [256, 512] as const) {
+    describe(`bitLength=${bitLength}`, (): void => {
+      for (const onlyJs of [false, true]) {
+        describe(`onlyJs=${(onlyJs && 'true') || 'false'}`, (): void => {
+          it('returns an hex representation (string)', (): void => {
+            expect(
+              keccakAsU8a(input, bitLength, onlyJs)
+            ).toEqual(output[bitLength]);
+          });
+
+          it('returns an hex representation (Buffer)', (): void => {
+            expect(
+              keccakAsU8a(Buffer.from(input), bitLength, onlyJs)
+            ).toEqual(output[bitLength]);
+          });
+
+          it('returns an hex representation (Uint8Array)', (): void => {
+            expect(
+              keccakAsU8a(stringToU8a(input), bitLength, onlyJs)
+            ).toEqual(output[bitLength]);
+          });
+        });
+      }
+
+      perfWasm(`keccakAsU8a, bitLength=${bitLength}`, 128000, (input, onlyJs) =>
+        keccakAsU8a(input, bitLength, onlyJs)
+      );
+    });
+  }
+});

package/src/keccak/asU8a.ts

@@ -0,0 +1,45 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { keccak_256 as keccak256Js, keccak_512 as keccak512Js } from '@noble/hashes/sha3';
+
+import { keccak256, keccak512 } from '@pezkuwi/wasm-crypto';
+
+import { createAsHex, createBitHasher, createDualHasher } from '../helpers.js';
+
+/**
+ * @name keccakAsU8a
+ * @summary Creates a keccak Uint8Array from the input.
+ * @description
+ * From either a `string` or a `Buffer` input, create the keccak and return the result as a `Uint8Array`.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { keccakAsU8a } from '@pezkuwi/util-crypto';
+ *
+ * keccakAsU8a('123'); // => Uint8Array
+ * ```
+ */
+export const keccakAsU8a = /*#__PURE__*/ createDualHasher(
+  { 256: keccak256, 512: keccak512 },
+  { 256: keccak256Js, 512: keccak512Js }
+);
+
+/**
+ * @name keccak256AsU8a
+ * @description Creates a keccak256 Uint8Array from the input.
+ */
+export const keccak256AsU8a = /*#__PURE__*/ createBitHasher(256, keccakAsU8a);
+
+/**
+ * @name keccak512AsU8a
+ * @description Creates a keccak512 Uint8Array from the input.
+ */
+export const keccak512AsU8a = /*#__PURE__*/ createBitHasher(512, keccakAsU8a);
+
+/**
+ * @name keccakAsHex
+ * @description Creates a keccak hex string from the input.
+ */
+export const keccakAsHex = /*#__PURE__*/ createAsHex(keccakAsU8a);

package/src/keccak/index.ts

@@ -0,0 +1,8 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @summary Create Keccak256/512 values as hex & Uint8Array output
+ */
+
+export { keccak256AsU8a, keccak512AsU8a, keccakAsHex, keccakAsU8a } from './asU8a.js';