eteres 0.0.1-security → 6.7.1

package/src.ts/wallet/json-keystore.ts

@@ -0,0 +1,389 @@
+/**
+ *  The JSON Wallet formats allow a simple way to store the private
+ *  keys needed in Ethereum along with related information and allows
+ *  for extensible forms of encryption.
+ *
+ *  These utilities facilitate decrypting and encrypting the most common
+ *  JSON Wallet formats.
+ *
+ *  @_subsection: api/wallet:JSON Wallets  [json-wallets]
+ */
+
+import { CTR } from "aes-js";
+
+import { getAddress } from "../address/index.js";
+import { keccak256, pbkdf2, randomBytes, scrypt, scryptSync } from "../crypto/index.js";
+import { computeAddress } from "../transaction/index.js";
+import {
+    concat, getBytes, hexlify, uuidV4, assert, assertArgument
+} from "../utils/index.js";
+
+import { getPassword, spelunk, zpad } from "./utils.js";
+
+import type { ProgressCallback } from "../crypto/index.js";
+import type { BytesLike } from "../utils/index.js";
+
+import { version } from "../_version.js";
+
+
+const defaultPath = "m/44'/60'/0'/0/0";
+
+/**
+ *  The contents of a JSON Keystore Wallet.
+ */
+export type KeystoreAccount = {
+    address: string;
+    privateKey: string;
+    mnemonic?: {
+        path?: string;
+        locale?: string;
+        entropy: string;
+    }
+};
+
+/**
+ *  The parameters to use when encrypting a JSON Keystore Wallet.
+ */
+export type EncryptOptions = {
+   progressCallback?: ProgressCallback;
+   iv?: BytesLike;
+   entropy?: BytesLike;
+   client?: string;
+   salt?: BytesLike;
+   uuid?: string;
+   scrypt?: {
+       N?: number;
+       r?: number;
+       p?: number;
+   }
+}
+
+/**
+ *  Returns true if %%json%% is a valid JSON Keystore Wallet.
+ */
+export function isKeystoreJson(json: string): boolean {
+    try {
+        const data = JSON.parse(json);
+        const version = ((data.version != null) ? parseInt(data.version): 0);
+        if (version === 3) { return true; }
+    } catch (error) { }
+    return false;
+}
+
+function decrypt(data: any, key: Uint8Array, ciphertext: Uint8Array): string {
+    const cipher = spelunk<string>(data, "crypto.cipher:string");
+    if (cipher === "aes-128-ctr") {
+        const iv = spelunk<Uint8Array>(data, "crypto.cipherparams.iv:data!")
+        const aesCtr = new CTR(key, iv);
+        return hexlify(aesCtr.decrypt(ciphertext));
+    }
+
+    assert(false, "unsupported cipher", "UNSUPPORTED_OPERATION", {
+        operation: "decrypt"
+    });
+}
+
+function getAccount(data: any, _key: string): KeystoreAccount {
+    const key = getBytes(_key);
+    const ciphertext = spelunk<Uint8Array>(data, "crypto.ciphertext:data!");
+
+    const computedMAC = hexlify(keccak256(concat([ key.slice(16, 32), ciphertext ]))).substring(2);
+    assertArgument(computedMAC === spelunk<string>(data, "crypto.mac:string!").toLowerCase(),
+        "incorrect password", "password", "[ REDACTED ]");
+
+    const privateKey = decrypt(data, key.slice(0, 16), ciphertext);
+
+    const address = computeAddress(privateKey);
+    if (data.address) {
+        let check = data.address.toLowerCase();
+        if (!check.startsWith("0x")) { check = "0x" + check; }
+
+        assertArgument(getAddress(check) === address, "keystore address/privateKey mismatch", "address", data.address);
+    }
+
+    const account: KeystoreAccount = { address, privateKey };
+
+    // Version 0.1 x-ethers metadata must contain an encrypted mnemonic phrase
+    const version = spelunk(data, "x-ethers.version:string");
+    if (version === "0.1") {
+        const mnemonicKey = key.slice(32, 64);
+
+        const mnemonicCiphertext = spelunk<Uint8Array>(data, "x-ethers.mnemonicCiphertext:data!");
+        const mnemonicIv = spelunk<Uint8Array>(data, "x-ethers.mnemonicCounter:data!");
+
+        const mnemonicAesCtr = new CTR(mnemonicKey, mnemonicIv);
+
+        account.mnemonic = {
+            path: (spelunk<null | string>(data, "x-ethers.path:string") || defaultPath),
+            locale: (spelunk<null | string>(data, "x-ethers.locale:string") || "en"),
+            entropy: hexlify(getBytes(mnemonicAesCtr.decrypt(mnemonicCiphertext)))
+        };
+    }
+
+    return account;
+}
+
+type ScryptParams = {
+    name: "scrypt";
+    salt: Uint8Array;
+    N: number;
+    r: number;
+    p: number;
+    dkLen: number;
+};
+
+type KdfParams = ScryptParams | {
+    name: "pbkdf2";
+    salt: Uint8Array;
+    count: number;
+    dkLen: number;
+    algorithm: "sha256" | "sha512";
+};
+
+function getDecryptKdfParams<T>(data: any): KdfParams {
+    const kdf = spelunk(data, "crypto.kdf:string");
+    if (kdf && typeof(kdf) === "string") {
+        if (kdf.toLowerCase() === "scrypt") {
+            const salt = spelunk<Uint8Array>(data, "crypto.kdfparams.salt:data!");
+            const N = spelunk<number>(data, "crypto.kdfparams.n:int!");
+            const r = spelunk<number>(data, "crypto.kdfparams.r:int!");
+            const p = spelunk<number>(data, "crypto.kdfparams.p:int!");
+
+            // Make sure N is a power of 2
+            assertArgument(N > 0 && (N & (N - 1)) === 0, "invalid kdf.N", "kdf.N", N);
+            assertArgument(r > 0 && p > 0, "invalid kdf", "kdf", kdf);
+
+            const dkLen = spelunk<number>(data, "crypto.kdfparams.dklen:int!");
+            assertArgument(dkLen === 32, "invalid kdf.dklen", "kdf.dflen", dkLen);
+
+            return { name: "scrypt", salt, N, r, p, dkLen: 64 };
+
+        } else if (kdf.toLowerCase() === "pbkdf2") {
+
+            const salt = spelunk<Uint8Array>(data, "crypto.kdfparams.salt:data!");
+
+            const prf = spelunk<string>(data, "crypto.kdfparams.prf:string!");
+            const algorithm = prf.split("-").pop();
+            assertArgument(algorithm === "sha256" || algorithm === "sha512", "invalid kdf.pdf", "kdf.pdf", prf);
+
+            const count = spelunk<number>(data, "crypto.kdfparams.c:int!");
+
+            const dkLen = spelunk<number>(data, "crypto.kdfparams.dklen:int!");
+            assertArgument(dkLen === 32, "invalid kdf.dklen", "kdf.dklen", dkLen);
+
+            return { name: "pbkdf2", salt, count, dkLen, algorithm };
+        }
+    }
+
+    assertArgument(false, "unsupported key-derivation function", "kdf", kdf);
+}
+
+
+/**
+ *  Returns the account details for the JSON Keystore Wallet %%json%%
+ *  using %%password%%.
+ *
+ *  It is preferred to use the [async version](decryptKeystoreJson)
+ *  instead, which allows a [[ProgressCallback]] to keep the user informed
+ *  as to the decryption status.
+ *
+ *  This method will block the event loop (freezing all UI) until decryption
+ *  is complete, which can take quite some time, depending on the wallet
+ *  paramters and platform.
+ */
+export function decryptKeystoreJsonSync(json: string, _password: string | Uint8Array): KeystoreAccount {
+    const data = JSON.parse(json);
+
+    const password = getPassword(_password);
+
+    const params = getDecryptKdfParams(data);
+    if (params.name === "pbkdf2") {
+        const { salt, count, dkLen, algorithm } = params;
+        const key = pbkdf2(password, salt, count, dkLen, algorithm);
+        return getAccount(data, key);
+    }
+
+    assert(params.name === "scrypt", "cannot be reached", "UNKNOWN_ERROR", { params })
+
+    const { salt, N, r, p, dkLen } = params;
+    const key = scryptSync(password, salt, N, r, p, dkLen);
+    return getAccount(data, key);
+}
+
+function stall(duration: number): Promise<void> {
+    return new Promise((resolve) => { setTimeout(() => { resolve(); }, duration); });
+}
+
+/**
+ *  Resolves to the decrypted JSON Keystore Wallet %%json%% using the
+ *  %%password%%.
+ *
+ *  If provided, %%progress%% will be called periodically during the
+ *  decrpytion to provide feedback, and if the function returns
+ *  ``false`` will halt decryption.
+ *
+ *  The %%progressCallback%% will **always** receive ``0`` before
+ *  decryption begins and ``1`` when complete.
+ */
+export async function decryptKeystoreJson(json: string, _password: string | Uint8Array, progress?: ProgressCallback): Promise<KeystoreAccount> {
+    const data = JSON.parse(json);
+
+    const password = getPassword(_password);
+
+    const params = getDecryptKdfParams(data);
+    if (params.name === "pbkdf2") {
+        if (progress) {
+            progress(0);
+            await stall(0);
+        }
+        const { salt, count, dkLen, algorithm } = params;
+        const key = pbkdf2(password, salt, count, dkLen, algorithm);
+        if (progress) {
+            progress(1);
+            await stall(0);
+        }
+        return getAccount(data, key);
+    }
+
+    assert(params.name === "scrypt", "cannot be reached", "UNKNOWN_ERROR", { params })
+
+    const { salt, N, r, p, dkLen } = params;
+    const key = await scrypt(password, salt, N, r, p, dkLen, progress);
+    return getAccount(data, key);
+}
+
+function getEncryptKdfParams(options: EncryptOptions): ScryptParams {
+    // Check/generate the salt
+    const salt = (options.salt != null) ? getBytes(options.salt, "options.salt"): randomBytes(32);
+
+    // Override the scrypt password-based key derivation function parameters
+    let N = (1 << 17), r = 8, p = 1;
+    if (options.scrypt) {
+        if (options.scrypt.N) { N = options.scrypt.N; }
+        if (options.scrypt.r) { r = options.scrypt.r; }
+        if (options.scrypt.p) { p = options.scrypt.p; }
+    }
+    assertArgument(typeof(N) === "number" && N > 0 && Number.isSafeInteger(N) && (BigInt(N) & BigInt(N - 1)) === BigInt(0), "invalid scrypt N parameter", "options.N", N);
+    assertArgument(typeof(r) === "number" && r > 0 && Number.isSafeInteger(r), "invalid scrypt r parameter", "options.r", r);
+    assertArgument(typeof(p) === "number" && p > 0 && Number.isSafeInteger(p), "invalid scrypt p parameter", "options.p", p);
+
+    return { name: "scrypt", dkLen: 32, salt, N, r, p };
+}
+
+function _encryptKeystore(key: Uint8Array, kdf: ScryptParams, account: KeystoreAccount, options: EncryptOptions): any {
+
+    const privateKey = getBytes(account.privateKey, "privateKey");
+
+    // Override initialization vector
+    const iv = (options.iv != null) ? getBytes(options.iv, "options.iv"): randomBytes(16);
+    assertArgument(iv.length === 16, "invalid options.iv length", "options.iv", options.iv);
+
+    // Override the uuid
+    const uuidRandom = (options.uuid != null) ? getBytes(options.uuid, "options.uuid"): randomBytes(16);
+    assertArgument(uuidRandom.length === 16, "invalid options.uuid length", "options.uuid", options.iv);
+
+    // This will be used to encrypt the wallet (as per Web3 secret storage)
+    // - 32 bytes   As normal for the Web3 secret storage (derivedKey, macPrefix)
+    // - 32 bytes   AES key to encrypt mnemonic with (required here to be Ethers Wallet)
+    const derivedKey = key.slice(0, 16);
+    const macPrefix = key.slice(16, 32);
+
+    // Encrypt the private key
+    const aesCtr = new CTR(derivedKey, iv);
+    const ciphertext = getBytes(aesCtr.encrypt(privateKey));
+
+    // Compute the message authentication code, used to check the password
+    const mac = keccak256(concat([ macPrefix, ciphertext ]))
+
+    // See: https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition
+    const data: { [key: string]: any } = {
+        address: account.address.substring(2).toLowerCase(),
+        id: uuidV4(uuidRandom),
+        version: 3,
+        Crypto: {
+            cipher: "aes-128-ctr",
+            cipherparams: {
+                iv: hexlify(iv).substring(2),
+            },
+            ciphertext: hexlify(ciphertext).substring(2),
+            kdf: "scrypt",
+            kdfparams: {
+                salt: hexlify(kdf.salt).substring(2),
+                n: kdf.N,
+                dklen: 32,
+                p: kdf.p,
+                r: kdf.r
+            },
+            mac: mac.substring(2)
+        }
+    };
+
+    // If we have a mnemonic, encrypt it into the JSON wallet
+    if (account.mnemonic) {
+        const client = (options.client != null) ? options.client: `ethers/${ version }`;
+
+        const path = account.mnemonic.path || defaultPath;
+        const locale = account.mnemonic.locale || "en";
+
+        const mnemonicKey = key.slice(32, 64);
+
+        const entropy = getBytes(account.mnemonic.entropy, "account.mnemonic.entropy");
+        const mnemonicIv = randomBytes(16);
+        const mnemonicAesCtr = new CTR(mnemonicKey, mnemonicIv);
+        const mnemonicCiphertext = getBytes(mnemonicAesCtr.encrypt(entropy));
+
+        const now = new Date();
+        const timestamp = (now.getUTCFullYear() + "-" +
+                           zpad(now.getUTCMonth() + 1, 2) + "-" +
+                           zpad(now.getUTCDate(), 2) + "T" +
+                           zpad(now.getUTCHours(), 2) + "-" +
+                           zpad(now.getUTCMinutes(), 2) + "-" +
+                           zpad(now.getUTCSeconds(), 2) + ".0Z");
+        const gethFilename = ("UTC--" + timestamp + "--" + data.address);
+
+        data["x-ethers"] = {
+            client, gethFilename, path, locale,
+            mnemonicCounter: hexlify(mnemonicIv).substring(2),
+            mnemonicCiphertext: hexlify(mnemonicCiphertext).substring(2),
+            version: "0.1"
+        };
+    }
+
+    return JSON.stringify(data);
+}
+
+/**
+ *  Return the JSON Keystore Wallet for %%account%% encrypted with
+ *  %%password%%.
+ *
+ *  The %%options%% can be used to tune the password-based key
+ *  derivation function parameters, explicitly set the random values
+ *  used. Any provided [[ProgressCallback]] is ignord.
+ */
+export function encryptKeystoreJsonSync(account: KeystoreAccount, password: string | Uint8Array, options?: EncryptOptions): string {
+    if (options == null) { options = { }; }
+
+    const passwordBytes = getPassword(password);
+    const kdf = getEncryptKdfParams(options);
+    const key = scryptSync(passwordBytes, kdf.salt, kdf.N, kdf.r, kdf.p, 64);
+    return _encryptKeystore(getBytes(key), kdf, account, options);
+}
+
+/**
+ *  Resolved to the JSON Keystore Wallet for %%account%% encrypted
+ *  with %%password%%.
+ *
+ *  The %%options%% can be used to tune the password-based key
+ *  derivation function parameters, explicitly set the random values
+ *  used and provide a [[ProgressCallback]] to receive periodic updates
+ *  on the completion status..
+ */
+export async function encryptKeystoreJson(account: KeystoreAccount, password: string | Uint8Array, options?: EncryptOptions): Promise<string> {
+    if (options == null) { options = { }; }
+
+    const passwordBytes = getPassword(password);
+    const kdf = getEncryptKdfParams(options);
+    const key = await scrypt(passwordBytes, kdf.salt, kdf.N, kdf.r, kdf.p, 64, options.progressCallback);
+    return _encryptKeystore(getBytes(key), kdf, account, options);
+}
+

package/src.ts/wallet/mnemonic.ts

@@ -0,0 +1,203 @@
+import { pbkdf2, sha256 } from "../crypto/index.js";
+import {
+    defineProperties, getBytes, hexlify, assertNormalize, assertPrivate, assertArgument, toUtf8Bytes
+} from "../utils/index.js";
+import { LangEn } from "../wordlists/lang-en.js";
+
+import type { BytesLike } from "../utils/index.js";
+import type { Wordlist } from "../wordlists/index.js";
+
+
+// Returns a byte with the MSB bits set
+function getUpperMask(bits: number): number {
+   return ((1 << bits) - 1) << (8 - bits) & 0xff;
+}
+
+// Returns a byte with the LSB bits set
+function getLowerMask(bits: number): number {
+   return ((1 << bits) - 1) & 0xff;
+}
+
+
+function mnemonicToEntropy(mnemonic: string, wordlist?: null | Wordlist): string {
+    assertNormalize("NFKD");
+
+    if (wordlist == null) { wordlist = LangEn.wordlist(); }
+
+    const words = wordlist.split(mnemonic);
+    assertArgument((words.length % 3) === 0 && words.length >= 12 && words.length <= 24,
+        "invalid mnemonic length", "mnemonic", "[ REDACTED ]");
+
+    const entropy = new Uint8Array(Math.ceil(11 * words.length / 8));
+
+    let offset = 0;
+    for (let i = 0; i < words.length; i++) {
+        let index = wordlist.getWordIndex(words[i].normalize("NFKD"));
+        assertArgument(index >= 0, `invalid mnemonic word at index ${ i }`, "mnemonic", "[ REDACTED ]");
+
+        for (let bit = 0; bit < 11; bit++) {
+            if (index & (1 << (10 - bit))) {
+                entropy[offset >> 3] |= (1 << (7 - (offset % 8)));
+            }
+            offset++;
+        }
+    }
+
+    const entropyBits = 32 * words.length / 3;
+
+
+    const checksumBits = words.length / 3;
+    const checksumMask = getUpperMask(checksumBits);
+
+    const checksum = getBytes(sha256(entropy.slice(0, entropyBits / 8)))[0] & checksumMask;
+
+    assertArgument(checksum === (entropy[entropy.length - 1] & checksumMask),
+        "invalid mnemonic checksum", "mnemonic", "[ REDACTED ]");
+
+    return hexlify(entropy.slice(0, entropyBits / 8));
+}
+
+function entropyToMnemonic(entropy: Uint8Array, wordlist?: null | Wordlist): string {
+
+    assertArgument((entropy.length % 4) === 0 && entropy.length >= 16 && entropy.length <= 32,
+        "invalid entropy size", "entropy", "[ REDACTED ]");
+
+    if (wordlist == null) { wordlist = LangEn.wordlist(); }
+
+    const indices: Array<number> = [ 0 ];
+
+    let remainingBits = 11;
+    for (let i = 0; i < entropy.length; i++) {
+
+        // Consume the whole byte (with still more to go)
+        if (remainingBits > 8) {
+            indices[indices.length - 1] <<= 8;
+            indices[indices.length - 1] |= entropy[i];
+
+            remainingBits -= 8;
+
+        // This byte will complete an 11-bit index
+        } else {
+            indices[indices.length - 1] <<= remainingBits;
+            indices[indices.length - 1] |= entropy[i] >> (8 - remainingBits);
+
+            // Start the next word
+            indices.push(entropy[i] & getLowerMask(8 - remainingBits));
+
+            remainingBits += 3;
+        }
+    }
+
+    // Compute the checksum bits
+    const checksumBits = entropy.length / 4;
+    const checksum = parseInt(sha256(entropy).substring(2, 4), 16) & getUpperMask(checksumBits);
+
+    // Shift the checksum into the word indices
+    indices[indices.length - 1] <<= checksumBits;
+    indices[indices.length - 1] |= (checksum >> (8 - checksumBits));
+
+    return wordlist.join(indices.map((index) => (<Wordlist>wordlist).getWord(index)));
+}
+
+const _guard = { };
+
+/**
+ *  A **Mnemonic** wraps all properties required to compute [[link-bip-39]]
+ *  seeds and convert between phrases and entropy.
+ */
+export class Mnemonic {
+    /**
+     *  The mnemonic phrase of 12, 15, 18, 21 or 24 words.
+     *
+     *  Use the [[wordlist]] ``split`` method to get the individual words.
+     */
+    readonly phrase!: string;
+
+    /**
+     *  The password used for this mnemonic. If no password is used this
+     *  is the empty string (i.e. ``""``) as per the specification.
+     */
+    readonly password!: string;
+
+    /**
+     *  The wordlist for this mnemonic.
+     */
+    readonly wordlist!: Wordlist;
+
+    /**
+     *  The underlying entropy which the mnemonic encodes.
+     */
+    readonly entropy!: string;
+
+    /**
+     *  @private
+     */
+    constructor(guard: any, entropy: string, phrase: string, password?: null | string, wordlist?: null | Wordlist) {
+        if (password == null) { password = ""; }
+        if (wordlist == null) { wordlist = LangEn.wordlist(); }
+        assertPrivate(guard, _guard, "Mnemonic");
+        defineProperties<Mnemonic>(this, { phrase, password, wordlist, entropy });
+    }
+
+    /**
+     *  Returns the seed for the mnemonic.
+     */
+    computeSeed(): string {
+        const salt = toUtf8Bytes("mnemonic" + this.password, "NFKD");
+        return pbkdf2(toUtf8Bytes(this.phrase, "NFKD"), salt, 2048, 64, "sha512");
+    }
+
+    /**
+     *  Creates a new Mnemonic for the %%phrase%%.
+     *
+     *  The default %%password%% is the empty string and the default
+     *  wordlist is the [English wordlists](LangEn).
+     */
+    static fromPhrase(phrase: string, password?: null | string, wordlist?: null | Wordlist): Mnemonic {
+        // Normalize the case and space; throws if invalid
+        const entropy = mnemonicToEntropy(phrase, wordlist);
+        phrase = entropyToMnemonic(getBytes(entropy), wordlist);
+        return new Mnemonic(_guard, entropy, phrase, password, wordlist);
+    }
+
+    /**
+     *  Create a new **Mnemonic** from the %%entropy%%.
+     *
+     *  The default %%password%% is the empty string and the default
+     *  wordlist is the [English wordlists](LangEn).
+     */
+    static fromEntropy(_entropy: BytesLike, password?: null | string, wordlist?: null | Wordlist): Mnemonic {
+        const entropy = getBytes(_entropy, "entropy");
+        const phrase = entropyToMnemonic(entropy, wordlist);
+        return new Mnemonic(_guard, hexlify(entropy), phrase, password, wordlist);
+    }
+
+    /**
+     *  Returns the phrase for %%mnemonic%%.
+     */
+    static entropyToPhrase(_entropy: BytesLike, wordlist?: null | Wordlist): string {
+        const entropy = getBytes(_entropy, "entropy");
+        return entropyToMnemonic(entropy, wordlist);
+    }
+
+    /**
+     *  Returns the entropy for %%phrase%%.
+     */
+    static phraseToEntropy(phrase: string, wordlist?: null | Wordlist): string {
+        return mnemonicToEntropy(phrase, wordlist);
+    }
+
+    /**
+     *  Returns true if %%phrase%% is a valid [[link-bip-39]] phrase.
+     *
+     *  This checks all the provided words belong to the %%wordlist%%,
+     *  that the length is valid and the checksum is correct.
+     */
+    static isValidMnemonic(phrase: string, wordlist?: null | Wordlist): boolean {
+        try {
+            mnemonicToEntropy(phrase, wordlist);
+            return true;
+        } catch (error) { }
+        return false;
+    }
+}