@scure/bip39 - npm Package Compare versions

Comparing version 1.2.1 to 1.2.2

esm/index.js

@@ -1,2 +0,3 @@
-import assert from '@noble/hashes/_assert';
+/*! scure-bip39 - MIT License (c) 2022 Patricio Palladino, Paul Miller (paulmillr.com) */
+import { bytes as assertBytes, number as assertNumber } from '@noble/hashes/_assert';
 import { pbkdf2, pbkdf2Async } from '@noble/hashes/pbkdf2';
@@ -7,3 +8,8 @@ import { sha256 } from '@noble/hashes/sha256';
 import { utils as baseUtils } from '@scure/base';
+// Japanese wordlist
 const isJapanese = (wordlist) => wordlist[0] === '\u3042\u3044\u3053\u304f\u3057\u3093';
+// Normalization replaces equivalent sequences of characters
+// so that any two texts that are equivalent will be reduced
+// to the same sequence of code points, called the normal form of the original text.
+// https://tonsky.me/blog/unicode/#why-is-a----
 function nfkd(str) {
@@ -22,6 +28,14 @@ if (typeof str !== 'string')
 function assertEntropy(entropy) {
-    assert.bytes(entropy, 16, 20, 24, 28, 32);
+    assertBytes(entropy, 16, 20, 24, 28, 32);
 }
+/**
+ * Generate x random words. Uses Cryptographically-Secure Random Number Generator.
+ * @param wordlist imported wordlist for specific language
+ * @param strength mnemonic strength 128-256 bits
+ * @example
+ * generateMnemonic(wordlist, 128)
+ * // 'legal winner thank year wave sausage worth useful legal winner thank yellow'
+ */
 export function generateMnemonic(wordlist, strength = 128) {
-    assert.number(strength);
+    assertNumber(strength);
     if (strength % 32 !== 0 || strength > 256)
@@ -32,3 +46,6 @@ throw new TypeError('Invalid entropy');
 const calcChecksum = (entropy) => {
+    // Checksum is ent.length/4 bits long
     const bitsLeft = 8 - entropy.length / 4;
+    // Zero rightmost "bitsLeft" bits in byte
+    // For example: bitsLeft=4 val=10111101 -> 10110000
     return new Uint8Array([(sha256(entropy)[0] >> bitsLeft) << bitsLeft]);
@@ -38,3 +55,3 @@ };
     if (!Array.isArray(wordlist) || wordlist.length !== 2048 || typeof wordlist[0] !== 'string')
-        throw new Error('Worlist: expected array of 2048 strings');
+        throw new Error('Wordlist: expected array of 2048 strings');
     wordlist.forEach((i) => {
@@ -46,2 +63,15 @@ if (typeof i !== 'string')
 }
+/**
+ * Reversible: Converts mnemonic string to raw entropy in form of byte array.
+ * @param mnemonic 12-24 words
+ * @param wordlist imported wordlist for specific language
+ * @example
+ * const mnem = 'legal winner thank year wave sausage worth useful legal winner thank yellow';
+ * mnemonicToEntropy(mnem, wordlist)
+ * // Produces
+ * new Uint8Array([
+ *   0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f,
+ *   0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f
+ * ])
+ */
 export function mnemonicToEntropy(mnemonic, wordlist) {
@@ -53,2 +83,15 @@ const { words } = normalize(mnemonic);
 }
+/**
+ * Reversible: Converts raw entropy in form of byte array to mnemonic string.
+ * @param entropy byte array
+ * @param wordlist imported wordlist for specific language
+ * @returns 12-24 words
+ * @example
+ * const ent = new Uint8Array([
+ *   0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f,
+ *   0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f, 0x7f
+ * ]);
+ * entropyToMnemonic(ent, wordlist);
+ * // 'legal winner thank year wave sausage worth useful legal winner thank yellow'
+ */
 export function entropyToMnemonic(entropy, wordlist) {
@@ -59,2 +102,5 @@ assertEntropy(entropy);
 }
+/**
+ * Validates mnemonic for being 12-24 words contained in `wordlist`.
+ */
 export function validateMnemonic(mnemonic, wordlist) {
@@ -70,8 +116,27 @@ try {
 const salt = (passphrase) => nfkd(`mnemonic${passphrase}`);
+/**
+ * Irreversible: Uses KDF to derive 64 bytes of key data from mnemonic + optional password.
+ * @param mnemonic 12-24 words
+ * @param passphrase string that will additionally protect the key
+ * @returns 64 bytes of key data
+ * @example
+ * const mnem = 'legal winner thank year wave sausage worth useful legal winner thank yellow';
+ * await mnemonicToSeed(mnem, 'password');
+ * // new Uint8Array([...64 bytes])
+ */
 export function mnemonicToSeed(mnemonic, passphrase = '') {
     return pbkdf2Async(sha512, normalize(mnemonic).nfkd, salt(passphrase), { c: 2048, dkLen: 64 });
 }
+/**
+ * Irreversible: Uses KDF to derive 64 bytes of key data from mnemonic + optional password.
+ * @param mnemonic 12-24 words
+ * @param passphrase string that will additionally protect the key
+ * @returns 64 bytes of key data
+ * @example
+ * const mnem = 'legal winner thank year wave sausage worth useful legal winner thank yellow';
+ * mnemonicToSeedSync(mnem, 'password');
+ * // new Uint8Array([...64 bytes])
+ */
 export function mnemonicToSeedSync(mnemonic, passphrase = '') {
     return pbkdf2(sha512, normalize(mnemonic).nfkd, salt(passphrase), { c: 2048, dkLen: 64 });
 }
-//# sourceMappingURL=index.js.map

esm/wordlists/czech.js

@@ -2049,2 +2049,1 @@ export const wordlist = `abdikace
 zvyk`.split('\n');
-//# sourceMappingURL=czech.js.map

esm/wordlists/english.js

@@ -2049,2 +2049,1 @@ export const wordlist = `abandon
 zoo`.split('\n');
-//# sourceMappingURL=english.js.map

esm/wordlists/french.js

@@ -2049,2 +2049,1 @@ export const wordlist = `abaisser
 zoologie`.split('\n');
-//# sourceMappingURL=french.js.map

esm/wordlists/italian.js

@@ -2049,2 +2049,1 @@ export const wordlist = `abaco
 zuppa`.split('\n');
-//# sourceMappingURL=italian.js.map

esm/wordlists/japanese.js

@@ -2049,2 +2049,1 @@ export const wordlist = `あいこくしん
 われる`.split('\n');
-//# sourceMappingURL=japanese.js.map

esm/wordlists/korean.js

@@ -2049,2 +2049,1 @@ export const wordlist = `가격
 힘껏`.split('\n');
-//# sourceMappingURL=korean.js.map

esm/wordlists/simplified-chinese.js

@@ -2049,2 +2049,1 @@ export const wordlist = `的
 歇`.split('\n');
-//# sourceMappingURL=simplified-chinese.js.map

esm/wordlists/spanish.js

@@ -2049,2 +2049,1 @@ export const wordlist = `ábaco
 zurdo`.split('\n');
-//# sourceMappingURL=spanish.js.map

esm/wordlists/traditional-chinese.js

@@ -2049,2 +2049,1 @@ export const wordlist = `的
 歇`.split('\n');
-//# sourceMappingURL=traditional-chinese.js.map

index.js

@@ -16,2 +16,3 @@ "use strict";
 // to the same sequence of code points, called the normal form of the original text.
+// https://tonsky.me/blog/unicode/#why-is-a----
 function nfkd(str) {
@@ -30,3 +31,3 @@ if (typeof str !== 'string')
 function assertEntropy(entropy) {
-    _assert_1.default.bytes(entropy, 16, 20, 24, 28, 32);
+    (0, _assert_1.bytes)(entropy, 16, 20, 24, 28, 32);
 }
@@ -42,3 +43,3 @@ /**
 function generateMnemonic(wordlist, strength = 128) {
-    _assert_1.default.number(strength);
+    (0, _assert_1.number)(strength);
     if (strength % 32 !== 0 || strength > 256)
@@ -58,3 +59,3 @@ throw new TypeError('Invalid entropy');
     if (!Array.isArray(wordlist) || wordlist.length !== 2048 || typeof wordlist[0] !== 'string')
-        throw new Error('Worlist: expected array of 2048 strings');
+        throw new Error('Wordlist: expected array of 2048 strings');
     wordlist.forEach((i) => {
@@ -61,0 +62,0 @@ if (typeof i !== 'string')

package.json

 {
   "name": "@scure/bip39",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Secure, audited & minimal implementation of BIP39 mnemonic phrases",
@@ -11,13 +11,14 @@ "main": "index.js",
     "wordlists/*.d.ts",
-    "esm"
+    "esm",
+    "src/index.ts"
   ],
   "types": "index.d.ts",
   "dependencies": {
-    "@noble/hashes": "~1.3.0",
-    "@scure/base": "~1.1.0"
+    "@noble/hashes": "~1.3.2",
+    "@scure/base": "~1.1.4"
   },
   "devDependencies": {
     "micro-should": "0.4.0",
-    "prettier": "2.8.4",
-    "typescript": "5.0.2"
+    "prettier": "3.1.1",
+    "typescript": "5.3.2"
   },
@@ -43,5 +44,6 @@ "author": "Paul Miller (https://paulmillr.com)",
     "build": "tsc && tsc -p tsconfig.esm.json",
-    "lint": "prettier --check 'src/**/*.ts' 'test/*.test.ts'",
-    "format": "prettier --write 'src/**/*.ts' 'test/*.test.ts'",
-    "test": "cd test && tsc && node bip39.test.js"
+    "lint": "prettier --check 'src/**/*.ts' 'test/*.test.ts' 'scripts/*.js'",
+    "format": "prettier --write 'src/**/*.ts' 'test/*.test.ts' 'scripts/*.js'",
+    "test": "cd test && tsc && node bip39.test.js",
+    "fetch-wordlist": "./scripts/fetch-wordlist.js"
   },
@@ -89,2 +91,7 @@ "exports": {
     },
+    "./wordlists/portuguese": {
+      "types": "./wordlists/portuguese.d.ts",
+      "import": "./esm/wordlists/portuguese.js",
+      "default": "./wordlists/portuguese.js"
+    },
     "./wordlists/simplified-chinese": {
@@ -113,3 +120,2 @@ "types": "./wordlists/simplified-chinese.d.ts",
     "bip-39",
-    "micro",
     "scure",
@@ -116,0 +122,0 @@ "wordlist",

README.md

 # scure-bip39
 
-Secure, [audited](#security) & minimal implementation of BIP39 mnemonic phrases.
+Audited & minimal JS implementation of [BIP39 mnemonic phrases](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki).
 
-Compared to popular `bip39` package, scure-bip39:
+- 🔒 [**Audited**](#security) by an independent security firm
+- 🔻 Tree-shaking-friendly: use only what's necessary, other code won't be included
+- 📦 ESM and common.js
+- ➰ Only 2 audited dependencies by the same author:
+  [noble-curves](https://github.com/paulmillr/noble-curves) and [scure-base](https://github.com/paulmillr/scure-base)
+- 🪶 37KB with all deps bundled and 279KB with wordlists: much smaller than similar libraries
 
-- Supports ESM and common.js
-- Supports tree-shaking: only actually used wordlists are bundled
-- Is 491KB all-bundled instead of 1.3MB
-- Uses 2 dependencies instead of 15
-- Wordlists are 157KB instead of 315KB
-- Had an external security [audit](#security) by Cure53
-
 Check out [scure-bip32](https://github.com/paulmillr/scure-bip32) if you need
@@ -19,11 +17,13 @@ hierarchical deterministic wallets ("HD Wallets").
 
-> **scure** — secure, independently audited packages for every use case.
+> **scure** — audited micro-libraries.
 
-- All releases are signed with PGP keys
-- As minimal as possible
-- Check out all libraries:
+- Zero or minimal dependencies
+- Highly readable TypeScript / JS code
+- PGP-signed releases and transparent NPM builds
+- Check out [homepage](https://paulmillr.com/noble/#scure) & all libraries:
   [base](https://github.com/paulmillr/scure-base),
   [bip32](https://github.com/paulmillr/scure-bip32),
   [bip39](https://github.com/paulmillr/scure-bip39),
-  [btc-signer](https://github.com/paulmillr/scure-btc-signer)
+  [btc-signer](https://github.com/paulmillr/scure-btc-signer),
+  [starknet](https://github.com/paulmillr/scure-starknet)
 
@@ -34,6 +34,2 @@ ## Usage
 
-Or
-
-> yarn add @scure/bip39
-
 ```js
@@ -61,3 +57,3 @@ import * as bip39 from '@scure/bip39';
 
-This submodule contains the word lists defined by BIP39 for Czech, English, French, Italian, Japanese, Korean, Simplified and Traditional Chinese, and Spanish. These are not imported by default, as that would increase bundle sizes too much. Instead, you should import and use them explicitly.
+This submodule contains the word lists defined by BIP39 for Czech, English, French, Italian, Japanese, Korean, Portuguese, Simplified and Traditional Chinese, and Spanish. These are not imported by default, as that would increase bundle sizes too much. Instead, you should import and use them explicitly.
 
@@ -82,5 +78,6 @@ ```typescript
 import { wordlist as korean } from '@scure/bip39/wordlists/korean';
-import { wordlist as simp } from '@scure/bip39/wordlists/simplified-chinese';
+import { wordlist as portuguese } from '@scure/bip39/wordlists/portuguese';
+import { wordlist as simplifiedChinese } from '@scure/bip39/wordlists/simplified-chinese';
 import { wordlist as spanish } from '@scure/bip39/wordlists/spanish';
-import { wordlist as trad } from '@scure/bip39/wordlists/traditional-chinese';
+import { wordlist as traditionalChinese } from '@scure/bip39/wordlists/traditional-chinese';
 ```
@@ -90,9 +87,16 @@
 
-The library has been audited by Cure53 on Jan 5, 2022. Check out the audit [PDF](./audit/2022-01-05-cure53-audit-nbl2.pdf) & [URL](https://cure53.de/pentest-report_hashing-libs.pdf). See [changes since audit](https://github.com/paulmillr/scure-bip39/compare/1.0.0..main).
+To audit wordlist content, run `node scripts/fetch-wordlist.js`.
 
-1. The library was initially developed for [js-ethereum-cryptography](https://github.com/ethereum/js-ethereum-cryptography)
-2. At commit [ae00e6d7](https://github.com/ethereum/js-ethereum-cryptography/commit/ae00e6d7d24fb3c76a1c7fe10039f6ecd120b77e), it
-  was extracted to a separate package called `micro-bip39`
-3. After the audit we've decided to use NPM namespace for security. Since `@micro` namespace was taken, we've renamed the package to `@scure/bip39`
+The library has been independently audited:
 
+- at version 1.0.0, in Jan 2022, by [cure53](https://cure53.de)
+  - PDFs: [online](https://cure53.de/pentest-report_hashing-libs.pdf), [offline](./audit/2022-01-05-cure53-audit-nbl2.pdf)
+  - [Changes since audit](https://github.com/paulmillr/scure-bip39/compare/1.0.0..main).
+  - The audit has been funded by [Ethereum Foundation](https://ethereum.org/en/) with help of [Nomic Labs](https://nomiclabs.io)
+
+The library was initially developed for [js-ethereum-cryptography](https://github.com/ethereum/js-ethereum-cryptography).
+At commit [ae00e6d7](https://github.com/ethereum/js-ethereum-cryptography/commit/ae00e6d7d24fb3c76a1c7fe10039f6ecd120b77e),
+it was extracted to a separate package called `micro-bip39`.
+After the audit we've decided to use `@scure` NPM namespace for security.
+
 ## License
@@ -99,0 +103,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

373469

increased by4.75%

Lines of code

41473

increased by11.57%

Number of lines in readme file

102

increased by4.08%

Worsened metrics

Number of package files

38

decreased by-13.64%

Dependency changes

• + Added@scure/base@1.1.9(transitive)

• - Removed@scure/base@1.1.8(transitive)

• Updated@noble/hashes@~1.3.2

• Updated@scure/base@~1.1.4