@pezkuwi/util-crypto 14.0.7 → 14.0.10

package/src/key/extractSuri.spec.ts

@@ -0,0 +1,147 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import type { ExtractResult } from './extractSuri.js';
+
+import { keyExtractSuri } from './extractSuri.js';
+
+describe('keyExtractSuri', (): void => {
+  it('does not extract from invalid suri', (): void => {
+    expect(
+      (): ExtractResult => keyExtractSuri('//2')
+    ).toThrow('Unable to match provided value to a secret URI');
+  });
+
+  it('derives on "hello world"', (): void => {
+    const test = keyExtractSuri('hello world');
+
+    expect(test.phrase).toEqual('hello world');
+    expect(test.path.length).toEqual(0);
+  });
+
+  it('derives on "hello world/1', (): void => {
+    const test = keyExtractSuri('hello world/1');
+
+    expect(test.password).not.toBeDefined();
+    expect(test.phrase).toEqual('hello world');
+    expect(test.path.length).toEqual(1);
+    expect(test.path[0].isHard).toEqual(false);
+    expect(test.path[0].chainCode).toEqual(Uint8Array.from([1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]));
+  });
+
+  it('derives on "hello world/DOT', (): void => {
+    const test = keyExtractSuri('hello world/DOT');
+
+    expect(test.password).not.toBeDefined();
+    expect(test.phrase).toEqual('hello world');
+    expect(test.path.length).toEqual(1);
+    expect(test.path[0].isHard).toEqual(false);
+    expect(test.path[0].chainCode).toEqual(Uint8Array.from([12, 68, 79, 84, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]));
+  });
+
+  it('derives on "hello world//1', (): void => {
+    const test = keyExtractSuri('hello world//1');
+
+    expect(test.password).not.toBeDefined();
+    expect(test.phrase).toEqual('hello world');
+    expect(test.path.length).toEqual(1);
+    expect(test.path[0].isHard).toEqual(true);
+    expect(test.path[0].chainCode).toEqual(Uint8Array.from([1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]));
+  });
+
+  it('derives on "hello world//DOT', (): void => {
+    const test = keyExtractSuri('hello world//DOT');
+
+    expect(test.password).not.toBeDefined();
+    expect(test.phrase).toEqual('hello world');
+    expect(test.path.length).toEqual(1);
+    expect(test.path[0].isHard).toEqual(true);
+    expect(test.path[0].chainCode).toEqual(Uint8Array.from([12, 68, 79, 84, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]));
+  });
+
+  it('derives on "hello world//1/DOT', (): void => {
+    const test = keyExtractSuri('hello world//1/DOT');
+
+    expect(test.password).not.toBeDefined();
+    expect(test.phrase).toEqual('hello world');
+    expect(test.path.length).toEqual(2);
+    expect(test.path[0].isHard).toEqual(true);
+    expect(test.path[0].chainCode).toEqual(Uint8Array.from([1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]));
+    expect(test.path[1].isHard).toEqual(false);
+    expect(test.path[1].chainCode).toEqual(Uint8Array.from([12, 68, 79, 84, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]));
+  });
+
+  it('derives on "hello world//DOT/1', (): void => {
+    const test = keyExtractSuri('hello world//DOT/1');
+
+    expect(test.password).not.toBeDefined();
+    expect(test.phrase).toEqual('hello world');
+    expect(test.path.length).toEqual(2);
+    expect(test.path[0].isHard).toEqual(true);
+    expect(test.path[0].chainCode).toEqual(Uint8Array.from([12, 68, 79, 84, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]));
+    expect(test.path[1].isHard).toEqual(false);
+    expect(test.path[1].chainCode).toEqual(Uint8Array.from([1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]));
+  });
+
+  it('derives on "hello world///password"', (): void => {
+    const test = keyExtractSuri('hello world///password');
+
+    expect(test.password).toEqual('password');
+    expect(test.phrase).toEqual('hello world');
+    expect(test.path.length).toEqual(0);
+  });
+
+  it('derives on "hello world//1/DOT///password"', (): void => {
+    const test = keyExtractSuri('hello world//1/DOT///password');
+
+    expect(test.password).toEqual('password');
+    expect(test.phrase).toEqual('hello world');
+    expect(test.path.length).toEqual(2);
+    expect(test.path[0].isHard).toEqual(true);
+    expect(test.path[0].chainCode).toEqual(Uint8Array.from([1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]));
+    expect(test.path[1].isHard).toEqual(false);
+    expect(test.path[1].chainCode).toEqual(Uint8Array.from([12, 68, 79, 84, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]));
+  });
+
+  it('derives on "hello world/1//DOT///password"', (): void => {
+    const test = keyExtractSuri('hello world/1//DOT///password');
+
+    expect(test.password).toEqual('password');
+    expect(test.phrase).toEqual('hello world');
+    expect(test.path.length).toEqual(2);
+    expect(test.path[0].isHard).toEqual(false);
+    expect(test.path[0].chainCode).toEqual(Uint8Array.from([1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]));
+    expect(test.path[1].isHard).toEqual(true);
+    expect(test.path[1].chainCode).toEqual(Uint8Array.from([12, 68, 79, 84, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]));
+  });
+
+  it('derives on actual Alice', (): void => {
+    const test = keyExtractSuri('bottom drive obey lake curtain smoke basket hold race lonely fit walk//Alice');
+
+    expect(test.password).not.toBeDefined();
+    expect(test.phrase).toEqual('bottom drive obey lake curtain smoke basket hold race lonely fit walk');
+    expect(test.path.length).toEqual(1);
+    expect(test.path[0].isHard).toEqual(true);
+    expect(test.path[0].chainCode).toEqual(Uint8Array.from([20, 65, 108, 105, 99, 101, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]));
+  });
+
+  it('derives on uncommon characters', (): void => {
+    const languageMnemonics = {
+      chineseSimplified: '熙 礼 淀 谋 耗 搜 雨 瑞 雷 合 析 感',
+      chineseTraditional: '召 胸 捕 乏 講 祥 隙 幫 動 框 場 給',
+      french: 'ruiner minute maison ouragan palourde piscine nerveux descente romance édifier ancien médaille',
+      japanese: 'ほったん はちみつ おやゆび ほかん いりぐち さんいん てぶくろ だいじょうぶ ふとん でぬかえ ちしき あわてる',
+      korean: '김밥 방향 논리 저절로 증상 지진 회장 오히려 시리즈 최근 학용품 곡식'
+    };
+
+    Object.keys(languageMnemonics).forEach((mnemonic) => {
+      const test = keyExtractSuri(mnemonic);
+
+      expect(test.password).not.toBeDefined();
+      expect(test.phrase).toEqual(mnemonic);
+      expect(test.path.length).toEqual(0);
+    });
+  });
+});

package/src/key/extractSuri.ts

@@ -0,0 +1,40 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { DeriveJunction } from './DeriveJunction.js';
+
+import { keyExtractPath } from './extractPath.js';
+
+export interface ExtractResult {
+  derivePath: string,
+  password?: string;
+  path: DeriveJunction[];
+  phrase: string;
+}
+
+const RE_CAPTURE = /^((0x[a-fA-F0-9]+|[\p{L}\d]+(?: [\p{L}\d]+)*))((\/\/?[^/]+)*)(\/\/\/(.*))?$/u;
+
+/**
+ * @description Extracts the phrase, path and password from a SURI format for specifying secret keys `<secret>/<soft-key>//<hard-key>///<password>` (the `///password` may be omitted, and `/<soft-key>` and `//<hard-key>` maybe repeated and mixed).
+ */
+export function keyExtractSuri (suri: string): ExtractResult {
+  // Normalize Unicode to NFC to avoid accent-related mismatches
+  const normalizedSuri = suri.normalize('NFC');
+
+  // eslint-disable-next-line @typescript-eslint/prefer-regexp-exec
+  const matches = normalizedSuri.match(RE_CAPTURE);
+
+  if (matches === null) {
+    throw new Error('Unable to match provided value to a secret URI');
+  }
+
+  const [, phrase, , derivePath, , , password] = matches;
+  const { path } = keyExtractPath(derivePath);
+
+  return {
+    derivePath,
+    password,
+    path,
+    phrase
+  };
+}

package/src/key/fromPath.ts

@@ -0,0 +1,28 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Keypair, KeypairType } from '../types.js';
+import type { DeriveJunction } from './DeriveJunction.js';
+
+import { keyHdkdEcdsa } from './hdkdEcdsa.js';
+import { keyHdkdEd25519 } from './hdkdEd25519.js';
+import { keyHdkdSr25519 } from './hdkdSr25519.js';
+
+const generators = {
+  ecdsa: keyHdkdEcdsa,
+  ed25519: keyHdkdEd25519,
+  // FIXME This is Substrate-compatible, not Ethereum-compatible
+  ethereum: keyHdkdEcdsa,
+  sr25519: keyHdkdSr25519
+};
+
+export function keyFromPath (pair: Keypair, path: DeriveJunction[], type: KeypairType): Keypair {
+  const keyHdkd = generators[type];
+  let result = pair;
+
+  for (const junction of path) {
+    result = keyHdkd(result, junction);
+  }
+
+  return result;
+}

package/src/key/hdkdDerive.ts

@@ -0,0 +1,17 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Keypair } from '../types.js';
+import type { DeriveJunction } from './DeriveJunction.js';
+
+export function createSeedDeriveFn (fromSeed: (seed: Uint8Array) => Keypair, derive: (seed: Uint8Array, chainCode: Uint8Array) => Uint8Array): (keypair: Keypair, junction: DeriveJunction) => Keypair {
+  return (keypair: Keypair, { chainCode, isHard }: DeriveJunction): Keypair => {
+    if (!isHard) {
+      throw new Error('A soft key was found in the path and is not supported');
+    }
+
+    return fromSeed(
+      derive(keypair.secretKey.subarray(0, 32), chainCode)
+    );
+  };
+}

package/src/key/hdkdEcdsa.ts

@@ -0,0 +1,8 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { secp256k1DeriveHard } from '../secp256k1/deriveHard.js';
+import { secp256k1PairFromSeed } from '../secp256k1/pair/fromSeed.js';
+import { createSeedDeriveFn } from './hdkdDerive.js';
+
+export const keyHdkdEcdsa = /*#__PURE__*/ createSeedDeriveFn(secp256k1PairFromSeed, secp256k1DeriveHard);

package/src/key/hdkdEd25519.ts

@@ -0,0 +1,7 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { ed25519DeriveHard, ed25519PairFromSeed } from '../ed25519/index.js';
+import { createSeedDeriveFn } from './hdkdDerive.js';
+
+export const keyHdkdEd25519 = /*#__PURE__*/ createSeedDeriveFn(ed25519PairFromSeed, ed25519DeriveHard);

package/src/key/hdkdSr25519.ts

@@ -0,0 +1,14 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Keypair } from '../types.js';
+import type { DeriveJunction } from './DeriveJunction.js';
+
+import { sr25519DeriveHard } from '../sr25519/deriveHard.js';
+import { sr25519DeriveSoft } from '../sr25519/deriveSoft.js';
+
+export function keyHdkdSr25519 (keypair: Keypair, { chainCode, isSoft }: DeriveJunction): Keypair {
+  return isSoft
+    ? sr25519DeriveSoft(keypair, chainCode)
+    : sr25519DeriveHard(keypair, chainCode);
+}

package/src/key/index.ts

@@ -0,0 +1,12 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @summary Create keys from paths, seeds and password
+ */
+export { keyExtractPath } from './extractPath.js';
+export { keyExtractSuri } from './extractSuri.js';
+export { keyFromPath } from './fromPath.js';
+export { keyHdkdEcdsa } from './hdkdEcdsa.js';
+export { keyHdkdEd25519 } from './hdkdEd25519.js';
+export { keyHdkdSr25519 } from './hdkdSr25519.js';

package/src/mnemonic/bip39.spec.ts

@@ -0,0 +1,80 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import * as lists from './wordlists/index.js';
+import { entropyToMnemonic, generateMnemonic, mnemonicToEntropy, validateMnemonic } from './bip39.js';
+
+describe('wordlists', (): void => {
+  for (const [lang, words] of Object.entries(lists)) {
+    describe(`language ${lang}`, (): void => {
+      it('has the correct number of words', (): void => {
+        expect(words).toHaveLength(2048);
+      });
+
+      it('has no empty words', (): void => {
+        expect(
+          words.some((w) => !w.length || w.trim() !== w)
+        ).toEqual(false);
+      });
+    });
+  }
+});
+
+describe('bip39', (): void => {
+  const m = 'seed sock milk update focus rotate barely fade car face mechanic mercy';
+  const e = mnemonicToEntropy(m);
+
+  it('generates a known entropy', (): void => {
+    expect(e).toEqual(
+      new Uint8Array([194, 249, 194, 50, 119, 69, 163, 120, 68, 162, 142, 34, 74, 50, 40, 197])
+    );
+  });
+
+  it('has a two-way entropy <-> mnemonic (default wordlist)', (): void => {
+    expect(
+      entropyToMnemonic(mnemonicToEntropy(entropyToMnemonic(e)))
+    ).toEqual(m);
+  });
+
+  for (const [lang, words] of Object.entries(lists)) {
+    const isUsingList = (test: string, length = 12): void => {
+      const split = test.split(' ');
+
+      expect(
+        split
+      ).toHaveLength(length);
+      expect(
+        split.some((w) => words.indexOf(w) === -1)
+      ).toEqual(false);
+    };
+
+    describe(`language ${lang}`, (): void => {
+      it('has a two-way entropy <-> mnemonic', (): void => {
+        const test = entropyToMnemonic(e, words);
+        const entr = mnemonicToEntropy(test, words);
+
+        isUsingList(test);
+
+        expect(
+          entr
+        ).toEqual(e);
+
+        expect(
+          entropyToMnemonic(entr, words)
+        ).toEqual(test);
+      });
+
+      it('generates a valid mnemonic', (): void => {
+        const test = generateMnemonic(24, words);
+
+        isUsingList(test, 24);
+
+        expect(
+          validateMnemonic(test, words)
+        ).toEqual(true);
+      });
+    });
+  }
+});

package/src/mnemonic/bip39.ts

@@ -0,0 +1,127 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// Adapted from the bitcoinjs/bip39 source
+// https://github.com/bitcoinjs/bip39/blob/1d063b6a6aee4145b34d701037cd3e67f5446ff9/ts_src/index.ts
+// Copyright (c) 2014, Wei Lu <luwei.here@gmail.com> and Daniel Cousens <email@dcousens.com>
+// ISC Licence
+//
+// Change made in this version -
+//   - Adjust formatting (just eslint differences)
+//   - Only English wordlist (this aligns with the wasm-crypto implementation)
+//   - Use util-crypto randomAsU8a (instead of randombytes)
+//   - Remove setting of wordlist passing of wordlist in functions
+//   - Remove mnemonicToSeed (we only use the sync variant)
+//   - generateMnemonic takes number of words (instead of strength)
+
+import { stringToU8a, u8aToU8a } from '@pezkuwi/util';
+
+import { pbkdf2Encode } from '../pbkdf2/index.js';
+import { randomAsU8a } from '../random/index.js';
+import { sha256AsU8a } from '../sha/index.js';
+import DEFAULT_WORDLIST from './wordlists/en.js';
+
+const INVALID_MNEMONIC = 'Invalid mnemonic';
+const INVALID_ENTROPY = 'Invalid entropy';
+const INVALID_CHECKSUM = 'Invalid mnemonic checksum';
+
+/** @internal */
+function normalize (str?: string): string {
+  return (str || '').normalize('NFKD');
+}
+
+/** @internal */
+function binaryToByte (bin: string): number {
+  return parseInt(bin, 2);
+}
+
+/** @internal */
+function bytesToBinary (bytes: number[]): string {
+  return bytes.map((x) => x.toString(2).padStart(8, '0')).join('');
+}
+
+/** @internal */
+function deriveChecksumBits (entropyBuffer: Uint8Array): string {
+  return bytesToBinary(
+    Array.from(sha256AsU8a(entropyBuffer))
+  ).slice(0, (entropyBuffer.length * 8) / 32);
+}
+
+export function mnemonicToSeedSync (mnemonic: string, password?: string): Uint8Array {
+  return pbkdf2Encode(
+    stringToU8a(normalize(mnemonic)),
+    stringToU8a(`mnemonic${normalize(password)}`)
+  ).password;
+}
+
+export function mnemonicToEntropy (mnemonic: string, wordlist: string[] = DEFAULT_WORDLIST): Uint8Array {
+  const words = normalize(mnemonic).split(' ');
+
+  if (words.length % 3 !== 0) {
+    throw new Error(INVALID_MNEMONIC);
+  }
+
+  // convert word indices to 11 bit binary strings
+  const bits = words
+    .map((word): string => {
+      const index = wordlist.indexOf(word);
+
+      if (index === -1) {
+        throw new Error(INVALID_MNEMONIC);
+      }
+
+      return index.toString(2).padStart(11, '0');
+    })
+    .join('');
+
+  // split the binary string into ENT/CS
+  const dividerIndex = Math.floor(bits.length / 33) * 32;
+  const entropyBits = bits.slice(0, dividerIndex);
+  const checksumBits = bits.slice(dividerIndex);
+
+  // calculate the checksum and compare
+  const matched = entropyBits.match(/(.{1,8})/g);
+  const entropyBytes = matched?.map(binaryToByte);
+
+  if (!entropyBytes || (entropyBytes.length % 4 !== 0) || (entropyBytes.length < 16) || (entropyBytes.length > 32)) {
+    throw new Error(INVALID_ENTROPY);
+  }
+
+  const entropy = u8aToU8a(entropyBytes);
+
+  if (deriveChecksumBits(entropy) !== checksumBits) {
+    throw new Error(INVALID_CHECKSUM);
+  }
+
+  return entropy;
+}
+
+export function entropyToMnemonic (entropy: Uint8Array, wordlist: string[] = DEFAULT_WORDLIST): string {
+  // 128 <= ENT <= 256
+  if ((entropy.length % 4 !== 0) || (entropy.length < 16) || (entropy.length > 32)) {
+    throw new Error(INVALID_ENTROPY);
+  }
+
+  const matched = `${bytesToBinary(Array.from(entropy))}${deriveChecksumBits(entropy)}`.match(/(.{1,11})/g);
+  const mapped = matched?.map((b) => wordlist[binaryToByte(b)]);
+
+  if (!mapped || (mapped.length < 12)) {
+    throw new Error('Unable to map entropy to mnemonic');
+  }
+
+  return mapped.join(' ');
+}
+
+export function generateMnemonic (numWords: 12 | 15 | 18 | 21 | 24, wordlist?: string[]): string {
+  return entropyToMnemonic(randomAsU8a((numWords / 3) * 4), wordlist);
+}
+
+export function validateMnemonic (mnemonic: string, wordlist?: string[]): boolean {
+  try {
+    mnemonicToEntropy(mnemonic, wordlist);
+  } catch {
+    return false;
+  }
+
+  return true;
+}

package/src/mnemonic/generate.spec.ts

@@ -0,0 +1,58 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { cryptoWaitReady } from '../index.js';
+import { french as frenchWords } from './wordlists/index.js';
+import { mnemonicGenerate } from './generate.js';
+import { mnemonicValidate } from './validate.js';
+
+await cryptoWaitReady();
+
+describe('mnemonicGenerate', (): void => {
+  it('generates a valid mnemonic (default strength)', (): void => {
+    expect(
+      mnemonicValidate(mnemonicGenerate())
+    ).toEqual(true);
+  });
+
+  it('generates a french mnemonic', (): void => {
+    const mnemonic = mnemonicGenerate(24, frenchWords);
+    const words = mnemonic.split(' ');
+
+    expect(words).toHaveLength(24);
+    expect(
+      mnemonicValidate(mnemonic, frenchWords)
+    ).toEqual(true);
+    expect(
+      mnemonicValidate(mnemonic)
+    ).toEqual(false);
+    expect(
+      words.every((w) => frenchWords.includes(w))
+    ).toEqual(true);
+  });
+
+  for (const onlyJs of [false, true]) {
+    describe(`onlyJs=${(onlyJs && 'true') || 'false'}`, (): void => {
+      for (const num of [12, 15, 18, 21, 24] as const) {
+        it(`generates a valid mnemonic (${num} words)`, (): void => {
+          const mnemonic = mnemonicGenerate(num, undefined, onlyJs);
+          const isValid = mnemonicValidate(mnemonic);
+
+          expect(mnemonic.split(' ')).toHaveLength(num);
+          expect(isValid).toEqual(true);
+        });
+      }
+
+      it('generates non-deterministic', (): void => {
+        const m1 = mnemonicGenerate(24, undefined, onlyJs);
+        const m2 = mnemonicGenerate(24, undefined, onlyJs);
+
+        expect(m1 === m2).toEqual(false);
+        expect(mnemonicValidate(m1)).toEqual(true);
+        expect(mnemonicValidate(m2)).toEqual(true);
+      });
+    });
+  }
+});

package/src/mnemonic/generate.ts

@@ -0,0 +1,25 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { hasBigInt } from '@pezkuwi/util';
+import { bip39Generate, isReady } from '@pezkuwi/wasm-crypto';
+
+import { generateMnemonic } from './bip39.js';
+
+/**
+ * @name mnemonicGenerate
+ * @summary Creates a valid mnemonic string using using [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki).
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { mnemonicGenerate } from '@pezkuwi/util-crypto';
+ *
+ * const mnemonic = mnemonicGenerate(); // => string
+ * ```
+ */
+export function mnemonicGenerate (numWords: 12 | 15 | 18 | 21 | 24 = 12, wordlist?: string[], onlyJs?: boolean): string {
+  return !hasBigInt || (!wordlist && !onlyJs && isReady())
+    ? bip39Generate(numWords)
+    : generateMnemonic(numWords, wordlist);
+}

package/src/mnemonic/index.ts

@@ -0,0 +1,11 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @summary Create valid mnemonic strings, validate them using BIP39, and convert them to valid seeds
+ */
+export { mnemonicGenerate } from './generate.js';
+export { mnemonicToEntropy } from './toEntropy.js';
+export { mnemonicToLegacySeed } from './toLegacySeed.js';
+export { mnemonicToMiniSecret } from './toMiniSecret.js';
+export { mnemonicValidate } from './validate.js';

package/src/mnemonic/toEntropy.spec.ts

@@ -0,0 +1,36 @@
+// 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 { cryptoWaitReady } from '../index.js';
+import tests from '../sr25519/pair/testing.spec.js';
+import { french as frenchWords } from './wordlists/index.js';
+import { mnemonicToEntropy } from './toEntropy.js';
+
+await cryptoWaitReady();
+
+describe('mnemonicToEntropy', (): void => {
+  for (const onlyJs of [false, true]) {
+    describe(`onlyJs=${(onlyJs && 'true') || 'false'}`, (): void => {
+      tests.forEach(([mnemonic, entropy], index): void => {
+        it(`Created correct entropy for ${index}`, (): void => {
+          expect(u8aToHex(mnemonicToEntropy(mnemonic, undefined, onlyJs))).toEqual(entropy);
+        });
+      });
+    });
+  }
+
+  it('has the correct entropy for non-Englist mnemonics', (): void => {
+    const mnemonic = 'pompier circuler pulpe injure aspect abyssal nuque boueux équerre balisage pieuvre médecin petit suffixe soleil cumuler monstre arlequin liasse pixel garrigue noble buisson scandale';
+
+    expect(
+      () => mnemonicToEntropy(mnemonic)
+    ).toThrow();
+    expect(
+      mnemonicToEntropy(mnemonic, frenchWords)
+    ).toEqual(new Uint8Array([189, 230, 55, 17, 65, 33, 40, 4, 106, 9, 11, 88, 227, 26, 229, 76, 59, 123, 200, 55, 177, 232, 158, 66, 34, 54, 93, 54, 255, 74, 137, 70]));
+  });
+});

package/src/mnemonic/toEntropy.ts

@@ -0,0 +1,13 @@
+// Copyright 2017-2025 @pezkuwi/util-crypto authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { hasBigInt } from '@pezkuwi/util';
+import { bip39ToEntropy, isReady } from '@pezkuwi/wasm-crypto';
+
+import { mnemonicToEntropy as jsToEntropy } from './bip39.js';
+
+export function mnemonicToEntropy (mnemonic: string, wordlist?: string[], onlyJs?: boolean): Uint8Array {
+  return !hasBigInt || (!wordlist && !onlyJs && isReady())
+    ? bip39ToEntropy(mnemonic)
+    : jsToEntropy(mnemonic, wordlist);
+}