@bsv/sdk 1.3.10 → 1.3.11

package/docs/auth.md

@@ -212,7 +212,7 @@ export default class Certificate {
     subject: PubKeyHex;
     certifier: PubKeyHex;
     revocationOutpoint: OutpointString;
-    fields: Record<CertificateFieldNameUnder50Bytes, string>;
+    fields: Record<CertificateFieldNameUnder50Bytes, Base64String>;
     signature?: HexString;
     constructor(type: Base64String, serialNumber: Base64String, subject: PubKeyHex, certifier: PubKeyHex, revocationOutpoint: OutpointString, fields: Record<CertificateFieldNameUnder50Bytes, string>, signature?: HexString) 
     toBinary(includeSignature: boolean = true): number[] 
@@ -269,12 +269,12 @@ See also: [PubKeyHex](#type-pubkeyhex)
 
 #### Property fields
 
-All the fields present in the certificate, with field names as keys and field values as strings.
+All the fields present in the certificate, with field names as keys and encrypted field values as Base64 strings.
 
 ```ts
-fields: Record<CertificateFieldNameUnder50Bytes, string>
+fields: Record<CertificateFieldNameUnder50Bytes, Base64String>
 ```
-See also: [CertificateFieldNameUnder50Bytes](#type-certificatefieldnameunder50bytes)
+See also: [Base64String](#type-base64string), [CertificateFieldNameUnder50Bytes](#type-certificatefieldnameunder50bytes)
 
 #### Property revocationOutpoint
 
@@ -466,9 +466,10 @@ export class MasterCertificate extends Certificate {
     declare signature?: HexString;
     masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>;
     constructor(type: Base64String, serialNumber: Base64String, subject: PubKeyHex, certifier: PubKeyHex, revocationOutpoint: OutpointString, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, signature?: HexString) 
-    async decryptFields(subjectWallet: WalletInterface): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
-    async createKeyringForVerifier(subjectWallet: WalletInterface, verifier: WalletCounterparty, fieldsToReveal: string[], originator?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
-    static async issueCertificateForSubject(certifierWallet: WalletInterface, subject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>, certificateType: string, getRevocationOutpoint = async (serialNumber: string): Promise<string> => { return "Certificate revocation not tracked."; }): Promise<MasterCertificate> 
+    static async createCertificateFields(creatorWallet: WalletInterface, certifierOrSubject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>): Promise<CreateCertificateFieldsResult> 
+    static async createKeyringForVerifier(subjectWallet: WalletInterface, certifier: WalletCounterparty, verifier: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, fieldsToReveal: string[], masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, serialNumber: Base64String, originator?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
+    static async issueCertificateForSubject(certifierWallet: WalletInterface, subject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>, certificateType: string, getRevocationOutpoint = async (serialNumber: string): Promise<string> => { return "Certificate revocation not tracked."; }, serialNumber?: string): Promise<MasterCertificate> 
+    static async decryptFields(subjectOrCertifierWallet: WalletInterface, masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, counterparty: WalletCounterparty): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
 }
 ```
 
@@ -478,6 +479,34 @@ See also: [Base64String](#type-base64string), [Certificate](#class-certificate),
 
 <summary>Class MasterCertificate Details</summary>
 
+#### Method createCertificateFields
+
+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.
+
+```ts
+static async createCertificateFields(creatorWallet: WalletInterface, certifierOrSubject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>): Promise<CreateCertificateFieldsResult> 
+```
+See also: [CertificateFieldNameUnder50Bytes](#type-certificatefieldnameunder50bytes), [WalletCounterparty](#type-walletcounterparty), [WalletInterface](#interface-walletinterface)
+
+Returns
+
+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.
+
+Argument Details
+
++ **creatorWallet**
+  + The wallet of the creator responsible for encrypting the fields.
++ **certifierOrSubject**
+  + The certifier or subject who will validate the certificate fields.
++ **fields**
+  + A record of certificate field names (under 50 bytes) mapped to their values.
+
 #### Method createKeyringForVerifier
 
 Creates a keyring for a verifier, enabling them to decrypt specific certificate fields.
@@ -486,9 +515,9 @@ for the verifier's identity key. The result is a keyring containing the keys nec
 for the verifier to access the designated fields.
 
 ```ts
-async createKeyringForVerifier(subjectWallet: WalletInterface, verifier: WalletCounterparty, fieldsToReveal: string[], originator?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
+static async createKeyringForVerifier(subjectWallet: WalletInterface, certifier: WalletCounterparty, verifier: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, fieldsToReveal: string[], masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, serialNumber: Base64String, originator?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
 ```
-See also: [CertificateFieldNameUnder50Bytes](#type-certificatefieldnameunder50bytes), [WalletCounterparty](#type-walletcounterparty), [WalletInterface](#interface-walletinterface)
+See also: [Base64String](#type-base64string), [CertificateFieldNameUnder50Bytes](#type-certificatefieldnameunder50bytes), [WalletCounterparty](#type-walletcounterparty), [WalletInterface](#interface-walletinterface)
 
 Returns
 
@@ -514,24 +543,33 @@ Throws an error if:
 
 #### Method decryptFields
 
-Decrypts all fields in the MasterCertificate using the subject's wallet.
+Decrypts all fields in the MasterCertificate using the subject's or certifier'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.
+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).
 
 ```ts
-async decryptFields(subjectWallet: WalletInterface): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
+static async decryptFields(subjectOrCertifierWallet: WalletInterface, masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, counterparty: WalletCounterparty): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
 ```
-See also: [CertificateFieldNameUnder50Bytes](#type-certificatefieldnameunder50bytes), [WalletInterface](#interface-walletinterface)
+See also: [Base64String](#type-base64string), [CertificateFieldNameUnder50Bytes](#type-certificatefieldnameunder50bytes), [WalletCounterparty](#type-walletcounterparty), [WalletInterface](#interface-walletinterface)
 
 Returns
 
-- A record of field names and their decrypted values in plaintext.
+A promise resolving to a record of field names and their decrypted values in plaintext.
 
 Argument Details
 
-+ **subjectWallet**
-  + The wallet of the subject, used to decrypt the master keyring and field values.
++ **subjectOrCertifierWallet**
+  + The wallet of the subject or certifier, used to decrypt the master keyring and field values.
++ **masterKeyring**
+  + A record containing encrypted keys for each field.
++ **fields**
+  + A record of encrypted field names and their values.
++ **counterparty**
+  + The counterparty responsible for creating or signing the certificate. For self-signed certificates, use 'self'.
 
 Throws
 
@@ -547,7 +585,7 @@ generated symmetric key, which is then encrypted for the subject. The certificat
 can also includes a revocation outpoint to manage potential revocation.
 
 ```ts
-static async issueCertificateForSubject(certifierWallet: WalletInterface, subject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>, certificateType: string, getRevocationOutpoint = async (serialNumber: string): Promise<string> => { return "Certificate revocation not tracked."; }): Promise<MasterCertificate> 
+static async issueCertificateForSubject(certifierWallet: WalletInterface, subject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>, certificateType: string, getRevocationOutpoint = async (serialNumber: string): Promise<string> => { return "Certificate revocation not tracked."; }, serialNumber?: string): Promise<MasterCertificate> 
 ```
 See also: [CertificateFieldNameUnder50Bytes](#type-certificatefieldnameunder50bytes), [MasterCertificate](#class-mastercertificate), [WalletCounterparty](#type-walletcounterparty), [WalletInterface](#interface-walletinterface)
 
@@ -1078,7 +1116,7 @@ export class VerifiableCertificate extends Certificate {
     declare signature?: HexString;
     keyring: Record<CertificateFieldNameUnder50Bytes, string>;
     decryptedFields?: Record<CertificateFieldNameUnder50Bytes, Base64String>;
-    constructor(type: Base64String, serialNumber: Base64String, subject: PubKeyHex, certifier: PubKeyHex, revocationOutpoint: OutpointString, fields: Record<CertificateFieldNameUnder50Bytes, string>, signature?: HexString, keyring?: Record<CertificateFieldNameUnder50Bytes, string>, decryptedFields?: Record<CertificateFieldNameUnder50Bytes, Base64String>) 
+    constructor(type: Base64String, serialNumber: Base64String, subject: PubKeyHex, certifier: PubKeyHex, revocationOutpoint: OutpointString, fields: Record<CertificateFieldNameUnder50Bytes, string>, keyring: Record<CertificateFieldNameUnder50Bytes, string>, signature?: HexString, decryptedFields?: Record<CertificateFieldNameUnder50Bytes, Base64String>) 
     async decryptFields(verifierWallet: WalletInterface): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
 }
 ```
@@ -1214,7 +1252,7 @@ getVerifiableCertificates = async (wallet: WalletInterface, requestedCertificate
             fieldsToReveal: requestedCertificates.types[certificate.type],
             verifier: verifierIdentityKey
         });
-        return new VerifiableCertificate(certificate.type, certificate.serialNumber, certificate.subject, certificate.certifier, certificate.revocationOutpoint, certificate.fields, certificate.signature, keyringForVerifier);
+        return new VerifiableCertificate(certificate.type, certificate.serialNumber, certificate.subject, certificate.certifier, certificate.revocationOutpoint, certificate.fields, keyringForVerifier, certificate.signature);
     }));
 }
 ```
@@ -1232,7 +1270,7 @@ validateCertificates = async (verifierWallet: WalletInterface, message: AuthMess
         if (incomingCert.subject !== message.identityKey) {
             throw new Error(`The subject of one of your certificates ("${incomingCert.subject}") is not the same as the request sender ("${message.identityKey}").`);
         }
-        const certToVerify = new VerifiableCertificate(incomingCert.type, incomingCert.serialNumber, incomingCert.subject, incomingCert.certifier, incomingCert.revocationOutpoint, incomingCert.fields, incomingCert.signature, incomingCert.keyring);
+        const certToVerify = new VerifiableCertificate(incomingCert.type, incomingCert.serialNumber, incomingCert.subject, incomingCert.certifier, incomingCert.revocationOutpoint, incomingCert.fields, incomingCert.keyring, incomingCert.signature);
         const isValidCert = await certToVerify.verify();
         if (!isValidCert) {
             throw new Error(`The signature for the certificate with serial number ${certToVerify.serialNumber} is invalid!`);

package/package.json

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

package/src/auth/__tests/Peer.test.ts

@@ -7,44 +7,8 @@ import { Utils, PrivateKey, SymmetricKey } from '../../../dist/cjs/src/primitive
 import { VerifiableCertificate, } from "../../../dist/cjs/src/auth/certificates/VerifiableCertificate.js"
 import { MasterCertificate } from '../../../dist/cjs/src/auth/certificates/MasterCertificate.js'
 import { getVerifiableCertificates } from '../../../dist/cjs/src/auth/utils/getVerifiableCertificates.js'
-import { Certificate } from "../../../dist/cjs/src/auth/certificates/index.js"
 jest.mock('../../../dist/cjs/src/auth/utils/getVerifiableCertificates.js')
 
-/**
- * A helper function to decrypt a VerifiableCertificate's fields using the provided wallets.
- */
-async function decryptCertificateFields(
-  cert: VerifiableCertificate,
-  localWallet: Wallet,
-  counterpartyWallet: Wallet
-): Promise<Record<string, string>> {
-  const entries = await Promise.all(
-    Object.entries(cert.keyring).map(async ([fieldName, encryptedKey]) => {
-      // Decrypt the per-field symmetric key
-      const { plaintext: masterFieldKey } = await localWallet.decrypt({
-        ciphertext: Utils.toArray(encryptedKey, 'base64'),
-        ...Certificate.getCertificateFieldEncryptionDetails(cert.serialNumber, fieldName),
-        counterparty: (await counterpartyWallet.getPublicKey({ identityKey: true })).publicKey,
-      })
-
-      // Decrypt the actual field contents using the decrypted symmetric key
-      try {
-        const decryptedData = new SymmetricKey(masterFieldKey).decrypt(
-          Utils.toArray(cert.fields[fieldName], 'base64')
-        )
-        return { key: fieldName, value: Utils.toUTF8(decryptedData as number[]) }
-      } catch (_) {
-        throw new Error(`Decryption of the "${fieldName}" field with its revelation key failed.`)
-      }
-    })
-  )
-
-  return entries.reduce((acc, { key, value }) => {
-    acc[key] = value
-    return acc
-  }, {} as Record<string, string>)
-}
-
 class LocalTransport implements Transport {
   private peerTransport?: LocalTransport
   private onDataCallback?: (message: AuthMessage) => void
@@ -117,7 +81,15 @@ describe('Peer class mutual authentication and certificate exchange', () => {
   ): Promise<VerifiableCertificate> {
     const certifierWallet = new ProtoWallet(certifierPrivateKey)
 
-    const keyringForVerifier = await masterCertificate.createKeyringForVerifier(wallet, verifierIdentityKey, fieldsToReveal)
+    const keyringForVerifier = await MasterCertificate.createKeyringForVerifier(
+      wallet,
+      certifierWallet.keyDeriver.identityKey,
+      verifierIdentityKey,
+      masterCertificate.fields,
+      fieldsToReveal,
+      masterCertificate.masterKeyring,
+      masterCertificate.serialNumber
+    )
     return new VerifiableCertificate(
       masterCertificate.type,
       masterCertificate.serialNumber,
@@ -125,8 +97,8 @@ describe('Peer class mutual authentication and certificate exchange', () => {
       masterCertificate.certifier,
       masterCertificate.revocationOutpoint,
       masterCertificate.fields,
-      masterCertificate.signature,
-      keyringForVerifier
+      keyringForVerifier,
+      masterCertificate.signature
     )
   }
 
@@ -234,7 +206,7 @@ describe('Peer class mutual authentication and certificate exchange', () => {
         if (certificatesReceivedByBob?.length !== 0) {
           certificatesReceivedByBob?.forEach(async cert => {
             // Decrypt to ensure it has the correct fields
-            const decryptedFields = await decryptCertificateFields(cert, walletB, walletA)
+            const decryptedFields = await cert.decryptFields(walletB)
             if (cert.certifier !== 'bob') {
               console.log('Bob accepted the message:', Utils.toUTF8(payload))
               console.log('Decrypted fields:', decryptedFields)
@@ -279,7 +251,7 @@ describe('Peer class mutual authentication and certificate exchange', () => {
     alice.listenForCertificatesReceived(async (senderPublicKey, certificates) => {
       for (const cert of certificates) {
         // Decrypt Bob's certificate fields
-        const decryptedFields = await decryptCertificateFields(cert, walletA, walletB)
+        const decryptedFields = await cert.decryptFields(walletA)
 
         // Check and use the decrypted fields
         if (Object.keys(decryptedFields).length !== 0 && decryptedFields.libraryCardNumber) {
@@ -342,7 +314,7 @@ describe('Peer class mutual authentication and certificate exchange', () => {
         if (certificates.length > 0) {
           // Decrypt to confirm
           for (const cert of certificates) {
-            const decrypted = await decryptCertificateFields(cert, walletB, walletA)
+            const decrypted = await cert.decryptFields(walletB)
             console.log('Bob received additional certificates from Alice:', cert)
             console.log('Decrypted fields:', decrypted)
           }
@@ -384,7 +356,7 @@ describe('Peer class mutual authentication and certificate exchange', () => {
       bob.listenForCertificatesReceived(async (senderPublicKey, certificates) => {
         for (const cert of certificates) {
           // Decrypt Alice's certificate fields
-          const decryptedFields = await decryptCertificateFields(cert, walletB, walletA)
+          const decryptedFields = await cert.decryptFields(walletB)
           if (decryptedFields.membershipStatus) {
             console.log(`Bob received Alice's membership status: ${decryptedFields.membershipStatus}`)
             bobAcceptedMembershipStatus()
@@ -451,7 +423,7 @@ describe('Peer class mutual authentication and certificate exchange', () => {
     const waitForAliceToAcceptBobDL = new Promise<void>((resolve) => {
       alice.listenForCertificatesReceived(async (senderPublicKey, certificates) => {
         for (const cert of certificates) {
-          const decryptedFields = await decryptCertificateFields(cert, walletA, walletB)
+          const decryptedFields = await cert.decryptFields(walletA)
           if (decryptedFields.driversLicenseNumber) {
             console.log(`Alice received Bob's driver's license number: ${decryptedFields.driversLicenseNumber}`)
             aliceAcceptedBobDL()
@@ -464,7 +436,7 @@ describe('Peer class mutual authentication and certificate exchange', () => {
     const waitForBobToAcceptAliceDL = new Promise<void>((resolve) => {
       bob.listenForCertificatesReceived(async (senderPublicKey, certificates) => {
         for (const cert of certificates) {
-          const decryptedFields = await decryptCertificateFields(cert, walletB, walletA)
+          const decryptedFields = await cert.decryptFields(walletB)
           if (decryptedFields.driversLicenseNumber) {
             console.log(`Bob received Alice's driver's license number: ${decryptedFields.driversLicenseNumber}`)
             bobAcceptedAliceDL()
@@ -544,7 +516,7 @@ describe('Peer class mutual authentication and certificate exchange', () => {
     const waitForAlicePartialCert = new Promise<void>((resolve) => {
       alice.listenForCertificatesReceived(async (senderPublicKey, certificates) => {
         for (const cert of certificates) {
-          const decryptedFields = await decryptCertificateFields(cert, walletA, walletB)
+          const decryptedFields = await cert.decryptFields(walletA)
           if (decryptedFields.email || decryptedFields.name) {
             console.log(`Alice received Bob's certificate with fields: ${Object.keys(decryptedFields).join(', ')}`)
             aliceAcceptedPartialCert()
@@ -557,7 +529,7 @@ describe('Peer class mutual authentication and certificate exchange', () => {
     const waitForBobPartialCert = new Promise<void>((resolve) => {
       bob.listenForCertificatesReceived(async (senderPublicKey, certificates) => {
         for (const cert of certificates) {
-          const decryptedFields = await decryptCertificateFields(cert, walletB, walletA)
+          const decryptedFields = await cert.decryptFields(walletB)
           if (decryptedFields.email || decryptedFields.name) {
             console.log(`Bob received Alice's certificate with fields: ${Object.keys(decryptedFields).join(', ')}`)
             bobAcceptedPartialCert()

package/src/auth/certificates/Certificate.ts

@@ -43,9 +43,9 @@ export default class Certificate {
   revocationOutpoint: OutpointString
 
   /**
-   * All the fields present in the certificate, with field names as keys and field values as strings.
+   * All the fields present in the certificate, with field names as keys and encrypted field values as Base64 strings.
    */
-  fields: Record<CertificateFieldNameUnder50Bytes, string>
+  fields: Record<CertificateFieldNameUnder50Bytes, Base64String>
 
   /**
    * Certificate signature by the certifier's private key, DER encoded hex string.
@@ -258,7 +258,7 @@ 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(serialNumber: string, fieldName: string): { protocolID: WalletProtocol, keyID: string } {
+  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

@@ -12,6 +12,11 @@ import {
 } 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 +61,42 @@ 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 {WalletInterface} 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: WalletInterface,
+    certifierOrSubject: WalletCounterparty,
+    fields: Record<CertificateFieldNameUnder50Bytes, string>
+  ): 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
+      })
+      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
     }
   }
 
@@ -107,37 +116,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: WalletInterface,
+    certifier: WalletCounterparty,
+    verifier: WalletCounterparty,
+    fields: Record<CertificateFieldNameUnder50Bytes, Base64String>,
+    fieldsToReveal: string[],
+    masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>,
+    serialNumber: Base64String,
+    originator?: string): 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)
 
@@ -175,27 +179,21 @@ export class MasterCertificate extends Certificate {
     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 +205,78 @@ 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 {WalletInterface} 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: WalletInterface,
+    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: WalletInterface,
+    masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>,
+    fieldName: Base64String,
+    fieldValue: Base64String,
+    counterparty: WalletCounterparty
+  ): 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 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
+  WalletInterface
 } 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)
@@ -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
         })