@marcuspuchalla/nachos 0.1.4 → 0.2.0

package/src/encoder/types.ts

@@ -3,12 +3,12 @@
  * Following RFC 8949 specification
  */
 
-import type { PlutusConstr, CborByteString, CborTextString } from '../parser/types'
+import type { PlutusConstr, CborByteString, CborTextString, MapKeyOrder } from '../parser/types'
 import { INDEFINITE_SYMBOL, ALL_ENTRIES_SYMBOL } from '../parser/types'
 
 // Re-export symbols and types for use in encoder
 export { INDEFINITE_SYMBOL, ALL_ENTRIES_SYMBOL }
-export type { CborByteString, CborTextString }
+export type { CborByteString, CborTextString, MapKeyOrder }
 
 /**
  * Encoder options for controlling behavior
@@ -20,6 +20,12 @@ export interface EncodeOptions {
   allowIndefinite?: boolean
   /** Reject duplicate map keys */
   rejectDuplicateKeys?: boolean
+  /**
+   * Map key ordering used in canonical mode.
+   * Defaults to 'length-first' (Cardano CIP-21 / RFC 7049 §3.9).
+   * Use 'bytewise' for RFC 8949 §4.2.1 core deterministic order.
+   */
+  mapKeyOrder?: MapKeyOrder
   /** Maximum nesting depth */
   maxDepth?: number
   /** Maximum output size in bytes */
@@ -33,6 +39,7 @@ export const DEFAULT_ENCODE_OPTIONS: Required<EncodeOptions> = {
   canonical: false,
   allowIndefinite: true,
   rejectDuplicateKeys: false,
+  mapKeyOrder: 'length-first',
   maxDepth: 64,
   maxOutputSize: 100 * 1024 * 1024  // 100 MB
 }

package/src/encoder/utils.ts

@@ -28,7 +28,8 @@ export function concatenateUint8Arrays(arrays: Uint8Array[]): Uint8Array {
 }
 
 /**
- * Compare two Uint8Arrays bytewise (for canonical map sorting)
+ * Compare two Uint8Arrays length-first (RFC 7049 §3.9 / Cardano CIP-21 ordering).
+ * Shorter keys sort first; equal-length keys are compared bytewise.
  */
 export function compareBytes(a: Uint8Array, b: Uint8Array): number {
   // First, compare lengths
@@ -51,6 +52,37 @@ export function compareBytes(a: Uint8Array, b: Uint8Array): number {
   return 0
 }
 
+/**
+ * Compare two Uint8Arrays in pure bytewise lexicographic order
+ * (RFC 8949 §4.2.1 core deterministic encoding). If one is a prefix of the
+ * other, the shorter sorts first.
+ */
+export function compareBytesLexicographic(a: Uint8Array, b: Uint8Array): number {
+  const min = Math.min(a.length, b.length)
+  for (let i = 0; i < min; i++) {
+    const byteA = a[i]!
+    const byteB = b[i]!
+    if (byteA !== byteB) {
+      return byteA - byteB
+    }
+  }
+  return a.length - b.length
+}
+
+/**
+ * Compare two encoded map keys according to the requested ordering.
+ *
+ * @param order - 'length-first' (CIP-21 / RFC 7049 §3.9, default) or
+ *                'bytewise' (RFC 8949 §4.2.1 core deterministic)
+ */
+export function compareMapKeys(
+  a: Uint8Array,
+  b: Uint8Array,
+  order: 'length-first' | 'bytewise' = 'length-first'
+): number {
+  return order === 'bytewise' ? compareBytesLexicographic(a, b) : compareBytes(a, b)
+}
+
 /**
  * Write unsigned integer to bytes (big-endian)
  */

package/src/index.ts

@@ -179,6 +179,16 @@ export function decodeWithSourceMap(input: string | Uint8Array, options?: ParseO
  *
  * @throws {Error} If value type is unsupported or encoding fails
  *
+ * @remarks
+ * Plain objects use `Object.entries()`, so all keys become **text strings** and
+ * integer-like keys (`"0"`, `"1"`, …) are reordered by the JS engine's
+ * integer-index property rule. For integer keys or guaranteed ordering (e.g.
+ * Cardano transaction bodies), pass a `Map` instead of a plain object.
+ *
+ * Canonical mode (`{ canonical: true }`) sorts map keys **length-first** by
+ * default (Cardano CIP-21 / RFC 7049 §3.9). Pass `{ mapKeyOrder: 'bytewise' }`
+ * for RFC 8949 §4.2.1 core deterministic ordering.
+ *
  * @example
  * ```typescript
  * // Encode number

package/src/parser/__tests__/utils-errors.test.ts

@@ -42,10 +42,10 @@ describe('Utils - Error Handling', () => {
   })
 
   describe('readUint - Valid Lengths', () => {
-    it('should read 1-8 bytes successfully', () => {
+    it('should read 1-7 bytes (within safe-integer range) successfully', () => {
       const buffer = new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08])
 
-      // Test all valid lengths (1-8)
+      // Lengths 1-7 stay within Number.MAX_SAFE_INTEGER (2^53 - 1)
       expect(readUint(buffer, 0, 1)).toBe(0x01)
       expect(readUint(buffer, 0, 2)).toBe(0x0102)
       expect(readUint(buffer, 0, 3)).toBe(0x010203)
@@ -53,7 +53,15 @@ describe('Utils - Error Handling', () => {
       expect(readUint(buffer, 0, 5)).toBe(0x0102030405)
       expect(readUint(buffer, 0, 6)).toBe(0x010203040506)
       expect(readUint(buffer, 0, 7)).toBe(0x01020304050607)
-      expect(readUint(buffer, 0, 8)).toBe(0x0102030405060708)
+    })
+
+    it('should throw rather than silently lose precision above MAX_SAFE_INTEGER', () => {
+      // 0x0102030405060708 ≈ 7.26e16 > 2^53, so readUint refuses it and
+      // directs callers to readBigUint (L3 precision-safety fix).
+      const buffer = new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08])
+      expect(() => readUint(buffer, 0, 8)).toThrow('exceeds MAX_SAFE_INTEGER')
+      // The exact value is available without loss via readBigUint:
+      expect(readBigUint(buffer, 0, 8)).toBe(0x0102030405060708n)
     })
   })
 

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, serializeValueForComparison } from '../utils'
+import { hexToBytes, readByte, readUint, readBigUint, extractCborHeader, compareMapKeys, serializeValueForComparison } from '../utils'
 import { useCborInteger } from './useCborInteger'
 import { useCborString } from './useCborString'
 import { useCborFloat } from './useCborFloat'
@@ -434,16 +434,19 @@ export function useCborCollection() {
     // Attach allEntries to map for byte-perfect round-trips with duplicates
     ;(map as any)[ALL_ENTRIES_SYMBOL] = allEntries
 
-    // Validate canonical key ordering (keys must be sorted by byte representation)
+    // Validate canonical key ordering (keys must be sorted by byte representation).
+    // Ordering follows options.mapKeyOrder: 'length-first' (CIP-21 / RFC 7049 §3.9,
+    // default) or 'bytewise' (RFC 8949 §4.2.1 core deterministic).
     if (options?.validateCanonical && keyBytes.length > 1) {
+      const keyOrder = options?.mapKeyOrder ?? 'length-first'
       for (let i = 1; i < keyBytes.length; i++) {
         const prevKey = keyBytes[i - 1]
         const currKey = keyBytes[i]
         if (prevKey && currKey) {
-          const cmp = compareBytes(prevKey, currKey)
+          const cmp = compareMapKeys(prevKey, currKey, keyOrder)
           if (cmp > 0) {
             throw new Error(
-              `Map keys are not in canonical order: key at index ${i} should come before key at index ${i - 1}`
+              `Map keys are not in canonical order (${keyOrder}): key at index ${i} should come before key at index ${i - 1}`
             )
           }
           if (cmp === 0) {

package/src/parser/composables/useCborDiagnostic.ts

@@ -15,6 +15,13 @@
  * ```
  */
 
+import { INDEFINITE_SYMBOL } from '../types'
+
+/** Detect the indefinite-length marker attached by the parser to a value. */
+function isIndefiniteValue(value: unknown): boolean {
+  return typeof value === 'object' && value !== null && (value as any)[INDEFINITE_SYMBOL] === true
+}
+
 /**
  * Options for diagnostic notation output
  */
@@ -186,6 +193,25 @@ export function useCborDiagnostic() {
       return `h'${bytesToHex(value)}'`
     }
 
+    // Handle parser wrapper types for indefinite-length strings
+    if (typeof value === 'object' && value !== null && 'type' in value) {
+      const t = (value as { type?: string }).type
+      if (t === 'cbor-byte-string') {
+        const bs = value as unknown as { bytes: Uint8Array }
+        return isIndefiniteValue(value) ? `(_ h'${bytesToHex(bs.bytes)}')` : `h'${bytesToHex(bs.bytes)}'`
+      }
+      if (t === 'cbor-text-string') {
+        const ts = value as unknown as { text: string }
+        return isIndefiniteValue(value) ? `(_ "${escapeString(ts.text)}")` : `"${escapeString(ts.text)}"`
+      }
+    }
+
+    // Handle unassigned simple values (Major Type 7): simple(N)
+    if (typeof value === 'object' && value !== null && 'simpleValue' in value &&
+        typeof (value as { simpleValue?: unknown }).simpleValue === 'number') {
+      return `simple(${(value as { simpleValue: number }).simpleValue})`
+    }
+
     // Handle tagged values
     if (isTaggedValue(value)) {
       const taggedContent = formatValue(
@@ -201,6 +227,7 @@ export function useCborDiagnostic() {
 
     // Handle arrays
     if (Array.isArray(value)) {
+      indefinite = indefinite || isIndefiniteValue(value)
       if (value.length === 0) {
         return indefinite ? '[_ ]' : '[]'
       }
@@ -222,6 +249,7 @@ export function useCborDiagnostic() {
 
     // Handle Maps
     if (value instanceof Map) {
+      indefinite = indefinite || isIndefiniteValue(value)
       if (value.size === 0) {
         return indefinite ? '{_ }' : '{}'
       }

package/src/parser/composables/useCborParser.ts

@@ -6,7 +6,7 @@
 
 import type { ParseResult, ParseResultWithMap, SourceMapEntry, ParseOptions, CborContext, CborValue, TaggedValue } from '../types'
 import { DEFAULT_OPTIONS, DEFAULT_LIMITS } from '../types'
-import { hexToBytes, readByte, readUint, readBigUint, extractCborHeader, serializeValueForComparison } from '../utils'
+import { hexToBytes, readByte, readUint, readBigUint, extractCborHeader, serializeValueForComparison, validateCanonicalInteger } from '../utils'
 import { useCborInteger } from './useCborInteger'
 import { useCborString } from './useCborString'
 import { useCborCollection } from './useCborCollection'
@@ -47,6 +47,9 @@ export function useCborParser() {
       validateSetUniqueness: options.validateSetUniqueness ?? (options.strict ? true : DEFAULT_OPTIONS.validateSetUniqueness),
       validateTagSemantics: options.validateTagSemantics ?? (options.strict ? true : DEFAULT_OPTIONS.validateTagSemantics),
       validatePlutusSemantics: options.validatePlutusSemantics ?? (options.strict ? true : DEFAULT_OPTIONS.validatePlutusSemantics),
+      mapKeyOrder: options.mapKeyOrder ?? DEFAULT_OPTIONS.mapKeyOrder,
+      // Strict mode rejects trailing data after the top-level item (well-formedness).
+      allowTrailingData: options.allowTrailingData ?? (options.strict ? false : DEFAULT_OPTIONS.allowTrailingData),
       limits: {
         maxInputSize: options.limits?.maxInputSize ?? DEFAULT_LIMITS.maxInputSize,
         maxOutputSize: options.limits?.maxOutputSize ?? DEFAULT_LIMITS.maxOutputSize,
@@ -115,7 +118,9 @@ export function useCborParser() {
         throw new Error(`Input size ${input.length} bytes exceeds limit of ${mergedOptions.limits.maxInputSize} bytes`)
       }
 
-      return dispatchFromBuffer(input, 0, mergedOptions)
+      const bufResult = dispatchFromBuffer(input, 0, mergedOptions)
+      checkTrailingData(bufResult.bytesRead, input.length, mergedOptions)
+      return bufResult
     }
 
     // Hex string path
@@ -146,30 +151,57 @@ export function useCborParser() {
     const { majorType } = extractCborHeader(initialByte)
 
     // Dispatch to appropriate parser based on major type
+    let result: ParseResult
     switch (majorType) {
       case 0: // Unsigned integer
       case 1: // Negative integer
-        return parseInteger(cleanHex, mergedOptions)
+        result = parseInteger(cleanHex, mergedOptions)
+        break
 
       case 2: // Byte string
       case 3: // Text string
-        return parseString(cleanHex, mergedOptions)
+        result = parseString(cleanHex, mergedOptions)
+        break
 
       case 4: // Array
-        return parseArray(cleanHex, mergedOptions)
+        result = parseArray(cleanHex, mergedOptions)
+        break
 
       case 5: // Map
-        return parseMap(cleanHex, mergedOptions)
+        result = parseMap(cleanHex, mergedOptions)
+        break
 
       case 6: // Tagged value
-        return parseTag(cleanHex, mergedOptions)
+        result = parseTag(cleanHex, mergedOptions)
+        break
 
       case 7: // Floating-point or simple value
-        return parseFloatOrSimple(cleanHex, mergedOptions)
+        result = parseFloatOrSimple(cleanHex, mergedOptions)
+        break
 
       default:
         throw new Error(`Unknown major type: ${majorType}`)
     }
+
+    checkTrailingData(result.bytesRead, buffer.length, mergedOptions)
+    return result
+  }
+
+  /**
+   * Rejects trailing bytes after the top-level data item when
+   * allowTrailingData is false (RFC 8949 well-formedness for a single item).
+   */
+  const checkTrailingData = (
+    bytesRead: number,
+    totalLength: number,
+    opts: Required<ParseOptions>
+  ): void => {
+    if (!opts.allowTrailingData && bytesRead < totalLength) {
+      throw new Error(
+        `Trailing data: ${totalLength - bytesRead} byte(s) remain after the top-level CBOR item ` +
+        `(bytesRead=${bytesRead}, length=${totalLength}). Use parseSequence to decode multiple items.`
+      )
+    }
   }
 
   /**
@@ -881,6 +913,17 @@ export function useCborParser() {
     path: string,
     sourceMap: SourceMapEntry[]
   ): ParseResult => {
+    // Enforce tag nesting depth (RUSTSEC-2019-0025). The source-map path
+    // previously lacked this guard, allowing a deeply nested tag chain to
+    // overflow the call stack with an uncatchable RangeError instead of a
+    // clean error — matching the decode() path's behaviour here.
+    const previousTagDepth = ctx.currentTagDepth ?? 0
+    const maxTagDepth = ctx.options?.limits?.maxTagDepth ?? DEFAULT_LIMITS.maxTagDepth
+    if (previousTagDepth >= maxTagDepth) {
+      throw new Error(`Tag nesting depth ${previousTagDepth} exceeds limit of ${maxTagDepth}`)
+    }
+    ctx.currentTagDepth = previousTagDepth + 1
+
     const startOffset = offset
     const initialByte = readByte(ctx.buffer, offset)
     const { additionalInfo } = extractCborHeader(initialByte)
@@ -892,6 +935,11 @@ export function useCborParser() {
       additionalInfo
     )
 
+    // Enforce canonical (shortest-form) tag number encoding when requested.
+    if (ctx.options?.validateCanonical) {
+      validateCanonicalInteger(tagNumber, additionalInfo)
+    }
+
     let currentOffset = offset + 1 + bytesConsumed
     const headerEnd = currentOffset
 
@@ -959,6 +1007,9 @@ export function useCborParser() {
       ...(plutusConstr && { plutus: plutusConstr })
     }
 
+    // Restore tag depth so sibling tags don't accumulate against the limit.
+    ctx.currentTagDepth = previousTagDepth
+
     return {
       value: taggedValue,
       bytesRead: currentOffset - startOffset
@@ -1092,11 +1143,10 @@ export function useCborParser() {
         throw new Error(`Unexpected break code (0xff) at offset ${offset}`)
       }
 
-      const remainingHex = Array.from(buffer.slice(offset))
-        .map(b => b.toString(16).padStart(2, '0'))
-        .join('')
-
-      const result = parseWithSourceMap(remainingHex, mergedOptions)
+      // Zero-copy view of the remaining bytes (parseWithSourceMap accepts
+      // Uint8Array). Avoids the previous O(N^2) per-item hex re-encode that
+      // re-stringified the whole tail of the buffer on every sequence item.
+      const result = parseWithSourceMap(buffer.subarray(offset), mergedOptions)
 
       // Adjust source map offsets to account for sequence position
       const adjustedSourceMap = result.sourceMap.map(entry => ({

package/src/parser/composables/useCborTag.ts

@@ -6,7 +6,7 @@
 
 import type { ParseResult, CborValue, TaggedValue, CborMap, ParseOptions, PlutusConstr, CborByteString } from '../types'
 import { INDEFINITE_SYMBOL, DEFAULT_LIMITS } from '../types'
-import { hexToBytes, readByte, readUint, readBigUint, extractCborHeader, hasDuplicates } from '../utils'
+import { hexToBytes, readByte, readUint, readBigUint, extractCborHeader, hasDuplicates, validateCanonicalInteger } from '../utils'
 import { useCborInteger } from './useCborInteger'
 import { useCborString } from './useCborString'
 import { useCborFloat } from './useCborFloat'
@@ -738,6 +738,13 @@ export function useCborTag() {
 
     // Parse the tag number
     const { tagNumber, bytesConsumed } = parseTagNumber(buffer, offset + 1, additionalInfo)
+
+    // Enforce canonical (shortest-form) tag number encoding when requested.
+    // RFC 8949 §4.2.1 preferred serialization applies to the tag number too.
+    if (options?.validateCanonical) {
+      validateCanonicalInteger(tagNumber, additionalInfo)
+    }
+
     let currentOffset = offset + 1 + bytesConsumed
 
     // Parse the tagged value (recursively)

package/src/parser/types.ts

@@ -33,6 +33,20 @@ export interface ParserLimits {
  */
 export type DupMapKeyMode = 'allow' | 'warn' | 'reject'
 
+/**
+ * Map key ordering for canonical/deterministic encoding and validation.
+ *
+ * - 'length-first': RFC 7049 Section 3.9 "Old Canonical CBOR" — shorter encoded
+ *   keys sort first, ties broken bytewise. This is what Cardano CIP-21 mandates
+ *   for transaction serialization, and is the default in this library.
+ * - 'bytewise': RFC 8949 Section 4.2.1 "Core Deterministic Encoding" — pure
+ *   bytewise lexicographic order of the encoded keys (the modern generic default).
+ *
+ * @see https://cips.cardano.org/cip/CIP-21
+ * @see https://www.rfc-editor.org/rfc/rfc8949.html#section-4.2.1
+ */
+export type MapKeyOrder = 'length-first' | 'bytewise'
+
 /**
  * Parser options for controlling behavior
  */
@@ -58,6 +72,19 @@ export interface ParseOptions {
   validateTagSemantics?: boolean
   /** Validate Plutus constructor semantics (Tags 102, 121-127, 1280-1400) */
   validatePlutusSemantics?: boolean
+  /**
+   * Map key ordering enforced when validateCanonical is set.
+   * Defaults to 'length-first' (Cardano CIP-21 / RFC 7049 Section 3.9).
+   * Use 'bytewise' for RFC 8949 Section 4.2.1 core deterministic order.
+   */
+  mapKeyOrder?: MapKeyOrder
+  /**
+   * Reject trailing bytes after the top-level data item (well-formedness).
+   * Defaults to true for backward compatibility (decode returns bytesRead so
+   * callers can detect leftover data); automatically false-tightened, i.e. set
+   * to reject, in strict mode. Set explicitly to override.
+   */
+  allowTrailingData?: boolean
   /** Resource limits */
   limits?: ParserLimits
 }
@@ -84,11 +111,15 @@ export const DEFAULT_OPTIONS: Required<ParseOptions> = {
   strict: false,
   validateCanonical: false,
   allowIndefinite: true,
-  dupMapKeyMode: 'allow',
+  // Default to 'warn' so duplicate keys are never silently collapsed in the Map
+  // view. Duplicates remain byte-perfect for round-trips via ALL_ENTRIES_SYMBOL.
+  dupMapKeyMode: 'warn',
   validateUtf8Strict: false,
   validateSetUniqueness: false,
   validateTagSemantics: false,
   validatePlutusSemantics: false,
+  mapKeyOrder: 'length-first',
+  allowTrailingData: true,
   limits: DEFAULT_LIMITS
 }
 

package/src/parser/utils.ts

@@ -75,6 +75,12 @@ export const readUint = (buffer: Uint8Array, offset: number, length: number): nu
   for (let i = 0; i < length; i++) {
     result = result * 256 + readByte(buffer, offset + i)
   }
+  // Guard against silent precision loss: values above 2^53 cannot be represented
+  // exactly as a JS number. Callers needing the full 64-bit range must use
+  // readBigUint instead (this helper is only invoked for <= 4-byte fields).
+  if (result > Number.MAX_SAFE_INTEGER) {
+    throw new Error(`Value at offset ${offset} (${length} bytes) exceeds MAX_SAFE_INTEGER; use readBigUint`)
+  }
   return result
 }
 
@@ -344,6 +350,41 @@ export function compareBytes(a: Uint8Array, b: Uint8Array): number {
   return 0 // Equal
 }
 
+/**
+ * Compare two byte arrays in pure bytewise lexicographic order.
+ * This is RFC 8949 Section 4.2.1 "Core Deterministic Encoding" ordering:
+ * compare byte-by-byte; if one is a prefix of the other, the shorter sorts first.
+ * (Contrast with compareBytes above, which sorts length-first per RFC 7049 §3.9.)
+ */
+export function compareBytesLexicographic(a: Uint8Array, b: Uint8Array): number {
+  if (!a || !b) {
+    throw new Error('compareBytesLexicographic: arguments cannot be null or undefined')
+  }
+  const min = Math.min(a.length, b.length)
+  for (let i = 0; i < min; i++) {
+    const byteA = a[i]!
+    const byteB = b[i]!
+    if (byteA !== byteB) {
+      return byteA - byteB
+    }
+  }
+  return a.length - b.length
+}
+
+/**
+ * Compare two encoded map keys according to the requested ordering.
+ *
+ * @param order - 'length-first' (CIP-21 / RFC 7049 §3.9, default) or
+ *                'bytewise' (RFC 8949 §4.2.1 core deterministic)
+ */
+export function compareMapKeys(
+  a: Uint8Array,
+  b: Uint8Array,
+  order: 'length-first' | 'bytewise' = 'length-first'
+): number {
+  return order === 'bytewise' ? compareBytesLexicographic(a, b) : compareBytes(a, b)
+}
+
 /**
  * Serializes a CBOR value to a normalized string for comparison
  * Used for detecting duplicates in sets and ensuring uniqueness