@bsv/sdk 1.3.10 → 1.3.12

package/src/auth/certificates/MasterCertificate.ts

@@ -8,10 +8,16 @@ import {
   PubKeyHex,
   Random,
   WalletCounterparty,
-  WalletInterface
+  ProtoWallet,
+  OriginatorDomainNameStringUnder250Bytes
 } from '../../../mod.js'
 import Certificate from './Certificate.js'
 
+interface CreateCertificateFieldsResult {
+  certificateFields: Record<CertificateFieldNameUnder50Bytes, Base64String>
+  masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>
+}
+
 /**
  * MasterCertificate extends the base Certificate class to manage a master keyring, enabling the creation of verifiable certificates.
  *
@@ -56,38 +62,43 @@ export class MasterCertificate extends Certificate {
   }
 
   /**
-   * Decrypts all fields in the MasterCertificate using the subject's wallet.
-   * 
-   * This method uses the `masterKeyring` to decrypt each field's encryption key and then
-   * decrypts the field values. The result is a record of plaintext field names and values.
-   * 
-   * @param {WalletInterface} subjectWallet - The wallet of the subject, used to decrypt the master keyring and field values.
-   * @returns {Promise<Record<CertificateFieldNameUnder50Bytes, string>>} - A record of field names and their decrypted values in plaintext.
-   * 
-   * @throws {Error} Throws an error if the `masterKeyring` is invalid or if decryption fails for any field.
+   * Encrypts certificate fields for a subject and generates a master keyring.
+   * 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 {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:
+   *   - `certificateFields` {Record<CertificateFieldNameUnder50Bytes, Base64String>}:
+   *     The encrypted certificate fields.
+   *   - `masterKeyring` {Record<CertificateFieldNameUnder50Bytes, Base64String>}:
+   *     The master keyring containing encrypted revelation keys for each field.
    */
-  async decryptFields(subjectWallet: WalletInterface): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
-    // const fields: Record<CertificateFieldNameUnder50Bytes, Base64String> = this.fields
-    const decryptedFields: Record<CertificateFieldNameUnder50Bytes, string> = {}
-    if (!this.masterKeyring || Object.keys(this.masterKeyring).length === 0) {
-      throw new Error('A MasterCertificate must have a valid masterKeyring!')
+  static async createCertificateFields(
+    creatorWallet: ProtoWallet,
+    certifierOrSubject: WalletCounterparty,
+    fields: Record<CertificateFieldNameUnder50Bytes, string>,
+    originator?: OriginatorDomainNameStringUnder250Bytes
+  ): Promise<CreateCertificateFieldsResult> {
+    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 { ciphertext: encryptedFieldRevelationKey } = await creatorWallet.encrypt({
+        plaintext: fieldSymmetricKey.toArray(),
+        ...Certificate.getCertificateFieldEncryptionDetails(fieldName), // Only fieldName used on MasterCertificate
+        counterparty: certifierOrSubject
+      }, originator)
+      masterKeyring[fieldName] = Utils.toBase64(encryptedFieldRevelationKey)
     }
 
-    try {
-      // Note: we want to iterate through all fields, not just masterKeyring keys/value pairs.
-      for (const fieldName of Object.keys(this.fields)) {
-        const { plaintext: fieldRevelationKey } = await subjectWallet.decrypt({
-          ciphertext: Utils.toArray(this.masterKeyring[fieldName], 'base64'),
-          counterparty: this.certifier,
-          ...Certificate.getCertificateFieldEncryptionDetails(this.serialNumber, fieldName)
-        })
-
-        const fieldValue = new SymmetricKey(fieldRevelationKey).decrypt(Utils.toArray(this.fields[fieldName], 'base64'))
-        decryptedFields[fieldName] = Utils.toUTF8(fieldValue as number[])
-      }
-      return decryptedFields
-    } catch (e) {
-      throw new Error('Failed to decrypt all master certificate fields.')
+    return {
+      certificateFields,
+      masterKeyring
     }
   }
 
@@ -97,7 +108,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.
@@ -107,37 +118,32 @@ export class MasterCertificate extends Certificate {
    *   - 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: WalletInterface, verifier: WalletCounterparty, fieldsToReveal: string[], originator?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
+  static async createKeyringForVerifier(
+    subjectWallet: ProtoWallet,
+    certifier: WalletCounterparty,
+    verifier: WalletCounterparty,
+    fields: Record<CertificateFieldNameUnder50Bytes, Base64String>,
+    fieldsToReveal: string[],
+    masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>,
+    serialNumber: Base64String,
+    originator?: OriginatorDomainNameStringUnder250Bytes): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
     if (!Array.isArray(fieldsToReveal)) {
       throw new Error('fieldsToReveal must be an array of strings')
     }
     const fieldRevelationKeyring = {}
     for (const fieldName of fieldsToReveal) {
       // Make sure that fields to reveal is a subset of the certificate fields
-      if (!this.fields[fieldName]) {
+      if (!fields[fieldName]) {
         throw new Error(`Fields to reveal must be a subset of the certificate fields. Missing the "${fieldName}" field.`)
       }
 
-      const encryptedMasterFieldKey = this.masterKeyring[fieldName]
-
-      // Decrypt the master field key
-      const { plaintext: masterFieldKey } = await subjectWallet.decrypt({
-        ciphertext: Utils.toArray(encryptedMasterFieldKey, 'base64'),
-        ...Certificate.getCertificateFieldEncryptionDetails(this.serialNumber, fieldName),
-        counterparty: this.certifier
-      }, originator)
-
-      // Verify that derived key actually decrypts requested field
-      try {
-        new SymmetricKey(masterFieldKey).decrypt(Utils.toArray(this.fields[fieldName], 'base64'))
-      } catch (_) {
-        throw new Error(`Decryption of the "${fieldName}" field with its revelation key failed.`)
-      }
+      // 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
 
       // Encrypt derived fieldRevelationKey for verifier
       const { ciphertext: encryptedFieldRevelationKey } = await subjectWallet.encrypt({
         plaintext: masterFieldKey,
-        ...Certificate.getCertificateFieldEncryptionDetails(this.serialNumber, fieldName),
+        ...Certificate.getCertificateFieldEncryptionDetails(fieldName, serialNumber),
         counterparty: verifier
       }, originator)
 
@@ -157,7 +163,7 @@ export class MasterCertificate extends Certificate {
    * 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.
@@ -169,33 +175,27 @@ export class MasterCertificate extends Certificate {
    * @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.' }
+    ): Promise<string> => { return 'Certificate revocation not tracked.' },
+    serialNumber?: string
   ): Promise<MasterCertificate> {
-    // 1. Generate serialNumber
-    const serialNumber = Utils.toBase64(Random(32))
-
-    const encryptedCertificateFields: Record<CertificateFieldNameUnder50Bytes, Base64String> = {}
-    const masterKeyringForSubject: Record<CertificateFieldNameUnder50Bytes, Base64String> = {}
-
-    // 2. For each field, generate a random key -> encrypt field -> encrypt key
-    for (const [fieldName, fieldValue] of Object.entries(fields)) {
-      const fieldSymmetricKey = SymmetricKey.fromRandom()
-      const encryptedFieldValue = fieldSymmetricKey.encrypt(Utils.toArray(fieldValue, 'utf8'))
-      encryptedCertificateFields[fieldName] = Utils.toBase64(encryptedFieldValue as number[])
-      const { ciphertext: encryptedFieldRevelationKey } = await certifierWallet.encrypt({
-        plaintext: fieldSymmetricKey.toArray(),
-        ...Certificate.getCertificateFieldEncryptionDetails(serialNumber, fieldName),
-        counterparty: subject
-      })
-      masterKeyringForSubject[fieldName] = Utils.toBase64(encryptedFieldRevelationKey)
+    // 1. Generate a random serialNumber if not provided
+    if (!serialNumber) {
+      serialNumber = Utils.toBase64(Random(32))
     }
 
+    // 2. Create encrypted certificate fields and associated master keyring
+    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)
     // TODO: Validate revocation outpoint format
@@ -207,12 +207,79 @@ export class MasterCertificate extends Certificate {
       subject,
       (await certifierWallet.getPublicKey({ identityKey: true })).publicKey,
       revocationOutpoint,
-      encryptedCertificateFields,
-      masterKeyringForSubject
+      certificateFields,
+      masterKeyring
     )
 
     // 5. Sign and return the new MasterCertificate certifying the subject.
     await certificate.sign(certifierWallet)
     return certificate
   }
+
+
+  /**
+   * Decrypts all fields in the MasterCertificate using the subject's or certifier's wallet.
+   *
+   * This method allows the subject or certifier to decrypt the `masterKeyring` and retrieve
+   * the encryption keys for each field, which are then used to decrypt the corresponding field values.
+   * The counterparty used for decryption depends on how the certificate fields were created:
+   * - 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 {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'.
+   * @returns {Promise<Record<CertificateFieldNameUnder50Bytes, string>>} A promise resolving to a record of field names and their decrypted values in plaintext.
+   *
+   * @throws {Error} Throws an error if the `masterKeyring` is invalid or if decryption fails for any field.
+   */
+  static async decryptFields(
+    subjectOrCertifierWallet: ProtoWallet,
+    masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>,
+    fields: Record<CertificateFieldNameUnder50Bytes, Base64String>,
+    counterparty: WalletCounterparty
+  ): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
+    if (!masterKeyring || Object.keys(masterKeyring).length === 0) {
+      throw new Error('A MasterCertificate must have a valid masterKeyring!')
+    }
+    try {
+      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
+      }
+      return decryptedFields
+    } catch (e) {
+      throw new Error('Failed to decrypt all master certificate fields.')
+    }
+  }
+
+  static async decryptField(
+    subjectOrCertifierWallet: ProtoWallet,
+    masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>,
+    fieldName: Base64String,
+    fieldValue: Base64String,
+    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
+      }, originator)
+
+      const decryptedFieldValue = new SymmetricKey(fieldRevelationKey).decrypt(Utils.toArray(fieldValue, 'base64'))
+      return {
+        fieldRevelationKey,
+        decryptedFieldValue: Utils.toUTF8(decryptedFieldValue as number[])
+      }
+    } catch (e) {
+      throw new Error('Failed to decrypt certificate field!')
+    }
+  }
 }

package/src/auth/certificates/VerifiableCertificate.ts

@@ -6,8 +6,7 @@ import {
   HexString,
   OutpointString,
   PubKeyHex,
-  WalletInterface,
-  WalletError
+  ProtoWallet
 } from '../../../mod.js'
 import Certificate from './Certificate.js'
 
@@ -34,8 +33,8 @@ export class VerifiableCertificate extends Certificate {
     certifier: PubKeyHex,
     revocationOutpoint: OutpointString,
     fields: Record<CertificateFieldNameUnder50Bytes, string>,
+    keyring: Record<CertificateFieldNameUnder50Bytes, string>,
     signature?: HexString,
-    keyring?: Record<CertificateFieldNameUnder50Bytes, string>,
     decryptedFields?: Record<CertificateFieldNameUnder50Bytes, Base64String>
   ) {
     super(type, serialNumber, subject, certifier, revocationOutpoint, fields, signature)
@@ -45,11 +44,11 @@ export class VerifiableCertificate extends Certificate {
 
   /**
    * 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.')
     }
@@ -58,7 +57,7 @@ export class VerifiableCertificate extends Certificate {
       for (const fieldName in this.keyring) {
         const { plaintext: fieldRevelationKey } = await verifierWallet.decrypt({
           ciphertext: Utils.toArray(this.keyring[fieldName], 'base64'),
-          ...Certificate.getCertificateFieldEncryptionDetails(this.serialNumber, fieldName),
+          ...Certificate.getCertificateFieldEncryptionDetails(fieldName, this.serialNumber),
           counterparty: this.subject
         })