@libp2p/keychain 3.0.8 → 4.0.0

package/src/index.ts

@@ -22,7 +22,7 @@
  *
  * The **key id** is the SHA-256 [multihash](https://github.com/multiformats/multihash) of its public key.
  *
- * The *public key* is a [protobuf encoding](https://github.com/libp2p/js-libp2p-crypto/blob/master/src/keys/keys.proto.js) containing a type and the [DER encoding](https://en.wikipedia.org/wiki/X.690) of the PKCS [SubjectPublicKeyInfo](https://www.ietf.org/rfc/rfc3279.txt).
+ * The *public key* is a [protobuf encoding](https://github.com/libp2p/js-libp2p/blob/main/packages/crypto/src/keys/keys.proto.js) containing a type and the [DER encoding](https://en.wikipedia.org/wiki/X.690) of the PKCS [SubjectPublicKeyInfo](https://www.ietf.org/rfc/rfc3279.txt).
  *
  * ## Private key storage
  *
@@ -50,25 +50,10 @@
  * A key benefit is that now the key chain can be used in browser with the [js-datastore-level](https://github.com/ipfs/js-datastore-level) implementation.
  */
 
-/* eslint max-nested-callbacks: ["error", 5] */
-
-import { pbkdf2, randomBytes } from '@libp2p/crypto'
-import { generateKeyPair, importKey, unmarshalPrivateKey } from '@libp2p/crypto/keys'
-import { CodeError } from '@libp2p/interface/errors'
-import { logger } from '@libp2p/logger'
-import { peerIdFromKeys } from '@libp2p/peer-id'
-import { Key } from 'interface-datastore/key'
-import mergeOptions from 'merge-options'
-import sanitize from 'sanitize-filename'
-import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
-import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
-import { codes } from './errors.js'
-import type { KeyChain, KeyInfo } from '@libp2p/interface/keychain'
-import type { KeyType } from '@libp2p/interface/keys'
-import type { PeerId } from '@libp2p/interface/peer-id'
+import { DefaultKeychain } from './keychain.js'
+import type { ComponentLogger, KeyType, PeerId } from '@libp2p/interface'
 import type { Datastore } from 'interface-datastore'
-
-const log = logger('libp2p:keychain')
+import type { Multibase } from 'multiformats/bases/interface.js'
 
 export interface DEKConfig {
   hash: string
@@ -77,556 +62,160 @@ export interface DEKConfig {
   keyLength: number
 }
 
-export interface KeyChainInit {
+export interface KeychainInit {
   pass?: string
   dek?: DEKConfig
 }
 
-const keyPrefix = '/pkcs8/'
-const infoPrefix = '/info/'
-const privates = new WeakMap<object, { dek: string }>()
-
-// NIST SP 800-132
-const NIST = {
-  minKeyLength: 112 / 8,
-  minSaltLength: 128 / 8,
-  minIterationCount: 1000
-}
-
-const defaultOptions = {
-  // See https://cryptosense.com/parametesr-choice-for-pbkdf2/
-  dek: {
-    keyLength: 512 / 8,
-    iterationCount: 10000,
-    salt: 'you should override this value with a crypto secure random number',
-    hash: 'sha2-512'
-  }
-}
-
-function validateKeyName (name: string): boolean {
-  if (name == null) {
-    return false
-  }
-  if (typeof name !== 'string') {
-    return false
-  }
-  return name === sanitize(name.trim()) && name.length > 0
-}
-
-/**
- * Throws an error after a delay
- *
- * This assumes than an error indicates that the keychain is under attack. Delay returning an
- * error to make brute force attacks harder.
- */
-async function randomDelay (): Promise<void> {
-  const min = 200
-  const max = 1000
-  const delay = Math.random() * (max - min) + min
-
-  await new Promise(resolve => setTimeout(resolve, delay))
-}
-
-/**
- * Converts a key name into a datastore name
- */
-function DsName (name: string): Key {
-  return new Key(keyPrefix + name)
-}
-
-/**
- * Converts a key name into a datastore info name
- */
-function DsInfoName (name: string): Key {
-  return new Key(infoPrefix + name)
-}
-
-export interface KeyChainComponents {
+export interface KeychainComponents {
   datastore: Datastore
+  logger: ComponentLogger
 }
 
-/**
- * Manages the lifecycle of a key. Keys are encrypted at rest using PKCS #8.
- *
- * A key in the store has two entries
- * - '/info/*key-name*', contains the KeyInfo for the key
- * - '/pkcs8/*key-name*', contains the PKCS #8 for the key
- *
- */
-export class DefaultKeyChain implements KeyChain {
-  private readonly components: KeyChainComponents
-  private readonly init: KeyChainInit
-
+export interface KeyInfo {
   /**
-   * Creates a new instance of a key chain
+   * The universally unique key id
    */
-  constructor (components: KeyChainComponents, init: KeyChainInit) {
-    this.components = components
-    this.init = mergeOptions(defaultOptions, init)
-
-    // Enforce NIST SP 800-132
-    if (this.init.pass != null && this.init.pass?.length < 20) {
-      throw new Error('pass must be least 20 characters')
-    }
-    if (this.init.dek?.keyLength != null && this.init.dek.keyLength < NIST.minKeyLength) {
-      throw new Error(`dek.keyLength must be least ${NIST.minKeyLength} bytes`)
-    }
-    if (this.init.dek?.salt?.length != null && this.init.dek.salt.length < NIST.minSaltLength) {
-      throw new Error(`dek.saltLength must be least ${NIST.minSaltLength} bytes`)
-    }
-    if (this.init.dek?.iterationCount != null && this.init.dek.iterationCount < NIST.minIterationCount) {
-      throw new Error(`dek.iterationCount must be least ${NIST.minIterationCount}`)
-    }
-
-    const dek = this.init.pass != null && this.init.dek?.salt != null
-      ? pbkdf2(
-        this.init.pass,
-        this.init.dek?.salt,
-        this.init.dek?.iterationCount,
-        this.init.dek?.keyLength,
-        this.init.dek?.hash)
-      : ''
-
-    privates.set(this, { dek })
-  }
+  id: string
 
   /**
-   * Generates the options for a keychain.  A random salt is produced.
-   *
-   * @returns {object}
+   * The local key name
    */
-  static generateOptions (): KeyChainInit {
-    const options = Object.assign({}, defaultOptions)
-    const saltLength = Math.ceil(NIST.minSaltLength / 3) * 3 // no base64 padding
-    options.dek.salt = uint8ArrayToString(randomBytes(saltLength), 'base64')
-    return options
-  }
+  name: string
+}
 
+export interface Keychain {
   /**
-   * Gets an object that can encrypt/decrypt protected data.
-   * The default options for a keychain.
+   * Export an existing key as a PEM encrypted PKCS #8 string.
    *
-   * @returns {object}
-   */
-  static get options (): typeof defaultOptions {
-    return defaultOptions
-  }
-
-  /**
-   * Create a new key.
+   * @example
    *
-   * @param {string} name - The local key name; cannot already exist.
-   * @param {string} type - One of the key types; 'rsa'.
-   * @param {number} [size = 2048] - The key size in bits. Used for rsa keys only
+   * ```js
+   * await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * const pemKey = await libp2p.keychain.exportKey('keyTest', 'password123')
+   * ```
    */
-  async createKey (name: string, type: KeyType, size = 2048): Promise<KeyInfo> {
-    if (!validateKeyName(name) || name === 'self') {
-      await randomDelay()
-      throw new CodeError('Invalid key name', codes.ERR_INVALID_KEY_NAME)
-    }
-
-    if (typeof type !== 'string') {
-      await randomDelay()
-      throw new CodeError('Invalid key type', codes.ERR_INVALID_KEY_TYPE)
-    }
-
-    const dsname = DsName(name)
-    const exists = await this.components.datastore.has(dsname)
-    if (exists) {
-      await randomDelay()
-      throw new CodeError('Key name already exists', codes.ERR_KEY_ALREADY_EXISTS)
-    }
-
-    switch (type.toLowerCase()) {
-      case 'rsa':
-        if (!Number.isSafeInteger(size) || size < 2048) {
-          await randomDelay()
-          throw new CodeError('Invalid RSA key size', codes.ERR_INVALID_KEY_SIZE)
-        }
-        break
-      default:
-        break
-    }
-
-    let keyInfo
-    try {
-      const keypair = await generateKeyPair(type, size)
-      const kid = await keypair.id()
-      const cached = privates.get(this)
-
-      if (cached == null) {
-        throw new CodeError('dek missing', codes.ERR_INVALID_PARAMETERS)
-      }
-
-      const dek = cached.dek
-      const pem = await keypair.export(dek)
-      keyInfo = {
-        name,
-        id: kid
-      }
-      const batch = this.components.datastore.batch()
-      batch.put(dsname, uint8ArrayFromString(pem))
-      batch.put(DsInfoName(name), uint8ArrayFromString(JSON.stringify(keyInfo)))
-
-      await batch.commit()
-    } catch (err: any) {
-      await randomDelay()
-      throw err
-    }
-
-    return keyInfo
-  }
+  exportKey(name: string, password: string): Promise<Multibase<'m'>>
 
   /**
-   * List all the keys.
+   * Import a new key from a PEM encoded PKCS #8 string.
    *
-   * @returns {Promise<KeyInfo[]>}
-   */
-  async listKeys (): Promise<KeyInfo[]> {
-    const query = {
-      prefix: infoPrefix
-    }
-
-    const info = []
-    for await (const value of this.components.datastore.query(query)) {
-      info.push(JSON.parse(uint8ArrayToString(value.value)))
-    }
-
-    return info
-  }
-
-  /**
-   * Find a key by it's id
+   * @example
+   *
+   * ```js
+   * await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * const pemKey = await libp2p.keychain.exportKey('keyTest', 'password123')
+   * const keyInfo = await libp2p.keychain.importKey('keyTestImport', pemKey, 'password123')
+   * ```
    */
-  async findKeyById (id: string): Promise<KeyInfo> {
-    try {
-      const keys = await this.listKeys()
-      const key = keys.find((k) => k.id === id)
-
-      if (key == null) {
-        throw new CodeError(`Key with id '${id}' does not exist.`, codes.ERR_KEY_NOT_FOUND)
-      }
-
-      return key
-    } catch (err: any) {
-      await randomDelay()
-      throw err
-    }
-  }
+  importKey(name: string, pem: string, password: string): Promise<KeyInfo>
 
   /**
-   * Find a key by it's name.
+   * Import a new key from a PeerId with a private key component
+   *
+   * @example
    *
-   * @param {string} name - The local key name.
-   * @returns {Promise<KeyInfo>}
+   * ```js
+   * const keyInfo = await libp2p.keychain.importPeer('keyTestImport', peerIdFromString('12D3Foo...'))
+   * ```
    */
-  async findKeyByName (name: string): Promise<KeyInfo> {
-    if (!validateKeyName(name)) {
-      await randomDelay()
-      throw new CodeError(`Invalid key name '${name}'`, codes.ERR_INVALID_KEY_NAME)
-    }
-
-    const dsname = DsInfoName(name)
-    try {
-      const res = await this.components.datastore.get(dsname)
-      return JSON.parse(uint8ArrayToString(res))
-    } catch (err: any) {
-      await randomDelay()
-      log.error(err)
-      throw new CodeError(`Key '${name}' does not exist.`, codes.ERR_KEY_NOT_FOUND)
-    }
-  }
+  importPeer(name: string, peerId: PeerId): Promise<KeyInfo>
 
   /**
-   * Remove an existing key.
+   * Export an existing key as a PeerId
+   *
+   * @example
    *
-   * @param {string} name - The local key name; must already exist.
-   * @returns {Promise<KeyInfo>}
+   * ```js
+   * const peerId = await libp2p.keychain.exportPeerId('key-name')
+   * ```
    */
-  async removeKey (name: string): Promise<KeyInfo> {
-    if (!validateKeyName(name) || name === 'self') {
-      await randomDelay()
-      throw new CodeError(`Invalid key name '${name}'`, codes.ERR_INVALID_KEY_NAME)
-    }
-    const dsname = DsName(name)
-    const keyInfo = await this.findKeyByName(name)
-    const batch = this.components.datastore.batch()
-    batch.delete(dsname)
-    batch.delete(DsInfoName(name))
-    await batch.commit()
-    return keyInfo
-  }
+  exportPeerId(name: string): Promise<PeerId>
 
   /**
-   * Rename a key
+   * Create a key in the keychain.
+   *
+   * @example
    *
-   * @param {string} oldName - The old local key name; must already exist.
-   * @param {string} newName - The new local key name; must not already exist.
-   * @returns {Promise<KeyInfo>}
+   * ```js
+   * const keyInfo = await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * ```
    */
-  async renameKey (oldName: string, newName: string): Promise<KeyInfo> {
-    if (!validateKeyName(oldName) || oldName === 'self') {
-      await randomDelay()
-      throw new CodeError(`Invalid old key name '${oldName}'`, codes.ERR_OLD_KEY_NAME_INVALID)
-    }
-    if (!validateKeyName(newName) || newName === 'self') {
-      await randomDelay()
-      throw new CodeError(`Invalid new key name '${newName}'`, codes.ERR_NEW_KEY_NAME_INVALID)
-    }
-    const oldDsname = DsName(oldName)
-    const newDsname = DsName(newName)
-    const oldInfoName = DsInfoName(oldName)
-    const newInfoName = DsInfoName(newName)
-
-    const exists = await this.components.datastore.has(newDsname)
-    if (exists) {
-      await randomDelay()
-      throw new CodeError(`Key '${newName}' already exists`, codes.ERR_KEY_ALREADY_EXISTS)
-    }
-
-    try {
-      const pem = await this.components.datastore.get(oldDsname)
-      const res = await this.components.datastore.get(oldInfoName)
-
-      const keyInfo = JSON.parse(uint8ArrayToString(res))
-      keyInfo.name = newName
-      const batch = this.components.datastore.batch()
-      batch.put(newDsname, pem)
-      batch.put(newInfoName, uint8ArrayFromString(JSON.stringify(keyInfo)))
-      batch.delete(oldDsname)
-      batch.delete(oldInfoName)
-      await batch.commit()
-      return keyInfo
-    } catch (err: any) {
-      await randomDelay()
-      throw err
-    }
-  }
+  createKey(name: string, type: KeyType, size?: number): Promise<KeyInfo>
 
   /**
-   * Export an existing key as a PEM encrypted PKCS #8 string
+   * List all the keys.
+   *
+   * @example
+   *
+   * ```js
+   * const keyInfos = await libp2p.keychain.listKeys()
+   * ```
    */
-  async exportKey (name: string, password: string): Promise<string> {
-    if (!validateKeyName(name)) {
-      await randomDelay()
-      throw new CodeError(`Invalid key name '${name}'`, codes.ERR_INVALID_KEY_NAME)
-    }
-    if (password == null) {
-      await randomDelay()
-      throw new CodeError('Password is required', codes.ERR_PASSWORD_REQUIRED)
-    }
-
-    const dsname = DsName(name)
-    try {
-      const res = await this.components.datastore.get(dsname)
-      const pem = uint8ArrayToString(res)
-      const cached = privates.get(this)
-
-      if (cached == null) {
-        throw new CodeError('dek missing', codes.ERR_INVALID_PARAMETERS)
-      }
-
-      const dek = cached.dek
-      const privateKey = await importKey(pem, dek)
-      const keyString = await privateKey.export(password)
-
-      return keyString
-    } catch (err: any) {
-      await randomDelay()
-      throw err
-    }
-  }
+  listKeys(): Promise<KeyInfo[]>
 
   /**
-   * Export an existing key as a PeerId
+   * Removes a key from the keychain.
+   *
+   * @example
+   *
+   * ```js
+   * await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * const keyInfo = await libp2p.keychain.removeKey('keyTest')
+   * ```
    */
-  async exportPeerId (name: string): Promise<PeerId> {
-    const password = 'temporary-password'
-    const pem = await this.exportKey(name, password)
-    const privateKey = await importKey(pem, password)
-
-    return peerIdFromKeys(privateKey.public.bytes, privateKey.bytes)
-  }
+  removeKey(name: string): Promise<KeyInfo>
 
   /**
-   * Import a new key from a PEM encoded PKCS #8 string
+   * Rename a key in the keychain.
    *
-   * @param {string} name - The local key name; must not already exist.
-   * @param {string} pem - The PEM encoded PKCS #8 string
-   * @param {string} password - The password.
-   * @returns {Promise<KeyInfo>}
+   * @example
+   *
+   * ```js
+   * await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * const keyInfo = await libp2p.keychain.renameKey('keyTest', 'keyNewNtest')
+   * ```
    */
-  async importKey (name: string, pem: string, password: string): Promise<KeyInfo> {
-    if (!validateKeyName(name) || name === 'self') {
-      await randomDelay()
-      throw new CodeError(`Invalid key name '${name}'`, codes.ERR_INVALID_KEY_NAME)
-    }
-    if (pem == null) {
-      await randomDelay()
-      throw new CodeError('PEM encoded key is required', codes.ERR_PEM_REQUIRED)
-    }
-    const dsname = DsName(name)
-    const exists = await this.components.datastore.has(dsname)
-    if (exists) {
-      await randomDelay()
-      throw new CodeError(`Key '${name}' already exists`, codes.ERR_KEY_ALREADY_EXISTS)
-    }
-
-    let privateKey
-    try {
-      privateKey = await importKey(pem, password)
-    } catch (err: any) {
-      await randomDelay()
-      throw new CodeError('Cannot read the key, most likely the password is wrong', codes.ERR_CANNOT_READ_KEY)
-    }
-
-    let kid
-    try {
-      kid = await privateKey.id()
-      const cached = privates.get(this)
-
-      if (cached == null) {
-        throw new CodeError('dek missing', codes.ERR_INVALID_PARAMETERS)
-      }
-
-      const dek = cached.dek
-      pem = await privateKey.export(dek)
-    } catch (err: any) {
-      await randomDelay()
-      throw err
-    }
-
-    const keyInfo = {
-      name,
-      id: kid
-    }
-    const batch = this.components.datastore.batch()
-    batch.put(dsname, uint8ArrayFromString(pem))
-    batch.put(DsInfoName(name), uint8ArrayFromString(JSON.stringify(keyInfo)))
-    await batch.commit()
-
-    return keyInfo
-  }
+  renameKey(oldName: string, newName: string): Promise<KeyInfo>
 
   /**
-   * Import a peer key
+   * Find a key by it's id.
+   *
+   * @example
+   *
+   * ```js
+   * const keyInfo = await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * const keyInfo2 = await libp2p.keychain.findKeyById(keyInfo.id)
+   * ```
    */
-  async importPeer (name: string, peer: PeerId): Promise<KeyInfo> {
-    try {
-      if (!validateKeyName(name)) {
-        throw new CodeError(`Invalid key name '${name}'`, codes.ERR_INVALID_KEY_NAME)
-      }
-      if (peer == null) {
-        throw new CodeError('PeerId is required', codes.ERR_MISSING_PRIVATE_KEY)
-      }
-      if (peer.privateKey == null) {
-        throw new CodeError('PeerId.privKey is required', codes.ERR_MISSING_PRIVATE_KEY)
-      }
-
-      const privateKey = await unmarshalPrivateKey(peer.privateKey)
-
-      const dsname = DsName(name)
-      const exists = await this.components.datastore.has(dsname)
-      if (exists) {
-        await randomDelay()
-        throw new CodeError(`Key '${name}' already exists`, codes.ERR_KEY_ALREADY_EXISTS)
-      }
-
-      const cached = privates.get(this)
-
-      if (cached == null) {
-        throw new CodeError('dek missing', codes.ERR_INVALID_PARAMETERS)
-      }
-
-      const dek = cached.dek
-      const pem = await privateKey.export(dek)
-      const keyInfo: KeyInfo = {
-        name,
-        id: peer.toString()
-      }
-      const batch = this.components.datastore.batch()
-      batch.put(dsname, uint8ArrayFromString(pem))
-      batch.put(DsInfoName(name), uint8ArrayFromString(JSON.stringify(keyInfo)))
-      await batch.commit()
-      return keyInfo
-    } catch (err: any) {
-      await randomDelay()
-      throw err
-    }
-  }
+  findKeyById(id: string): Promise<KeyInfo>
 
   /**
-   * Gets the private key as PEM encoded PKCS #8 string
+   * Find a key by it's name.
+   *
+   * @example
+   *
+   * ```js
+   * const keyInfo = await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+   * const keyInfo2 = await libp2p.keychain.findKeyByName('keyTest')
+   * ```
    */
-  async getPrivateKey (name: string): Promise<string> {
-    if (!validateKeyName(name)) {
-      await randomDelay()
-      throw new CodeError(`Invalid key name '${name}'`, codes.ERR_INVALID_KEY_NAME)
-    }
-
-    try {
-      const dsname = DsName(name)
-      const res = await this.components.datastore.get(dsname)
-      return uint8ArrayToString(res)
-    } catch (err: any) {
-      await randomDelay()
-      log.error(err)
-      throw new CodeError(`Key '${name}' does not exist.`, codes.ERR_KEY_NOT_FOUND)
-    }
-  }
+  findKeyByName(name: string): Promise<KeyInfo>
 
   /**
    * Rotate keychain password and re-encrypt all associated keys
+   *
+   * @example
+   *
+   * ```js
+   * await libp2p.keychain.rotateKeychainPass('oldPassword', 'newPassword')
+   * ```
    */
-  async rotateKeychainPass (oldPass: string, newPass: string): Promise<void> {
-    if (typeof oldPass !== 'string') {
-      await randomDelay()
-      throw new CodeError(`Invalid old pass type '${typeof oldPass}'`, codes.ERR_INVALID_OLD_PASS_TYPE)
-    }
-    if (typeof newPass !== 'string') {
-      await randomDelay()
-      throw new CodeError(`Invalid new pass type '${typeof newPass}'`, codes.ERR_INVALID_NEW_PASS_TYPE)
-    }
-    if (newPass.length < 20) {
-      await randomDelay()
-      throw new CodeError(`Invalid pass length ${newPass.length}`, codes.ERR_INVALID_PASS_LENGTH)
-    }
-    log('recreating keychain')
-    const cached = privates.get(this)
-
-    if (cached == null) {
-      throw new CodeError('dek missing', codes.ERR_INVALID_PARAMETERS)
-    }
-
-    const oldDek = cached.dek
-    this.init.pass = newPass
-    const newDek = newPass != null && this.init.dek?.salt != null
-      ? pbkdf2(
-        newPass,
-        this.init.dek.salt,
-        this.init.dek?.iterationCount,
-        this.init.dek?.keyLength,
-        this.init.dek?.hash)
-      : ''
-    privates.set(this, { dek: newDek })
-    const keys = await this.listKeys()
-    for (const key of keys) {
-      const res = await this.components.datastore.get(DsName(key.name))
-      const pem = uint8ArrayToString(res)
-      const privateKey = await importKey(pem, oldDek)
-      const password = newDek.toString()
-      const keyAsPEM = await privateKey.export(password)
+  rotateKeychainPass(oldPass: string, newPass: string): Promise<void>
+}
 
-      // Update stored key
-      const batch = this.components.datastore.batch()
-      const keyInfo = {
-        name: key.name,
-        id: key.id
-      }
-      batch.put(DsName(key.name), uint8ArrayFromString(keyAsPEM))
-      batch.put(DsInfoName(key.name), uint8ArrayFromString(JSON.stringify(keyInfo)))
-      await batch.commit()
-    }
-    log('keychain reconstructed')
+export function keychain (init: KeychainInit = {}): (components: KeychainComponents) => Keychain {
+  return (components: KeychainComponents) => {
+    return new DefaultKeychain(components, init)
   }
 }