@libp2p/keychain 3.0.8 → 4.0.0

package/dist/src/index.d.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
  *
@@ -49,128 +49,151 @@
  *
  * 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.
  */
-import type { KeyChain, KeyInfo } from '@libp2p/interface/keychain';
-import type { KeyType } from '@libp2p/interface/keys';
-import type { PeerId } from '@libp2p/interface/peer-id';
+import type { ComponentLogger, KeyType, PeerId } from '@libp2p/interface';
 import type { Datastore } from 'interface-datastore';
+import type { Multibase } from 'multiformats/bases/interface.js';
 export interface DEKConfig {
     hash: string;
     salt: string;
     iterationCount: number;
     keyLength: number;
 }
-export interface KeyChainInit {
+export interface KeychainInit {
     pass?: string;
     dek?: DEKConfig;
 }
-declare const defaultOptions: {
-    dek: {
-        keyLength: number;
-        iterationCount: number;
-        salt: string;
-        hash: string;
-    };
-};
-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 declare class DefaultKeyChain implements KeyChain {
-    private readonly components;
-    private readonly init;
+export interface KeyInfo {
+    /**
+     * The universally unique key id
+     */
+    id: string;
     /**
-     * Creates a new instance of a key chain
+     * The local key name
      */
-    constructor(components: KeyChainComponents, init: KeyChainInit);
+    name: string;
+}
+export interface Keychain {
     /**
-     * Generates the options for a keychain.  A random salt is produced.
+     * Export an existing key as a PEM encrypted PKCS #8 string.
+     *
+     * @example
      *
-     * @returns {object}
+     * ```js
+     * await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+     * const pemKey = await libp2p.keychain.exportKey('keyTest', 'password123')
+     * ```
      */
-    static generateOptions(): KeyChainInit;
+    exportKey(name: string, password: string): Promise<Multibase<'m'>>;
     /**
-     * Gets an object that can encrypt/decrypt protected data.
-     * The default options for a keychain.
+     * Import a new key from a PEM encoded PKCS #8 string.
+     *
+     * @example
      *
-     * @returns {object}
+     * ```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')
+     * ```
      */
-    static get options(): typeof defaultOptions;
+    importKey(name: string, pem: string, password: string): Promise<KeyInfo>;
     /**
-     * Create a new key.
+     * Import a new key from a PeerId with a private key component
+     *
+     * @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
+     * const keyInfo = await libp2p.keychain.importPeer('keyTestImport', peerIdFromString('12D3Foo...'))
+     * ```
      */
-    createKey(name: string, type: KeyType, size?: number): Promise<KeyInfo>;
+    importPeer(name: string, peerId: PeerId): Promise<KeyInfo>;
     /**
-     * List all the keys.
+     * Export an existing key as a PeerId
+     *
+     * @example
      *
-     * @returns {Promise<KeyInfo[]>}
+     * ```js
+     * const peerId = await libp2p.keychain.exportPeerId('key-name')
+     * ```
      */
-    listKeys(): Promise<KeyInfo[]>;
+    exportPeerId(name: string): Promise<PeerId>;
     /**
-     * Find a key by it's id
+     * Create a key in the keychain.
+     *
+     * @example
+     *
+     * ```js
+     * const keyInfo = await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+     * ```
      */
-    findKeyById(id: string): Promise<KeyInfo>;
+    createKey(name: string, type: KeyType, size?: number): Promise<KeyInfo>;
     /**
-     * Find a key by it's name.
+     * List all the keys.
      *
-     * @param {string} name - The local key name.
-     * @returns {Promise<KeyInfo>}
+     * @example
+     *
+     * ```js
+     * const keyInfos = await libp2p.keychain.listKeys()
+     * ```
      */
-    findKeyByName(name: string): Promise<KeyInfo>;
+    listKeys(): Promise<KeyInfo[]>;
     /**
-     * Remove an existing key.
+     * Removes a key from the keychain.
      *
-     * @param {string} name - The local key name; must already exist.
-     * @returns {Promise<KeyInfo>}
+     * @example
+     *
+     * ```js
+     * await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+     * const keyInfo = await libp2p.keychain.removeKey('keyTest')
+     * ```
      */
     removeKey(name: string): Promise<KeyInfo>;
     /**
-     * Rename a key
+     * Rename 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
+     * await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+     * const keyInfo = await libp2p.keychain.renameKey('keyTest', 'keyNewNtest')
+     * ```
      */
     renameKey(oldName: string, newName: string): Promise<KeyInfo>;
     /**
-     * Export an existing key as a PEM encrypted PKCS #8 string
-     */
-    exportKey(name: string, password: string): Promise<string>;
-    /**
-     * Export an existing key as a PeerId
-     */
-    exportPeerId(name: string): Promise<PeerId>;
-    /**
-     * Import a new key from a PEM encoded PKCS #8 string
+     * Find a key by it's id.
      *
-     * @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>}
-     */
-    importKey(name: string, pem: string, password: string): Promise<KeyInfo>;
-    /**
-     * Import a peer key
+     * @example
+     *
+     * ```js
+     * const keyInfo = await libp2p.keychain.createKey('keyTest', 'RSA', 4096)
+     * const keyInfo2 = await libp2p.keychain.findKeyById(keyInfo.id)
+     * ```
      */
-    importPeer(name: string, peer: PeerId): Promise<KeyInfo>;
+    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')
+     * ```
      */
-    getPrivateKey(name: string): Promise<string>;
+    findKeyByName(name: string): Promise<KeyInfo>;
     /**
      * Rotate keychain password and re-encrypt all associated keys
+     *
+     * @example
+     *
+     * ```js
+     * await libp2p.keychain.rotateKeychainPass('oldPassword', 'newPassword')
+     * ```
      */
     rotateKeychainPass(oldPass: string, newPass: string): Promise<void>;
 }
-export {};
+export declare function keychain(init?: KeychainInit): (components: KeychainComponents) => Keychain;
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAeH,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAA;AACnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAIpD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,SAAS,CAAA;CAChB;AAaD,QAAA,MAAM,cAAc;;;;;;;CAQnB,CAAA;AAwCD,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,SAAS,CAAA;CACrB;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IAEnC;;OAEG;gBACU,UAAU,EAAE,kBAAkB,EAAE,IAAI,EAAE,YAAY;IA8B/D;;;;OAIG;IACH,MAAM,CAAC,eAAe,IAAK,YAAY;IAOvC;;;;;OAKG;IACH,MAAM,KAAK,OAAO,IAAK,OAAO,cAAc,CAE3C;IAED;;;;;;OAMG;IACG,SAAS,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,SAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IA0D5E;;;;OAIG;IACG,QAAQ,IAAK,OAAO,CAAC,OAAO,EAAE,CAAC;IAarC;;OAEG;IACG,WAAW,CAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBhD;;;;;OAKG;IACG,aAAa,CAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBpD;;;;;OAKG;IACG,SAAS,CAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAchD;;;;;;OAMG;IACG,SAAS,CAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAuCpE;;OAEG;IACG,SAAS,CAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA+BjE;;OAEG;IACG,YAAY,CAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQlD;;;;;;;OAOG;IACG,SAAS,CAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoD/E;;OAEG;IACG,UAAU,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA4C/D;;OAEG;IACG,aAAa,CAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBnD;;OAEG;IACG,kBAAkB,CAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAmD3E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAA;AAEhE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,SAAS,CAAA;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,SAAS,CAAA;IACpB,MAAM,EAAE,eAAe,CAAA;CACxB;AAED,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAA;IAEV;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,QAAQ;IACvB;;;;;;;;;OASG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAA;IAElE;;;;;;;;;;OAUG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAExE;;;;;;;;OAQG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE1D;;;;;;;;OAQG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE3C;;;;;;;;OAQG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEvE;;;;;;;;OAQG;IACH,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;IAE9B;;;;;;;;;OASG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEzC;;;;;;;;;OASG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE7D;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEzC;;;;;;;;;OASG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE7C;;;;;;;;OAQG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpE;AAED,wBAAgB,QAAQ,CAAE,IAAI,GAAE,YAAiB,GAAG,CAAC,UAAU,EAAE,kBAAkB,KAAK,QAAQ,CAI/F"}