@aeternity/aepp-sdk 10.0.0 → 12.0.0

package/src/utils/hd-wallet.ts

@@ -0,0 +1,134 @@
+import nacl from 'tweetnacl'
+import { full as hmac } from 'tweetnacl-auth'
+import { fromString } from 'bip32-path'
+import { decryptKey, encryptKey } from './crypto'
+import { encode } from './encoder'
+import { CryptographyError } from './errors'
+import { bytesToHex } from './bytes'
+import { concatBuffers } from './other'
+
+/**
+ * @category exception
+ */
+export class DerivationError extends CryptographyError {
+  constructor (message: string) {
+    super(message)
+    this.name = 'DerivationError'
+  }
+}
+
+const ED25519_CURVE = Buffer.from('ed25519 seed')
+const HARDENED_OFFSET = 0x80000000
+
+interface KeyTreeNode {
+  secretKey: Uint8Array
+  chainCode: Uint8Array
+}
+
+interface HDWallet {
+  secretKey: string
+  chainCode: string
+}
+
+interface Account {
+  secretKey: string
+  publicKey: string
+}
+
+type Dec<N extends number> = [-1, 0, 1, 2, 3, 4][N]
+type Bip32PathT<MaxLen extends number, H extends 'H' | 'h' | '\''> = MaxLen extends -1
+  ? `${number}${H}`
+  : Bip32PathT<Dec<MaxLen>, H> | `${Bip32PathT<Dec<MaxLen>, H>}/${number}${H}`
+type Bip32Path<MaxLen extends number> =
+  '' | Bip32PathT<MaxLen, 'H'> | Bip32PathT<MaxLen, 'h'> | Bip32PathT<MaxLen, '\''>
+
+export function derivePathFromKey (path: Bip32Path<5>, key: KeyTreeNode): KeyTreeNode {
+  const segments = path === '' ? [] : fromString(path).toPathArray()
+  segments.forEach((segment, i) => {
+    if (segment < HARDENED_OFFSET) {
+      throw new DerivationError(`Segment #${i + 1} is not hardened`)
+    }
+  })
+
+  return segments.reduce((parentKey, segment) => deriveChild(parentKey, segment), key)
+}
+
+export function derivePathFromSeed (path: 'm' | `m/${Bip32Path<5>}`, seed: Uint8Array): KeyTreeNode {
+  if (!['m', 'm/'].includes(path.slice(0, 2))) {
+    throw new DerivationError('Root element is required')
+  }
+  const masterKey = getMasterKeyFromSeed(seed)
+  return derivePathFromKey(path.slice(2) as Bip32Path<5>, masterKey)
+}
+
+function formatAccount (keys: nacl.SignKeyPair): Account {
+  const { secretKey, publicKey } = keys
+  return {
+    secretKey: bytesToHex(secretKey),
+    publicKey: encode(publicKey, 'ak')
+  }
+}
+
+export function getKeyPair (secretKey: Uint8Array): nacl.SignKeyPair {
+  return nacl.sign.keyPair.fromSeed(secretKey)
+}
+
+export function getMasterKeyFromSeed (seed: Uint8Array): KeyTreeNode {
+  const I = hmac(seed, ED25519_CURVE)
+  const IL = I.slice(0, 32)
+  const IR = I.slice(32)
+  return {
+    secretKey: IL,
+    chainCode: IR
+  }
+}
+
+export function deriveChild ({ secretKey, chainCode }: KeyTreeNode, index: number): KeyTreeNode {
+  if (index < HARDENED_OFFSET) {
+    throw new DerivationError(`Segment ${index} is not hardened`)
+  }
+  const indexBuffer = Buffer.allocUnsafe(4)
+  indexBuffer.writeUInt32BE(index, 0)
+
+  const data = concatBuffers([Buffer.alloc(1, 0), secretKey, indexBuffer])
+
+  const I = hmac(data, chainCode)
+  const IL = I.slice(0, 32)
+  const IR = I.slice(32)
+  return {
+    secretKey: IL,
+    chainCode: IR
+  }
+}
+
+export function generateSaveHDWalletFromSeed (seed: Uint8Array, password: string): HDWallet {
+  const walletKey = derivePathFromSeed('m/44h/457h', seed)
+  return {
+    secretKey: bytesToHex(encryptKey(password, walletKey.secretKey)),
+    chainCode: bytesToHex(encryptKey(password, walletKey.chainCode))
+  }
+}
+
+export function getSaveHDWalletAccounts (
+  saveHDWallet: HDWallet, password: string, accountCount: number
+): Account[] {
+  const walletKey = {
+    secretKey: decryptKey(password, Buffer.from(saveHDWallet.secretKey, 'hex')),
+    chainCode: decryptKey(password, Buffer.from(saveHDWallet.chainCode, 'hex'))
+  }
+  return (new Array(accountCount)).fill(undefined)
+    .map((_, idx) =>
+      formatAccount(getKeyPair(derivePathFromKey(`${idx}h/0h/0h`, walletKey).secretKey)))
+}
+
+export const getHdWalletAccountFromSeed = (
+  seed: Uint8Array, accountIdx: number
+): Account & { idx: number } => {
+  const walletKey = derivePathFromSeed('m/44h/457h', seed)
+  const derived = derivePathFromKey(`${accountIdx}h/0h/0h`, walletKey)
+  const keyPair = getKeyPair(derived.secretKey)
+  return {
+    ...formatAccount(keyPair),
+    idx: accountIdx
+  }
+}

package/src/utils/json-big.ts

@@ -0,0 +1,26 @@
+import JsonBig from 'json-bigint'
+import BigNumber from 'bignumber.js'
+import { mapObject } from './other'
+
+const jsonBig = JsonBig({ storeAsString: true })
+
+const convertValuesToBigNumbers = (value: any): any => {
+  if (typeof value === 'object' && value !== null && value.constructor === Object) {
+    return mapObject(value, ([key, value]) => [key, convertValuesToBigNumbers(value)])
+  }
+  if (Array.isArray(value)) {
+    return value.map(item => convertValuesToBigNumbers(item))
+  }
+  if (typeof value === 'string' && new BigNumber(value).toString(10) === value) {
+    const bn = new BigNumber(value)
+    bn.toJSON = () => bn.toString(10)
+    return bn
+  }
+  return value
+}
+
+export default {
+  stringify: (...args: Parameters<typeof JsonBig['stringify']>): string =>
+    jsonBig.stringify(convertValuesToBigNumbers(args[0]), ...args.slice(1)),
+  parse: jsonBig.parse
+}

package/src/utils/keystore.ts

@@ -0,0 +1,179 @@
+import nacl from 'tweetnacl'
+import { v4 as uuid } from '@aeternity/uuid'
+import { ArgonType, hash } from '@aeternity/argon2-browser/dist/argon2-bundled.min.js'
+import { getAddressFromPriv } from './crypto'
+import { bytesToHex, hexToBytes } from './bytes'
+import { InvalidPasswordError } from './errors'
+
+const DERIVED_KEY_FUNCTIONS = {
+  async argon2id (
+    pass: string | Uint8Array,
+    salt: string | Uint8Array,
+    params: Partial<Keystore['crypto']['kdf_params']>
+  ): Promise<Uint8Array> {
+    const { memlimit_kib: mem, opslimit: time } = params
+
+    return (await hash({
+      hashLen: 32,
+      pass,
+      salt,
+      time,
+      mem,
+      type: ArgonType.Argon2id
+    })).hash
+  }
+}
+
+const CRYPTO_FUNCTIONS = {
+  'xsalsa20-poly1305': {
+    encrypt: nacl.secretbox,
+    decrypt (...args: Parameters<typeof nacl.secretbox.open>): Uint8Array {
+      const res = nacl.secretbox.open(...args)
+      if (res == null) throw new InvalidPasswordError()
+      return res
+    }
+  }
+}
+
+export interface Keystore {
+  name: string
+  version: 1
+  public_key: string
+  id: string
+  crypto: {
+    secret_type: 'ed25519'
+    symmetric_alg: keyof typeof CRYPTO_FUNCTIONS
+    ciphertext: string
+    cipher_params: {
+      nonce: string
+    }
+    kdf: keyof typeof DERIVED_KEY_FUNCTIONS
+    kdf_params: {
+      memlimit_kib: number
+      opslimit: number
+      parallelism: number
+      salt: string
+    }
+  }
+}
+
+const CRYPTO_DEFAULTS = {
+  secret_type: 'ed25519',
+  symmetric_alg: 'xsalsa20-poly1305',
+  kdf: 'argon2id',
+  kdf_params: {
+    memlimit_kib: 65536,
+    opslimit: 3,
+    parallelism: 1
+  }
+} as const
+
+/**
+ * Symmetric private key encryption using secret (derived) key.
+ * @param plaintext - Data to be encrypted.
+ * @param key - Secret key.
+ * @param nonce - Randomly generated nonce.
+ * @param algo - Encryption algorithm.
+ * @returns Encrypted data.
+ */
+function encrypt (
+  plaintext: Uint8Array,
+  key: Uint8Array,
+  nonce: Uint8Array,
+  algo: keyof typeof CRYPTO_FUNCTIONS = CRYPTO_DEFAULTS.symmetric_alg
+): Uint8Array {
+  return CRYPTO_FUNCTIONS[algo].encrypt(plaintext, nonce, key)
+}
+
+/**
+ * Symmetric private key decryption using secret (derived) key.
+ * @param ciphertext - Data to be decrypted.
+ * @param key - Secret key.
+ * @param nonce - Nonce from key-object.
+ * @param algo - Encryption algorithm.
+ * @returns Decrypted data.
+ */
+function decrypt (
+  ciphertext: Uint8Array,
+  key: Uint8Array,
+  nonce: Uint8Array,
+  algo: keyof typeof CRYPTO_FUNCTIONS = CRYPTO_DEFAULTS.symmetric_alg
+): Uint8Array {
+  return CRYPTO_FUNCTIONS[algo].decrypt(ciphertext, nonce, key)
+}
+
+/**
+ * Derive secret key from password with key derivation function.
+ * @param password - User-supplied password.
+ * @param nonce - Randomly generated nonce.
+ * @param kdf - Key derivation function.
+ * @param kdfParams - KDF parameters.
+ * @returns Secret key derived from password.
+ */
+async function deriveKey (
+  password: string | Uint8Array,
+  nonce: string | Uint8Array,
+  kdf: Keystore['crypto']['kdf'],
+  kdfParams: Omit<Keystore['crypto']['kdf_params'], 'salt'>
+): Promise<Uint8Array> {
+  return await DERIVED_KEY_FUNCTIONS[kdf](password, nonce, kdfParams)
+}
+
+/**
+ * Recover plaintext private key from secret-storage key object.
+ * @param password - Keystore object password.
+ * @param keystore - Keystore object.
+ * @returns Plaintext private key.
+ */
+export async function recover (
+  password: string | Uint8Array, { crypto }: Keystore
+): Promise<string> {
+  const salt = hexToBytes(crypto.kdf_params.salt)
+  return bytesToHex(decrypt(
+    hexToBytes(crypto.ciphertext),
+    await deriveKey(password, salt, crypto.kdf, crypto.kdf_params),
+    hexToBytes(crypto.cipher_params.nonce),
+    crypto.symmetric_alg
+  ))
+}
+
+/**
+ * Export private key to keystore secret-storage format.
+ * @param name - Key name.
+ * @param password - User-supplied password.
+ * @param privateKey - Private key as hex-string or a Buffer.
+ * @param nonce - Randomly generated 24byte nonce.
+ * @param salt - Randomly generated 16byte salt.
+ * @param options - Encryption parameters.
+ * @param options.kdf - Key derivation function.
+ * @param options.kdf_params - KDF parameters.
+ */
+export async function dump (
+  name: string,
+  password: string | Uint8Array,
+  privateKey: string | Uint8Array,
+  nonce: Uint8Array = nacl.randomBytes(24),
+  salt: Uint8Array = nacl.randomBytes(16),
+  options?: Partial<Keystore['crypto']>
+): Promise<Keystore> {
+  const opt = { ...CRYPTO_DEFAULTS, ...options }
+  const derivedKey = await deriveKey(password, salt, opt.kdf, opt.kdf_params)
+  const payload = typeof privateKey === 'string' ? hexToBytes(privateKey) : privateKey
+  return {
+    name,
+    version: 1,
+    public_key: getAddressFromPriv(payload),
+    id: uuid(),
+    crypto: {
+      secret_type: opt.secret_type,
+      symmetric_alg: opt.symmetric_alg,
+      ciphertext: bytesToHex(encrypt(payload, derivedKey, nonce, opt.symmetric_alg)),
+      cipher_params: { nonce: bytesToHex(nonce) },
+      kdf: opt.kdf,
+      kdf_params: {
+        ...opt.kdf_params,
+        salt: bytesToHex(salt)
+      }
+    }
+  }
+}

package/src/utils/mptree.ts

@@ -17,7 +17,13 @@
 
 import { encode as rlpEncode } from 'rlp'
 import type { Input } from 'rlp'
-import { hash } from './crypto-ts'
+import { hash } from './crypto'
+import {
+  MerkleTreeHashMismatchError,
+  MissingNodeInTreeError,
+  UnknownPathNibbleError,
+  UnknownNodeLengthError
+} from './errors'
 
 enum NodeType {
   Branch,
@@ -37,9 +43,8 @@ export default class MPTree {
 
   /**
    * Deserialize Merkle Patricia Tree
-   * @rtype (binary: Array) => MPTree
-   * @param {Array} binary - Binary
-   * @return {MPTree} Merkle Patricia Tree
+   * @param binary - Binary
+   * @returns Merkle Patricia Tree
    */
   constructor (binary: MPTreeBinary) {
     this.rootHash = binary[0].toString('hex')
@@ -47,9 +52,9 @@ export default class MPTree {
       binary[1].map((node) => [node[0].toString('hex'), node[1]])
     )
 
-    if (this.nodes[this.rootHash] === undefined) throw new Error('Can\'t find a node by root hash')
+    if (this.nodes[this.rootHash] === undefined) throw new MissingNodeInTreeError('Can\'t find a node by root hash')
     Object.entries(this.nodes).forEach(([key, node]) => {
-      if (MPTree.nodeHash(node) !== key) throw new Error('Node hash is not equal to provided one')
+      if (MPTree.nodeHash(node) !== key) throw new MerkleTreeHashMismatchError()
       const { type, payload } = MPTree.parseNode(node)
       switch (type) {
         case NodeType.Branch:
@@ -58,13 +63,13 @@ export default class MPTree {
             .filter(n => n.length)
             .forEach((n) => {
               if (this.nodes[n.toString('hex')] === undefined) {
-                throw new Error('Can\'t find a node by hash in branch node')
+                throw new MissingNodeInTreeError('Can\'t find a node by hash in branch node')
               }
             })
           break
         case NodeType.Extension:
           if (this.nodes[payload[0].toString('hex')] === undefined) {
-            throw new Error('Can\'t find a node by hash in extension node')
+            throw new MissingNodeInTreeError('Can\'t find a node by hash in extension node')
           }
       }
     })
@@ -74,27 +79,29 @@ export default class MPTree {
     return this.rootHash === tree.rootHash
   }
 
-  private static parseNode (node: Buffer[]): { type: NodeType, payload: Buffer[], path: string | null } {
+  private static parseNode (node: Buffer[]): {
+    type: NodeType
+    payload: Buffer[]
+    path: string | null
+  } {
     switch (node.length) {
       case 17:
         return { type: NodeType.Branch, payload: node, path: null }
       case 2: {
-        const path = node[0].toString('hex')
-        const nibble = parseInt(path[0], 16)
-        if (nibble > 3) throw new Error(`Unknown path nibble: ${nibble}`)
+        const nibble = node[0][0] >> 4
+        if (nibble > 3) throw new UnknownPathNibbleError(nibble)
         const type = nibble <= 1 ? NodeType.Extension : NodeType.Leaf
         const slice = [0, 2].includes(nibble) ? 2 : 1
-        return { type, payload: [node[1]], path: path.slice(slice) }
+        return { type, payload: [node[1]], path: node[0].toString('hex').slice(slice) }
       }
       default:
-        throw new Error(`Unknown node length: ${node.length}`)
+        throw new UnknownNodeLengthError(node.length)
     }
   }
 
   /**
    * Serialize Merkle Patricia Tree
-   * @rtype () => Array
-   * @return {Array} Binary
+   * @returns Binary
    */
   serialize (): MPTreeBinary {
     return [
@@ -108,9 +115,8 @@ export default class MPTree {
 
   /**
    * Retrieve value from Merkle Patricia Tree
-   * @rtype (key: String) => Buffer
-   * @param {String} key - The key of the element to retrieve
-   * @return {Buffer} Value associated to the specified key
+   * @param key - The key of the element to retrieve
+   * @returns Value associated to the specified key
    */
   get (key: string): Buffer | undefined {
     let searchFrom = this.rootHash
@@ -119,7 +125,7 @@ export default class MPTree {
       switch (type) {
         case NodeType.Branch:
           if (key.length === 0) return payload[16]
-          searchFrom = payload[parseInt(key[0], 16)].toString('hex')
+          searchFrom = payload[+`0x${key[0]}`].toString('hex')
           key = key.substr(1)
           break
         case NodeType.Extension:

package/src/utils/other.ts

@@ -1,51 +1,36 @@
-import { snakeToPascal, pascalToSnake } from './string'
-
 export const pause = async (duration: number): Promise<void> =>
   await new Promise(resolve => setTimeout(resolve, duration))
 
-export const mapObject = (
-  object: object,
-  fn: (value: [string, any], index: number, array: Array<[string, any]>) => Array<[string, any]>
-): object => Object.fromEntries(Object.entries(object).map(fn))
-
-export const filterObject = (
-  object: object,
-  fn: (value: [string, any], index: number, array: Array<[string, any]>) => boolean
-): object => Object.fromEntries(Object.entries(object).filter(fn))
+export const mapObject = <InputV, OutputV>(
+  object: { [k: string]: InputV },
+  fn: (
+    value: [string, InputV], index: number, array: Array<[string, InputV]>
+  ) => [number | string, OutputV]
+): { [k: string]: OutputV } => Object.fromEntries(Object.entries(object).map(fn))
 
-/**
- * Key traversal metafunction
- * @static
- * @function
- * @rtype (fn: (s: String) => String) => (o: Object) => Object
- * @param {Function} fn - Key transformation function
- * @param {Object} object - Object to traverse
- * @return {Object} Transformed object
- */
-export const traverseKeys = (fn: Function, object: any): any => {
-  if (typeof object !== 'object' || object === null) return object
-  if (Array.isArray(object)) return object.map(i => traverseKeys(fn, i))
-  return mapObject(object, ([key, value]: [string, any]) => [
-    fn(key), traverseKeys(fn, value)
-  ])
-}
+// remove after dropping webpack4 support
+const isWebpack4Buffer = (() => {
+  try {
+    Buffer.concat([Uint8Array.from([])])
+    return false
+  } catch (error) {
+    return true
+  }
+})()
 
-/**
- * snake_case key traversal
- * @static
- * @rtype (o: Object) => Object
- * @param {Object} object - Object to traverse
- * @return {Object} Transformed object
- * @see pascalToSnake
- */
-export const snakizeKeys = traverseKeys.bind(null, pascalToSnake)
+export const concatBuffers = isWebpack4Buffer
+  ? (list: readonly Uint8Array[], totalLength?: number): Buffer =>
+      Buffer.concat(list.map(el => Buffer.from(el)), totalLength)
+  : Buffer.concat
 
 /**
- * PascalCase key traversal
- * @static
- * @rtype (o: Object) => Object
- * @param {Object} object - Object to traverse
- * @return {Object} Transformed object
- * @see snakeToPascal
+ * Object key type guard
+ * @param key - Object key
+ * @param object - object
  */
-export const pascalizeKeys = traverseKeys.bind(null, snakeToPascal)
+export function isKeyOfObject<T> (
+  key: string | number | symbol,
+  object: T
+): key is keyof T {
+  return key in object
+}

package/src/utils/string.ts

@@ -17,9 +17,8 @@
 
 /**
  * Convert string from snake_case to PascalCase
- * @rtype (s: String) => String
- * @param {String} s - String to convert
- * @return {String} Converted string
+ * @param s - String to convert
+ * @returns Converted string
  */
 export function snakeToPascal (s: string): string {
   return s.replace(/_./g, match => match[1].toUpperCase())
@@ -27,9 +26,8 @@ export function snakeToPascal (s: string): string {
 
 /**
  * Convert string from PascalCase to snake_case
- * @rtype (s: String) => String
- * @param {String} s - String to convert
- * @return {String} Converted string
+ * @param s - String to convert
+ * @returns Converted string
  */
 export function pascalToSnake (s: string): string {
   return s.replace(/[A-Z]/g, match => `_${match.toLowerCase()}`)
@@ -37,8 +35,8 @@ export function pascalToSnake (s: string): string {
 
 /**
  * Check whether a string is valid hex.
- * @param {string} str String to validate.
- * @return {boolean} True if the string is valid hex, false otherwise.
+ * @param str - String to validate.
+ * @returns True if the string is valid hex, false otherwise.
  */
 export function isHex (str: string): boolean {
   return str.length % 2 === 0 && /^[0-9a-f]+$/i.test(str)
@@ -46,8 +44,8 @@ export function isHex (str: string): boolean {
 
 /**
  * Check whether a string is valid base-64.
- * @param {string} str String to validate.
- * @return {boolean} True if the string is valid base-64, false otherwise.
+ * @param str - String to validate.
+ * @returns True if the string is valid base-64, false otherwise.
  */
 export function isBase64 (str: string): boolean {
   if (str.length % 4 > 0 || /[^0-9a-z+/=]/i.test(str)) return false