@bsv/sdk 1.3.12 → 1.3.14

package/src/wallet/KeyDeriver.ts

@@ -1,10 +1,15 @@
-import { PrivateKey, PublicKey, SymmetricKey, Hash, Utils } from '../primitives/index.js'
+import {
+  PrivateKey,
+  PublicKey,
+  SymmetricKey,
+  Hash,
+  Utils
+} from '../primitives/index.js'
 import { WalletProtocol, PubKeyHex } from './Wallet.interfaces.js'
 
 export type Counterparty = PublicKey | PubKeyHex | 'self' | 'anyone'
 
 export interface KeyDeriverApi {
-
   /**
    * The root key from which all other keys are derived.
    */
@@ -16,51 +21,68 @@ export interface KeyDeriverApi {
   identityKey: string
 
   /**
-     * Derives a public key based on protocol ID, key ID, and counterparty.
-     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
-     * @param {string} keyID - The key identifier.
-     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @param {boolean} [forSelf=false] - Optional. false if undefined. Whether deriving for self.
-     * @returns {PublicKey} - The derived public key.
-     */
-  derivePublicKey: (protocolID: WalletProtocol, keyID: string, counterparty: Counterparty, forSelf?: boolean) => PublicKey
+   * Derives a public key based on protocol ID, key ID, and counterparty.
+   * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
+   * @param {string} keyID - The key identifier.
+   * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+   * @param {boolean} [forSelf=false] - Optional. false if undefined. Whether deriving for self.
+   * @returns {PublicKey} - The derived public key.
+   */
+  derivePublicKey: (
+    protocolID: WalletProtocol,
+    keyID: string,
+    counterparty: Counterparty,
+    forSelf?: boolean
+  ) => PublicKey
 
   /**
-     * Derives a private key based on protocol ID, key ID, and counterparty.
-     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
-     * @param {string} keyID - The key identifier.
-     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @returns {PrivateKey} - The derived private key.
-     */
-  derivePrivateKey: (protocolID: WalletProtocol, keyID: string, counterparty: Counterparty) => PrivateKey
+   * Derives a private key based on protocol ID, key ID, and counterparty.
+   * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
+   * @param {string} keyID - The key identifier.
+   * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+   * @returns {PrivateKey} - The derived private key.
+   */
+  derivePrivateKey: (
+    protocolID: WalletProtocol,
+    keyID: string,
+    counterparty: Counterparty
+  ) => PrivateKey
 
   /**
-     * Derives a symmetric key based on protocol ID, key ID, and counterparty.
-     * Note: Symmetric keys should not be derivable by everyone due to security risks.
-     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
-     * @param {string} keyID - The key identifier.
-     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @returns {SymmetricKey} - The derived symmetric key.
-     */
-  deriveSymmetricKey: (protocolID: WalletProtocol, keyID: string, counterparty: Counterparty) => SymmetricKey
+   * Derives a symmetric key based on protocol ID, key ID, and counterparty.
+   * Note: Symmetric keys should not be derivable by everyone due to security risks.
+   * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
+   * @param {string} keyID - The key identifier.
+   * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+   * @returns {SymmetricKey} - The derived symmetric key.
+   */
+  deriveSymmetricKey: (
+    protocolID: WalletProtocol,
+    keyID: string,
+    counterparty: Counterparty
+  ) => SymmetricKey
 
   /**
-     * Reveals the shared secret between the root key and the counterparty.
-     * Note: This should not be used for 'self'.
-     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @returns {number[]} - The shared secret as a number array.
-     * @throws {Error} - Throws an error if attempting to reveal a shared secret for 'self'.
-     */
+   * Reveals the shared secret between the root key and the counterparty.
+   * Note: This should not be used for 'self'.
+   * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+   * @returns {number[]} - The shared secret as a number array.
+   * @throws {Error} - Throws an error if attempting to reveal a shared secret for 'self'.
+   */
   revealCounterpartySecret: (counterparty: Counterparty) => number[]
 
   /**
-     * Reveals the specific key association for a given protocol ID, key ID, and counterparty.
-     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
-     * @param {string} keyID - The key identifier.
-     * @returns {number[]} - The specific key association as a number array.
-     */
-  revealSpecificSecret: (counterparty: Counterparty, protocolID: WalletProtocol, keyID: string) => number[]
+   * Reveals the specific key association for a given protocol ID, key ID, and counterparty.
+   * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+   * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
+   * @param {string} keyID - The key identifier.
+   * @returns {number[]} - The specific key association as a number array.
+   */
+  revealSpecificSecret: (
+    counterparty: Counterparty,
+    protocolID: WalletProtocol,
+    keyID: string
+  ) => number[]
 }
 
 /**
@@ -72,9 +94,9 @@ export class KeyDeriver implements KeyDeriverApi {
   identityKey: string
 
   /**
-     * Initializes the KeyDeriver instance with a root private key.
-     * @param {PrivateKey | 'anyone'} rootKey - The root private key or the string 'anyone'.
-     */
+   * Initializes the KeyDeriver instance with a root private key.
+   * @param {PrivateKey | 'anyone'} rootKey - The root private key or the string 'anyone'.
+   */
   constructor (rootKey: PrivateKey | 'anyone') {
     if (rootKey === 'anyone') {
       this.rootKey = new PrivateKey(1)
@@ -85,101 +107,147 @@ export class KeyDeriver implements KeyDeriverApi {
   }
 
   /**
-     * Derives a public key based on protocol ID, key ID, and counterparty.
-     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
-     * @param {string} keyID - The key identifier.
-     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @param {boolean} [forSelf=false] - Whether deriving for self.
-     * @returns {PublicKey} - The derived public key.
-     */
-  derivePublicKey (protocolID: WalletProtocol, keyID: string, counterparty: Counterparty, forSelf: boolean = false): PublicKey {
+   * Derives a public key based on protocol ID, key ID, and counterparty.
+   * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
+   * @param {string} keyID - The key identifier.
+   * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+   * @param {boolean} [forSelf=false] - Whether deriving for self.
+   * @returns {PublicKey} - The derived public key.
+   */
+  derivePublicKey (
+    protocolID: WalletProtocol,
+    keyID: string,
+    counterparty: Counterparty,
+    forSelf: boolean = false
+  ): PublicKey {
     counterparty = this.normalizeCounterparty(counterparty)
     if (forSelf) {
-      return this.rootKey.deriveChild(counterparty, this.computeInvoiceNumber(protocolID, keyID)).toPublicKey()
+      return this.rootKey
+        .deriveChild(counterparty, this.computeInvoiceNumber(protocolID, keyID))
+        .toPublicKey()
     } else {
-      return counterparty.deriveChild(this.rootKey, this.computeInvoiceNumber(protocolID, keyID))
+      return counterparty.deriveChild(
+        this.rootKey,
+        this.computeInvoiceNumber(protocolID, keyID)
+      )
     }
   }
 
   /**
-     * Derives a private key based on protocol ID, key ID, and counterparty.
-     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
-     * @param {string} keyID - The key identifier.
-     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @returns {PrivateKey} - The derived private key.
-     */
-  derivePrivateKey (protocolID: WalletProtocol, keyID: string, counterparty: Counterparty): PrivateKey {
+   * Derives a private key based on protocol ID, key ID, and counterparty.
+   * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
+   * @param {string} keyID - The key identifier.
+   * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+   * @returns {PrivateKey} - The derived private key.
+   */
+  derivePrivateKey (
+    protocolID: WalletProtocol,
+    keyID: string,
+    counterparty: Counterparty
+  ): PrivateKey {
     counterparty = this.normalizeCounterparty(counterparty)
-    return this.rootKey.deriveChild(counterparty, this.computeInvoiceNumber(protocolID, keyID))
+    return this.rootKey.deriveChild(
+      counterparty,
+      this.computeInvoiceNumber(protocolID, keyID)
+    )
   }
 
   /**
-     * Derives a symmetric key based on protocol ID, key ID, and counterparty.
-     * Note: Symmetric keys should not be derivable by everyone due to security risks.
-     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
-     * @param {string} keyID - The key identifier.
-     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @returns {SymmetricKey} - The derived symmetric key.
-     */
-  deriveSymmetricKey (protocolID: WalletProtocol, keyID: string, counterparty: Counterparty): SymmetricKey {
+   * Derives a symmetric key based on protocol ID, key ID, and counterparty.
+   * Note: Symmetric keys should not be derivable by everyone due to security risks.
+   * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
+   * @param {string} keyID - The key identifier.
+   * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+   * @returns {SymmetricKey} - The derived symmetric key.
+   */
+  deriveSymmetricKey (
+    protocolID: WalletProtocol,
+    keyID: string,
+    counterparty: Counterparty
+  ): SymmetricKey {
     // If counterparty is 'anyone', we use 1*G as the public key.
     // This is a publicly derivable key and should only be used in scenarios where public disclosure is intended.
     if (counterparty === 'anyone') {
       counterparty = new PrivateKey(1).toPublicKey()
     }
     counterparty = this.normalizeCounterparty(counterparty)
-    const derivedPublicKey = this.derivePublicKey(protocolID, keyID, counterparty)
-    const derivedPrivateKey = this.derivePrivateKey(protocolID, keyID, counterparty)
-    return new SymmetricKey(derivedPrivateKey.deriveSharedSecret(derivedPublicKey).x.toArray())
+    const derivedPublicKey = this.derivePublicKey(
+      protocolID,
+      keyID,
+      counterparty
+    )
+    const derivedPrivateKey = this.derivePrivateKey(
+      protocolID,
+      keyID,
+      counterparty
+    )
+    return new SymmetricKey(
+      derivedPrivateKey.deriveSharedSecret(derivedPublicKey)?.x?.toArray() ?? []
+    )
   }
 
   /**
-     * Reveals the shared secret between the root key and the counterparty.
-     * Note: This should not be used for 'self'.
-     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @returns {number[]} - The shared secret as a number array.
-     * @throws {Error} - Throws an error if attempting to reveal a shared secret for 'self'.
-     */
+   * Reveals the shared secret between the root key and the counterparty.
+   * Note: This should not be used for 'self'.
+   * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+   * @returns {number[]} - The shared secret as a number array.
+   * @throws {Error} - Throws an error if attempting to reveal a shared secret for 'self'.
+   */
   revealCounterpartySecret (counterparty: Counterparty): number[] {
     if (counterparty === 'self') {
-      throw new Error('Counterparty secrets cannot be revealed for counterparty=self.')
+      throw new Error(
+        'Counterparty secrets cannot be revealed for counterparty=self.'
+      )
     }
     counterparty = this.normalizeCounterparty(counterparty)
 
     // Double-check to ensure not revealing the secret for 'self'
     const self = this.rootKey.toPublicKey()
     const keyDerivedBySelf = this.rootKey.deriveChild(self, 'test').toHex()
-    const keyDerivedByCounterparty = this.rootKey.deriveChild(counterparty, 'test').toHex()
+    const keyDerivedByCounterparty = this.rootKey
+      .deriveChild(counterparty, 'test')
+      .toHex()
 
     if (keyDerivedBySelf === keyDerivedByCounterparty) {
-      throw new Error('Counterparty secrets cannot be revealed for counterparty=self.')
+      throw new Error(
+        'Counterparty secrets cannot be revealed for counterparty=self.'
+      )
     }
 
-    return this.rootKey.deriveSharedSecret(counterparty).encode(true) as number[]
+    return this.rootKey
+      .deriveSharedSecret(counterparty)
+      .encode(true) as number[]
   }
 
   /**
-     * Reveals the specific key association for a given protocol ID, key ID, and counterparty.
-     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
-     * @param {string} keyID - The key identifier.
-     * @returns {number[]} - The specific key association as a number array.
-     */
-  revealSpecificSecret (counterparty: Counterparty, protocolID: WalletProtocol, keyID: string): number[] {
+   * Reveals the specific key association for a given protocol ID, key ID, and counterparty.
+   * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+   * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
+   * @param {string} keyID - The key identifier.
+   * @returns {number[]} - The specific key association as a number array.
+   */
+  revealSpecificSecret (
+    counterparty: Counterparty,
+    protocolID: WalletProtocol,
+    keyID: string
+  ): number[] {
     counterparty = this.normalizeCounterparty(counterparty)
     const sharedSecret = this.rootKey.deriveSharedSecret(counterparty)
-    const invoiceNumberBin = Utils.toArray(this.computeInvoiceNumber(protocolID, keyID), 'utf8')
+    const invoiceNumberBin = Utils.toArray(
+      this.computeInvoiceNumber(protocolID, keyID),
+      'utf8'
+    )
     return Hash.sha256hmac(sharedSecret.encode(true), invoiceNumberBin)
   }
 
   /**
-     * Normalizes the counterparty to a public key.
-     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @returns {PublicKey} - The normalized counterparty public key.
-     * @throws {Error} - Throws an error if the counterparty is invalid.
-     */
+   * Normalizes the counterparty to a public key.
+   * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+   * @returns {PublicKey} - The normalized counterparty public key.
+   * @throws {Error} - Throws an error if the counterparty is invalid.
+   */
   private normalizeCounterparty (counterparty: Counterparty): PublicKey {
-    if (!counterparty) {
+    if (counterparty === null || counterparty === undefined) {
       throw new Error('counterparty must be self, anyone or a public key!')
     } else if (counterparty === 'self') {
       return this.rootKey.toPublicKey()
@@ -193,15 +261,22 @@ export class KeyDeriver implements KeyDeriverApi {
   }
 
   /**
-     * Computes the invoice number based on the protocol ID and key ID.
-     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
-     * @param {string} keyID - The key identifier.
-     * @returns {string} - The computed invoice number.
-     * @throws {Error} - Throws an error if protocol ID or key ID are invalid.
-     */
-  private computeInvoiceNumber (protocolID: WalletProtocol, keyID: string): string {
+   * Computes the invoice number based on the protocol ID and key ID.
+   * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
+   * @param {string} keyID - The key identifier.
+   * @returns {string} - The computed invoice number.
+   * @throws {Error} - Throws an error if protocol ID or key ID are invalid.
+   */
+  private computeInvoiceNumber (
+    protocolID: WalletProtocol,
+    keyID: string
+  ): string {
     const securityLevel = protocolID[0]
-    if (!Number.isInteger(securityLevel) || securityLevel < 0 || securityLevel > 2) {
+    if (
+      !Number.isInteger(securityLevel) ||
+      securityLevel < 0 ||
+      securityLevel > 2
+    ) {
       throw new Error('Protocol security level must be 0, 1, or 2')
     }
     const protocolName = protocolID[1].toLowerCase().trim()
@@ -219,7 +294,9 @@ export class KeyDeriver implements KeyDeriverApi {
         // Where: x is the security level and YYYYY is the target protocol
         // Thus, the max acceptable length is 30 + 400 = 430 bytes
         if (protocolName.length > 430) {
-          throw new Error('Specific linkage revelation protocol names must be 430 characters or less')
+          throw new Error(
+            'Specific linkage revelation protocol names must be 430 characters or less'
+          )
         }
       } else {
         throw new Error('Protocol names must be 400 characters or less')
@@ -229,10 +306,14 @@ export class KeyDeriver implements KeyDeriverApi {
       throw new Error('Protocol names must be 5 characters or more')
     }
     if (protocolName.includes('  ')) {
-      throw new Error('Protocol names cannot contain multiple consecutive spaces ("  ")')
+      throw new Error(
+        'Protocol names cannot contain multiple consecutive spaces ("  ")'
+      )
     }
     if (!/^[a-z0-9 ]+$/g.test(protocolName)) {
-      throw new Error('Protocol names can only contain letters, numbers and spaces')
+      throw new Error(
+        'Protocol names can only contain letters, numbers and spaces'
+      )
     }
     if (protocolName.endsWith(' protocol')) {
       throw new Error('No need to end your protocol name with " protocol"')