@bsv/sdk 1.9.18 → 1.9.20

package/src/primitives/__tests/hex.test.ts

@@ -0,0 +1,57 @@
+/* eslint-env jest */
+
+import { assertValidHex, normalizeHex } from '../../primitives/hex'
+
+describe('hex utils', () => {
+  describe('assertValidHex', () => {
+    it('should not throw on valid hex strings', () => {
+      expect(() => assertValidHex('')).not.toThrow()          // empty is allowed
+      expect(() => assertValidHex('00')).not.toThrow()
+      expect(() => assertValidHex('abcdef')).not.toThrow()
+      expect(() => assertValidHex('ABCDEF')).not.toThrow()
+      expect(() => assertValidHex('1234567890')).not.toThrow()
+    })
+
+    it('should throw on non-hex characters', () => {
+      expect(() => assertValidHex('zz')).toThrow('Invalid hex string')
+      expect(() => assertValidHex('0x1234')).toThrow('Invalid hex string')
+      expect(() => assertValidHex('12 34')).toThrow('Invalid hex string')
+      expect(() => assertValidHex('g1')).toThrow('Invalid hex string')
+    })
+
+    // ❌ old behavior: empty string was considered invalid
+    // it('should throw on empty string', () => {
+    //   expect(() => assertValidHex('')).toThrow('Invalid hex string')
+    // })
+
+    it('should throw on undefined or null', () => {
+      expect(() => assertValidHex(undefined as any)).toThrow('Invalid hex string')
+      expect(() => assertValidHex(null as any)).toThrow('Invalid hex string')
+    })
+  })
+
+  describe('normalizeHex', () => {
+    it('should return lowercase hex', () => {
+      expect(normalizeHex('ABCD')).toBe('abcd')
+    })
+
+    it('should prepend 0 to odd-length hex strings', () => {
+      expect(normalizeHex('abc')).toBe('0abc')
+      expect(normalizeHex('f')).toBe('0f')
+    })
+
+    it('should leave even-length hex strings untouched (except lowercase)', () => {
+      expect(normalizeHex('AABB')).toBe('aabb')
+      expect(normalizeHex('001122')).toBe('001122')
+    })
+
+    it('should return empty string unchanged', () => {
+      expect(normalizeHex('')).toBe('')
+    })
+
+    it('should throw on invalid hex', () => {
+      expect(() => normalizeHex('xyz')).toThrow('Invalid hex string')
+      expect(() => normalizeHex('12 34')).toThrow('Invalid hex string')
+    })
+  })
+})

package/src/primitives/__tests/utils.test.ts

@@ -320,3 +320,42 @@ describe('verifyNotNull', () => {
     expect(() => verifyNotNull(undefined, 'Another custom error')).toThrow('Another custom error')
   })
 })
+
+describe('toUTF8 strict UTF-8 decoding (TOB-21)', () => {
+
+  it('replaces invalid 2-byte sequences with U+FFFD', () => {
+    // 0xC2 should expect a continuation byte 0x80–0xBF
+    const arr = [0xC2, 0x20]   // 0x20 is INVALID continuation
+    const str = toUTF8(arr)
+    expect(str).toBe('\uFFFD')
+  })
+
+  it('decodes valid 3-byte sequences', () => {
+    const euro = [0xE2, 0x82, 0xAC]
+    expect(toUTF8(euro)).toBe('€')
+  })
+
+  it('replaces invalid 3-byte sequences', () => {
+    // Middle byte invalid
+    const arr = [0xE2, 0x20, 0xAC]
+    expect(toUTF8(arr)).toBe('\uFFFD')
+  })
+
+  it('decodes valid 4-byte sequences into surrogate pairs', () => {
+    const smile = [0xF0, 0x9F, 0x98, 0x80] // 😀
+    expect(toUTF8(smile)).toBe('😀')
+  })
+
+  it('replaces invalid 4-byte sequences with U+FFFD', () => {
+    // 0x9F is valid, 0x20 is INVALID continuation for byte 3
+    const arr = [0xF0, 0x9F, 0x20, 0x80]
+    expect(toUTF8(arr)).toBe('\uFFFD')
+  })
+
+  it('replaces incomplete UTF-8 sequence at end', () => {
+    const arr = [0xE2] // incomplete 3-byte seq
+    expect(toUTF8(arr)).toBe('\uFFFD')
+  })
+
+})
+

package/src/primitives/hex.ts

@@ -0,0 +1,35 @@
+// src/primitives/hex.ts
+
+// Accepts empty string because empty byte arrays are valid in Bitcoin.
+const PURE_HEX_REGEX = /^[0-9a-fA-F]*$/
+
+export function assertValidHex (msg: string): void {
+  if (typeof msg !== 'string') {
+    console.error('assertValidHex FAIL (non-string):', msg)
+    throw new Error('Invalid hex string')
+  }
+
+  // allow empty
+  if (msg.length === 0) return
+
+  if (!PURE_HEX_REGEX.test(msg)) {
+    console.error('assertValidHex FAIL (bad hex):', msg)
+    throw new Error('Invalid hex string')
+  }
+}
+
+export function normalizeHex (msg: string): string {
+  assertValidHex(msg)
+
+  // If empty, return empty — never force to "00"
+  if (msg.length === 0) return ''
+
+  let normalized = msg.toLowerCase()
+
+  // Pad odd-length hex
+  if (normalized.length % 2 !== 0) {
+    normalized = '0' + normalized
+  }
+
+  return normalized
+}

package/src/primitives/utils.ts

@@ -1,11 +1,11 @@
 import BigNumber from './BigNumber.js'
 import { hash256 } from './Hash.js'
+import { assertValidHex } from './hex.js'
 
 const BufferCtor =
   typeof globalThis !== 'undefined' ? (globalThis as any).Buffer : undefined
 const CAN_USE_BUFFER =
   BufferCtor != null && typeof BufferCtor.from === 'function'
-const PURE_HEX_REGEX = /^[0-9a-fA-F]+$/
 
 /**
  * Prepends a '0' to an odd character length word to ensure it has an even number of characters.
@@ -80,28 +80,19 @@ for (let i = 0; i < 6; i++) {
 }
 
 const hexToArray = (msg: string): number[] => {
-  if (CAN_USE_BUFFER && PURE_HEX_REGEX.test(msg)) {
-    const normalized = msg.length % 2 === 0 ? msg : '0' + msg
+  assertValidHex(msg)
+  const normalized = msg.length % 2 === 0 ? msg : '0' + msg
+  if (CAN_USE_BUFFER) {
     return Array.from(BufferCtor.from(normalized, 'hex'))
   }
-  const res: number[] = new Array(Math.ceil(msg.length / 2))
-  let nibble = -1
-  let size = 0
-  for (let i = 0; i < msg.length; i++) {
-    const value = HEX_CHAR_TO_VALUE[msg.charCodeAt(i)]
-    if (value === -1) continue
-    if (nibble === -1) {
-      nibble = value
-    } else {
-      res[size++] = (nibble << 4) | value
-      nibble = -1
-    }
-  }
-  if (nibble !== -1) {
-    res[size++] = nibble
+  const out = new Array(normalized.length / 2)
+  let o = 0
+  for (let i = 0; i < normalized.length; i += 2) {
+    const hi = HEX_CHAR_TO_VALUE[normalized.charCodeAt(i)]
+    const lo = HEX_CHAR_TO_VALUE[normalized.charCodeAt(i + 1)]
+    out[o++] = (hi << 4) | lo
   }
-  if (size !== res.length) res.length = size
-  return res
+  return out
 }
 
 export function base64ToArray (msg: string): number[] {
@@ -233,69 +224,84 @@ function utf8ToArray (str: string): number[] {
  */
 export const toUTF8 = (arr: number[]): string => {
   let result = ''
-  let skip = 0
-
+  const replacementChar = '\uFFFD'
   for (let i = 0; i < arr.length; i++) {
-    const byte = arr[i]
-    // this byte is part of a multi-byte sequence, skip it
-    // added to avoid modifying i within the loop which is considered unsafe.
-    if (skip > 0) {
-      skip--
+    const byte1 = arr[i]
+    if (byte1 <= 0x7f) {
+      result += String.fromCharCode(byte1)
       continue
     }
-
-    // 1-byte sequence (0xxxxxxx)
-    if (byte <= 0x7f) {
-      result += String.fromCharCode(byte)
-      continue
+    const emitReplacement = (): void => {
+      result += replacementChar
     }
-
-    // 2-byte sequence (110xxxxx 10xxxxxx)
-    if (byte >= 0xc0 && byte <= 0xdf) {
-      const avail = arr.length - (i + 1)
-      const byte2 = avail >= 1 ? arr[i + 1] : 0
-      skip = Math.min(1, avail)
-
-      const codePoint = ((byte & 0x1f) << 6) | (byte2 & 0x3f)
+    if (byte1 >= 0xc0 && byte1 <= 0xdf) {
+      if (i + 1 >= arr.length) {
+        emitReplacement()
+        continue
+      }
+      const byte2 = arr[i + 1]
+      if ((byte2 & 0xc0) !== 0x80) {
+        emitReplacement()
+        i += 1
+        continue
+      }
+      const codePoint = ((byte1 & 0x1f) << 6) | (byte2 & 0x3f)
       result += String.fromCharCode(codePoint)
+      i += 1
       continue
     }
-
-    // 3-byte sequence (1110xxxx 10xxxxxx 10xxxxxx)
-    if (byte >= 0xe0 && byte <= 0xef) {
-      const avail = arr.length - (i + 1)
-      const byte2 = avail >= 1 ? arr[i + 1] : 0
-      const byte3 = avail >= 2 ? arr[i + 2] : 0
-      skip = Math.min(2, avail)
-
+    if (byte1 >= 0xe0 && byte1 <= 0xef) {
+      if (i + 2 >= arr.length) {
+        emitReplacement()
+        continue
+      }
+      const byte2 = arr[i + 1]
+      const byte3 = arr[i + 2]
+      if ((byte2 & 0xc0) !== 0x80 || (byte3 & 0xc0) !== 0x80) {
+        emitReplacement()
+        i += 2
+        continue
+      }
       const codePoint =
-        ((byte & 0x0f) << 12) | ((byte2 & 0x3f) << 6) | (byte3 & 0x3f)
+        ((byte1 & 0x0f) << 12) |
+        ((byte2 & 0x3f) << 6) |
+        (byte3 & 0x3f)
+
       result += String.fromCharCode(codePoint)
+      i += 2
       continue
     }
-
-    // 4-byte sequence (11110xxx 10xxxxxx 10xxxxxx 10xxxxxx)
-    if (byte >= 0xf0 && byte <= 0xf7) {
-      const avail = arr.length - (i + 1)
-      const byte2 = avail >= 1 ? arr[i + 1] : 0
-      const byte3 = avail >= 2 ? arr[i + 2] : 0
-      const byte4 = avail >= 3 ? arr[i + 3] : 0
-      skip = Math.min(3, avail)
-
+    if (byte1 >= 0xf0 && byte1 <= 0xf7) {
+      if (i + 3 >= arr.length) {
+        emitReplacement()
+        continue
+      }
+      const byte2 = arr[i + 1]
+      const byte3 = arr[i + 2]
+      const byte4 = arr[i + 3]
+      if (
+        (byte2 & 0xc0) !== 0x80 ||
+        (byte3 & 0xc0) !== 0x80 ||
+        (byte4 & 0xc0) !== 0x80
+      ) {
+        emitReplacement()
+        i += 3
+        continue
+      }
       const codePoint =
-        ((byte & 0x07) << 18) |
+        ((byte1 & 0x07) << 18) |
         ((byte2 & 0x3f) << 12) |
         ((byte3 & 0x3f) << 6) |
         (byte4 & 0x3f)
-
-      // Convert to UTF-16 surrogate pair
-      const surrogate1 = 0xd800 + ((codePoint - 0x10000) >> 10)
-      const surrogate2 = 0xdc00 + ((codePoint - 0x10000) & 0x3ff)
-      result += String.fromCharCode(surrogate1, surrogate2)
+      const offset = codePoint - 0x10000
+      const highSurrogate = 0xd800 + (offset >> 10)
+      const lowSurrogate = 0xdc00 + (offset & 0x3ff)
+      result += String.fromCharCode(highSurrogate, lowSurrogate)
+      i += 3
       continue
     }
+    emitReplacement()
   }
-
   return result
 }
 

package/src/script/__tests/Script.test.ts

@@ -286,7 +286,7 @@ describe('Script', () => {
       }
 
       // Expect the function to throw an error with the specified message
-      expect(createScript).toThrow('invalid hex string in script')
+      expect(createScript).toThrow('Invalid hex string')
     })
 
     it('should parse this long PUSHDATA1 script in ASM', () => {