@bsv/sdk 1.3.5 → 1.3.7

package/src/auth/Peer.ts

@@ -25,7 +25,7 @@ export class Peer {
   private callbackIdCounter: number = 0
 
   // Whether to auto-persist the session with the last-interacted-with peer
-  private autoPersistLastSession: boolean = true
+  private readonly autoPersistLastSession: boolean = true
 
   // Last-interacted-with peer identity key
   private lastInteractedWithPeer: string | undefined
@@ -39,7 +39,7 @@ export class Peer {
    * @param {SessionManager} [sessionManager] - Optional SessionManager to be used for managing peer sessions.
    * @param {boolean} [autoPersistLastSession] - Whether to auto-persist the session with the last-interacted-with peer. Defaults to true.
    */
-  constructor(
+  constructor (
     wallet: Wallet,
     transport: Transport,
     certificatesToRequest?: RequestedCertificateSet,
@@ -51,7 +51,7 @@ export class Peer {
     this.certificatesToRequest = certificatesToRequest ?? { certifiers: [], types: {} }
     this.transport.onData(this.handleIncomingMessage.bind(this))
     this.sessionManager = sessionManager || new SessionManager()
-    if (autoPersistLastSession === false) {
+    if (!autoPersistLastSession) {
       this.autoPersistLastSession = false
     } else {
       this.autoPersistLastSession = true
@@ -66,7 +66,7 @@ export class Peer {
    * @returns {Promise<void>}
    * @throws Will throw an error if the message fails to send.
    */
-  async toPeer(message: number[], identityKey?: string, maxWaitTime?: number): Promise<void> {
+  async toPeer (message: number[], identityKey?: string, maxWaitTime?: number): Promise<void> {
     if (this.autoPersistLastSession && this.lastInteractedWithPeer && typeof identityKey !== 'string') {
       identityKey = this.lastInteractedWithPeer
     }
@@ -111,7 +111,7 @@ export class Peer {
   * @returns {Promise<void>} Resolves if the certificate request message is successfully sent.
   * @throws Will throw an error if the peer session is not authenticated or if sending the request fails.
   */
-  async requestCertificates(certificatesToRequest: RequestedCertificateSet, identityKey?: string, maxWaitTime = 10000): Promise<void> {
+  async requestCertificates (certificatesToRequest: RequestedCertificateSet, identityKey?: string, maxWaitTime = 10000): Promise<void> {
     const peerSession = await this.getAuthenticatedSession(identityKey, maxWaitTime)
 
     // Prepare the general message
@@ -152,7 +152,7 @@ export class Peer {
    * @returns {Promise<PeerSession>} - A promise that resolves with an authenticated `PeerSession`.
    * @throws {Error} - Throws an error if the transport is not connected or if the handshake fails.
    */
-  async getAuthenticatedSession(identityKey?: string, maxWaitTime?: number): Promise<PeerSession> {
+  async getAuthenticatedSession (identityKey?: string, maxWaitTime?: number): Promise<PeerSession> {
     if (!this.transport) {
       throw new Error('Peer transport is not connected!')
     }
@@ -175,7 +175,7 @@ export class Peer {
    * @param {(senderPublicKey: string, payload: number[]) => void} callback - The function to call when a general message is received.
    * @returns {number} The ID of the callback listener.
    */
-  listenForGeneralMessages(callback: (senderPublicKey: string, payload: number[]) => void): number {
+  listenForGeneralMessages (callback: (senderPublicKey: string, payload: number[]) => void): number {
     const callbackID = this.callbackIdCounter++
     this.onGeneralMessageReceivedCallbacks.set(callbackID, callback)
     return callbackID
@@ -186,7 +186,7 @@ export class Peer {
    *
    * @param {number} callbackID - The ID of the callback to remove.
    */
-  stopListeningForGeneralMessages(callbackID: number): void {
+  stopListeningForGeneralMessages (callbackID: number): void {
     this.onGeneralMessageReceivedCallbacks.delete(callbackID)
   }
 
@@ -196,7 +196,7 @@ export class Peer {
    * @param {(certs: VerifiableCertificate[]) => void} callback - The function to call when certificates are received.
    * @returns {number} The ID of the callback listener.
    */
-  listenForCertificatesReceived(callback: (senderPublicKey: string, certs: VerifiableCertificate[]) => void): number {
+  listenForCertificatesReceived (callback: (senderPublicKey: string, certs: VerifiableCertificate[]) => void): number {
     const callbackID = this.callbackIdCounter++
     this.onCertificatesReceivedCallbacks.set(callbackID, callback)
     return callbackID
@@ -207,7 +207,7 @@ export class Peer {
    *
    * @param {number} callbackID - The ID of the certificates received callback to cancel.
    */
-  stopListeningForCertificatesReceived(callbackID: number): void {
+  stopListeningForCertificatesReceived (callbackID: number): void {
     this.onCertificatesReceivedCallbacks.delete(callbackID)
   }
 
@@ -217,7 +217,7 @@ export class Peer {
    * @param {(requestedCertificates: RequestedCertificateSet) => void} callback - The function to call when a certificate request is received
    * @returns {number} The ID of the callback listener.
    */
-  listenForCertificatesRequested(callback: (senderPublicKey: string, requestedCertificates: RequestedCertificateSet) => void): number {
+  listenForCertificatesRequested (callback: (senderPublicKey: string, requestedCertificates: RequestedCertificateSet) => void): number {
     const callbackID = this.callbackIdCounter++
     this.onCertificateRequestReceivedCallbacks.set(callbackID, callback)
     return callbackID
@@ -228,7 +228,7 @@ export class Peer {
    *
    * @param {number} callbackID - The ID of the requested certificates callback to cancel.
    */
-  stopListeningForCertificatesRequested(callbackID: number): void {
+  stopListeningForCertificatesRequested (callbackID: number): void {
     this.onCertificateRequestReceivedCallbacks.delete(callbackID)
   }
 
@@ -239,7 +239,7 @@ export class Peer {
    * @param {string} [identityKey] - The identity public key of the peer.
    * @returns {Promise<string>} A promise that resolves to the session nonce.
    */
-  private async initiateHandshake(identityKey?: string, maxWaitTime = 10000): Promise<string> {
+  private async initiateHandshake (identityKey?: string, maxWaitTime = 10000): Promise<string> {
     const sessionNonce = await createNonce(this.wallet) // Initial request nonce
     this.sessionManager.addSession({
       isAuthenticated: false,
@@ -265,7 +265,7 @@ export class Peer {
    * @param {string} sessionNonce - The session nonce created in the initial request.
    * @returns {Promise<string>} A promise that resolves with the session nonce when the initial response is received.
    */
-  private async waitForInitialResponse(sessionNonce: string, maxWaitTime = 10000): Promise<string> {
+  private async waitForInitialResponse (sessionNonce: string, maxWaitTime = 10000): Promise<string> {
     return await new Promise((resolve, reject) => {
       const callbackID = this.listenForInitialResponse(sessionNonce, (sessionNonce) => {
         clearTimeout(timeoutHandle)
@@ -288,7 +288,7 @@ export class Peer {
    * @param {(sessionNonce: string) => void} callback - The callback to invoke when the initial response is received.
    * @returns {number} The ID of the callback listener.
    */
-  private listenForInitialResponse(sessionNonce: string, callback: (sessionNonce: string) => void) {
+  private listenForInitialResponse (sessionNonce: string, callback: (sessionNonce: string) => void) {
     const callbackID = this.callbackIdCounter++
     this.onInitialResponseReceivedCallbacks.set(callbackID, { callback, sessionNonce })
     return callbackID
@@ -300,7 +300,7 @@ export class Peer {
    * @private
    * @param {number} callbackID - The ID of the callback to remove.
    */
-  private stopListeningForInitialResponses(callbackID: number) {
+  private stopListeningForInitialResponses (callbackID: number) {
     this.onInitialResponseReceivedCallbacks.delete(callbackID)
   }
 
@@ -310,7 +310,7 @@ export class Peer {
    * @param {AuthMessage} message - The incoming message to process.
    * @returns {Promise<void>}
    */
-  private async handleIncomingMessage(message: AuthMessage): Promise<void> {
+  private async handleIncomingMessage (message: AuthMessage): Promise<void> {
     if (!message.version || message.version !== AUTH_VERSION) {
       console.error(`Invalid message auth version! Received: ${message.version}, expected: ${AUTH_VERSION}`)
       return
@@ -343,7 +343,7 @@ export class Peer {
    * @param {AuthMessage} message - The incoming initial request message.
    * @returns {Promise<void>}
    */
-  async processInitialRequest(message: AuthMessage) {
+  async processInitialRequest (message: AuthMessage) {
     if (!message.identityKey || !message.initialNonce) {
       throw new Error('Missing required fields in initialResponse message.')
     }
@@ -406,7 +406,7 @@ export class Peer {
    * @returns {Promise<void>}
    * @throws Will throw an error if nonce verification or signature verification fails.
    */
-  private async processInitialResponse(message: AuthMessage) {
+  private async processInitialResponse (message: AuthMessage) {
     const validNonce = await verifyNonce(message.yourNonce, this.wallet)
     if (!validNonce) {
       throw new Error(`Initial response nonce verification failed from peer: ${message.identityKey}`)
@@ -478,7 +478,7 @@ export class Peer {
    * @param {AuthMessage} message - The certificate request message received from the peer.
    * @throws {Error} Throws an error if nonce verification fails, or the message signature is invalid.
    */
-  private async processCertificateRequest(message: AuthMessage) {
+  private async processCertificateRequest (message: AuthMessage) {
     const validNonce = await verifyNonce(message.yourNonce, this.wallet)
     if (!validNonce) {
       throw new Error(`Unable to verify nonce for certificate request message from: ${message.identityKey}`)
@@ -520,7 +520,7 @@ export class Peer {
    *
    * @throws {Error} Throws an error if the peer session could not be authenticated or if message signing fails.
    */
-  async sendCertificateResponse(
+  async sendCertificateResponse (
     verifierIdentityKey: string,
     certificates: VerifiableCertificate[]
   ) {
@@ -559,7 +559,7 @@ export class Peer {
    * @returns {Promise<void>}
    * @throws Will throw an error if nonce verification or signature verification fails.
    */
-  private async processCertificateResponse(
+  private async processCertificateResponse (
     message: AuthMessage
   ) {
     const validNonce = await verifyNonce(message.yourNonce, this.wallet)
@@ -597,7 +597,7 @@ export class Peer {
    * @returns {Promise<void>}
    * @throws Will throw an error if nonce verification or signature verification fails.
    */
-  private async processGeneralMessage(message: AuthMessage) {
+  private async processGeneralMessage (message: AuthMessage) {
     const validNonce = await verifyNonce(message.yourNonce, this.wallet)
     if (!validNonce) {
       throw new Error(`Unable to verify nonce for general message from: ${message.identityKey}`)

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

@@ -7,6 +7,7 @@ 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')
 
 /**
@@ -22,8 +23,7 @@ async function decryptCertificateFields(
       // Decrypt the per-field symmetric key
       const { plaintext: masterFieldKey } = await localWallet.decrypt({
         ciphertext: Utils.toArray(encryptedKey, 'base64'),
-        protocolID: [2, 'certificate field encryption'],
-        keyID: `${cert.serialNumber} ${fieldName}`,
+        ...Certificate.getCertificateFieldEncryptionDetails(cert.serialNumber, fieldName),
         counterparty: (await counterpartyWallet.getPublicKey({ identityKey: true })).publicKey,
       })
 
@@ -87,33 +87,26 @@ describe('Peer class mutual authentication and certificate exchange', () => {
   const aliceFields = { name: 'Alice', email: 'alice@example.com', libraryCardNumber: 'A123456' }
   const bobFields = { name: 'Bob', email: 'bob@example.com', libraryCardNumber: 'B654321' }
 
-  async function createMasterCertificate(wallet: Wallet, fields: Record<string, string>) {
-    const certificateFields: Record<string, string> = {}
-    const masterKeyring: Record<string, string> = {}
-
-    for (const fieldName in fields) {
-      const fieldSymmetricKey = SymmetricKey.fromRandom()
-      const encryptedFieldValue = fieldSymmetricKey.encrypt(Utils.toArray(fields[fieldName], 'utf8'))
-      certificateFields[fieldName] = Utils.toBase64(encryptedFieldValue as number[])
-
-      const encryptedFieldKey = await wallet.encrypt({
-        plaintext: fieldSymmetricKey.toArray(),
-        protocolID: [2, 'certificate field encryption'],
-        keyID: `${certificateSerialNumber} ${fieldName}`,
-        counterparty: 'self'
-      })
-      masterKeyring[fieldName] = Utils.toBase64(encryptedFieldKey.ciphertext)
-    }
+  async function createMasterCertificate(subjectWallet: Wallet, fields: Record<string, string>) {
+    const subjectPubKey = (await subjectWallet.getPublicKey({ identityKey: true })).publicKey
+    const certifierWallet = new ProtoWallet(certifierPrivateKey)
 
-    return new MasterCertificate(
+    // Issue a new MasterCertificate for the subject (e.g. Alice/Bob)
+    const masterCertificate = await MasterCertificate.issueCertificateForSubject(
+      certifierWallet,
+      subjectPubKey,
+      fields,
       certificateType,
-      certificateSerialNumber,
-      (await wallet.getPublicKey({ identityKey: true })).publicKey,
-      certifierPublicKey,
-      'revocationOutpoint',
-      certificateFields,
-      masterKeyring
+      async () => 'revocationOutpoint' // or any revocation outpoint logic you want
     )
+
+    // For test consistency, override the automatically generated serialNumber 
+    // with the globally used 'certificateSerialNumber' and re-sign:
+    // masterCertificate.signature = undefined
+    // masterCertificate.serialNumber = certificateSerialNumber
+    // await masterCertificate.sign(certifierWallet)
+
+    return masterCertificate
   }
 
   async function createVerifiableCertificate(
@@ -123,7 +116,6 @@ describe('Peer class mutual authentication and certificate exchange', () => {
     fieldsToReveal: string[]
   ): Promise<VerifiableCertificate> {
     const certifierWallet = new ProtoWallet(certifierPrivateKey)
-    await masterCertificate.sign(certifierWallet)
 
     const keyringForVerifier = await masterCertificate.createKeyringForVerifier(wallet, verifierIdentityKey, fieldsToReveal)
     return new VerifiableCertificate(

package/src/auth/certificates/Certificate.ts

@@ -1,13 +1,13 @@
 import {
   Utils,
-  Wallet,
   Base64String,
   PubKeyHex,
   HexString,
   OutpointString,
   CertificateFieldNameUnder50Bytes,
   ProtoWallet,
-  Signature
+  Signature,
+  WalletProtocol
 } from '../../../mod.js'
 
 /**
@@ -112,9 +112,12 @@ export default class Certificate {
     writer.writeVarIntNum(Number(outputIndex))
 
     // Write fields
-    const fieldEntries = Object.entries(this.fields)
-    writer.writeVarIntNum(fieldEntries.length)
-    for (const [fieldName, fieldValue] of fieldEntries) {
+    // Sort field names lexicographically
+    const fieldNames = Object.keys(this.fields).sort()
+    writer.writeVarIntNum(fieldNames.length)
+    for (const fieldName of fieldNames) {
+      const fieldValue = this.fields[fieldName]
+
       // Field name
       const fieldNameBytes = Utils.toArray(fieldName, 'utf8')
       writer.writeVarIntNum(fieldNameBytes.length)
@@ -225,16 +228,36 @@ export default class Certificate {
   /**
    * Signs the certificate using the provided certifier wallet.
    *
-   * @param {Wallet} certifier - The wallet representing the certifier.
+   * @param {Wallet} certifierWallet - The wallet representing the certifier.
    * @returns {Promise<void>}
    */
-  async sign(certifier: ProtoWallet): Promise<void> {
+  async sign(certifierWallet: ProtoWallet): Promise<void> {
+    if (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
+
     const preimage = this.toBinary(false) // Exclude the signature when signing
-    const { signature } = await certifier.createSignature({
+    const { signature } = await certifierWallet.createSignature({
       data: preimage,
       protocolID: [2, 'certificate signature'],
       keyID: `${this.type} ${this.serialNumber}`
     })
     this.signature = Utils.toHex(signature)
   }
+
+  /**
+   * Helper function which retrieves the protocol ID and key ID for certificate field encryption.
+   *
+   * @param serialNumber - The serial number of the certificate.
+   * @param fieldName - The name of the field within the certificate to be encrypted.
+   * @returns An object containing the protocol ID and key ID:
+   *   - `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 } {
+    return { protocolID: [2, 'certificate field encryption'], keyID: `${serialNumber} ${fieldName}` }
+  }
 }

package/src/auth/certificates/MasterCertificate.ts

@@ -6,8 +6,9 @@ import {
   HexString,
   OutpointString,
   PubKeyHex,
-  Wallet,
-  ProtoWallet
+  ProtoWallet,
+  Random,
+  WalletCounterparty
 } from '../../../mod.js'
 import Certificate from './Certificate.js'
 
@@ -25,10 +26,10 @@ export class MasterCertificate extends Certificate {
   declare subject: PubKeyHex
   declare certifier: PubKeyHex
   declare revocationOutpoint: OutpointString
-  declare fields: Record<CertificateFieldNameUnder50Bytes, string>
+  declare fields: Record<CertificateFieldNameUnder50Bytes, Base64String>
   declare signature?: HexString
 
-  masterKeyring: Record<CertificateFieldNameUnder50Bytes, string>
+  masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>
 
   constructor(
     type: Base64String,
@@ -36,30 +37,77 @@ export class MasterCertificate extends Certificate {
     subject: PubKeyHex,
     certifier: PubKeyHex,
     revocationOutpoint: OutpointString,
-    fields: Record<CertificateFieldNameUnder50Bytes, string>,
-    masterKeyring: Record<CertificateFieldNameUnder50Bytes, string>,
+    fields: Record<CertificateFieldNameUnder50Bytes, Base64String>,
+    masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>,
     signature?: HexString
   ) {
     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)) {
+      if (!masterKeyring[fieldName]) {
+        throw new Error(
+          `Master keyring must contain a value for every field. Missing key for field: "${fieldName}".`
+        )
+      }
+    }
+
     this.masterKeyring = masterKeyring
   }
 
   /**
-   * Creates a verifiable certificate structure for a specific verifier, allowing them access to specified fields.
-   * This method decrypts the master field keys for each field specified in `fieldsToReveal` and re-encrypts them
-   * for the verifier's identity key. The resulting certificate structure includes only the fields intended to be
-   * revealed and a verifier-specific keyring for field decryption.
+   * 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 {ProtoWallet} 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.
+   */
+  async decryptFields(subjectWallet: ProtoWallet): 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!')
+    }
+
+    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.')
+    }
+  }
+
+  /**
+   * Creates a keyring for a verifier, enabling them to decrypt specific certificate fields.
+   * This method decrypts the master field keys for the specified fields and re-encrypts them
+   * for the verifier's identity key. The result is a keyring containing the keys necessary
+   * for the verifier to access the designated fields.
    *
-   * @param {Wallet} subjectWallet - The wallet instance of the subject, used to decrypt and re-encrypt field keys.
-   * @param {string} verifierIdentityKey - The public identity key of the verifier who will receive access to the specified fields.
+   * @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.
-   * @returns {Promise<Object>} - A new certificate structure containing the original encrypted fields, the verifier-specific field decryption keyring, and essential certificate metadata.
+   * @returns {Promise<Record<CertificateFieldNameUnder50Bytes, string>>} - A keyring mapping field names to encrypted field revelation keys, allowing the verifier to decrypt specified fields.
    * @throws {Error} Throws an error if:
-   *   - fieldsToReveal is empty or a field in `fieldsToReveal` does not exist in the certificate.
+   *   - fieldsToReveal is not an array of strings.
+   *   - 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: ProtoWallet, verifierIdentityKey: string, fieldsToReveal: string[], originator?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
+  async createKeyringForVerifier(subjectWallet: ProtoWallet, verifier: WalletCounterparty, fieldsToReveal: string[], originator?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
     if (!Array.isArray(fieldsToReveal)) {
       throw new Error('fieldsToReveal must be an array of strings')
     }
@@ -70,16 +118,13 @@ export class MasterCertificate extends Certificate {
         throw new Error(`Fields to reveal must be a subset of the certificate fields. Missing the "${fieldName}" field.`)
       }
 
-      // Create a keyID
-      const keyID = `${this.serialNumber} ${fieldName}`
       const encryptedMasterFieldKey = this.masterKeyring[fieldName]
 
       // Decrypt the master field key
       const { plaintext: masterFieldKey } = await subjectWallet.decrypt({
         ciphertext: Utils.toArray(encryptedMasterFieldKey, 'base64'),
-        protocolID: [2, 'certificate field encryption'],
-        keyID,
-        counterparty: 'self'
+        ...Certificate.getCertificateFieldEncryptionDetails(this.serialNumber, fieldName),
+        counterparty: this.certifier
       }, originator)
 
       // Verify that derived key actually decrypts requested field
@@ -92,9 +137,8 @@ export class MasterCertificate extends Certificate {
       // Encrypt derived fieldRevelationKey for verifier
       const { ciphertext: encryptedFieldRevelationKey } = await subjectWallet.encrypt({
         plaintext: masterFieldKey,
-        protocolID: [2, 'certificate field encryption'],
-        keyID: `${this.serialNumber} ${fieldName}`,
-        counterparty: verifierIdentityKey
+        ...Certificate.getCertificateFieldEncryptionDetails(this.serialNumber, fieldName),
+        counterparty: verifier
       }, originator)
 
       // Add encryptedFieldRevelationKey to fieldRevelationKeyring
@@ -104,4 +148,71 @@ export class MasterCertificate extends Certificate {
     // Return the field revelation keyring which can be used to create a verifiable certificate for a verifier.
     return fieldRevelationKeyring
   }
+
+  /**
+   * 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 {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 - 
+   *   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: ProtoWallet,
+    subject: WalletCounterparty,
+    fields: Record<CertificateFieldNameUnder50Bytes, string>,
+    certificateType: string,
+    getRevocationOutpoint = async (
+      serialNumber: string
+    ): Promise<string> => { return 'Certificate revocation not tracked.' }
+  ): 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)
+    }
+
+    // 3. Obtain a revocation outpoint (ex. certifier can call wallet.createAction())
+    const revocationOutpoint = await getRevocationOutpoint(serialNumber)
+    // TODO: Validate revocation outpoint format
+
+    // 4. Create new MasterCertificate instance
+    const certificate = new MasterCertificate(
+      certificateType,
+      serialNumber,
+      subject,
+      (await certifierWallet.getPublicKey({ identityKey: true })).publicKey,
+      revocationOutpoint,
+      encryptedCertificateFields,
+      masterKeyringForSubject
+    )
+
+    // 5. Sign and return the new MasterCertificate certifying the subject.
+    await certificate.sign(certifierWallet)
+    return certificate
+  }
 }

package/src/auth/certificates/VerifiableCertificate.ts

@@ -6,7 +6,8 @@ import {
   HexString,
   OutpointString,
   PubKeyHex,
-  Wallet
+  Wallet,
+  WalletError
 } from '../../../mod.js'
 import Certificate from './Certificate.js'
 
@@ -43,7 +44,7 @@ export class VerifiableCertificate extends Certificate {
   }
 
   /**
-   * Decrypts certificate fields using the provided keyring and verifier wallet
+   * Decrypts selectively revealed certificate fields using the provided keyring and verifier wallet
    * @param {Wallet} 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.
@@ -53,12 +54,11 @@ export class VerifiableCertificate extends Certificate {
       throw new Error('A keyring is required to decrypt certificate fields for the verifier.')
     }
     try {
-      const decryptedFields = {}
+      const decryptedFields: Record<CertificateFieldNameUnder50Bytes, string> = {}
       for (const fieldName in this.keyring) {
         const { plaintext: fieldRevelationKey } = await verifierWallet.decrypt({
           ciphertext: Utils.toArray(this.keyring[fieldName], 'base64'),
-          protocolID: [2, 'certificate field encryption'],
-          keyID: `${this.serialNumber} ${fieldName}`,
+          ...Certificate.getCertificateFieldEncryptionDetails(this.serialNumber, fieldName),
           counterparty: this.subject
         })
 
@@ -67,7 +67,7 @@ export class VerifiableCertificate extends Certificate {
       }
       return decryptedFields
     } catch (error) {
-      throw new Error(`Failed to decrypt 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}`)
     }
   }
 }