@bsv/sdk 1.3.2 → 1.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/auth/certificates/Certificate.ts

@@ -6,7 +6,8 @@ import {
   HexString,
   OutpointString,
   CertificateFieldNameUnder50Bytes,
-  ProtoWallet
+  ProtoWallet,
+  Signature
 } from '../../../mod.js'
 
 /**
@@ -128,7 +129,6 @@ export default class Certificate {
     // Write signature if included
     if (includeSignature && this.signature && this.signature.length > 0) {
       const signatureBytes = Utils.toArray(this.signature, 'hex')
-      writer.writeVarIntNum(signatureBytes.length)
       writer.write(signatureBytes)
     }
 
@@ -186,9 +186,9 @@ export default class Certificate {
     // Read signature if present
     let signature: string | undefined
     if (!reader.eof()) {
-      const signatureLength = reader.readVarIntNum()
-      const signatureBytes = reader.read(signatureLength)
-      signature = Utils.toHex(signatureBytes)
+      const signatureBytes = reader.read()
+      const sig = Signature.fromDER(signatureBytes)
+      signature = sig.toString('hex') as string
     }
 
     return new Certificate(
@@ -228,7 +228,7 @@ export default class Certificate {
    * @param {Wallet} certifier - The wallet representing the certifier.
    * @returns {Promise<void>}
    */
-  async sign(certifier: Wallet): Promise<void> {
+  async sign(certifier: ProtoWallet): Promise<void> {
     const preimage = this.toBinary(false) // Exclude the signature when signing
     const { signature } = await certifier.createSignature({
       data: preimage,

package/src/auth/certificates/MasterCertificate.ts

@@ -6,7 +6,8 @@ import {
   HexString,
   OutpointString,
   PubKeyHex,
-  Wallet
+  Wallet,
+  ProtoWallet
 } from '../../../mod.js'
 import Certificate from './Certificate.js'
 
@@ -58,7 +59,7 @@ export class MasterCertificate extends Certificate {
    *   - fieldsToReveal is empty or a field in `fieldsToReveal` does not exist in the certificate.
    *   - The decrypted master field key fails to decrypt the corresponding field (indicating an invalid key).
    */
-  async createKeyringForVerifier(subjectWallet: Wallet, verifierIdentityKey: string, fieldsToReveal: string[], originator?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
+  async createKeyringForVerifier(subjectWallet: ProtoWallet, verifierIdentityKey: string, fieldsToReveal: string[], originator?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
     if (!Array.isArray(fieldsToReveal)) {
       throw new Error('fieldsToReveal must be an array of strings')
     }

package/src/auth/utils/certificateHelpers.ts

@@ -1,11 +1,11 @@
-import { PrivateKey, SymmetricKey, Utils, Wallet, ProtoWallet } from "../../../mod.js"
+import { PrivateKey, SymmetricKey, Utils, ProtoWallet } from "../../../mod.js"
 import { MasterCertificate } from "../certificates/MasterCertificate.js"
 import { VerifiableCertificate } from "../certificates/VerifiableCertificate.js"
 
 /**
  * Creates a Master Certificate by encrypting provided fields and generating a master keyring.
  * 
- * @param {Wallet} wallet - The wallet instance used for encryption and public key retrieval.
+ * @param {ProtoWallet} wallet - The wallet instance used for encryption and public key retrieval.
  * @param {Record<string, string>} fields - The certificate fields to encrypt.
  * @param {string} certificateType - The type of the certificate being created.
  * @param {string} certificateSerialNumber - The serial number of the certificate.
@@ -13,7 +13,7 @@ import { VerifiableCertificate } from "../certificates/VerifiableCertificate.js"
  * @returns {Promise<MasterCertificate>} A promise resolving to the created Master Certificate.
  */
 export async function createMasterCertificate(
-  wallet: Wallet,
+  wallet: ProtoWallet,
   fields: Record<string, string>,
   certificateType: string,
   certificateSerialNumber: string,
@@ -51,7 +51,7 @@ export async function createMasterCertificate(
  * Creates a Verifiable Certificate by signing a Master Certificate and generating a keyring for a verifier.
  * 
  * @param {MasterCertificate} masterCertificate - The master certificate to convert into a verifiable certificate.
- * @param {Wallet} wallet - The wallet instance used for generating a keyring for the verifier.
+ * @param {ProtoWallet} wallet - The wallet instance used for generating a keyring for the verifier.
  * @param {string} verifierIdentityKey - The identity key of the verifier.
  * @param {string[]} fieldsToReveal - The list of fields to reveal to the verifier.
  * @param {PrivateKey} certifierPrivateKey - The private key of the certifier for signing the certificate.
@@ -59,7 +59,7 @@ export async function createMasterCertificate(
  */
 export async function createVerifiableCertificate(
   masterCertificate: MasterCertificate,
-  wallet: Wallet,
+  wallet: ProtoWallet,
   verifierIdentityKey: string,
   fieldsToReveal: string[],
   certifierPrivateKey: PrivateKey

package/src/wallet/CachedKeyDeriver.ts

@@ -1,6 +1,6 @@
 import { PrivateKey, PublicKey, SymmetricKey } from '../primitives/index.js'
-import KeyDeriver from './KeyDeriver.js'
-import { SecurityLevel } from './Wallet.interfaces.js'
+import { Counterparty, KeyDeriver } from './KeyDeriver.js'
+import { WalletProtocol } from './Wallet.interfaces.js'
 
 /**
  * A cached version of KeyDeriver that caches the results of key derivation methods.
@@ -24,19 +24,20 @@ export default class CachedKeyDeriver {
     this.maxCacheSize = options?.maxCacheSize || 1000
   }
 
+
   /**
      * Derives a public key based on protocol ID, key ID, and counterparty.
      * Caches the result for future calls with the same parameters.
-     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
-     * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+     * @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: [SecurityLevel, string],
+    protocolID: WalletProtocol,
     keyID: string,
-    counterparty: PublicKey | string | 'self' | 'anyone',
+    counterparty: Counterparty,
     forSelf: boolean = false
   ): PublicKey {
     const cacheKey = this.generateCacheKey('derivePublicKey', protocolID, keyID, counterparty, forSelf)
@@ -52,15 +53,15 @@ export default class CachedKeyDeriver {
   /**
      * Derives a private key based on protocol ID, key ID, and counterparty.
      * Caches the result for future calls with the same parameters.
-     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
-     * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
      * @returns {PrivateKey} - The derived private key.
      */
   derivePrivateKey (
-    protocolID: [SecurityLevel, string],
+    protocolID: WalletProtocol,
     keyID: string,
-    counterparty: PublicKey | string | 'self' | 'anyone'
+    counterparty: Counterparty
   ): PrivateKey {
     const cacheKey = this.generateCacheKey('derivePrivateKey', protocolID, keyID, counterparty)
     if (this.cache.has(cacheKey)) {
@@ -75,16 +76,16 @@ export default class CachedKeyDeriver {
   /**
      * Derives a symmetric key based on protocol ID, key ID, and counterparty.
      * Caches the result for future calls with the same parameters.
-     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
-     * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
      * @returns {SymmetricKey} - The derived symmetric key.
      * @throws {Error} - Throws an error if attempting to derive a symmetric key for 'anyone'.
      */
   deriveSymmetricKey (
-    protocolID: [SecurityLevel, string],
+    protocolID: WalletProtocol,
     keyID: string,
-    counterparty: PublicKey | string | 'self' | 'anyone'
+    counterparty: Counterparty
   ): SymmetricKey {
     const cacheKey = this.generateCacheKey('deriveSymmetricKey', protocolID, keyID, counterparty)
     if (this.cache.has(cacheKey)) {
@@ -99,11 +100,11 @@ export default class CachedKeyDeriver {
   /**
      * Reveals the shared secret between the root key and the counterparty.
      * Caches the result for future calls with the same parameters.
-     * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+     * @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: PublicKey | string | 'self' | 'anyone'): number[] {
+  revealCounterpartySecret (counterparty: Counterparty): number[] {
     const cacheKey = this.generateCacheKey('revealCounterpartySecret', counterparty)
     if (this.cache.has(cacheKey)) {
       return this.cacheGet(cacheKey)
@@ -117,14 +118,14 @@ export default class CachedKeyDeriver {
   /**
      * Reveals the specific key association for a given protocol ID, key ID, and counterparty.
      * Caches the result for future calls with the same parameters.
-     * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @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: PublicKey | string | 'self' | 'anyone',
-    protocolID: [SecurityLevel, string],
+    counterparty: Counterparty,
+    protocolID: WalletProtocol,
     keyID: string
   ): number[] {
     const cacheKey = this.generateCacheKey('revealSpecificSecret', counterparty, protocolID, keyID)
@@ -187,7 +188,7 @@ export default class CachedKeyDeriver {
     if (this.cache.size >= this.maxCacheSize) {
       // Evict the least recently used item (first item in Map)
       const firstKey = this.cache.keys().next().value
-      this.cache.delete(firstKey)
+      this.cache.delete(firstKey!)
     }
     this.cache.set(cacheKey, value)
   }

package/src/wallet/KeyDeriver.ts

@@ -1,34 +1,99 @@
 import { PrivateKey, PublicKey, SymmetricKey, Hash, Utils } from '../primitives/index.js'
-import { SecurityLevel } from '../wallet/Wallet.interfaces.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.
+   */
+  rootKey: PrivateKey
+
+  /**
+   * The identity of this key deriver which is normally the public key associated with the `rootKey`
+   */
+  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 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.
+     * @throws {Error} - Throws an error if attempting to derive a symmetric key for 'anyone'.
+     */
+  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'.
+     */
+  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[]
+}
 
 /**
  * Class responsible for deriving various types of keys using a root private key.
  * It supports deriving public and private keys, symmetric keys, and revealing key linkages.
  */
-export default class KeyDeriver {
+export class KeyDeriver implements KeyDeriverApi {
   rootKey: PrivateKey
+  identityKey: string
 
   /**
      * 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') {
+  constructor(rootKey: PrivateKey | 'anyone') {
     if (rootKey === 'anyone') {
       this.rootKey = new PrivateKey(1)
     } else {
       this.rootKey = rootKey
     }
+    this.identityKey = this.rootKey.toPublicKey().toString()
   }
 
   /**
      * Derives a public key based on protocol ID, key ID, and counterparty.
-     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
-     * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+     * @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: [SecurityLevel, string], keyID: string, counterparty: PublicKey | string | 'self' | 'anyone', forSelf: boolean = false): PublicKey {
+  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()
@@ -39,12 +104,12 @@ export default class KeyDeriver {
 
   /**
      * Derives a private key based on protocol ID, key ID, and counterparty.
-     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
-     * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
      * @returns {PrivateKey} - The derived private key.
      */
-  derivePrivateKey (protocolID: [SecurityLevel, string], keyID: string, counterparty: PublicKey | string | 'self' | 'anyone'): PrivateKey {
+  derivePrivateKey(protocolID: WalletProtocol, keyID: string, counterparty: Counterparty): PrivateKey {
     counterparty = this.normalizeCounterparty(counterparty)
     return this.rootKey.deriveChild(counterparty, this.computeInvoiceNumber(protocolID, keyID))
   }
@@ -52,13 +117,13 @@ export default class KeyDeriver {
   /**
      * 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 {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {WalletProtocol} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
-     * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+     * @param {Counterparty} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
      * @returns {SymmetricKey} - The derived symmetric key.
      * @throws {Error} - Throws an error if attempting to derive a symmetric key for 'anyone'.
      */
-  deriveSymmetricKey (protocolID: [SecurityLevel, string], keyID: string, counterparty: PublicKey | string | 'self' | 'anyone'): SymmetricKey {
+  deriveSymmetricKey(protocolID: WalletProtocol, keyID: string, counterparty: Counterparty): SymmetricKey {
     if (counterparty === 'anyone') {
       throw new Error(
         'Symmetric keys (such as encryption keys or HMAC keys) should not be derivable by everyone, because messages would be decryptable by anyone who knows the identity public key of the user, and HMACs would be similarly forgeable.'
@@ -67,17 +132,17 @@ export default class KeyDeriver {
     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())
+    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 {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+     * @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: PublicKey | string | 'self' | 'anyone'): number[] {
+  revealCounterpartySecret(counterparty: Counterparty): number[] {
     if (counterparty === 'self') {
       throw new Error('Counterparty secrets cannot be revealed for counterparty=self.')
     }
@@ -97,12 +162,12 @@ export default class KeyDeriver {
 
   /**
      * Reveals the specific key association for a given protocol ID, key ID, and counterparty.
-     * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @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: PublicKey | string | 'self' | 'anyone', protocolID: [SecurityLevel, string], keyID: string): number[] {
+  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')
@@ -111,11 +176,11 @@ export default class KeyDeriver {
 
   /**
      * Normalizes the counterparty to a public key.
-     * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
+     * @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: PublicKey | string | 'self' | 'anyone'): PublicKey {
+  private normalizeCounterparty(counterparty: Counterparty): PublicKey {
     if (!counterparty) {
       throw new Error('counterparty must be self, anyone or a public key!')
     } else if (counterparty === 'self') {
@@ -131,12 +196,12 @@ export default class KeyDeriver {
 
   /**
      * Computes the invoice number based on the protocol ID and key ID.
-     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @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: [SecurityLevel, string], keyID: string): string {
+  private computeInvoiceNumber(protocolID: WalletProtocol, keyID: string): string {
     const securityLevel = protocolID[0]
     if (!Number.isInteger(securityLevel) || securityLevel < 0 || securityLevel > 2) {
       throw new Error('Protocol security level must be 0, 1, or 2')
@@ -177,3 +242,5 @@ export default class KeyDeriver {
     return `${securityLevel}-${protocolName}-${keyID}`
   }
 }
+
+export default KeyDeriver