@bsv/sdk 1.3.9 → 1.3.10

package/docs/auth.md

@@ -1129,13 +1129,13 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ### Function: createNonce
 
-Creates a nonce derived from a privateKey
+Creates a nonce derived from a wallet
 
 ```ts
-export async function createNonce(wallet: WalletInterface): Promise<string> 
+export async function createNonce(wallet: WalletInterface, counterparty: WalletCounterparty = "self"): Promise<string> 
 ```
 
-See also: [WalletInterface](#interface-walletinterface)
+See also: [WalletCounterparty](#type-walletcounterparty), [WalletInterface](#interface-walletinterface)
 
 <details>
 
@@ -1145,6 +1145,11 @@ Returns
 
 A random nonce derived with a wallet
 
+Argument Details
+
++ **counterparty**
+  + The counterparty to the nonce creation. Defaults to 'self'.
+
 </details>
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
@@ -1155,10 +1160,10 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 Verifies a nonce derived from a wallet
 
 ```ts
-export async function verifyNonce(nonce: string, wallet: WalletInterface): Promise<boolean> 
+export async function verifyNonce(nonce: string, wallet: WalletInterface, counterparty: WalletCounterparty = "self"): Promise<boolean> 
 ```
 
-See also: [WalletInterface](#interface-walletinterface)
+See also: [WalletCounterparty](#type-walletcounterparty), [WalletInterface](#interface-walletinterface)
 
 <details>
 
@@ -1172,6 +1177,8 @@ Argument Details
 
 + **nonce**
   + A nonce to verify as a base64 string.
++ **counterparty**
+  + The counterparty to the nonce creation. Defaults to 'self'.
 
 </details>
 

package/package.json

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

package/src/auth/Peer.ts

@@ -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: WalletInterface,
     transport: Transport,
     certificatesToRequest?: RequestedCertificateSet,
@@ -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/utils/__tests/cryptononce.test.ts

@@ -1,16 +1,17 @@
-import { PrivateKey } from '../../../../dist/cjs/src/primitives/index.js'
-import { ProtoWallet } from '../../../../dist/cjs/src/wallet/index.js'
-import { Wallet } from '../../../../dist/cjs/src/wallet/Wallet.interfaces.js'
+import { PrivateKey, Random, Utils } from '../../../../dist/cjs/src/primitives/index.js'
+import { ProtoWallet } from '../../../../dist/cjs/src/wallet/ProtoWallet.js'
+import { WalletInterface } from '../../../../dist/cjs/src/wallet/Wallet.interfaces.js'
 import { createNonce } from '../../../../dist/cjs/src/auth/utils/createNonce.js'
 import { verifyNonce } from '../../../../dist/cjs/src/auth/utils/verifyNonce.js'
+import { hash256 } from '../../../../dist/cjs/src/primitives/Hash.js'
 
 describe('createNonce', () => {
-  let mockWallet: Wallet
+  let mockWallet: WalletInterface
 
   beforeEach(() => {
     mockWallet = {
       createHmac: jest.fn().mockResolvedValue({ hmac: new Uint8Array(16) }),
-    } as unknown as Wallet
+    } as unknown as WalletInterface
   })
 
   afterEach(() => {
@@ -31,13 +32,13 @@ describe('createNonce', () => {
 })
 
 describe('verifyNonce', () => {
-  let mockWallet: Wallet
+  let mockWallet: WalletInterface
 
   beforeEach(() => {
     mockWallet = {
       createHmac: jest.fn().mockResolvedValue({ hmac: new Uint8Array(16) }),
       verifyHmac: jest.fn().mockResolvedValue({ valid: true }),
-    } as unknown as Wallet
+    } as unknown as WalletInterface
   })
 
   afterEach(() => {
@@ -81,4 +82,38 @@ describe('verifyNonce', () => {
 
     expect(isValid).toEqual(true)
   })
+
+  it('SerialNumber use-case', async () => {
+    const clientWallet = new ProtoWallet(PrivateKey.fromRandom())
+    const serverWallet = new ProtoWallet(PrivateKey.fromRandom())
+
+    // Client creates a random nonce that the server can verify
+    const clientNonce = await createNonce(clientWallet, (await serverWallet.getPublicKey({ identityKey: true })).publicKey)
+    // The server verifies the client created the nonce provided
+    await verifyNonce(clientNonce, serverWallet, (await clientWallet.getPublicKey({ identityKey: true })).publicKey)
+    // Server creates a random nonce that the client can verify
+    const serverNonce = await createNonce(serverWallet, (await clientWallet.getPublicKey({ identityKey: true })).publicKey)
+    // The server compute a serial number from the client and server nonce
+    const { hmac: serialNumber } = await serverWallet.createHmac({
+      data: clientNonce + serverNonce,
+      protocolID: [2, 'certificate creation'],
+      keyID: serverNonce + clientNonce,
+      counterparty: (await clientWallet.getPublicKey({ identityKey: true })).publicKey
+    })
+
+    // Client verifies server's nonce
+    await verifyNonce(serverNonce, clientWallet, (await serverWallet.getPublicKey({ identityKey: true })).publicKey)
+
+    // Client verifies the server included their nonce
+    const { valid } = await clientWallet.verifyHmac({
+      hmac: serialNumber,
+      data: clientNonce + serverNonce,
+      protocolID: [2, 'certificate creation'],
+      keyID: serverNonce + clientNonce,
+      counterparty: (await serverWallet.getPublicKey({ identityKey: true })).publicKey,
+    })
+
+    console.log(Utils.toBase64(serialNumber))
+    expect(valid).toEqual(true)
+  })
 })

package/src/auth/utils/createNonce.ts

@@ -1,15 +1,21 @@
-import { Utils, Random, WalletInterface } from '../../../mod.js'
+import { Utils, Random, WalletInterface, WalletCounterparty } from '../../../mod.js'
 
 /**
- * Creates a nonce derived from a privateKey
+ * Creates a nonce derived from a wallet
  * @param wallet
+ * @param counterparty - The counterparty to the nonce creation. Defaults to 'self'.
  * @returns A random nonce derived with a wallet
  */
-export async function createNonce(wallet: WalletInterface): Promise<string> {
+export async function createNonce(wallet: WalletInterface, counterparty: WalletCounterparty = 'self'): Promise<string> {
   // Generate 16 random bytes for the first half of the data
   const firstHalf = Random(16)
   // Create an sha256 HMAC
-  const { hmac } = await wallet.createHmac({ protocolID: [2, 'server hmac'], keyID: Utils.toUTF8(firstHalf), data: firstHalf, counterparty: 'self' })
+  const { hmac } = await wallet.createHmac({
+    protocolID: [2, 'server hmac'],
+    keyID: Utils.toUTF8(firstHalf),
+    data: firstHalf,
+    counterparty
+  })
   // Concatenate firstHalf and secondHalf as the nonce bytes
   const nonceBytes = [...firstHalf, ...hmac]
   return Utils.toBase64(nonceBytes)

package/src/auth/utils/verifyNonce.ts

@@ -1,12 +1,13 @@
-import { Utils, WalletInterface } from '../../../mod.js'
+import { Utils, WalletCounterparty, WalletInterface } from '../../../mod.js'
 
 /**
  * Verifies a nonce derived from a wallet
  * @param nonce - A nonce to verify as a base64 string.
  * @param wallet
+ * @param counterparty - The counterparty to the nonce creation. Defaults to 'self'.
  * @returns The status of the validation
  */
-export async function verifyNonce(nonce: string, wallet: WalletInterface): Promise<boolean> {
+export async function verifyNonce(nonce: string, wallet: WalletInterface, counterparty: WalletCounterparty = 'self'): Promise<boolean> {
   // Convert nonce from base64 string to Uint8Array
   const buffer = Utils.toArray(nonce, 'base64')
 
@@ -20,7 +21,7 @@ export async function verifyNonce(nonce: string, wallet: WalletInterface): Promi
     hmac,
     protocolID: [2, 'server hmac'],
     keyID: Utils.toUTF8(data),
-    counterparty: 'self'
+    counterparty
   })
 
   return valid

package/src/overlay-tools/OverlayAdminTokenTemplate.ts

@@ -15,7 +15,7 @@ export default class OverlayAdminTokenTemplate implements ScriptTemplate {
      * @param script Locking script comprising a SHIP or SLAP token to decode
      * @returns Decoded SHIP or SLAP advertisement
      */
-  static decode(script: LockingScript): { protocol: 'SHIP' | 'SLAP', identityKey: string, domain: string, topicOrService: string } {
+  static decode (script: LockingScript): { protocol: 'SHIP' | 'SLAP', identityKey: string, domain: string, topicOrService: string } {
     const result = PushDrop.decode(script)
     if (result.fields.length < 4) {
       throw new Error('Invalid SHIP/SLAP advertisement!')
@@ -39,7 +39,7 @@ export default class OverlayAdminTokenTemplate implements ScriptTemplate {
      * Constructs a new Overlay Admin template instance
      * @param wallet Wallet to use for locking and unlocking
      */
-  constructor(wallet: WalletInterface) {
+  constructor (wallet: WalletInterface) {
     this.pushDrop = new PushDrop(wallet)
   }
 
@@ -50,7 +50,7 @@ export default class OverlayAdminTokenTemplate implements ScriptTemplate {
      * @param topicOrService Topic or service to advertise
      * @returns Locking script comprising the advertisement token
      */
-  async lock(protocol: 'SHIP' | 'SLAP', domain: string, topicOrService: string): Promise<LockingScript> {
+  async lock (protocol: 'SHIP' | 'SLAP', domain: string, topicOrService: string): Promise<LockingScript> {
     const { publicKey: identityKey } = await this.pushDrop.wallet.getPublicKey({ identityKey: true })
     return await this.pushDrop.lock(
       [
@@ -70,7 +70,7 @@ export default class OverlayAdminTokenTemplate implements ScriptTemplate {
      * @param protocol SHIP or SLAP, depending on the token to unlock
      * @returns Script unlocker capable of unlocking the advertisement token
      */
-  unlock(protocol: 'SHIP' | 'SLAP'): {
+  unlock (protocol: 'SHIP' | 'SLAP'): {
     sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>
     estimateLength: (tx: Transaction, inputIndex: number) => Promise<number>
   } {

package/src/wallet/ProtoWallet.ts

@@ -35,14 +35,14 @@ import {
 export class ProtoWallet {
   keyDeriver: KeyDeriverApi
 
-  constructor(rootKeyOrKeyDeriver: PrivateKey | 'anyone' | KeyDeriverApi) {
+  constructor (rootKeyOrKeyDeriver: PrivateKey | 'anyone' | KeyDeriverApi) {
     if (typeof (rootKeyOrKeyDeriver as KeyDeriver).identityKey !== 'string') {
       rootKeyOrKeyDeriver = new KeyDeriver(rootKeyOrKeyDeriver as PrivateKey | 'anyone')
     }
     this.keyDeriver = rootKeyOrKeyDeriver as KeyDeriver
   }
 
-  async getPublicKey(
+  async getPublicKey (
     args: GetPublicKeyArgs
   ): Promise<{ publicKey: PubKeyHex }> {
     if (args.identityKey) {
@@ -64,7 +64,7 @@ export class ProtoWallet {
     }
   }
 
-  async revealCounterpartyKeyLinkage(
+  async revealCounterpartyKeyLinkage (
     args: RevealCounterpartyKeyLinkageArgs
   ): Promise<RevealCounterpartyKeyLinkageResult> {
     const { publicKey: identityKey } = await this.getPublicKey({ identityKey: true })
@@ -98,7 +98,7 @@ export class ProtoWallet {
     }
   }
 
-  async revealSpecificKeyLinkage(
+  async revealSpecificKeyLinkage (
     args: RevealSpecificKeyLinkageArgs
   ): Promise<RevealSpecificKeyLinkageResult> {
     const { publicKey: identityKey } = await this.getPublicKey({ identityKey: true })
@@ -131,7 +131,7 @@ export class ProtoWallet {
     }
   }
 
-  async encrypt(
+  async encrypt (
     args: WalletEncryptArgs
   ): Promise<WalletEncryptResult> {
     const key = this.keyDeriver.deriveSymmetricKey(
@@ -142,7 +142,7 @@ export class ProtoWallet {
     return { ciphertext: key.encrypt(args.plaintext) as number[] }
   }
 
-  async decrypt(
+  async decrypt (
     args: WalletDecryptArgs
   ): Promise<WalletDecryptResult> {
     const key = this.keyDeriver.deriveSymmetricKey(
@@ -153,7 +153,7 @@ export class ProtoWallet {
     return { plaintext: key.decrypt(args.ciphertext) as number[] }
   }
 
-  async createHmac(
+  async createHmac (
     args: CreateHmacArgs
   ): Promise<CreateHmacResult> {
     const key = this.keyDeriver.deriveSymmetricKey(
@@ -164,7 +164,7 @@ export class ProtoWallet {
     return { hmac: Hash.sha256hmac(key.toArray(), args.data) }
   }
 
-  async verifyHmac(
+  async verifyHmac (
     args: VerifyHmacArgs
   ): Promise<VerifyHmacResult> {
     const key = this.keyDeriver.deriveSymmetricKey(
@@ -181,7 +181,7 @@ export class ProtoWallet {
     return { valid }
   }
 
-  async createSignature(
+  async createSignature (
     args: CreateSignatureArgs
   ): Promise<CreateSignatureResult> {
     if (!args.hashToDirectlySign && !args.data) {
@@ -196,7 +196,7 @@ export class ProtoWallet {
     return { signature: ECDSA.sign(new BigNumber(hash), key, true).toDER() as number[] }
   }
 
-  async verifySignature(
+  async verifySignature (
     args: VerifySignatureArgs
   ): Promise<VerifySignatureResult> {
     if (!args.hashToDirectlyVerify && !args.data) {