feat!: switch CBOR library to cborg

BREAKING CHANGE!

* Will be much more strict with data types on encode and decode, only
  IPLD Data Model values will be accepted, all others will be rejected
  (including `undefined`). No other tags than 42 will be involved in encode
  or decode.
* Will strictly reject decode of data where integers are encoded using more
  bytes than are required, as per deterministic DAG-CBOR rules.
* Strictly only tag 42 and no others. Also no exotic types like Simple Values.
* Indefinite length items will not be accepted for decode.
* BigInt will be used for integers decoded outside of the safe integer range.
  They are also accepted for encodes, within the 64-bit range. The exotic
  bignumber type from borc is no longer supported.
* Floats are now always encoded as 64-bit, to match the updated DAG-CBOR spec
  and the Go implementation.
* Uint8Arrays are native through the stack now, `Buffer` isn't required for
  browser bundling.

Author: rvagg

index.js

@@ -1,141 +1,70 @@
 // @ts-check
 
-import cbor from 'borc'
-import isCircular from '@ipld/is-circular'
+import * as cborg from 'cborg'
 // @ts-ignore
-import { bytes, CID } from 'multiformats'
-
-const { asCID } = CID
-const decodeCID = CID.decode
+import { CID } from 'multiformats'
 
 // https://github.com/ipfs/go-ipfs/issues/3570#issuecomment-273931692
 const CID_CBOR_TAG = 42
-
 const code = 0x71
 const name = 'dag-cbor'
 
-function tagCID (cid) {
-  const tag = bytes.fromHex('00')
-  const buffer = new Uint8Array(tag.byteLength + cid.bytes.byteLength)
-  buffer.set(tag)
-  buffer.set(cid.bytes, tag.byteLength)
-  const tagged = new cbor.Tagged(CID_CBOR_TAG, buffer, null)
-  return tagged
-}
-
-function replaceCIDbyTAG (dagNode, config) {
-  if (dagNode && typeof dagNode === 'object' && isCircular(dagNode, { asCID: true })) {
-    throw new Error('The object passed has circular references')
+// this will receive all Objects, we need to filter out anything that's not
+// a CID and return `null` for that so it's encoded as normal
+function cidEncoder (obj) {
+  if (obj.asCID !== obj) {
+    return null // any other kind of object
   }
-
-  function transform (obj) {
-    if (bytes.isBinary(obj)) return bytes.coerce(obj)
-    if (!obj || typeof obj === 'string') {
-      return obj
-    }
-
-    if (Array.isArray(obj)) {
-      return obj.map(transform)
-    }
-
-    const cid = asCID(obj, config)
-    if (cid) {
-      return tagCID(cid)
-    }
-
-    const keys = Object.keys(obj)
-
-    if (keys.length > 0) {
-      // Recursive transform
-      const out = {}
-      keys.forEach((key) => {
-        if (typeof obj[key] === 'object') {
-          out[key] = transform(obj[key])
-        } else {
-          out[key] = obj[key]
-        }
-      })
-      return out
-    } else {
-      return obj
-    }
+  const cid = CID.asCID(obj)
+  /* c8 ignore next 4 */
+  // very unlikely case, and it'll probably throw a recursion error in cborg
+  if (!cid) {
+    return null
   }
-
-  return transform(dagNode)
+  const bytes = new Uint8Array(cid.bytes.byteLength + 1)
+  bytes.set(cid.bytes, 1) // prefix is 0x00, for historical reasons
+  return [
+    new cborg.Token(cborg.Type.tag, CID_CBOR_TAG),
+    new cborg.Token(cborg.Type.bytes, bytes)
+  ]
 }
 
-const defaultTags = {
-  [CID_CBOR_TAG]: (val) => {
-    return decodeCID(val.subarray(1), cidConfig)
-  }
+function undefinedEncoder () {
+  throw new Error('`undefined` is not supported by the IPLD Data Model and cannot be encoded')
 }
 
-const defaultSize = 64 * 1024 // current decoder heap size, 64 Kb
-const defaultMaxSize = 64 * 1024 * 1024 // max heap size when auto-growing, 64 Mb
-
-let currentSize = defaultSize
-let maxSize = defaultMaxSize
-let decoder = null
-let cidConfig = null
-
-/**
- * Configure the underlying CBOR decoder.
- *
- * @param {Object} [options] - The options the decoder takes. The decoder will reset to the defaul values if no options are given.
- * @param {number} [options.size=65536] - The current heap size used in CBOR parsing, this may grow automatically as larger blocks are encountered up to `maxSize`
- * @param {number} [options.maxSize=67108864] - The maximum size the CBOR parsing heap is allowed to grow to before `dagCBOR.util.deserialize()` returns an error
- * @param {Object} [options.tags] - An object whose keys are CBOR tag numbers and values are transform functions that accept a `value` and return a decoded representation of that `value`
- */
-const configureDecoder = (options) => {
-  const tags = defaultTags
-
-  if (options) {
-    if (typeof options.size === 'number') {
-      currentSize = options.size
-    }
-    if (typeof options.maxSize === 'number') {
-      maxSize = options.maxSize
-    }
-  } else {
-    // no options, reset to defaults
-    currentSize = defaultSize
-    maxSize = defaultMaxSize
-  }
-
-  const decoderOptions = {
-    tags,
-    size: currentSize
+const encodeOptions = {
+  float64: true,
+  typeEncoders: {
+    Object: cidEncoder,
+    undefined: undefinedEncoder
   }
-
-  decoder = new cbor.Decoder(decoderOptions)
-  // borc edits opts.size in-place so we can capture _actual_ size
-  currentSize = decoderOptions.size
 }
-configureDecoder()
 
-const encode = (node, config) => {
-  const nodeTagged = replaceCIDbyTAG(node, config)
-  const serialized = cbor.encode(nodeTagged)
-  return bytes.coerce(serialized)
+function encode (node) {
+  return cborg.encode(node, encodeOptions)
 }
 
-const decode = (data, config) => {
-  cidConfig = config
-  if (data.length > currentSize && data.length <= maxSize) {
-    configureDecoder({ size: data.length })
+function cidDecoder (bytes) {
+  if (bytes[0] !== 0) {
+    throw new Error('Invalid CID for CBOR tag 42; expected leading 0x00')
   }
+  return CID.decode(bytes.subarray(1)) // ignore leading 0x00
+}
 
-  if (data.length > currentSize) {
-    throw new Error('Data is too large to deserialize with current decoder')
-  }
+const decodeOptions = {
+  allowIndefinite: false,
+  allowUndefined: false,
+  allowBigInt: true, // this will lead to BigInt for ints outside of
+  // safe-integer range, which may surprise users
+  strict: true,
+  useMaps: false,
+  tags: []
+}
+decodeOptions.tags[CID_CBOR_TAG] = cidDecoder
 
-  // borc will decode back-to-back objects into an implicit top-level array, we
-  // strictly want to only see a single explicit top-level object
-  const all = decoder.decodeAll(data)
-  if (all.length !== 1) {
-    throw new Error('Extraneous CBOR data found beyond initial top-level object')
-  }
-  return all[0]
+function decode (data) {
+  return cborg.decode(data, decodeOptions)
 }
 
-export { name, code, encode, decode, configureDecoder }
+export { name, code, encode, decode }

package.json

@@ -29,16 +29,16 @@
   },
   "homepage": "https://github.com/ipld/js-dag-cbor",
   "dependencies": {
-    "@ipld/is-circular": "^2.0.0",
-    "borc": "^2.1.2",
+    "cborg": "^1.0.1",
     "multiformats": "^4.0.0"
   },
   "devDependencies": {
-    "garbage": "0.0.0",
+    "chai": "^4.2.0",
     "hundreds": "0.0.8",
-    "mocha": "^8.1.3",
+    "ipld-garbage": "^1.0.3",
+    "mocha": "^8.2.1",
     "polendina": "^1.1.0",
-    "standard": "^14.3.4"
+    "standard": "^16.0.3"
   },
   "directories": {
     "test": "test"

test/test-basics.js

@@ -1,28 +1,13 @@
 /* eslint-env mocha */
 'use strict'
-import garbage from 'garbage'
-import assert from 'assert'
-import { encode, decode, configureDecoder } from '../index.js'
+import garbage from 'ipld-garbage'
+import chai from 'chai'
+import { encode, decode } from '../index.js'
 import { bytes, CID } from 'multiformats'
 
+const { assert } = chai
 const test = it
-const _same = assert.deepStrictEqual
-
-const same = (x, y) => {
-  if (typeof x !== 'object') return _same(x, y)
-  const skip = { nested: null, bytes: null, multihash: null, digest: null, link: null }
-  for (const prop of Object.keys(skip)) {
-    if (x[prop]) same(x[prop], y[prop])
-  }
-  if (x.links) {
-    same(x.links.length, y.links.length)
-    for (let i = 0; i < x.links.length; i++) {
-      same(x[i], y[i])
-    }
-  }
-  skip.links = null
-  _same({ ...x, ...skip }, { ...y, ...skip })
-}
+const same = assert.deepStrictEqual
 
 describe('dag-cbor', () => {
   const obj = {
@@ -36,7 +21,7 @@ describe('dag-cbor', () => {
       hello: 'world',
       link: CID.parse('QmRgutAxd8t7oGkSm4wmeuByG6M51wcTso6cubDdQtuEfL')
     },
-    bytes: Buffer.from('asdf')
+    bytes: new TextEncoder().encode('asdf')
   }
   const serializedObj = encode(obj)
 
@@ -48,7 +33,7 @@ describe('dag-cbor', () => {
     same(bytes.toHex(serializedObj).match(/d82a/g).length, 4)
 
     const deserializedObj = decode(serializedObj)
-    same(obj, deserializedObj)
+    same(deserializedObj, obj)
   })
 
   test('.serialize and .deserialize large objects', () => {
@@ -61,36 +46,6 @@ describe('dag-cbor', () => {
 
     const deserialized = decode(serialized)
     same(largeObj, deserialized)
-    // reset decoder to default
-    configureDecoder()
-  })
-
-  test('.deserialize fail on large objects beyond maxSize', () => {
-    // larger than the default borc heap size, should bust the heap if we turn off auto-grow
-    const dataSize = (128 * 1024) + 1
-    const largeObj = { someKey: [].slice.call(new Uint8Array(dataSize)) }
-
-    configureDecoder({ size: 64 * 1024, maxSize: 128 * 1024 }) // 64 Kb start, 128 Kb max
-    const serialized = encode(largeObj)
-    same(bytes.isBinary(serialized), true)
-
-    assert.throws(() => decode(serialized), /^Error: Data is too large to deserialize with current decoder$/)
-    // reset decoder to default
-    configureDecoder()
-  })
-
-  test('.deserialize fail on large objects beyond maxSize - omit size', () => {
-    // larger than the default borc heap size, should bust the heap if we turn off auto-grow
-    const dataSize = (128 * 1024) + 1
-    const largeObj = { someKey: [].slice.call(new Uint8Array(dataSize)) }
-
-    configureDecoder({ maxSize: 128 * 1024 }) // 64 Kb start, 128 Kb max
-    const serialized = encode(largeObj)
-    same(bytes.isBinary(serialized), true)
-
-    assert.throws(() => decode(serialized), /^Error: Data is too large to deserialize with current decoder$/)
-    // reset decoder to default
-    configureDecoder()
   })
 
   test('.serialize and .deserialize object with slash as property', () => {
@@ -108,15 +63,24 @@ describe('dag-cbor', () => {
     same(actual, expected)
   })
 
-  test('error catching', () => {
-    const circlarObj = {}
-    circlarObj.a = circlarObj
-    assert.throws(() => encode(circlarObj), /^Error: The object passed has circular references$/)
+  test('error on circular references', () => {
+    const circularObj = {}
+    circularObj.a = circularObj
+    assert.throws(() => encode(circularObj), /object contains circular references/)
+    const circularArr = [circularObj]
+    circularObj.a = circularArr
+    assert.throws(() => encode(circularArr), /object contains circular references/)
+  })
+
+  test('error on encoding undefined', () => {
+    assert.throws(() => encode(undefined), /\Wundefined\W.*not supported/)
+    const objWithUndefined = { a: 'a', b: undefined }
+    assert.throws(() => encode(objWithUndefined), /\Wundefined\W.*not supported/)
   })
 
   test('fuzz serialize and deserialize with garbage', () => {
     for (let ii = 0; ii < 1000; ii++) {
-      const original = { in: garbage(100) }
+      const original = garbage(100)
       const encoded = encode(original)
       const decoded = decode(encoded)
       same(decoded, original)
@@ -125,13 +89,12 @@ describe('dag-cbor', () => {
 
   test('CIDv1', () => {
     const link = CID.parse('zdj7Wd8AMwqnhJGQCbFxBVodGSBG84TM7Hs1rcJuQMwTyfEDS')
-
     const encoded = encode({ link })
     const decoded = decode(encoded)
     same(decoded, { link })
   })
 
-  test('encode and decode consistency  with Uint8Array and Buffer fields', () => {
+  test('encode and decode consistency with Uint8Array and Buffer fields', () => {
     const buffer = Buffer.from('some data')
     const bytes = Uint8Array.from(buffer)
 
@@ -155,6 +118,13 @@ describe('dag-cbor', () => {
       // two top-level CBOR objects, the original and a single uint=0, valid if using
       // CBOR in streaming mode, not valid here
       decode(Buffer.concat([Buffer.from(serializedObj), Buffer.alloc(1)]))
-    }, /^Error: Extraneous CBOR data found beyond initial top-level object/)
+    }, /too many terminals/)
+  })
+
+  test('reject bad CID lead-in', () => {
+    // this is the same data as the CIDv1 produces but has the lead-in to the
+    // CID replaced with 0x01 .......................  ↓↓ here
+    const encoded = bytes.fromHex('a1646c696e6bd82a582501017012207252523e6591fb8fe553d67ff55a86f84044b46a3e4176e10c58fa529a4aabd5')
+    assert.throws(() => decode(encoded), /Invalid CID for CBOR tag 42; expected leading 0x00/)
   })
 })