@bsv/sdk 1.3.11 → 1.3.13

package/src/auth/certificates/Certificate.ts

@@ -5,11 +5,10 @@ import {
   HexString,
   OutpointString,
   CertificateFieldNameUnder50Bytes,
-  WalletInterface,
   Signature,
   WalletProtocol,
   ProtoWallet
-} from '../../../mod.js'
+} from '../../../mod'
 
 /**
  * Represents an Identity Certificate as per the Wallet interface specifications.
@@ -49,7 +48,7 @@ export default class Certificate {
 
   /**
    * Certificate signature by the certifier's private key, DER encoded hex string.
-  */
+   */
   signature?: HexString
 
   /**
@@ -232,13 +231,17 @@ export default class Certificate {
    * @param {Wallet} certifierWallet - The wallet representing the certifier.
    * @returns {Promise<void>}
    */
-  async sign(certifierWallet: WalletInterface): Promise<void> {
+  async sign(certifierWallet: ProtoWallet): Promise<void> {
     if (this.signature) {
-      throw new Error(`Certificate has already been signed! Signature present: ${this.signature}`)
+      throw new Error(
+        `Certificate has already been signed! Signature present: ${this.signature}`
+      )
     }
 
     // Ensure the certifier declared is the one actually signing
-    this.certifier = (await certifierWallet.getPublicKey({ identityKey: true })).publicKey
+    this.certifier = (
+      await certifierWallet.getPublicKey({ identityKey: true })
+    ).publicKey
 
     const preimage = this.toBinary(false) // Exclude the signature when signing
     const { signature } = await certifierWallet.createSignature({
@@ -258,7 +261,13 @@ export default class Certificate {
    *   - `protocolID` (WalletProtocol): The protocol ID for certificate field encryption.
    *   - `keyID` (string): A unique key identifier derived from the serial number and field name.
    */
-  static getCertificateFieldEncryptionDetails(fieldName: string, serialNumber?: string): { protocolID: WalletProtocol, keyID: string } {
-    return { protocolID: [2, 'certificate field encryption'], keyID: `${serialNumber} ${fieldName}` }
+  static getCertificateFieldEncryptionDetails(
+    fieldName: string,
+    serialNumber?: string
+  ): { protocolID: WalletProtocol; keyID: string } {
+    return {
+      protocolID: [2, 'certificate field encryption'],
+      keyID: `${serialNumber} ${fieldName}`
+    }
   }
 }

package/src/auth/certificates/MasterCertificate.ts

@@ -8,9 +8,10 @@ import {
   PubKeyHex,
   Random,
   WalletCounterparty,
-  WalletInterface
-} from '../../../mod.js'
-import Certificate from './Certificate.js'
+  ProtoWallet,
+  OriginatorDomainNameStringUnder250Bytes
+} from '../../../mod'
+import Certificate from './Certificate'
 
 interface CreateCertificateFieldsResult {
   certificateFields: Record<CertificateFieldNameUnder50Bytes, Base64String>
@@ -46,7 +47,15 @@ export class MasterCertificate extends Certificate {
     masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>,
     signature?: HexString
   ) {
-    super(type, serialNumber, subject, certifier, revocationOutpoint, fields, signature)
+    super(
+      type,
+      serialNumber,
+      subject,
+      certifier,
+      revocationOutpoint,
+      fields,
+      signature
+    )
 
     // Ensure every field in `fields` is a string and has a corresponding key in `masterKeyring`
     for (const fieldName of Object.keys(fields)) {
@@ -65,7 +74,7 @@ export class MasterCertificate extends Certificate {
    * This method returns a master keyring tied to a specific certifier or subject who will validate
    * and sign off on the fields, along with the encrypted certificate fields.
    *
-   * @param {WalletInterface} creatorWallet - The wallet of the creator responsible for encrypting the fields.
+   * @param {ProtoWallet} creatorWallet - The wallet of the creator responsible for encrypting the fields.
    * @param {WalletCounterparty} certifierOrSubject - The certifier or subject who will validate the certificate fields.
    * @param {Record<CertificateFieldNameUnder50Bytes, string>} fields - A record of certificate field names (under 50 bytes) mapped to their values.
    * @returns {Promise<CreateCertificateFieldsResult>} A promise resolving to an object containing:
@@ -75,22 +84,37 @@ export class MasterCertificate extends Certificate {
    *     The master keyring containing encrypted revelation keys for each field.
    */
   static async createCertificateFields(
-    creatorWallet: WalletInterface,
+    creatorWallet: ProtoWallet,
     certifierOrSubject: WalletCounterparty,
-    fields: Record<CertificateFieldNameUnder50Bytes, string>
+    fields: Record<CertificateFieldNameUnder50Bytes, string>,
+    originator?: OriginatorDomainNameStringUnder250Bytes
   ): Promise<CreateCertificateFieldsResult> {
-    const certificateFields: Record<CertificateFieldNameUnder50Bytes, Base64String> = {}
-    const masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String> = {}
+    const certificateFields: Record<
+      CertificateFieldNameUnder50Bytes,
+      Base64String
+    > = {}
+    const masterKeyring: Record<
+      CertificateFieldNameUnder50Bytes,
+      Base64String
+    > = {}
     for (const [fieldName, fieldValue] of Object.entries(fields)) {
       const fieldSymmetricKey = SymmetricKey.fromRandom()
-      const encryptedFieldValue = fieldSymmetricKey.encrypt(Utils.toArray(fieldValue, 'utf8'))
-      certificateFields[fieldName] = Utils.toBase64(encryptedFieldValue as number[])
+      const encryptedFieldValue = fieldSymmetricKey.encrypt(
+        Utils.toArray(fieldValue, 'utf8')
+      )
+      certificateFields[fieldName] = Utils.toBase64(
+        encryptedFieldValue as number[]
+      )
 
-      const { ciphertext: encryptedFieldRevelationKey } = await creatorWallet.encrypt({
-        plaintext: fieldSymmetricKey.toArray(),
-        ...Certificate.getCertificateFieldEncryptionDetails(fieldName), // Only fieldName used on MasterCertificate
-        counterparty: certifierOrSubject
-      })
+      const { ciphertext: encryptedFieldRevelationKey } =
+        await creatorWallet.encrypt(
+          {
+            plaintext: fieldSymmetricKey.toArray(),
+            ...Certificate.getCertificateFieldEncryptionDetails(fieldName), // Only fieldName used on MasterCertificate
+            counterparty: certifierOrSubject
+          },
+          originator
+        )
       masterKeyring[fieldName] = Utils.toBase64(encryptedFieldRevelationKey)
     }
 
@@ -106,7 +130,7 @@ export class MasterCertificate extends Certificate {
    * for the verifier's identity key. The result is a keyring containing the keys necessary
    * for the verifier to access the designated fields.
    *
-   * @param {WalletInterface} subjectWallet - The wallet instance of the subject, used to decrypt and re-encrypt field keys.
+   * @param {ProtoWallet} subjectWallet - The wallet instance of the subject, used to decrypt and re-encrypt field keys.
    * @param {WalletCounterparty} verifier - The verifier who will receive access to the selectively revealed fields. Can be an identity key as hex, 'anyone', or 'self'.
    * @param {string[]} fieldsToReveal - An array of field names to be revealed to the verifier. Must be a subset of the certificate's fields.
    * @param {string} [originator] - Optional originator identifier, used if additional context is needed for decryption and encryption operations.
@@ -117,14 +141,15 @@ export class MasterCertificate extends Certificate {
    *   - The decrypted master field key fails to decrypt the corresponding field (indicating an invalid key).
    */
   static async createKeyringForVerifier(
-    subjectWallet: WalletInterface,
+    subjectWallet: ProtoWallet,
     certifier: WalletCounterparty,
     verifier: WalletCounterparty,
     fields: Record<CertificateFieldNameUnder50Bytes, Base64String>,
     fieldsToReveal: string[],
     masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>,
     serialNumber: Base64String,
-    originator?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
+    originator?: OriginatorDomainNameStringUnder250Bytes
+  ): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
     if (!Array.isArray(fieldsToReveal)) {
       throw new Error('fieldsToReveal must be an array of strings')
     }
@@ -132,21 +157,40 @@ export class MasterCertificate extends Certificate {
     for (const fieldName of fieldsToReveal) {
       // Make sure that fields to reveal is a subset of the certificate fields
       if (!fields[fieldName]) {
-        throw new Error(`Fields to reveal must be a subset of the certificate fields. Missing the "${fieldName}" field.`)
+        throw new Error(
+          `Fields to reveal must be a subset of the certificate fields. Missing the "${fieldName}" field.`
+        )
       }
 
       // Decrypt the master field key and verify that derived key actually decrypts requested field
-      const masterFieldKey = (await this.decryptField(subjectWallet, masterKeyring, fieldName, fields[fieldName], certifier)).fieldRevelationKey
+      const masterFieldKey = (
+        await this.decryptField(
+          subjectWallet,
+          masterKeyring,
+          fieldName,
+          fields[fieldName],
+          certifier
+        )
+      ).fieldRevelationKey
 
       // Encrypt derived fieldRevelationKey for verifier
-      const { ciphertext: encryptedFieldRevelationKey } = await subjectWallet.encrypt({
-        plaintext: masterFieldKey,
-        ...Certificate.getCertificateFieldEncryptionDetails(fieldName, serialNumber),
-        counterparty: verifier
-      }, originator)
+      const { ciphertext: encryptedFieldRevelationKey } =
+        await subjectWallet.encrypt(
+          {
+            plaintext: masterFieldKey,
+            ...Certificate.getCertificateFieldEncryptionDetails(
+              fieldName,
+              serialNumber
+            ),
+            counterparty: verifier
+          },
+          originator
+        )
 
       // Add encryptedFieldRevelationKey to fieldRevelationKeyring
-      fieldRevelationKeyring[fieldName] = Utils.toBase64(encryptedFieldRevelationKey)
+      fieldRevelationKeyring[fieldName] = Utils.toBase64(
+        encryptedFieldRevelationKey
+      )
     }
 
     // Return the field revelation keyring which can be used to create a verifiable certificate for a verifier.
@@ -155,31 +199,31 @@ export class MasterCertificate extends Certificate {
 
   /**
    * Issues a new MasterCertificate for a specified subject.
-   * 
+   *
    * This method generates a certificate containing encrypted fields and a keyring
    * for the subject to decrypt all fields. Each field is encrypted with a randomly
    * generated symmetric key, which is then encrypted for the subject. The certificate
    * can also includes a revocation outpoint to manage potential revocation.
-   * 
-   * @param {WalletInterface} certifierWallet - The wallet of the certifier, used to sign the certificate and encrypt field keys.
+   *
+   * @param {ProtoWallet} certifierWallet - The wallet of the certifier, used to sign the certificate and encrypt field keys.
    * @param {WalletCounterparty} subject - The subject for whom the certificate is issued.
    * @param {Record<CertificateFieldNameUnder50Bytes, string>} fields - Unencrypted certificate fields to include, with their names and values.
    * @param {string} certificateType - The type of certificate being issued.
-   * @param {function(string, Record<CertificateFieldNameUnder50Bytes, string>?): Promise<string>} getRevocationOutpoint - 
+   * @param {function(string, Record<CertificateFieldNameUnder50Bytes, string>?): Promise<string>} getRevocationOutpoint -
    *   Optional function to obtain a revocation outpoint for the certificate. Defaults to a placeholder.
    * @param {function(string): Promise<void>} updateProgress - Optional callback for reporting progress updates during the operation. Defaults to a no-op.
    * @returns {Promise<MasterCertificate>} - A signed MasterCertificate instance containing the encrypted fields and subject specific keyring.
-   * 
+   *
    * @throws {Error} Throws an error if any operation (e.g., encryption, signing) fails during certificate issuance.
    */
   static async issueCertificateForSubject(
-    certifierWallet: WalletInterface,
+    certifierWallet: ProtoWallet,
     subject: WalletCounterparty,
     fields: Record<CertificateFieldNameUnder50Bytes, string>,
     certificateType: string,
-    getRevocationOutpoint = async (
-      serialNumber: string
-    ): Promise<string> => { return 'Certificate revocation not tracked.' },
+    getRevocationOutpoint = async (serialNumber: string): Promise<string> => {
+      return 'Certificate revocation not tracked.'
+    },
     serialNumber?: string
   ): Promise<MasterCertificate> {
     // 1. Generate a random serialNumber if not provided
@@ -188,11 +232,8 @@ export class MasterCertificate extends Certificate {
     }
 
     // 2. Create encrypted certificate fields and associated master keyring
-    const { certificateFields, masterKeyring } = await this.createCertificateFields(
-      certifierWallet,
-      subject,
-      fields,
-    )
+    const { certificateFields, masterKeyring } =
+      await this.createCertificateFields(certifierWallet, subject, fields)
 
     // 3. Obtain a revocation outpoint (ex. certifier can call wallet.createAction())
     const revocationOutpoint = await getRevocationOutpoint(serialNumber)
@@ -214,7 +255,6 @@ export class MasterCertificate extends Certificate {
     return certificate
   }
 
-
   /**
    * Decrypts all fields in the MasterCertificate using the subject's or certifier's wallet.
    *
@@ -224,7 +264,7 @@ export class MasterCertificate extends Certificate {
    * - If the certificate is self-signed, the counterparty should be set to 'self'.
    * - Otherwise, the counterparty should always be the other party involved in the certificate issuance process (the subject or certifier).
    *
-   * @param {WalletInterface} subjectOrCertifierWallet - The wallet of the subject or certifier, used to decrypt the master keyring and field values.
+   * @param {ProtoWallet} subjectOrCertifierWallet - The wallet of the subject or certifier, used to decrypt the master keyring and field values.
    * @param {Record<CertificateFieldNameUnder50Bytes, Base64String>} masterKeyring - A record containing encrypted keys for each field.
    * @param {Record<CertificateFieldNameUnder50Bytes, Base64String>} fields - A record of encrypted field names and their values.
    * @param {WalletCounterparty} counterparty - The counterparty responsible for creating or signing the certificate. For self-signed certificates, use 'self'.
@@ -233,7 +273,7 @@ export class MasterCertificate extends Certificate {
    * @throws {Error} Throws an error if the `masterKeyring` is invalid or if decryption fails for any field.
    */
   static async decryptFields(
-    subjectOrCertifierWallet: WalletInterface,
+    subjectOrCertifierWallet: ProtoWallet,
     masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>,
     fields: Record<CertificateFieldNameUnder50Bytes, Base64String>,
     counterparty: WalletCounterparty
@@ -242,10 +282,19 @@ export class MasterCertificate extends Certificate {
       throw new Error('A MasterCertificate must have a valid masterKeyring!')
     }
     try {
-      const decryptedFields: Record<CertificateFieldNameUnder50Bytes, string> = {}
+      const decryptedFields: Record<CertificateFieldNameUnder50Bytes, string> =
+        {}
       // Note: we want to iterate through all fields, not just masterKeyring keys/value pairs.
       for (const fieldName of Object.keys(fields)) {
-        decryptedFields[fieldName] = (await this.decryptField(subjectOrCertifierWallet, masterKeyring, fieldName, fields[fieldName], counterparty)).decryptedFieldValue
+        decryptedFields[fieldName] = (
+          await this.decryptField(
+            subjectOrCertifierWallet,
+            masterKeyring,
+            fieldName,
+            fields[fieldName],
+            counterparty
+          )
+        ).decryptedFieldValue
       }
       return decryptedFields
     } catch (e) {
@@ -254,23 +303,30 @@ export class MasterCertificate extends Certificate {
   }
 
   static async decryptField(
-    subjectOrCertifierWallet: WalletInterface,
+    subjectOrCertifierWallet: ProtoWallet,
     masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>,
     fieldName: Base64String,
     fieldValue: Base64String,
-    counterparty: WalletCounterparty
-  ): Promise<{ fieldRevelationKey: number[], decryptedFieldValue: string }> {
+    counterparty: WalletCounterparty,
+    originator?: OriginatorDomainNameStringUnder250Bytes
+  ): Promise<{ fieldRevelationKey: number[]; decryptedFieldValue: string }> {
     if (!masterKeyring || Object.keys(masterKeyring).length === 0) {
       throw new Error('A MasterCertificate must have a valid masterKeyring!')
     }
     try {
-      const { plaintext: fieldRevelationKey } = await subjectOrCertifierWallet.decrypt({
-        ciphertext: Utils.toArray(masterKeyring[fieldName], 'base64'),
-        ...Certificate.getCertificateFieldEncryptionDetails(fieldName), // Only fieldName used on MasterCertificate
-        counterparty
-      })
+      const { plaintext: fieldRevelationKey } =
+        await subjectOrCertifierWallet.decrypt(
+          {
+            ciphertext: Utils.toArray(masterKeyring[fieldName], 'base64'),
+            ...Certificate.getCertificateFieldEncryptionDetails(fieldName), // Only fieldName used on MasterCertificate
+            counterparty
+          },
+          originator
+        )
 
-      const decryptedFieldValue = new SymmetricKey(fieldRevelationKey).decrypt(Utils.toArray(fieldValue, 'base64'))
+      const decryptedFieldValue = new SymmetricKey(fieldRevelationKey).decrypt(
+        Utils.toArray(fieldValue, 'base64')
+      )
       return {
         fieldRevelationKey,
         decryptedFieldValue: Utils.toUTF8(decryptedFieldValue as number[])

package/src/auth/certificates/VerifiableCertificate.ts

@@ -6,9 +6,9 @@ import {
   HexString,
   OutpointString,
   PubKeyHex,
-  WalletInterface
-} from '../../../mod.js'
-import Certificate from './Certificate.js'
+  ProtoWallet
+} from '../../../mod'
+import Certificate from './Certificate'
 
 /**
  * VerifiableCertificate extends the Certificate class, adding functionality to manage a verifier-specific keyring.
@@ -37,36 +37,56 @@ export class VerifiableCertificate extends Certificate {
     signature?: HexString,
     decryptedFields?: Record<CertificateFieldNameUnder50Bytes, Base64String>
   ) {
-    super(type, serialNumber, subject, certifier, revocationOutpoint, fields, signature)
+    super(
+      type,
+      serialNumber,
+      subject,
+      certifier,
+      revocationOutpoint,
+      fields,
+      signature
+    )
     this.keyring = keyring
     this.decryptedFields = decryptedFields
   }
 
   /**
    * Decrypts selectively revealed certificate fields using the provided keyring and verifier wallet
-   * @param {WalletInterface} verifierWallet - The wallet instance of the certificate's verifier, used to decrypt field keys.
+   * @param {ProtoWallet} verifierWallet - The wallet instance of the certificate's verifier, used to decrypt field keys.
    * @returns {Promise<Record<CertificateFieldNameUnder50Bytes, string>>} - A promise that resolves to an object where each key is a field name and each value is the decrypted field value as a string.
    * @throws {Error} Throws an error if any of the decryption operations fail, with a message indicating the failure context.
    */
-  async decryptFields(verifierWallet: WalletInterface): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
+  async decryptFields(
+    verifierWallet: ProtoWallet
+  ): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
     if (!this.keyring || Object.keys(this.keyring).length === 0) {
-      throw new Error('A keyring is required to decrypt certificate fields for the verifier.')
+      throw new Error(
+        'A keyring is required to decrypt certificate fields for the verifier.'
+      )
     }
     try {
-      const decryptedFields: Record<CertificateFieldNameUnder50Bytes, string> = {}
+      const decryptedFields: Record<CertificateFieldNameUnder50Bytes, string> =
+        {}
       for (const fieldName in this.keyring) {
         const { plaintext: fieldRevelationKey } = await verifierWallet.decrypt({
           ciphertext: Utils.toArray(this.keyring[fieldName], 'base64'),
-          ...Certificate.getCertificateFieldEncryptionDetails(fieldName, this.serialNumber),
+          ...Certificate.getCertificateFieldEncryptionDetails(
+            fieldName,
+            this.serialNumber
+          ),
           counterparty: this.subject
         })
 
-        const fieldValue = new SymmetricKey(fieldRevelationKey).decrypt(Utils.toArray(this.fields[fieldName], 'base64'))
+        const fieldValue = new SymmetricKey(fieldRevelationKey).decrypt(
+          Utils.toArray(this.fields[fieldName], 'base64')
+        )
         decryptedFields[fieldName] = Utils.toUTF8(fieldValue as number[])
       }
       return decryptedFields
     } catch (error) {
-      throw new Error(`Failed to decrypt selectively revealed certificate fields using keyring: ${error instanceof Error ? error.message : error}`)
+      throw new Error(
+        `Failed to decrypt selectively revealed certificate fields using keyring: ${error instanceof Error ? error.message : error}`
+      )
     }
   }
 }