@marcuspuchalla/nachos 0.1.1 → 0.1.4

package/src/parser/__tests__/cbor-tag-reparse-fix.test.ts

@@ -0,0 +1,268 @@
+/**
+ * Tests for eliminating exponential re-parsing in source-map tag handling
+ * Task 2-B: parseTagWithMap should NOT re-parse the entire tag subtree
+ *
+ * The fix ensures that parseTagWithMap uses already-parsed values plus
+ * direct calls to validateTagSemantics and decodePlutusConstructor,
+ * instead of calling parseTag(hexString) which re-parses everything.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { useCborParser } from '../composables/useCborParser'
+import { useCborTag } from '../composables/useCborTag'
+
+describe('Tag Source Map Re-parse Elimination (Task 2-B)', () => {
+  describe('Correctness: parseWithSourceMap still produces correct values', () => {
+    it('should correctly decode tag 121 with array', () => {
+      const { parseWithSourceMap } = useCborParser()
+      const result = parseWithSourceMap('d87983010203') // Tag 121, [1, 2, 3]
+
+      expect(result.value).toEqual({
+        tag: 121,
+        value: [1, 2, 3],
+        plutus: { constructor: 0, fields: [1, 2, 3] }
+      })
+    })
+
+    it('should correctly decode tag 122 with array', () => {
+      const { parseWithSourceMap } = useCborParser()
+      const result = parseWithSourceMap('d87a81182a') // Tag 122, [42]
+
+      expect(result.value).toEqual({
+        tag: 122,
+        value: [42],
+        plutus: { constructor: 1, fields: [42] }
+      })
+    })
+
+    it('should correctly decode tag 102 alternative constructor', () => {
+      const { parseWithSourceMap } = useCborParser()
+      const result = parseWithSourceMap('d8668218c8811863') // Tag 102, [200, [99]]
+
+      expect(result.value).toEqual({
+        tag: 102,
+        value: [200, [99]],
+        plutus: { constructor: 200, fields: [99] }
+      })
+    })
+
+    it('should correctly decode extended constructor tag 1283', () => {
+      const { parseWithSourceMap } = useCborParser()
+      const result = parseWithSourceMap('d9050383010203') // Tag 1283, [1, 2, 3]
+
+      expect(result.value).toEqual({
+        tag: 1283,
+        value: [1, 2, 3],
+        plutus: { constructor: 10, fields: [1, 2, 3] }
+      })
+    })
+
+    it('should correctly decode bignum tag 2 (positive)', () => {
+      const { parseWithSourceMap } = useCborParser()
+      // Tag 2, byte string 0x01 0x00 (= 256)
+      const result = parseWithSourceMap('c2420100')
+
+      expect(result.value).toEqual({
+        tag: 2,
+        value: 256n
+      })
+    })
+
+    it('should correctly decode bignum tag 3 (negative)', () => {
+      const { parseWithSourceMap } = useCborParser()
+      // Tag 3, byte string 0x01 0x00 (= -1 - 256 = -257)
+      const result = parseWithSourceMap('c3420100')
+
+      expect(result.value).toEqual({
+        tag: 3,
+        value: -257n
+      })
+    })
+
+    it('should correctly handle tag 0 (date/time string)', () => {
+      const { parseWithSourceMap } = useCborParser()
+      // Tag 0 containing "2013-03-21T20:04:00Z"
+      const result = parseWithSourceMap('c074323031332d30332d32315432303a30343a30305a')
+
+      const value = result.value as any
+      expect(value.tag).toBe(0)
+      expect(value.value).toBe('2013-03-21T20:04:00Z')
+    })
+
+    it('should correctly handle tag 1 (epoch time)', () => {
+      const { parseWithSourceMap } = useCborParser()
+      // Tag 1 containing 1363896240
+      const result = parseWithSourceMap('c11a514b67b0')
+
+      expect(result.value).toEqual({
+        tag: 1,
+        value: 1363896240
+      })
+    })
+
+    it('should correctly handle nested tags', () => {
+      const { parseWithSourceMap } = useCborParser()
+      // Tag 121 -> [Tag 121 -> []]
+      const result = parseWithSourceMap('d87981d87980')
+
+      const outer = result.value as any
+      expect(outer.tag).toBe(121)
+      expect(outer.plutus).toEqual({ constructor: 0, fields: [{ tag: 121, value: [], plutus: { constructor: 0, fields: [] } }] })
+    })
+
+    it('should correctly handle tag 121 with empty array', () => {
+      const { parseWithSourceMap } = useCborParser()
+      const result = parseWithSourceMap('d87980')
+
+      expect(result.value).toEqual({
+        tag: 121,
+        value: [],
+        plutus: { constructor: 0, fields: [] }
+      })
+    })
+
+    it('should correctly handle self-describe tag 55799', () => {
+      const { parseWithSourceMap } = useCborParser()
+      // Tag 55799 wrapping integer 42
+      const result = parseWithSourceMap('d9d9f7182a')
+
+      expect(result.value).toEqual({
+        tag: 55799,
+        value: 42
+      })
+    })
+
+    it('should correctly handle non-Plutus tag with non-array value', () => {
+      const { parseWithSourceMap } = useCborParser()
+      // Tag 1 containing 0
+      const result = parseWithSourceMap('c100')
+
+      expect(result.value).toEqual({
+        tag: 1,
+        value: 0
+      })
+    })
+  })
+
+  describe('Correctness: source maps remain identical', () => {
+    it('should produce same source map for simple tagged value', () => {
+      const { parseWithSourceMap } = useCborParser()
+      const result = parseWithSourceMap('d879182a') // Tag 121, 42
+
+      expect(result.sourceMap).toHaveLength(2)
+      expect(result.sourceMap[0]).toMatchObject({
+        path: '',
+        majorType: 6,
+        type: 'tag(121)',
+        children: ['.value']
+      })
+      expect(result.sourceMap[1]).toMatchObject({
+        path: '.value',
+        majorType: 0,
+        parent: ''
+      })
+    })
+
+    it('should produce same source map for nested tags', () => {
+      const { parseWithSourceMap } = useCborParser()
+      const result = parseWithSourceMap('d87981d87980')
+
+      const outerTag = result.sourceMap.find(e => e.path === '')
+      expect(outerTag?.majorType).toBe(6)
+      expect(outerTag?.children).toEqual(['.value'])
+
+      const array = result.sourceMap.find(e => e.path === '.value')
+      expect(array?.majorType).toBe(4)
+      expect(array?.parent).toBe('')
+
+      const innerTag = result.sourceMap.find(e => e.path === '.value[0]')
+      expect(innerTag?.majorType).toBe(6)
+      expect(innerTag?.parent).toBe('.value')
+    })
+  })
+
+  describe('Validation still works through source-map path', () => {
+    it('should validate tag 2/3 bignum byte limit', () => {
+      const { parseWithSourceMap } = useCborParser()
+      // Tag 2 with a byte string exceeding the limit
+      // Create a very long byte string (> default 1024 bytes)
+      const longByteString = '59' + '0401' + 'ff'.repeat(1025)
+      const hex = 'c2' + longByteString
+
+      expect(() => parseWithSourceMap(hex)).toThrow(/bignum/i)
+    })
+
+    it('should validate tag semantics in strict mode', () => {
+      const { parseWithSourceMap } = useCborParser()
+      // Tag 0 (date/time) with integer value (should be text string)
+      // c0 00 = tag(0) + integer(0)
+      expect(() => parseWithSourceMap('c000', { strict: true })).toThrow(/tag 0/i)
+    })
+
+    it('should validate Plutus semantics in strict mode', () => {
+      const { parseWithSourceMap } = useCborParser()
+      // Tag 121 with non-array value (should be array)
+      // d8 79 00 = tag(121) + integer(0)
+      expect(() => parseWithSourceMap('d87900', { strict: true })).toThrow(/Plutus/i)
+    })
+  })
+
+  describe('Performance: no exponential re-parsing', () => {
+    it('should parse deeply nested tags in linear time', () => {
+      const { parseWithSourceMap } = useCborParser()
+
+      // Build a deeply nested tag: tag(121) -> [tag(121) -> [tag(121) -> ... -> []]]
+      // At depth D, the old code would do O(D^2) work due to re-parsing.
+      // With the fix, it should be O(D).
+      const buildNestedTagHex = (depth: number): string => {
+        // Each level: d8 79 81 (tag 121, 1-element array)
+        // Innermost: d8 79 80 (tag 121, empty array)
+        let hex = ''
+        for (let i = 0; i < depth - 1; i++) {
+          hex += 'd87981' // tag(121), array(1)
+        }
+        hex += 'd87980' // tag(121), array(0)
+        return hex
+      }
+
+      // Time a moderate depth (20 levels)
+      const hex20 = buildNestedTagHex(20)
+      const start20 = performance.now()
+      const result20 = parseWithSourceMap(hex20)
+      const time20 = performance.now() - start20
+
+      // Time a deeper nesting (40 levels)
+      const hex40 = buildNestedTagHex(40)
+      const start40 = performance.now()
+      const result40 = parseWithSourceMap(hex40)
+      const time40 = performance.now() - start40
+
+      // With O(D^2), doubling depth quadruples time: time40/time20 ~ 4
+      // With O(D), doubling depth doubles time: time40/time20 ~ 2
+      // Use a generous bound: if fixed, ratio should be < 3
+      // If unfixed (quadratic), ratio tends toward 4+
+      //
+      // Note: for small absolute times, jitter can dominate.
+      // The real test is that 40-deep should still complete quickly (< 100ms).
+      expect(time40).toBeLessThan(100) // Should be very fast with fix
+
+      // Both should parse successfully
+      expect((result20.value as any).tag).toBe(121)
+      expect((result40.value as any).tag).toBe(121)
+    })
+  })
+
+  describe('useCborTag exports', () => {
+    it('should export validateTagSemantics function', () => {
+      const tag = useCborTag()
+      expect(tag.validateTagSemantics).toBeDefined()
+      expect(typeof tag.validateTagSemantics).toBe('function')
+    })
+
+    it('should export decodePlutusConstructor function', () => {
+      const tag = useCborTag()
+      expect(tag.decodePlutusConstructor).toBeDefined()
+      expect(typeof tag.decodePlutusConstructor).toBe('function')
+    })
+  })
+})

package/src/parser/composables/useCborCollection.ts

@@ -6,7 +6,7 @@
 
 import type { ParseResult, CborValue, CborMap, ParseOptions } from '../types'
 import { INDEFINITE_SYMBOL, ALL_ENTRIES_SYMBOL } from '../types'
-import { hexToBytes, readByte, readUint, readBigUint, extractCborHeader, compareBytes, bytesToHex } from '../utils'
+import { hexToBytes, readByte, readUint, readBigUint, extractCborHeader, compareBytes, serializeValueForComparison } from '../utils'
 import { useCborInteger } from './useCborInteger'
 import { useCborString } from './useCborString'
 import { useCborFloat } from './useCborFloat'
@@ -25,21 +25,13 @@ import { logger } from '../../utils/logger'
  * ```
  */
 export function useCborCollection() {
-  const { parseInteger } = useCborInteger()
+  const { parseIntegerFromBuffer } = useCborInteger()
   const { parseByteString, parseTextString } = useCborString()
-  const { parse: parseFloatOrSimple } = useCborFloat()
-  const { parseTag } = useCborTag()
+  const { parseFromBuffer: parseFloatOrSimpleFromBuffer } = useCborFloat()
+  const { parseTagFromBuffer } = useCborTag()
 
-  /**
-   * Convert a CBOR value to a string key for use in JavaScript objects
-   * Handles Uint8Array keys by converting them to hex strings
-   */
-  const convertKeyToString = (key: CborValue): string => {
-    if (key instanceof Uint8Array) {
-      return bytesToHex(key)
-    }
-    return String(key)
-  }
+  /** Tracks when parsing started for timeout enforcement */
+  let parseStartTime = 0
 
   /**
    * Internal parser dispatcher for CBOR items
@@ -52,6 +44,14 @@ export function useCborCollection() {
    * @returns Parsed value and bytes consumed
    */
   const parseItem = (buffer: Uint8Array, offset: number, options?: ParseOptions, depth: number = 0): ParseResult => {
+    // Check timeout on every recursive call
+    if (parseStartTime > 0 && options?.limits?.maxParseTime) {
+      const elapsed = Date.now() - parseStartTime
+      if (elapsed > options.limits.maxParseTime) {
+        throw new Error(`Parse timeout: exceeded ${options.limits.maxParseTime}ms limit`)
+      }
+    }
+
     if (offset >= buffer.length) {
       throw new Error(`Unexpected end of buffer at offset ${offset}`)
     }
@@ -62,14 +62,7 @@ export function useCborCollection() {
     switch (majorType) {
       case 0: // Unsigned integer
       case 1: // Negative integer
-        {
-          // Create a hex string from the buffer starting at offset
-          const intHex = Array.from(buffer.slice(offset))
-            .map(b => b.toString(16).padStart(2, '0'))
-            .join('')
-          const result = parseInteger(intHex, options)
-          return { value: result.value, bytesRead: result.bytesRead }
-        }
+        return parseIntegerFromBuffer(buffer, offset, options)
 
       case 2: // Byte string
         return parseByteString(buffer, offset, options)
@@ -84,22 +77,10 @@ export function useCborCollection() {
         return parseMapFromBuffer(buffer, offset, options, depth)
 
       case 6: // Tag
-        {
-          const tagHex = Array.from(buffer.slice(offset))
-            .map(b => b.toString(16).padStart(2, '0'))
-            .join('')
-          const result = parseTag(tagHex, options)
-          return { value: result.value, bytesRead: result.bytesRead }
-        }
+        return parseTagFromBuffer(buffer, offset, options)
 
       case 7: // Simple/Float
-        {
-          const floatHex = Array.from(buffer.slice(offset))
-            .map(b => b.toString(16).padStart(2, '0'))
-            .join('')
-          const result = parseFloatOrSimple(floatHex, options)
-          return { value: result.value, bytesRead: result.bytesRead }
-        }
+        return parseFloatOrSimpleFromBuffer(buffer, offset, options)
 
       default:
         throw new Error(`Unknown major type: ${majorType}`)
@@ -356,8 +337,10 @@ export function useCborCollection() {
         const valueResult = parseItem(buffer, currentOffset, options, depth + 1)
         currentOffset += valueResult.bytesRead
 
-        // For duplicate key detection, serialize the key
-        const keyString = convertKeyToString(keyResult.value)
+        // For duplicate key detection, serialize the parsed value semantically
+        // RFC 8949 Section 5.6: comparison must be on semantic values, not raw bytes
+        // (raw bytes differ when same value uses different byte widths)
+        const keyString = serializeValueForComparison(keyResult.value)
 
         // Check for duplicate keys based on dupMapKeyMode
         // RFC 8949: Deterministic encoding SHOULD reject duplicate keys
@@ -420,8 +403,10 @@ export function useCborCollection() {
         const valueResult = parseItem(buffer, currentOffset, options, depth + 1)
         currentOffset += valueResult.bytesRead
 
-        // For duplicate key detection, serialize the key
-        const keyString = convertKeyToString(keyResult.value)
+        // For duplicate key detection, serialize the parsed value semantically
+        // RFC 8949 Section 5.6: comparison must be on semantic values, not raw bytes
+        // (raw bytes differ when same value uses different byte widths)
+        const keyString = serializeValueForComparison(keyResult.value)
 
         // Check for duplicate keys based on dupMapKeyMode
         // RFC 8949: Deterministic encoding SHOULD reject duplicate keys
@@ -485,7 +470,16 @@ export function useCborCollection() {
     // Remove spaces from hex string
     const cleanHex = hexString.replace(/\s+/g, '')
     const buffer = hexToBytes(cleanHex)
-    return parseArrayFromBuffer(buffer, 0, options, 0)
+
+    // Set parse start time for timeout enforcement
+    if (options?.limits?.maxParseTime) {
+      parseStartTime = Date.now()
+    }
+    try {
+      return parseArrayFromBuffer(buffer, 0, options, 0)
+    } finally {
+      parseStartTime = 0
+    }
   }
 
   /**
@@ -499,7 +493,16 @@ export function useCborCollection() {
     // Remove spaces from hex string
     const cleanHex = hexString.replace(/\s+/g, '')
     const buffer = hexToBytes(cleanHex)
-    return parseMapFromBuffer(buffer, 0, options, 0)
+
+    // Set parse start time for timeout enforcement
+    if (options?.limits?.maxParseTime) {
+      parseStartTime = Date.now()
+    }
+    try {
+      return parseMapFromBuffer(buffer, 0, options, 0)
+    } finally {
+      parseStartTime = 0
+    }
   }
 
   return {

package/src/parser/composables/useCborFloat.ts

@@ -62,6 +62,58 @@ export function useCborFloat() {
     return (sign === 0 ? 1 : -1) * Math.pow(2, exponent - 15) * (1 + fraction / 1024)
   }
 
+  /**
+   * Checks if a float64 value can be exactly represented as float16
+   * Used for canonical encoding validation (RFC 8949 Section 4.2.2)
+   */
+  const fitsInFloat16 = (value: number): boolean => {
+    if (Number.isNaN(value) || value === Infinity || value === -Infinity) return true
+    if (Object.is(value, 0) || Object.is(value, -0)) return true
+
+    const abs = Math.abs(value)
+    // Float16 range: subnormals ~5.96e-8 to max normal 65504
+    if (abs > 65504) return false
+    if (abs < 5.960464477539063e-8) return false
+
+    // Encode to float16 and back to see if value is preserved
+    const sign = value < 0 ? 1 : 0
+    const buf = new ArrayBuffer(8)
+    const view = new DataView(buf)
+    view.setFloat64(0, abs, false)
+    const bits64 = view.getBigUint64(0, false)
+    const exp64 = Number((bits64 >> 52n) & 0x7ffn) - 1023
+    const mant64 = Number(bits64 & 0xfffffffffffffn)
+
+    let exp16: number
+    let mant16: number
+    if (exp64 < -14) {
+      // Subnormal float16
+      exp16 = 0
+      const shift = -14 - exp64
+      mant16 = ((1 << 10) | (mant64 >> 42)) >> shift
+    } else if (exp64 > 15) {
+      return false
+    } else {
+      exp16 = exp64 + 15
+      mant16 = mant64 >> 42
+    }
+
+    const float16Bits = (sign << 15) | (exp16 << 10) | mant16
+    // Decode back
+    const s = (float16Bits & 0x8000) >> 15
+    const e = (float16Bits & 0x7c00) >> 10
+    const f = float16Bits & 0x03ff
+    let reconstructed: number
+    if (e === 0) {
+      reconstructed = (s === 0 ? 1 : -1) * Math.pow(2, -14) * (f / 1024)
+    } else if (e === 0x1f) {
+      reconstructed = f === 0 ? (s === 0 ? Infinity : -Infinity) : NaN
+    } else {
+      reconstructed = (s === 0 ? 1 : -1) * Math.pow(2, e - 15) * (1 + f / 1024)
+    }
+    return reconstructed === value
+  }
+
   /**
    * Parses simple values (booleans, null, undefined, unassigned)
    *
@@ -142,7 +194,7 @@ export function useCborFloat() {
    * @param offset - Current offset
    * @returns Parsed float and bytes read
    */
-  const parseFloatFromBuffer = (buffer: Uint8Array, offset: number): ParseResult => {
+  const parseFloatFromBuffer = (buffer: Uint8Array, offset: number, options?: ParseOptions): ParseResult => {
     const initialByte = readByte(buffer, offset)
     const { majorType, additionalInfo } = extractCborHeader(initialByte)
 
@@ -156,6 +208,16 @@ export function useCborFloat() {
           if (offset + 2 >= buffer.length) {
             throw new Error('Unexpected end of buffer while reading Float16')
           }
+          if (options?.validateCanonical) {
+            const byte1 = readByte(buffer, offset + 1)
+            const byte2 = readByte(buffer, offset + 2)
+            const bits = (byte1 << 8) | byte2
+            const exp = (bits >> 10) & 0x1f
+            const mant = bits & 0x03ff
+            if (exp === 0x1f && mant !== 0 && bits !== 0x7e00) {
+              throw new Error('Non-canonical NaN encoding: use 0xf97e00')
+            }
+          }
           const value = float16ToFloat64(buffer, offset + 1)
           return { value, bytesRead: 3 }
         }
@@ -168,6 +230,15 @@ export function useCborFloat() {
           // Use DataView for proper IEEE 754 parsing
           const dataView = new DataView(buffer.buffer, buffer.byteOffset + offset + 1, 4)
           const value = dataView.getFloat32(0, false) // false = big-endian
+          if (options?.validateCanonical) {
+            if (Number.isNaN(value)) {
+              throw new Error('Non-canonical NaN encoding: NaN must use float16 0xf97e00')
+            }
+            // Check if value could be represented as float16 (shortest form)
+            if (fitsInFloat16(value)) {
+              throw new Error('Non-canonical float32: value fits in float16, use shortest encoding')
+            }
+          }
           return { value, bytesRead: 5 }
         }
 
@@ -179,6 +250,20 @@ export function useCborFloat() {
           // Use DataView for proper IEEE 754 parsing
           const dataView = new DataView(buffer.buffer, buffer.byteOffset + offset + 1, 8)
           const value = dataView.getFloat64(0, false) // false = big-endian
+          if (options?.validateCanonical) {
+            if (Number.isNaN(value)) {
+              throw new Error('Non-canonical NaN encoding: NaN must use float16 0xf97e00')
+            }
+            // Check if value could be represented in a smaller float
+            if (fitsInFloat16(value)) {
+              throw new Error('Non-canonical float64: value fits in float16/float32, use shortest encoding')
+            }
+            // Check if float64 value fits in float32
+            const f32 = Math.fround(value)
+            if (f32 === value || (Object.is(value, -0) && Object.is(f32, -0))) {
+              throw new Error('Non-canonical float64: value fits in float16/float32, use shortest encoding')
+            }
+          }
           return { value, bytesRead: 9 }
         }
 
@@ -194,7 +279,7 @@ export function useCborFloat() {
    * @param offset - Current offset
    * @returns Parsed value and bytes read
    */
-  const parseFromBuffer = (buffer: Uint8Array, offset: number): ParseResult => {
+  const parseFromBuffer = (buffer: Uint8Array, offset: number, options?: ParseOptions): ParseResult => {
     const initialByte = readByte(buffer, offset)
     const { majorType, additionalInfo } = extractCborHeader(initialByte)
 
@@ -205,7 +290,7 @@ export function useCborFloat() {
     // Determine if it's a float or simple value based on additional info
     if (additionalInfo === 25 || additionalInfo === 26 || additionalInfo === 27) {
       // Float16, Float32, or Float64
-      return parseFloatFromBuffer(buffer, offset)
+      return parseFloatFromBuffer(buffer, offset, options)
     } else {
       // Simple value (including false, true, null, undefined)
       return parseSimpleFromBuffer(buffer, offset)
@@ -216,7 +301,7 @@ export function useCborFloat() {
    * Parses CBOR simple value from hex string
    *
    * @param hexString - CBOR hex string
-   * @param _options - Parser options (optional, for future use)
+   * @param _options - Parser options (reserved for future use)
    * @returns Parsed simple value and bytes read
    */
   const parseSimple = (hexString: string, _options?: ParseOptions): ParseResult => {
@@ -231,9 +316,9 @@ export function useCborFloat() {
    * @param _options - Parser options (optional, for future use)
    * @returns Parsed float and bytes read
    */
-  const parseFloat = (hexString: string, _options?: ParseOptions): ParseResult => {
+  const parseFloat = (hexString: string, options?: ParseOptions): ParseResult => {
     const buffer = hexToBytes(hexString)
-    return parseFloatFromBuffer(buffer, 0)
+    return parseFloatFromBuffer(buffer, 0, options)
   }
 
   /**
@@ -243,14 +328,15 @@ export function useCborFloat() {
    * @param _options - Parser options (optional, for future use)
    * @returns Parsed value and bytes read
    */
-  const parse = (hexString: string, _options?: ParseOptions): ParseResult => {
+  const parse = (hexString: string, options?: ParseOptions): ParseResult => {
     const buffer = hexToBytes(hexString)
-    return parseFromBuffer(buffer, 0)
+    return parseFromBuffer(buffer, 0, options)
   }
 
   return {
     parse,
     parseFloat,
-    parseSimple
+    parseSimple,
+    parseFromBuffer
   }
 }

package/src/parser/composables/useCborInteger.ts

@@ -20,15 +20,15 @@ import { hexToBytes, readByte, readUint, readBigUint, extractCborHeader, validat
  */
 export function useCborInteger() {
   /**
-   * Parses CBOR integer (Major Type 0 or 1)
+   * Parses CBOR integer (Major Type 0 or 1) from a buffer at a given offset
    *
-   * @param hexString - CBOR hex string
+   * @param buffer - Data buffer
+   * @param offset - Current offset into the buffer
    * @param options - Parser options (optional)
    * @returns Parsed integer value and bytes read
    */
-  const parseInteger = (hexString: string, options?: ParseOptions): ParseResult => {
-    const buffer = hexToBytes(hexString)
-    const initialByte = readByte(buffer, 0)
+  const parseIntegerFromBuffer = (buffer: Uint8Array, offset: number, options?: ParseOptions): ParseResult => {
+    const initialByte = readByte(buffer, offset)
 
     const { majorType, additionalInfo } = extractCborHeader(initialByte)
 
@@ -42,19 +42,19 @@ export function useCborInteger() {
       bytesRead = 1
     } else if (additionalInfo === 24) {
       // 1 byte follows
-      rawValue = readByte(buffer, 1)
+      rawValue = readByte(buffer, offset + 1)
       bytesRead = 2
     } else if (additionalInfo === 25) {
       // 2 bytes follow
-      rawValue = readUint(buffer, 1, 2)
+      rawValue = readUint(buffer, offset + 1, 2)
       bytesRead = 3
     } else if (additionalInfo === 26) {
       // 4 bytes follow
-      rawValue = readUint(buffer, 1, 4)
+      rawValue = readUint(buffer, offset + 1, 4)
       bytesRead = 5
     } else if (additionalInfo === 27) {
       // 8 bytes follow - use BigInt for large values
-      const bigValue = readBigUint(buffer, 1, 8)
+      const bigValue = readBigUint(buffer, offset + 1, 8)
 
       // Check if value fits in Number.MAX_SAFE_INTEGER
       if (bigValue <= BigInt(Number.MAX_SAFE_INTEGER)) {
@@ -108,7 +108,21 @@ export function useCborInteger() {
     }
   }
 
+  /**
+   * Parses CBOR integer (Major Type 0 or 1) from hex string
+   * Thin wrapper around parseIntegerFromBuffer
+   *
+   * @param hexString - CBOR hex string
+   * @param options - Parser options (optional)
+   * @returns Parsed integer value and bytes read
+   */
+  const parseInteger = (hexString: string, options?: ParseOptions): ParseResult => {
+    const buffer = hexToBytes(hexString)
+    return parseIntegerFromBuffer(buffer, 0, options)
+  }
+
   return {
-    parseInteger
+    parseInteger,
+    parseIntegerFromBuffer
   }
 }