@bsv/wallet-toolbox 1.1.24 → 1.1.25

package/src/__tests/WalletPermissionsManager.encryption.test.ts

@@ -0,0 +1,407 @@
+import {
+  mockUnderlyingWallet,
+  MockedBSV_SDK
+} from './WalletPermissionsManager.fixtures'
+import { WalletPermissionsManager } from '../WalletPermissionsManager'
+import { jest } from '@jest/globals'
+
+jest.mock('@bsv/sdk', () => MockedBSV_SDK)
+
+describe('WalletPermissionsManager - Metadata Encryption & Decryption', () => {
+  let underlying: ReturnType<typeof mockUnderlyingWallet>
+
+  beforeEach(() => {
+    // Create a fresh underlying mock wallet before each test
+    underlying = mockUnderlyingWallet()
+  })
+
+  afterEach(() => {
+    jest.clearAllMocks()
+  })
+
+  describe('Unit Tests for metadata encryption helpers', () => {
+    it('should call underlying.encrypt() with the correct protocol and key when encryptWalletMetadata=true', async () => {
+      const manager = new WalletPermissionsManager(
+        underlying,
+        'admin.domain.com',
+        {
+          encryptWalletMetadata: true
+        }
+      )
+
+      const plaintext = 'Hello, world!'
+      await manager['maybeEncryptMetadata'](plaintext)
+
+      // We expect underlying.encrypt() to have been called exactly once
+      expect(underlying.encrypt).toHaveBeenCalledTimes(1)
+
+      // Check that the call was with the correct protocol ID and key
+      expect(underlying.encrypt).toHaveBeenCalledWith(
+        {
+          plaintext: expect.any(Array), // byte array version of 'Hello, world!'
+          protocolID: [2, 'admin metadata encryption'],
+          keyID: '1'
+        },
+        'admin.domain.com'
+      )
+    })
+
+    it('should NOT call underlying.encrypt() if encryptWalletMetadata=false', async () => {
+      const manager = new WalletPermissionsManager(
+        underlying,
+        'admin.domain.com',
+        {
+          encryptWalletMetadata: false
+        }
+      )
+
+      const plaintext = 'No encryption needed!'
+      const result = await manager['maybeEncryptMetadata'](plaintext)
+
+      expect(result).toBe(plaintext)
+      expect(underlying.encrypt).not.toHaveBeenCalled()
+    })
+
+    it('should call underlying.decrypt() with correct protocol and key, returning plaintext on success', async () => {
+      const manager = new WalletPermissionsManager(
+        underlying,
+        'admin.domain.com',
+        {
+          encryptWalletMetadata: true
+        }
+      )
+
+      // Underlying decrypt mock returns { plaintext: [42, 42] } by default
+      // which would become "**" if using our ASCII interpretation
+      ;(underlying.decrypt as any).mockResolvedValueOnce({
+        plaintext: [72, 105] // 'Hi'
+      })
+
+      const ciphertext = 'random-string-representing-ciphertext'
+      const result = await manager['maybeDecryptMetadata'](ciphertext)
+
+      // We expect underlying.decrypt() to have been called
+      expect(underlying.decrypt).toHaveBeenCalledTimes(1)
+      expect(underlying.decrypt).toHaveBeenCalledWith(
+        {
+          ciphertext: expect.any(Array), // byte array version of ciphertext
+          protocolID: [2, 'admin metadata encryption'],
+          keyID: '1'
+        },
+        'admin.domain.com'
+      )
+
+      // The manager returns the decrypted UTF-8 string
+      expect(result).toBe('Hi')
+    })
+
+    it('should fallback to original string if underlying.decrypt() fails', async () => {
+      const manager = new WalletPermissionsManager(
+        underlying,
+        'admin.domain.com',
+        {
+          encryptWalletMetadata: true
+        }
+      )
+
+      // Make underlying.decrypt() throw an error to simulate failure
+      ;(underlying.decrypt as any).mockImplementationOnce(() => {
+        throw new Error('Decryption error')
+      })
+
+      const ciphertext = 'this-was-not-valid-for-decryption'
+      const result = await manager['maybeDecryptMetadata'](ciphertext)
+
+      // The manager should return the original ciphertext if decryption throws
+      expect(result).toBe(ciphertext)
+    })
+  })
+
+  describe('Integration Tests for createAction + listActions (round-trip encryption)', () => {
+    it('should encrypt metadata fields in createAction when encryptWalletMetadata=true, then decrypt them in listActions', async () => {
+      const manager = new WalletPermissionsManager(
+        underlying,
+        'admin.domain.com',
+        {
+          encryptWalletMetadata: true
+        }
+      )
+      manager.bindCallback('onSpendingAuthorizationRequested', x => {
+        manager.grantPermission({ requestID: x.requestID, ephemeral: true })
+      })
+
+      // We prepare an action with multiple metadata fields
+      const actionDescription = 'User Action #1: Doing something important'
+      const inputDesc = 'Some input desc'
+      const outputDesc = 'Some output desc'
+      const customInstr = 'Some custom instructions'
+
+      // Our createAction call
+      await manager.createAction(
+        {
+          description: actionDescription,
+          inputs: [
+            {
+              outpoint: 'txid1.0',
+              unlockingScriptLength: 73,
+              inputDescription: inputDesc
+            }
+          ],
+          outputs: [
+            {
+              lockingScript: 'OP_RETURN 1234',
+              satoshis: 500,
+              outputDescription: outputDesc,
+              customInstructions: customInstr
+            }
+          ]
+        },
+        'nonadmin.com'
+      )
+
+      // 1) Confirm underlying.encrypt() was called for each field that is non-empty:
+      //    - description
+      //    - inputDescription
+      //    - outputDescription
+      //    - customInstructions
+      // (We can't be certain how many times exactly, but we can check that it was at least 4.)
+      expect(underlying.encrypt).toHaveBeenCalledTimes(4)
+
+      // 2) Now we simulate listing actions. We'll have the manager call underlying.listActions.
+      //    Our mock underlying wallet returns an empty array by default, so let's override it
+      //    to return the "encrypted" data that the manager gave it.
+      //    But the manager doesn't store that data in the underlying wallet mock automatically.
+      //    We'll just pretend that the wallet returns some data, and ensure the manager tries to decrypt it.
+      ;(underlying.listActions as any).mockResolvedValueOnce({
+        totalActions: 1,
+        actions: [
+          {
+            description: 'fake-encrypted-string-for-description',
+            inputs: [
+              {
+                outpoint: 'txid1.0',
+                inputDescription: 'fake-encrypted-string-for-inputDesc'
+              }
+            ],
+            outputs: [
+              {
+                lockingScript: 'OP_RETURN 1234',
+                satoshis: 500,
+                outputDescription: 'fake-encrypted-string-for-outputDesc',
+                customInstructions: 'fake-encrypted-string-for-customInstr'
+              }
+            ]
+          }
+        ]
+      })
+
+      // Also mock decrypt calls to simulate a correct round-trip
+      const decryptMock = underlying.decrypt as any
+      decryptMock.mockResolvedValueOnce({
+        plaintext: Array.from(actionDescription).map(c => c.charCodeAt(0))
+      })
+      decryptMock.mockResolvedValueOnce({
+        plaintext: Array.from(inputDesc).map(c => c.charCodeAt(0))
+      })
+      decryptMock.mockResolvedValueOnce({
+        plaintext: Array.from(outputDesc).map(c => c.charCodeAt(0))
+      })
+      decryptMock.mockResolvedValueOnce({
+        plaintext: Array.from(customInstr).map(c => c.charCodeAt(0))
+      })
+
+      const result = await (manager as any).listActions({}, 'nonadmin.com')
+
+      // We should get exactly 1 action
+      expect(result.actions.length).toBe(1)
+      const action = result.actions[0]
+
+      // The manager is expected to have decrypted each field
+      expect(action.description).toBe(actionDescription)
+      expect(action.inputs[0].inputDescription).toBe(inputDesc)
+      expect(action.outputs[0].outputDescription).toBe(outputDesc)
+      expect(action.outputs[0].customInstructions).toBe(customInstr)
+    })
+
+    it('should not encrypt metadata if encryptWalletMetadata=false, storing and retrieving plaintext', async () => {
+      const manager = new WalletPermissionsManager(
+        underlying,
+        'admin.domain.com',
+        {
+          encryptWalletMetadata: false
+        }
+      )
+      manager.bindCallback('onSpendingAuthorizationRequested', x => {
+        manager.grantPermission({ requestID: x.requestID, ephemeral: true })
+      })
+
+      const actionDescription = 'Plaintext action description'
+      const inputDesc = 'Plaintext input desc'
+      const outputDesc = 'Plaintext output desc'
+      const customInstr = 'Plaintext instructions'
+      await manager.createAction(
+        {
+          description: actionDescription,
+          inputs: [
+            {
+              outpoint: 'someTx.0',
+              unlockingScriptLength: 73,
+              inputDescription: inputDesc
+            }
+          ],
+          outputs: [
+            {
+              lockingScript: 'OP_RETURN ABCD',
+              satoshis: 123,
+              outputDescription: outputDesc,
+              customInstructions: customInstr
+            }
+          ]
+        },
+        'nonadmin.com'
+      )
+
+      // Because encryption is disabled, underlying.encrypt() is not called
+      expect(underlying.encrypt).not.toHaveBeenCalled()
+
+      // Simulate that the wallet actually stored them in plaintext and is returning them as-is
+      ;(underlying.listActions as any).mockResolvedValue({
+        totalActions: 1,
+        actions: [
+          {
+            description: actionDescription,
+            inputs: [
+              {
+                outpoint: 'someTx.0',
+                inputDescription: inputDesc
+              }
+            ],
+            outputs: [
+              {
+                lockingScript: 'OP_RETURN ABCD',
+                satoshis: 123,
+                outputDescription: outputDesc,
+                customInstructions: customInstr
+              }
+            ]
+          }
+        ]
+      })
+
+      // Decrypt is still called, because we try to decrypt regardless of whether encryption is enabled.
+      // This allows us to disable it on a wallet that had it in the past. The result is that when not encrypted,
+      // the plaintext is returned if decryption fails. If it was encrypted from metadata encryption being enabled in
+      // the past (even when not enabled now), we will still decrypt and see the correct plaintext rather than garbage.
+      // To simulate, we make decryption pass through.
+      underlying.decrypt.mockImplementation(x => x)
+      const listResult = await (manager as any).listActions({}, 'nonadmin.com')
+      expect(underlying.decrypt).toHaveBeenCalledTimes(4)
+
+      // Confirm the returned data is the same as originally provided (plaintext)
+      const [first] = listResult.actions
+      expect(first.description).toBe(actionDescription)
+      expect(first.inputs[0].inputDescription).toBe(inputDesc)
+      expect(first.outputs[0].outputDescription).toBe(outputDesc)
+      expect(first.outputs[0].customInstructions).toBe(customInstr)
+    })
+  })
+
+  describe('Integration Test for listOutputs decryption', () => {
+    it('should decrypt customInstructions in listOutputs if encryptWalletMetadata=true', async () => {
+      const manager = new WalletPermissionsManager(
+        underlying,
+        'admin.domain.com',
+        {
+          encryptWalletMetadata: true
+        }
+      )
+      manager.bindCallback('onBasketAccessRequested', x => {
+        manager.grantPermission({ requestID: x.requestID, ephemeral: true })
+      })
+
+      // Suppose we have an output with custom instructions that was stored encrypted
+      ;(underlying.listOutputs as any).mockResolvedValue({
+        totalOutputs: 1,
+        outputs: [
+          {
+            outpoint: 'fakeTxid.0',
+            satoshis: 999,
+            lockingScript: 'OP_RETURN something',
+            basket: 'some-basket',
+            customInstructions: 'fake-encrypted-instructions-string'
+          }
+        ]
+      })
+
+      const originalInstr = 'Please do not reveal this data.'
+      // We'll mock decrypt() to interpret 'fake-encrypted-instructions-string' as a success
+      ;(underlying.decrypt as any).mockResolvedValueOnce({
+        plaintext: Array.from(originalInstr).map(ch => ch.charCodeAt(0))
+      })
+
+      const outputsResult = await manager.listOutputs(
+        {
+          basket: 'some-basket'
+        },
+        'some-origin.com'
+      )
+
+      expect(outputsResult.outputs.length).toBe(1)
+      expect(outputsResult.outputs[0].customInstructions).toBe(originalInstr)
+
+      // Confirm we tried to decrypt
+      expect(underlying.decrypt).toHaveBeenCalledTimes(1)
+      expect(underlying.decrypt).toHaveBeenCalledWith(
+        {
+          ciphertext: expect.any(Array),
+          protocolID: [2, 'admin metadata encryption'],
+          keyID: '1'
+        },
+        'admin.domain.com'
+      )
+    })
+
+    it('should fallback to the original ciphertext if decrypt fails in listOutputs', async () => {
+      const manager = new WalletPermissionsManager(
+        underlying,
+        'admin.domain.com',
+        {
+          encryptWalletMetadata: true
+        }
+      )
+      manager.bindCallback('onBasketAccessRequested', x => {
+        manager.grantPermission({ requestID: x.requestID, ephemeral: true })
+      })
+      ;(underlying.listOutputs as any).mockResolvedValue({
+        totalOutputs: 1,
+        outputs: [
+          {
+            outpoint: 'fakeTxid.1',
+            satoshis: 500,
+            lockingScript: 'OP_RETURN something',
+            basket: 'some-basket',
+            customInstructions: 'bad-ciphertext-of-some-kind'
+          }
+        ]
+      })
+
+      // Force an error from decrypt
+      ;(underlying.decrypt as any).mockImplementationOnce(() => {
+        throw new Error('Failed to decrypt')
+      })
+
+      const outputsResult = await manager.listOutputs(
+        {
+          basket: 'some-basket'
+        },
+        'some-origin.com'
+      )
+
+      expect(outputsResult.outputs.length).toBe(1)
+      // Should fall back to the original 'bad-ciphertext-of-some-kind'
+      expect(outputsResult.outputs[0].customInstructions).toBe(
+        'bad-ciphertext-of-some-kind'
+      )
+    })
+  })
+})

package/src/__tests/WalletPermissionsManager.fixtures.ts

@@ -0,0 +1,283 @@
+/**
+ * A permissions manager testing mock/stub file for:
+ *  1) The `@bsv/sdk` library: Transaction, LockingScript, PushDrop, Utils, Random, etc.
+ *  2) A BRC-100 `WalletInterface` (the underlying wallet).
+ *
+ * This file bypasses real validation/logic in `@bsv/sdk`, returning placeholders and
+ * stubs to prevent test-time errors such as "Invalid Atomic BEEF prefix."
+ */
+
+/* ---------------------------------------------------------------------------
+ * 1) Partial Mocks for @bsv/sdk
+ * -------------------------------------------------------------------------*/
+
+/**
+ * A minimal mock for `Transaction` that won't throw "Invalid Atomic BEEF prefix."
+ * We override the static methods so they do not do real parsing/validation.
+ */
+export class MockTransaction {
+  public inputs: any[] = [{}]
+  public outputs: any[] = []
+  public fee: number = 0
+
+  constructor() {}
+  static fromAtomicBEEF() {
+    // Mocked below
+  }
+
+  static fromBEEF(beef: number[]): MockTransaction {
+    // Same approach as above
+    return new MockTransaction()
+  }
+
+  getFee(): number {
+    return this.fee
+  }
+}
+
+;(MockTransaction as any).fromAtomicBEEF = jest.fn(() => {
+  // We skip real validation, returning a MockTransaction with minimal structure.
+  const tx = new MockTransaction()
+  return tx
+})
+
+/**
+ * Mocks for `LockingScript`. If your code calls e.g. LockingScript.fromHex, we can just
+ * store the hex and do nothing else.
+ */
+export class MockLockingScript {
+  hex: string
+  constructor(hex: string) {
+    this.hex = hex
+  }
+  public toHex(): string {
+    return this.hex
+  }
+  static fromHex(hex: string): MockLockingScript {
+    return new MockLockingScript(hex)
+  }
+}
+
+/**
+ * We stub out all methods: `decode()`, `lock()`, `unlock()`.
+ */
+export class MockPushDrop {
+  // Typically we might store the wallet reference, but we can skip for now.
+  constructor() {
+    //
+  }
+
+  // Decodes a LockingScript into some {fields: number[][], protocol...} or undefined
+  static decode(script: MockLockingScript): { fields: number[][] } | undefined {
+    // If you rely on a real format, parse or store a pattern.
+    // For now, returning a minimal stub: empty fields
+    if (!script || !script.hex) return undefined
+    if (script.hex.includes('some script')) {
+      // When needed, return some fields
+      return {
+        fields: [
+          [],
+          [],
+          [],
+          [],
+          [],
+          [],
+          [] // 7 fields should always be enough...
+        ]
+      }
+    }
+    // Just pretend we always decode to a single empty field array
+    return { fields: [] }
+  }
+
+  lock(
+    fields: number[][],
+    protocolID: [number, string],
+    keyID: string,
+    counterparty: string,
+    singleSignature: boolean,
+    anyoneCanPay: boolean
+  ): MockLockingScript {
+    return new MockLockingScript('deadbeef')
+  }
+
+  unlock(
+    protocolID: [number, string],
+    keyID: string,
+    counterparty: string,
+    sighashType: string,
+    enforceReplayProtection: boolean,
+    sigSize: number,
+    lockingScript: MockLockingScript
+  ): {
+    sign: (tx: MockTransaction, vin: number) => Promise<MockLockingScript>
+  } {
+    // In real usage, it would handle signature logic. We'll return a minimal stub.
+    return {
+      sign: async (tx: MockTransaction, vin: number) => {
+        // produce a minimal unlocking script
+        return new MockLockingScript('mockUnlockingScript')
+      }
+    }
+  }
+}
+
+/**
+ * Mocks for Utils, e.g. toHex, toUTF8, fromUTF8, etc.
+ * We can provide minimal stubs that won't break your code.
+ */
+export const MockUtils = {
+  toHex: (data: number[]) => {
+    // Converts an array of numbers to a hexadecimal string.
+    return data.map(num => num.toString(16).padStart(2, '0')).join('')
+  },
+
+  toArray: (str: string, encoding = 'utf8') => {
+    // Converts a string to an array of numbers based on the encoding.
+    if (encoding === 'hex') {
+      const arr: number[] = []
+      for (let i = 0; i < str.length; i += 2) {
+        arr.push(parseInt(str.substr(i, 2), 16))
+      }
+      return arr
+    } else if (encoding === 'base64') {
+      const binaryStr = atob(str)
+      return Array.from(binaryStr, char => char.charCodeAt(0))
+    } else if (encoding === 'utf8') {
+      return Array.from(str, char => char.charCodeAt(0))
+    } else {
+      throw new Error('Unsupported encoding: ' + encoding)
+    }
+  },
+
+  toUTF8: (arr: number[]) => {
+    // Converts an array of numbers to a UTF-8 string.
+    return String.fromCharCode(...arr)
+  }
+}
+
+/**
+ * Mocks for Random
+ */
+export const MockRandom = (size: number): number[] => {
+  return [...require('crypto').randomBytes(size)]
+}
+
+/**
+ * Overriding the real classes with our mocks.
+ */
+export const MockedBSV_SDK = {
+  Transaction: MockTransaction,
+  LockingScript: MockLockingScript,
+  PushDrop: MockPushDrop,
+  Utils: MockUtils,
+  Random: MockRandom
+}
+
+/* ---------------------------------------------------------------------------
+ * 2) A full mock for the BRC-100 WalletInterface
+ * -------------------------------------------------------------------------*/
+
+/**
+ * A helper function returning a Jest-mocked `WalletInterface`.
+ * This ensures all required methods exist and return plausible values.
+ *
+ * - By default, `createAction` returns a signableTransaction with empty arrays,
+ *   so that the manager can call `Transaction.fromAtomicBEEF([])` without throwing.
+ * - You can override or chain .mockResolvedValueOnce(...) inside individual tests
+ *   if you want more specific behavior in certain test steps.
+ */
+export function mockUnderlyingWallet(): jest.Mocked<any> {
+  return {
+    getPublicKey: jest.fn().mockResolvedValue({ publicKey: '029999...' }),
+    revealCounterpartyKeyLinkage: jest.fn().mockResolvedValue({
+      encryptedLinkage: [1, 2, 3],
+      encryptedLinkageProof: [4, 5, 6],
+      prover: '02abcdef...',
+      verifier: '02cccccc...',
+      counterparty: '02bbbbbb...',
+      revelationTime: new Date().toISOString()
+    }),
+    revealSpecificKeyLinkage: jest.fn().mockResolvedValue({
+      encryptedLinkage: [1, 2, 3],
+      encryptedLinkageProof: [4, 5, 6],
+      prover: '02abcdef...',
+      verifier: '02cccccc...',
+      counterparty: '02bbbbbb...',
+      protocolID: [1, 'test-protocol'],
+      keyID: 'testKey',
+      proofType: 1
+    }),
+    encrypt: jest.fn().mockResolvedValue({ ciphertext: [42, 42, 42] }),
+    decrypt: jest.fn().mockResolvedValue({ plaintext: [42, 42] }),
+    createHmac: jest.fn().mockResolvedValue({ hmac: [0xaa] }),
+    verifyHmac: jest.fn().mockResolvedValue({ valid: true }),
+    createSignature: jest.fn().mockResolvedValue({ signature: [0x30, 0x44] }),
+    verifySignature: jest.fn().mockResolvedValue({ valid: true }),
+
+    createAction: jest.fn(async x => {
+      if (x.options && x.options.signAndProcess === true) {
+        return {
+          tx: []
+        }
+      }
+      return {
+        signableTransaction: {
+          tx: [],
+          reference: 'mockReference'
+        }
+      }
+    }),
+    signAction: jest.fn().mockResolvedValue({
+      txid: 'fake-txid',
+      tx: []
+    }),
+    abortAction: jest.fn().mockResolvedValue({ aborted: true }),
+    listActions: jest.fn().mockResolvedValue({
+      totalActions: 0,
+      actions: []
+    }),
+    internalizeAction: jest.fn().mockResolvedValue({ accepted: true }),
+    listOutputs: jest.fn().mockResolvedValue({
+      totalOutputs: 0,
+      outputs: []
+    }),
+    relinquishOutput: jest.fn().mockResolvedValue({ relinquished: true }),
+
+    acquireCertificate: jest.fn().mockResolvedValue({
+      type: 'some-cert-type',
+      subject: '02aaaaaaaaaa...',
+      serialNumber: 'serial123',
+      certifier: '02ccccccccccc...',
+      revocationOutpoint: 'some.txid.1',
+      signature: 'deadbeef',
+      fields: { name: 'Alice', dob: '1990-01-01' }
+    }),
+    listCertificates: jest.fn().mockResolvedValue({
+      totalCertificates: 0,
+      certificates: []
+    }),
+    proveCertificate: jest.fn().mockResolvedValue({
+      keyringForVerifier: {},
+      certificate: undefined,
+      verifier: undefined
+    }),
+    relinquishCertificate: jest.fn().mockResolvedValue({ relinquished: true }),
+    discoverByIdentityKey: jest.fn().mockResolvedValue({
+      totalCertificates: 0,
+      certificates: []
+    }),
+    discoverByAttributes: jest.fn().mockResolvedValue({
+      totalCertificates: 0,
+      certificates: []
+    }),
+    isAuthenticated: jest.fn().mockResolvedValue({ authenticated: true }),
+    waitForAuthentication: jest.fn().mockResolvedValue({ authenticated: true }),
+    getHeight: jest.fn().mockResolvedValue({ height: 777777 }),
+    getHeaderForHeight: jest.fn().mockResolvedValue({
+      header: '000000000000abc...'
+    }),
+    getNetwork: jest.fn().mockResolvedValue({ network: 'testnet' }),
+    getVersion: jest.fn().mockResolvedValue({ version: 'vendor-1.0.0' })
+  }
+}