@bsv/sdk 1.3.31 → 1.3.33

package/docs/auth.md

@@ -334,6 +334,12 @@ Argument Details
 
 Helper function which retrieves the protocol ID and key ID for certificate field encryption.
 
+For master certificate creation, no serial number is provided because entropy is required
+from both the client and the certifier. In this case, the `keyID` is simply the `fieldName`.
+
+For VerifiableCertificates verifier keyring creation, both the serial number and field name are available,
+so the `keyID` is formed by concatenating the `serialNumber` and `fieldName`.
+
 ```ts
 static getCertificateFieldEncryptionDetails(fieldName: string, serialNumber?: string): {
     protocolID: WalletProtocol;
@@ -344,16 +350,17 @@ See also: [WalletProtocol](./wallet.md#type-walletprotocol)
 
 Returns
 
-An object containing the protocol ID and key ID:
+An object containing:
 - `protocolID` (WalletProtocol): The protocol ID for certificate field encryption.
-- `keyID` (string): A unique key identifier derived from the serial number and field name.
+- `keyID` (string): A unique key identifier. It is the `fieldName` if `serialNumber` is undefined,
+otherwise it is a combination of `serialNumber` and `fieldName`.
 
 Argument Details
 
-+ **serialNumber**
-  + The serial number of the certificate.
 + **fieldName**
   + The name of the field within the certificate to be encrypted.
++ **serialNumber**
+  + (Optional) The serial number of the certificate.
 
 #### Method sign
 
@@ -456,14 +463,14 @@ 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) 
-    static async createCertificateFields(creatorWallet: ProtoWallet, certifierOrSubject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>): Promise<CreateCertificateFieldsResult> 
-    static async createKeyringForVerifier(subjectWallet: ProtoWallet, certifier: WalletCounterparty, verifier: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, fieldsToReveal: string[], masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, serialNumber: Base64String): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
+    static async createCertificateFields(creatorWallet: ProtoWallet, certifierOrSubject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>, privileged?: boolean, privilegedReason?: string): Promise<CreateCertificateFieldsResult> 
+    static async createKeyringForVerifier(subjectWallet: ProtoWallet, certifier: WalletCounterparty, verifier: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, fieldsToReveal: string[], masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, serialNumber: Base64String, privileged?: boolean, privilegedReason?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
     static async issueCertificateForSubject(certifierWallet: ProtoWallet, subject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>, certificateType: string, getRevocationOutpoint = async (_serial: string): Promise<string> => {
         void _serial;
         return "Certificate revocation not tracked.";
     }, serialNumber?: string): Promise<MasterCertificate> 
-    static async decryptFields(subjectOrCertifierWallet: ProtoWallet, masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, counterparty: WalletCounterparty): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
-    static async decryptField(subjectOrCertifierWallet: ProtoWallet, masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, fieldName: Base64String, fieldValue: Base64String, counterparty: WalletCounterparty): Promise<{
+    static async decryptFields(subjectOrCertifierWallet: ProtoWallet, masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, counterparty: WalletCounterparty, privileged?: boolean, privilegedReason?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
+    static async decryptField(subjectOrCertifierWallet: ProtoWallet, masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, fieldName: Base64String, fieldValue: Base64String, counterparty: WalletCounterparty, privileged?: boolean, privilegedReason?: string): Promise<{
         fieldRevelationKey: number[];
         decryptedFieldValue: string;
     }> 
@@ -479,7 +486,7 @@ This method returns a master keyring tied to a specific certifier or subject who
 and sign off on the fields, along with the encrypted certificate fields.
 
 ```ts
-static async createCertificateFields(creatorWallet: ProtoWallet, certifierOrSubject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>): Promise<CreateCertificateFieldsResult> 
+static async createCertificateFields(creatorWallet: ProtoWallet, certifierOrSubject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>, privileged?: boolean, privilegedReason?: string): Promise<CreateCertificateFieldsResult> 
 ```
 See also: [CertificateFieldNameUnder50Bytes](./wallet.md#type-certificatefieldnameunder50bytes), [ProtoWallet](./wallet.md#class-protowallet), [WalletCounterparty](./wallet.md#type-walletcounterparty)
 
@@ -499,6 +506,10 @@ Argument Details
   + The certifier or subject who will validate the certificate fields.
 + **fields**
   + A record of certificate field names (under 50 bytes) mapped to their values.
++ **privileged**
+  + Whether this is a privileged request.
++ **privilegedReason**
+  + Reason provided for privileged access, required if this is a privileged operation.   *
 
 #### Method createKeyringForVerifier
 
@@ -508,7 +519,7 @@ for the verifier's identity key. The result is a keyring containing the keys nec
 for the verifier to access the designated fields.
 
 ```ts
-static async createKeyringForVerifier(subjectWallet: ProtoWallet, certifier: WalletCounterparty, verifier: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, fieldsToReveal: string[], masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, serialNumber: Base64String): 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, privileged?: boolean, privilegedReason?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
 ```
 See also: [Base64String](./wallet.md#type-base64string), [CertificateFieldNameUnder50Bytes](./wallet.md#type-certificatefieldnameunder50bytes), [ProtoWallet](./wallet.md#class-protowallet), [WalletCounterparty](./wallet.md#type-walletcounterparty)
 
@@ -526,6 +537,10 @@ Argument Details
   + An array of field names to be revealed to the verifier. Must be a subset of the certificate's fields.
 + **originator**
   + Optional originator identifier, used if additional context is needed for decryption and encryption operations.
++ **privileged**
+  + Whether this is a privileged request.
++ **privilegedReason**
+  + Reason provided for privileged access, required if this is a privileged operation.   *
 
 Throws
 
@@ -545,7 +560,7 @@ The counterparty used for decryption depends on how the certificate fields were
 - Otherwise, the counterparty should always be the other party involved in the certificate issuance process (the subject or certifier).
 
 ```ts
-static async decryptFields(subjectOrCertifierWallet: ProtoWallet, masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, counterparty: WalletCounterparty): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
+static async decryptFields(subjectOrCertifierWallet: ProtoWallet, masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, counterparty: WalletCounterparty, privileged?: boolean, privilegedReason?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
 ```
 See also: [Base64String](./wallet.md#type-base64string), [CertificateFieldNameUnder50Bytes](./wallet.md#type-certificatefieldnameunder50bytes), [ProtoWallet](./wallet.md#class-protowallet), [WalletCounterparty](./wallet.md#type-walletcounterparty)
 
@@ -563,6 +578,10 @@ Argument Details
   + 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'.
++ **privileged**
+  + Whether this is a privileged request.
++ **privilegedReason**
+  + Reason provided for privileged access, required if this is a privileged operation.
 
 Throws
 
@@ -1087,7 +1106,7 @@ export class VerifiableCertificate extends Certificate {
     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: ProtoWallet): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
+    async decryptFields(verifierWallet: ProtoWallet, privileged?: boolean, privilegedReason?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
 }
 ```
 
@@ -1098,7 +1117,7 @@ See also: [Base64String](./wallet.md#type-base64string), [Certificate](./auth.md
 Decrypts selectively revealed certificate fields using the provided keyring and verifier wallet
 
 ```ts
-async decryptFields(verifierWallet: ProtoWallet): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
+async decryptFields(verifierWallet: ProtoWallet, privileged?: boolean, privilegedReason?: string): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
 ```
 See also: [CertificateFieldNameUnder50Bytes](./wallet.md#type-certificatefieldnameunder50bytes), [ProtoWallet](./wallet.md#class-protowallet)
 
@@ -1110,6 +1129,10 @@ Argument Details
 
 + **verifierWallet**
   + The wallet instance of the certificate's verifier, used to decrypt field keys.
++ **privileged**
+  + Whether this is a privileged request.
++ **privilegedReason**
+  + Reason provided for privileged access, required if this is a privileged operation.
 
 Throws
 

package/package.json

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

package/src/auth/certificates/Certificate.ts

@@ -258,11 +258,18 @@ export default class Certificate {
   /**
    * Helper function which retrieves the protocol ID and key ID for certificate field encryption.
    *
-   * @param serialNumber - The serial number of the certificate.
+   * For master certificate creation, no serial number is provided because entropy is required
+   * from both the client and the certifier. In this case, the `keyID` is simply the `fieldName`.
+   *
+   * For VerifiableCertificates verifier keyring creation, both the serial number and field name are available,
+   * so the `keyID` is formed by concatenating the `serialNumber` and `fieldName`.
+   *
    * @param fieldName - The name of the field within the certificate to be encrypted.
-   * @returns An object containing the protocol ID and key ID:
+   * @param serialNumber - (Optional) The serial number of the certificate.
+   * @returns An object containing:
    *   - `protocolID` (WalletProtocol): The protocol ID for certificate field encryption.
-   *   - `keyID` (string): A unique key identifier derived from the serial number and field name.
+   *   - `keyID` (string): A unique key identifier. It is the `fieldName` if `serialNumber` is undefined,
+   *     otherwise it is a combination of `serialNumber` and `fieldName`.
    */
   static getCertificateFieldEncryptionDetails(
     fieldName: string,
@@ -270,7 +277,7 @@ export default class Certificate {
   ): { protocolID: WalletProtocol, keyID: string } {
     return {
       protocolID: [2, 'certificate field encryption'],
-      keyID: `${serialNumber ?? 'unknown'} ${fieldName}`
+      keyID: serialNumber ? `${serialNumber} ${fieldName}` : fieldName
     }
   }
 }

package/src/auth/certificates/MasterCertificate.ts

@@ -76,6 +76,8 @@ export class MasterCertificate extends Certificate {
    * @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.
+   * @param {BooleanDefaultFalse} [privileged] - Whether this is a privileged request.
+   * @param {DescriptionString5to50Bytes} [privilegedReason] - Reason provided for privileged access, required if this is a privileged operation.   * 
    * @returns {Promise<CreateCertificateFieldsResult>} A promise resolving to an object containing:
    *   - `certificateFields` {Record<CertificateFieldNameUnder50Bytes, Base64String>}:
    *     The encrypted certificate fields.
@@ -85,7 +87,9 @@ export class MasterCertificate extends Certificate {
   static async createCertificateFields(
     creatorWallet: ProtoWallet,
     certifierOrSubject: WalletCounterparty,
-    fields: Record<CertificateFieldNameUnder50Bytes, string>
+    fields: Record<CertificateFieldNameUnder50Bytes, string>,
+    privileged?: boolean,
+    privilegedReason?: string
   ): Promise<CreateCertificateFieldsResult> {
     const certificateFields: Record<
       CertificateFieldNameUnder50Bytes,
@@ -109,7 +113,9 @@ export class MasterCertificate extends Certificate {
           {
             plaintext: fieldSymmetricKey.toArray(),
             ...Certificate.getCertificateFieldEncryptionDetails(fieldName), // Only fieldName used on MasterCertificate
-            counterparty: certifierOrSubject
+            counterparty: certifierOrSubject,
+            privileged,
+            privilegedReason
           }
         )
       masterKeyring[fieldName] = Utils.toBase64(encryptedFieldRevelationKey)
@@ -132,6 +138,8 @@ export class MasterCertificate extends Certificate {
    * @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<Record<CertificateFieldNameUnder50Bytes, string>>} - A keyring mapping field names to encrypted field revelation keys, allowing the verifier to decrypt specified fields.
+   * @param {BooleanDefaultFalse} [privileged] - Whether this is a privileged request.
+   * @param {DescriptionString5to50Bytes} [privilegedReason] - Reason provided for privileged access, required if this is a privileged operation.   * 
    * @throws {Error} Throws an error if:
    *   - fieldsToReveal is not an array of strings.
    *   - A field in `fieldsToReveal` does not exist in the certificate.
@@ -144,7 +152,9 @@ export class MasterCertificate extends Certificate {
     fields: Record<CertificateFieldNameUnder50Bytes, Base64String>,
     fieldsToReveal: string[],
     masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>,
-    serialNumber: Base64String
+    serialNumber: Base64String,
+    privileged?: boolean,
+    privilegedReason?: string
   ): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
     if (!Array.isArray(fieldsToReveal)) {
       throw new Error('fieldsToReveal must be an array of strings')
@@ -165,7 +175,9 @@ export class MasterCertificate extends Certificate {
           masterKeyring,
           fieldName,
           fields[fieldName],
-          certifier
+          certifier,
+          privileged,
+          privilegedReason
         )
       ).fieldRevelationKey
 
@@ -178,7 +190,9 @@ export class MasterCertificate extends Certificate {
               fieldName,
               serialNumber
             ),
-            counterparty: verifier
+            counterparty: verifier,
+            privileged,
+            privilegedReason
           }
         )
 
@@ -220,22 +234,22 @@ export class MasterCertificate extends Certificate {
       void _serial // Explicitly acknowledge unused parameter
       return 'Certificate revocation not tracked.'
     },
-    serialNumber?: string // ✅ Optional parameter
+    serialNumber?: string
   ): Promise<MasterCertificate> {
     // 1. Generate a random serialNumber if not provided
-    const finalSerialNumber = serialNumber ?? Utils.toBase64(Random(32)) // ✅ Explicit nullish check
+    const finalSerialNumber = 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
-    const revocationOutpoint = await getRevocationOutpoint(finalSerialNumber) // ✅ Use `finalSerialNumber`
+    const revocationOutpoint = await getRevocationOutpoint(finalSerialNumber)
 
     // 4. Create new MasterCertificate instance
     const certificate = new MasterCertificate(
       certificateType,
-      finalSerialNumber, // ✅ Use `finalSerialNumber`
+      finalSerialNumber,
       subject,
       (await certifierWallet.getPublicKey({ identityKey: true })).publicKey,
       revocationOutpoint,
@@ -261,6 +275,8 @@ export class MasterCertificate extends Certificate {
    * @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'.
+   * @param {BooleanDefaultFalse} [privileged] - Whether this is a privileged request.
+   * @param {DescriptionString5to50Bytes} [privilegedReason] - Reason provided for privileged access, required if this is a privileged operation.
    * @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.
@@ -269,7 +285,9 @@ export class MasterCertificate extends Certificate {
     subjectOrCertifierWallet: ProtoWallet,
     masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>,
     fields: Record<CertificateFieldNameUnder50Bytes, Base64String>,
-    counterparty: WalletCounterparty
+    counterparty: WalletCounterparty,
+    privileged?: boolean,
+    privilegedReason?: string
   ): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
     if (masterKeyring == null || Object.keys(masterKeyring).length === 0) {
       throw new Error('A MasterCertificate must have a valid masterKeyring!')
@@ -285,7 +303,9 @@ export class MasterCertificate extends Certificate {
             masterKeyring,
             fieldName,
             fields[fieldName],
-            counterparty
+            counterparty,
+            privileged,
+            privilegedReason
           )
         ).decryptedFieldValue
       }
@@ -300,7 +320,9 @@ export class MasterCertificate extends Certificate {
     masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>,
     fieldName: Base64String,
     fieldValue: Base64String,
-    counterparty: WalletCounterparty
+    counterparty: WalletCounterparty,
+    privileged?: boolean,
+    privilegedReason?: string
   ): Promise<{ fieldRevelationKey: number[], decryptedFieldValue: string }> {
     if (masterKeyring == null || Object.keys(masterKeyring).length === 0) {
       throw new Error('A MasterCertificate must have a valid masterKeyring!')
@@ -311,7 +333,9 @@ export class MasterCertificate extends Certificate {
           {
             ciphertext: Utils.toArray(masterKeyring[fieldName], 'base64'),
             ...Certificate.getCertificateFieldEncryptionDetails(fieldName), // Only fieldName used on MasterCertificate
-            counterparty
+            counterparty,
+            privileged,
+            privilegedReason
           }
         )
 

package/src/auth/certificates/VerifiableCertificate.ts

@@ -54,10 +54,14 @@ export class VerifiableCertificate extends Certificate {
    * Decrypts selectively revealed certificate fields using the provided keyring and verifier wallet
    * @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.
+   * @param {BooleanDefaultFalse} [privileged] - Whether this is a privileged request.
+   * @param {DescriptionString5to50Bytes} [privilegedReason] - Reason provided for privileged access, required if this is a privileged operation.
    * @throws {Error} Throws an error if any of the decryption operations fail, with a message indicating the failure context.
    */
   async decryptFields(
-    verifierWallet: ProtoWallet
+    verifierWallet: ProtoWallet,
+    privileged?: boolean,
+    privilegedReason?: string
   ): Promise<Record<CertificateFieldNameUnder50Bytes, string>> {
     if (this.keyring == null || Object.keys(this.keyring).length === 0) { // ✅ Explicitly check null and empty object
       throw new Error(
@@ -75,7 +79,9 @@ export class VerifiableCertificate extends Certificate {
             fieldName,
             this.serialNumber
           ),
-          counterparty: this.subject
+          counterparty: this.subject,
+          privileged,
+          privilegedReason
         })
 
         const fieldValue = new SymmetricKey(fieldRevelationKey).decrypt(