@did-btcr2/kms 0.1.0

package/src/kms.ts

@@ -0,0 +1,324 @@
+import { Bytes, HashBytes, KeyBytes, KeyIdentifier, KeyManagerError, SignatureBytes } from '@did-btcr2/common';
+import { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { KeyManager } from './interface.js';
+import { KeyValueStore, MemoryStore } from './store.js';
+
+/**
+ * Class for managing cryptographic keys for the BTCR2 DID method.
+ * @class Kms
+ * @type {Kms}
+ */
+export class Kms implements KeyManager {
+  /**
+   * Singleton instance of the Kms.
+   * @private
+   * @type {KeyManager}
+   */
+  static #instance?: Kms;
+
+  /**
+   * The `store` is a private variable in `KeyManager`. It is a `KeyValueStore` instance used for
+   * storing and managing cryptographic keys. It allows the `KeyManager` class to save,
+   * retrieve, and handle keys efficiently within the local Key Management System (KMS) context.
+   * This variable can be configured to use different storage backends, like in-memory storage or
+   * persistent storage, providing flexibility in key management according to the application's
+   * requirements.
+   * @private
+   * @type {KeyValueStore<KeyIdentifier, KeyBytes>} The key store for managing cryptographic keys.
+   */
+  #store: KeyValueStore<KeyIdentifier, KeyBytes>;
+
+
+  /**
+   * The `#activeKeyId` property is a string that points to the currently active key.
+   * It is used to identify the key that will be used for signing and verifying operations.
+   * This property is optional and can be set to a specific key ID when initializing the
+   * `KeyManager` instance. If not set, the key manager will use the default key id.
+   * @private
+   * @type {KeyIdentifier}
+   */
+  #activeKeyId?: KeyIdentifier;
+
+  /**
+   * Creates an instance of KeyManager.
+   * @param {KeyValueStore<KeyIdentifier, KeyBytes>} store An optional property to specify a custom
+   * `KeyValueStore` instance for key management. If not provided, {@link KeyManager} uses a default `MemoryStore`
+   * instance. This store is responsible for managing cryptographic keys, allowing them to be retrieved, stored, and
+   * managed during cryptographic operations.
+   */
+  constructor(store?: KeyValueStore<KeyIdentifier, KeyBytes>) {
+    // Set the default key store to a MemoryStore instance
+    this.#store = store ?? new MemoryStore<KeyIdentifier, KeyBytes>();
+  }
+
+  /**
+   * Gets the ID of the active key.
+   * @returns {KeyIdentifier | undefined} The ID of the active key.
+   */
+  get activeKeyId(): KeyIdentifier | undefined {
+    return this.#activeKeyId;
+  }
+
+  /**
+   * Gets the key pair associated with the given ID or the active key if no ID is provided.
+   * @param {KeyIdentifier} [id] The ID of the key to get.
+   * @returns {KeyBytes} A promise resolving to the key pair.
+   * @throws {KeyManagerError} If the key is not found or no active key is set.
+   */
+  #getKeyOrThrow(id?: KeyIdentifier): SchnorrKeyPair {
+    // Get the key id
+    const keyId = id ?? this.#activeKeyId;
+    // Throw an error if no active key is set
+    if (!keyId) {
+      throw new KeyManagerError('No active key set', 'ACTIVE_KEY_URI_NOT_SET');
+    }
+
+    // Get the secret key from the store, throw an error if not found
+    const _secretKey = this.#store.get(keyId);
+    if (!_secretKey) {
+      throw new KeyManagerError(`Key not found: ${keyId}`, 'KEY_NOT_FOUND');
+    }
+
+    // Create a key pair from the secret key
+    const kp = new SchnorrKeyPair({ secretKey: _secretKey });
+
+    // Return the secret key
+    return kp;
+  }
+
+  /**
+   * Checks if a key with the given ID exists in the key store.
+   * @param {KeyIdentifier} id The ID of the key to check.
+   * @returns {boolean} A promise resolving to a boolean indicating if the key exists.
+   */
+  #exists(id: KeyIdentifier): boolean {
+    const key = this.#store.get(id);
+    return !!key;
+  }
+
+  /**
+   * Removes a key from the key store.
+   * @param {KeyIdentifier} id The key identifier of the key to remove.
+   * @param {{ force?: boolean }} options The options for removing the key.
+   * @param {boolean} [options.force] Whether to force the removal of the key.
+   * @returns {void} A promise that resolves when the key is removed.
+   * @throws {KeyManagerError} If attempting to remove the active key without force.
+   */
+  removeKey(id: KeyIdentifier, options: { force?: boolean } = {}): void {
+    // Check if trying to remove the active key without force
+    if (this.#activeKeyId === id && !options.force) {
+      throw new KeyManagerError('Cannot remove active key (use "force": true or switch active key)', 'ACTIVE_KEY_DELETE');
+    }
+
+    // Check if the key exists, if not throw an error
+    if (!this.#exists(id)) {
+      throw new KeyManagerError(`Key not found: ${id}`, 'KEY_NOT_FOUND');
+    }
+
+    // Remove the key from the store
+    this.#store.delete(id);
+
+    // Clear the active key if it was the one removed
+    if (this.#activeKeyId === id) {
+      this.#activeKeyId = undefined;
+    }
+  }
+
+  /**
+   * Lists all key identifiers in the key store.
+   * @returns {Promise<KeyIdentifier[]>} A promise that resolves to an array of key identifiers.
+   */
+  listKeys(): KeyIdentifier[] {
+    return this.#store.entries().flatMap(([k, _]) => [k as KeyIdentifier]);
+  }
+
+  /**
+   * Sets the active key to the key associated with the given ID.
+   * @param {KeyIdentifier} id The ID of the key to set as active.
+   * @returns {Promise<void>} A promise that resolves when the active key is set.
+   * @throws {KeyManagerError} If the key is not found.
+   */
+  setActiveKey(id: KeyIdentifier): void {
+    // Check if the key exists, if not throw an error
+    this.#getKeyOrThrow(id);
+
+    // Set the active key ID
+    this.#activeKeyId = id;
+  }
+
+  /**
+   * Gets the public key associated with the given ID or the active key if no ID is provided.
+   * @param {KeyIdentifier} [id] The ID of the key to get the public key for.
+   * @returns {Promise<KeyBytes>} A promise resolving to the public key bytes.
+   */
+  getPublicKey(id?: KeyIdentifier): KeyBytes {
+    // Get the key pair from the store
+    const { publicKey } = this.#getKeyOrThrow(id);
+
+    // Return the public key bytes
+    return publicKey.compressed;
+  }
+
+  /**
+   * Signs the given data using the key associated with the key ID.
+   * @param {Bytes} data The data to sign.
+   * @param {KeyIdentifier} [id] The ID of the key to sign the data with.
+   * @returns {Promise<SignatureBytes>} A promise resolving to the signature of the data.
+   */
+  sign(data: Bytes, id?: KeyIdentifier): SignatureBytes {
+    // Get the key from the store
+    const { secretKey } = this.#getKeyOrThrow(id);
+
+    // Check if the key can sign
+    if(!secretKey) {
+      throw new KeyManagerError(`Key ID ${id} is not a signer`, 'KEY_NOT_SIGNER');
+    }
+
+    // Sign the data using the key and return the signature
+    return secretKey.sign(data);
+  }
+
+  /**
+   * Verifies a signature using the key associated with the key ID.
+   * @param {KeyIdentifier} id The ID of the key to verify the signature with.
+   * @param {SignatureBytes} signature The signature to verify.
+   * @param {Hex} data The data to verify the signature with.
+   * @returns {Promise<boolean>} A promise resolving to a boolean indicating the verification result.
+   */
+  verify(signature: SignatureBytes, data: Bytes, id?: KeyIdentifier): boolean {
+    // Get the key from the store
+    const { publicKey } = this.#getKeyOrThrow(id);
+
+    // Verify the signature using the multikey
+    return publicKey.verify(signature, data);
+  }
+
+  /**
+   * Imports a key pair into the key store.
+   * @param {SchnorrKeyPair} keyPair The key pair to import.
+   * @param {{ id?: KeyIdentifier; setActive?: boolean }} options The options for importing the key pair.
+   * @param {KeyIdentifier} [options.id] The ID of the key to import (optional).
+   * @param {boolean} [options.setActive] Whether to set the key as active (optional, default: true).
+   * @returns {Promise<KeyIdentifier>} A promise resolving to the ID of the imported key.
+   */
+  importKey(
+    keyPair: SchnorrKeyPair,
+    options: {
+      id?: KeyIdentifier;
+      setActive?: boolean
+    } = {}
+  ): KeyIdentifier {
+    // Ensure the key pair has a public key
+    if(!keyPair.publicKey) {
+      keyPair.publicKey = keyPair.secretKey.computePublicKey();
+    }
+
+    // Determine the key ID
+    const id = options.id ?? (keyPair.publicKey.hex as string);
+
+    // Check if the key already exists
+    if (this.#exists(id)) {
+      throw new KeyManagerError(`Key already exists: ${id}`, 'KEY_FOUND');
+    }
+
+    // Store the key pair in the key store
+    this.#store.set(id, keyPair.secretKey.bytes);
+
+    // Determine whether to set the key as active, defaulting to true
+    const setActive = options.setActive ?? true;
+
+    // Set the active key if specified
+    if (setActive) {
+      this.#activeKeyId = id;
+    }
+
+    // Return the key ID
+    return id;
+  }
+
+  /**
+   * Computes the hash of the given data.
+   * @param {Uint8Array} data The data to hash.
+   * @returns {HashBytes} The hash of the data.
+   */
+  digest(data: Uint8Array): HashBytes {
+    return sha256(data);
+  }
+
+  /**
+   * Generates a new key pair and stores it in the key store.
+   * @returns {KeyIdentifier} The key identifier of the generated key.
+   */
+  generateKey(): KeyIdentifier {
+    // Generate a new Schnorr key pair
+    const kp = SchnorrKeyPair.generate();
+
+    // Store the key pair in the key store
+    const id = kp.publicKey.hex;
+    this.#store.set(id, kp.secretKey.bytes);
+
+    // Set the active key to the newly generated key
+    this.#activeKeyId = id;
+
+    // Return the key ID
+    return id;
+  }
+
+  /**
+   * Initializes a singleton KeyManager instance.
+   * @param {SchnorrKeyPair} keyPair The secret key to import.
+   * @param {string} id The ID to set as the active key.
+   * @returns {void}
+   */
+  static initialize(keyPair: SchnorrKeyPair, id: string): Kms {
+    // Check if the KeyManager instance is already initialized
+    if (Kms.#instance) {
+      console.warn('WARNING: Kms global instance is already initialized.');
+      return Kms.#instance;
+    }
+
+    // Check if the keypair is provided
+    if(!keyPair) {
+      // Log a warning message if not provided
+      console.warn('WARNING: secretKey not provided, generating new SchnorrKeyPair ...');
+    }
+
+    // Generate a new keypair if not provided
+    keyPair ??= SchnorrKeyPair.generate();
+
+    // Initialize the singleton key manager with the keypair
+    Kms.#instance = new Kms();
+
+    // Import the keypair into the key store
+    Kms.#instance.importKey(keyPair, { setActive: true, id });
+
+    // Set the active key URI7
+    Kms.#instance.#activeKeyId = id;
+
+    // Log the active key ID
+    console.info(`Kms initialized with Active Key ID: ${Kms.#instance.#activeKeyId}`);
+
+    // Return the singleton instance
+    return Kms.#instance;
+  }
+
+  /**
+   * Retrieves a keypair from the key store using the provided key ID.
+   * @public
+   * @param {KeyIdentifier} id The ID of the keypair to retrieve.
+   * @returns {Promise<SchnorrKeyPair | undefined>} The retrieved keypair, or undefined if not found.
+   */
+  static getKey(id?: KeyIdentifier): SchnorrKeyPair | undefined {
+    // Ensure the Kms instance is initialized
+    if(!Kms.#instance) {
+      throw new KeyManagerError('Kms instance not initialized', 'KMS_NOT_INITIALIZED');
+    }
+
+    // Use the active key ID if not provided
+    id ??= Kms.#instance.activeKeyId;
+
+    // Instantiate a new Kms with the default key store
+    return Kms.#instance.#getKeyOrThrow(id);
+  }
+}

package/src/signer.ts

@@ -0,0 +1,60 @@
+import { AvailableNetworks } from '@did-btcr2/bitcoin';
+import { KeyBytes, Bytes, SignatureBytes } from '@did-btcr2/common';
+import {  SchnorrKeyPair } from '@did-btcr2/keypair';
+
+/**
+ * Class representing a signer for cryptographic operations.
+ * Remains for backwards compatibility. Plan to migrate to Kms.
+ * @class Signer
+ * @type {Signer}
+ */
+export class Signer {
+  /**
+   * The key pair used for signing.
+   * @type {SchnorrKeyPair}
+   */
+  keyPair: SchnorrKeyPair;
+
+  /**
+   * The network associated with the signer.
+   * @type {keyof AvailableNetworks}
+   */
+  network: keyof AvailableNetworks;
+
+  /**
+   * Creates an instance of Signer.
+   * @param {{ keyPair: SchnorrKeyPair; network: keyof AvailableNetworks; }} params The parameters for the signer.
+   * @param {SchnorrKeyPair} params.keyPair The key pair used for signing.
+   * @param {keyof AvailableNetworks} params.network The network associated with the signer.
+   */
+  constructor(params: { keyPair: SchnorrKeyPair; network: keyof AvailableNetworks; }) {
+    this.keyPair = params.keyPair;
+    this.network = params.network;
+  }
+
+  /**
+   * Gets the public key bytes.
+   * @returns {KeyBytes} The public key bytes.
+   */
+  get publicKey(): KeyBytes {
+    return this.keyPair.publicKey.compressed;
+  }
+
+  /**
+   * Signs the given hash using ECDSA.
+   * @param {Bytes} hash The hash to sign.
+   * @returns {SignatureBytes} The signature of the hash.
+   */
+  signEcdsa(hash: Bytes): SignatureBytes {
+    return this.keyPair.secretKey.sign(hash, { scheme: 'ecdsa' });
+  };
+
+  /**
+   * Signs the given hash using Schnorr signature.
+   * @param {Bytes} hash The hash to sign.
+   * @returns {SignatureBytes} The Schnorr signature of the hash.
+   */
+  sign(hash: Bytes): SignatureBytes {
+    return this.keyPair.secretKey.sign(hash);
+  }
+}

package/src/store.ts

@@ -0,0 +1,153 @@
+/**
+ * Re-implmentation of a interface for a generic key-value store.
+ */
+export interface KeyValueStore<K, V> {
+  /**
+   * Clears the store, removing all key-value pairs.
+   *
+   * @returns {void} when the store has been cleared.
+   */
+  clear(): void;
+
+  /**
+   * Closes the store, freeing up any resources used. After calling this method, no other operations can be performed on the store.
+   *
+   * @returns {void} when the store has been closed.
+   */
+  close(): void;
+
+  /**
+   * Deletes a key-value pair from the store.
+   *
+   * @param {K} key - The key of the value to delete.
+   * @returns {boolean | void} True if the element existed and has been removed, or false if the element does not exist.
+   */
+  delete(key: K): boolean | void;
+
+  /**
+   * Fetches a value from the store given its key.
+   *
+   * @param {K} key - The key of the value to retrieve.
+   * @returns {V | undefined} The value associated with the key, or `undefined` if no value exists for that key.
+   */
+  get(key: K): V | undefined;
+
+  /**
+   * Sets the value for a key in the store.
+   *
+   * @param {K} key - The key under which to store the value.
+   * @param {V} value - The value to be stored.
+   * @returns {void} once the value has been set.
+   */
+  set(key: K, value: V): void;
+
+  /**
+   * Fetches the keys and values as a nested array.
+   *
+   * @returns {Array<[K, V]>} An array of key-value pair arrays in the store.
+   */
+  entries(): Array<[K, V]>;
+}
+
+/**
+ * Re-implementation of a simple in-memory key-value store.
+ *
+ * The `MemoryStore` class is an implementation of
+ * `KeyValueStore` that holds data in memory.
+ *
+ * It provides a basic key-value store that works synchronously and keeps all
+ * data in memory. This can be used for testing, or for handling small amounts
+ * of data with simple key-value semantics.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const memoryStore = new MemoryStore<string, number>();
+ * await memoryStore.set("key1", 1);
+ * const value = await memoryStore.get("key1");
+ * console.log(value); // 1
+ * ```
+ *
+ * @public
+ */
+export class MemoryStore<K, V> implements KeyValueStore<K, V> {
+  /**
+   * A private field that contains the Map used as the key-value store.
+   */
+  private store: Map<K, V> = new Map();
+
+  /**
+   * Clears all entries in the key-value store.
+   *
+   * @returns {void} returns once the operation is complete.
+   */
+  clear(): void {
+    this.store.clear();
+  }
+
+  /**
+   * This operation is no-op for `MemoryStore`.
+   */
+  close(): void {
+    /** no-op */
+  }
+
+  /**
+   * Deletes an entry from the key-value store by its key.
+   *
+   * @param {K} id - The key of the entry to delete.
+   * @returns {boolean} a boolean indicating whether the entry was successfully deleted.
+   */
+  delete(id: K): boolean {
+    return this.store.delete(id);
+  }
+
+  /**
+   * Retrieves the value of an entry by its key.
+   *
+   * @param {K} id - The key of the entry to retrieve.
+   * @returns {V | undefined} the value of the entry, or `undefined` if the entry does not exist.
+   */
+  get(id: K): V | undefined {
+    return this.store.get(id);
+  }
+
+  /**
+   * Checks for the presence of an entry by key.
+   *
+   * @param {K} id - The key to check for the existence of.
+   * @returns {boolean} a boolean indicating whether an element with the specified key exists or not.
+   */
+  has(id: K): boolean {
+    return this.store.has(id);
+  }
+
+  /**
+   * Retrieves all values in the key-value store.
+
+   * @returns {Array<V>} an array of all values in the store.
+   */
+  list(): Array<V> {
+    return Array.from(this.store.values());
+  }
+
+  /**
+   * Retrieves all entries in the key-value store.
+   *
+   * @returns {Array<[K, V]>} an array of key-value pairs in the store.
+   */
+  entries(): Array<[K, V]> {
+    return Array.from(this.store.entries());
+  }
+
+  /**
+   * Sets the value of an entry in the key-value store.
+   *
+   * @param {K} id - The key of the entry to set.
+   * @param {V} key - The new value for the entry.
+   * @returns {void} once operation is complete.
+   */
+  set(id: K, key: V): void {
+    this.store.set(id, key);
+  }
+}