@helia/verified-fetch 0.0.0-f58d467 → 1.0.0

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@helia/verified-fetch",
-  "version": "0.0.0-f58d467",
-  "description": "A fetch-like API for obtaining verified & trustless IPFS content on the web.",
+  "version": "1.0.0",
+  "description": "A fetch-like API for obtaining verified & trustless IPFS content on the web",
   "license": "Apache-2.0 OR MIT",
-  "homepage": "https://github.com/ipfs/helia/tree/main/packages/verified-fetch#readme",
+  "homepage": "https://github.com/ipfs/helia-verified-fetch/tree/main/packages/verified-fetch#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ipfs/helia.git"
+    "url": "git+https://github.com/ipfs/helia-verified-fetch.git"
   },
   "bugs": {
-    "url": "https://github.com/ipfs/helia/issues"
+    "url": "https://github.com/ipfs/helia-verified-fetch/issues"
   },
   "publishConfig": {
     "access": "public",
@@ -41,95 +41,11 @@
       "sourceType": "module"
     }
   },
-  "release": {
-    "branches": [
-      "main"
-    ],
-    "plugins": [
-      [
-        "@semantic-release/commit-analyzer",
-        {
-          "preset": "conventionalcommits",
-          "releaseRules": [
-            {
-              "breaking": true,
-              "release": "major"
-            },
-            {
-              "revert": true,
-              "release": "patch"
-            },
-            {
-              "type": "feat",
-              "release": "minor"
-            },
-            {
-              "type": "fix",
-              "release": "patch"
-            },
-            {
-              "type": "docs",
-              "release": "patch"
-            },
-            {
-              "type": "test",
-              "release": "patch"
-            },
-            {
-              "type": "deps",
-              "release": "patch"
-            },
-            {
-              "scope": "no-release",
-              "release": false
-            }
-          ]
-        }
-      ],
-      [
-        "@semantic-release/release-notes-generator",
-        {
-          "preset": "conventionalcommits",
-          "presetConfig": {
-            "types": [
-              {
-                "type": "feat",
-                "section": "Features"
-              },
-              {
-                "type": "fix",
-                "section": "Bug Fixes"
-              },
-              {
-                "type": "chore",
-                "section": "Trivial Changes"
-              },
-              {
-                "type": "docs",
-                "section": "Documentation"
-              },
-              {
-                "type": "deps",
-                "section": "Dependencies"
-              },
-              {
-                "type": "test",
-                "section": "Tests"
-              }
-            ]
-          }
-        }
-      ],
-      "@semantic-release/changelog",
-      "@semantic-release/npm",
-      "@semantic-release/github",
-      "@semantic-release/git"
-    ]
-  },
   "scripts": {
     "clean": "aegir clean",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
     "build": "aegir build",
     "test": "aegir test",
     "test:chrome": "aegir test -t browser --cov",
@@ -141,36 +57,57 @@
     "release": "aegir release"
   },
   "dependencies": {
-    "@helia/block-brokers": "2.0.1-f58d467",
-    "@helia/dag-cbor": "3.0.0-f58d467",
-    "@helia/dag-json": "3.0.0-f58d467",
-    "@helia/http": "1.0.1-f58d467",
-    "@helia/interface": "4.0.0-f58d467",
-    "@helia/ipns": "6.0.0-f58d467",
-    "@helia/json": "3.0.0-f58d467",
-    "@helia/routers": "1.0.0-f58d467",
-    "@helia/unixfs": "3.0.0-f58d467",
-    "@ipld/dag-cbor": "^9.1.0",
-    "@ipld/dag-json": "^10.1.7",
-    "@ipld/dag-pb": "^4.0.8",
-    "@libp2p/interface": "^1.1.2",
-    "@libp2p/peer-id": "^4.0.5",
+    "@helia/block-brokers": "^2.0.2",
+    "@helia/car": "^3.1.0",
+    "@helia/http": "^1.0.2",
+    "@helia/interface": "^4.0.1",
+    "@helia/ipns": "^6.0.1",
+    "@helia/routers": "^1.0.1",
+    "@helia/unixfs": "^3.0.1",
+    "@ipld/dag-cbor": "^9.2.0",
+    "@ipld/dag-json": "^10.2.0",
+    "@ipld/dag-pb": "^4.1.0",
+    "@libp2p/interface": "^1.1.4",
+    "@libp2p/kad-dht": "^12.0.8",
+    "@libp2p/peer-id": "^4.0.7",
+    "cborg": "^4.0.9",
     "hashlru": "^2.3.0",
+    "interface-blockstore": "^5.2.10",
+    "interface-datastore": "^8.2.11",
     "ipfs-unixfs-exporter": "^13.5.0",
-    "multiformats": "^13.0.1",
-    "progress-events": "^1.0.0"
+    "it-map": "^3.0.5",
+    "it-pipe": "^3.0.1",
+    "it-tar": "^6.0.5",
+    "it-to-browser-readablestream": "^2.0.6",
+    "multiformats": "^13.1.0",
+    "progress-events": "^1.0.0",
+    "uint8arrays": "^5.0.2"
   },
   "devDependencies": {
-    "@libp2p/logger": "^4.0.5",
-    "@libp2p/peer-id-factory": "^4.0.5",
+    "@helia/car": "^3.1.0",
+    "@helia/dag-cbor": "^3.0.1",
+    "@helia/dag-json": "^3.0.1",
+    "@helia/json": "^3.0.1",
+    "@helia/utils": "^0.0.2",
+    "@ipld/car": "^5.3.0",
+    "@libp2p/logger": "^4.0.7",
+    "@libp2p/peer-id-factory": "^4.0.7",
     "@sgtpooki/file-type": "^1.0.1",
     "@types/sinon": "^17.0.3",
-    "aegir": "^42.2.2",
-    "helia": "4.0.1-f58d467",
+    "aegir": "^42.2.5",
+    "blockstore-core": "^4.4.0",
+    "browser-readablestream-to-it": "^2.0.5",
+    "datastore-core": "^9.2.9",
+    "helia": "^4.0.2",
+    "ipfs-unixfs-importer": "^15.2.4",
+    "ipns": "^9.0.0",
+    "it-all": "^3.0.4",
+    "it-last": "^3.0.4",
+    "it-to-buffer": "^4.0.5",
     "magic-bytes.js": "^1.8.0",
+    "p-defer": "^4.0.0",
     "sinon": "^17.0.1",
-    "sinon-ts": "^2.0.0",
-    "uint8arrays": "^5.0.1"
+    "sinon-ts": "^2.0.0"
   },
   "sideEffects": false
 }

package/src/index.ts

@@ -3,7 +3,7 @@
  *
  * `@helia/verified-fetch` provides a [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-like API for retrieving content from the [IPFS](https://ipfs.tech/) network.
  *
- * All content is retrieved in a [trustless manner](https://www.techopedia.com/definition/trustless), and the integrity of all bytes are verified by comparing hashes of the data.
+ * All content is retrieved in a [trustless manner](https://www.techopedia.com/definition/trustless), and the integrity of all bytes are verified by comparing hashes of the data. By default, CIDs are retrieved over HTTP from [trustless gateways](https://specs.ipfs.tech/http-gateways/trustless-gateway/).
  *
  * This is a marked improvement over `fetch` which offers no such protections and is vulnerable to all sorts of attacks like [Content Spoofing](https://owasp.org/www-community/attacks/Content_Spoofing), [DNS Hijacking](https://en.wikipedia.org/wiki/DNS_hijacking), etc.
  *
@@ -33,7 +33,7 @@
  * import { verifiedFetch } from '@helia/verified-fetch'
  * import { CID } from 'multiformats/cid'
  *
- * const cid = CID.parse('bafyFoo') // some image file
+ * const cid = CID.parse('bafyFoo') // some json file
  * const response = await verifiedFetch(cid)
  * const json = await response.json()
  * ```
@@ -56,7 +56,7 @@
  * import { verifiedFetch } from '@helia/verified-fetch'
  *
  * const response = await verifiedFetch('ipns://mydomain.com/path/to/very-long-file.log')
- * const bigFileStreamReader = await response.body.getReader()
+ * const bigFileStreamReader = await response.body?.getReader()
  * ```
  *
  * ## Configuration
@@ -73,8 +73,8 @@
  * import { createVerifiedFetch } from '@helia/verified-fetch'
  *
  * const fetch = await createVerifiedFetch({
- *  gateways: ['https://trustless-gateway.link'],
- *  routers: ['http://delegated-ipfs.dev']
+ *   gateways: ['https://trustless-gateway.link'],
+ *   routers: ['http://delegated-ipfs.dev']
  * })
  *
  * const resp = await fetch('ipfs://bafy...')
@@ -98,13 +98,13 @@
  *
  * const fetch = await createVerifiedFetch(
  *   await createHeliaHTTP({
- *       blockBrokers: [
- *         trustlessGateway({
- *           gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
- *         })
- *       ],
- *       routers: ['http://delegated-ipfs.dev'].map((routerUrl) => delegatedHTTPRouting(routerUrl))
- *     })
+ *     blockBrokers: [
+ *       trustlessGateway({
+ *         gateways: ['https://mygateway.example.net', 'https://trustless-gateway.link']
+ *       })
+ *     ],
+ *     routers: ['http://delegated-ipfs.dev'].map((routerUrl) => delegatedHTTPRouting(routerUrl))
+ *   })
  * )
  *
  * const resp = await fetch('ipfs://bafy...')
@@ -114,7 +114,7 @@
  *
  * ### Custom content-type parsing
  *
- * By default, `@helia/verified-fetch` sets the `Content-Type` header as `application/octet-stream` - this is because the `.json()`, `.text()`, `.blob()`, and `.arrayBuffer()` methods will usually work as expected without a detailed content type.
+ * By default, if the response can be parsed as JSON, `@helia/verified-fetch` sets the `Content-Type` header as `application/json`, otherwise it sets it as `application/octet-stream` - this is because the `.json()`, `.text()`, `.blob()`, and `.arrayBuffer()` methods will usually work as expected without a detailed content type.
  *
  * If you require an accurate content-type you can provide a `contentTypeParser` function as an option to `createVerifiedFetch` to handle parsing the content type.
  *
@@ -127,16 +127,258 @@
  * import { fileTypeFromBuffer } from '@sgtpooki/file-type'
  *
  * const fetch = await createVerifiedFetch({
- *  gateways: ['https://trustless-gateway.link'],
- *  routers: ['http://delegated-ipfs.dev'],
- *  contentTypeParser: async (bytes) => {
- *    // call to some magic-byte recognition library like magic-bytes, file-type, or your own custom byte recognition
- *    const result = await fileTypeFromBuffer(bytes)
- *    return result?.mime
- *  }
+ *   gateways: ['https://trustless-gateway.link'],
+ *   routers: ['http://delegated-ipfs.dev']
+ * }, {
+ *   contentTypeParser: async (bytes) => {
+ *     // call to some magic-byte recognition library like magic-bytes, file-type, or your own custom byte recognition
+ *     const result = await fileTypeFromBuffer(bytes)
+ *     return result?.mime
+ *   }
  * })
  * ```
  *
+ * ### Custom DNS resolvers
+ *
+ * If you don't want to leak DNS queries to the default resolvers, you can provide your own list of DNS resolvers to `createVerifiedFetch`.
+ *
+ * Note that you do not need to provide both a DNS-over-HTTPS and a DNS-over-JSON resolver, and you should prefer `dnsJsonOverHttps` resolvers for usage in the browser for a smaller bundle size. See https://github.com/ipfs/helia/tree/main/packages/ipns#example---using-dns-json-over-https for more information.
+ *
+ * @example Customizing DNS resolvers
+ *
+ * ```typescript
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
+ * import { dnsJsonOverHttps, dnsOverHttps } from '@helia/ipns/dns-resolvers'
+ *
+ * const fetch = await createVerifiedFetch({
+ *   gateways: ['https://trustless-gateway.link'],
+ *   routers: ['http://delegated-ipfs.dev'],
+ *   dnsResolvers: [
+ *     dnsJsonOverHttps('https://my-dns-resolver.example.com/dns-json'),
+ *     dnsOverHttps('https://my-dns-resolver.example.com/dns-query')
+ *   ]
+ * })
+ * ```
+ *
+ * ### IPLD codec handling
+ *
+ * IPFS supports several data formats (typically referred to as codecs) which are included in the CID. `@helia/verified-fetch` attempts to abstract away some of the details for easier consumption.
+ *
+ * #### DAG-PB
+ *
+ * [DAG-PB](https://ipld.io/docs/codecs/known/dag-pb/) is the codec we are most likely to encounter, it is what [UnixFS](https://github.com/ipfs/specs/blob/main/UNIXFS.md) uses under the hood.
+ *
+ * ##### Using the DAG-PB codec as a Blob
+ *
+ * ```typescript
+ * import { verifiedFetch } from '@helia/verified-fetch'
+ *
+ * const res = await verifiedFetch('ipfs://Qmfoo')
+ * const blob = await res.blob()
+ *
+ * console.info(blob) // Blob { size: x, type: 'application/octet-stream' }
+ * ```
+ *
+ * ##### Using the DAG-PB codec as an ArrayBuffer
+ *
+ * ```typescript
+ * import { verifiedFetch } from '@helia/verified-fetch'
+ *
+ * const res = await verifiedFetch('ipfs://Qmfoo')
+ * const buf = await res.arrayBuffer()
+ *
+ * console.info(buf) // ArrayBuffer { [Uint8Contents]: < ... >, byteLength: x }
+ * ```
+ *
+ * ##### Using the DAG-PB codec as a stream
+ *
+ * ```typescript
+ * import { verifiedFetch } from '@helia/verified-fetch'
+ *
+ * const res = await verifiedFetch('ipfs://Qmfoo')
+ * const reader = res.body?.getReader()
+ *
+ * if (reader == null) {
+ *   throw new Error('Could not create reader from response body')
+ * }
+ *
+ * while (true) {
+ *   const next = await reader.read()
+ *
+ *   if (next?.done === true) {
+ *     break
+ *   }
+ *
+ *   if (next?.value != null) {
+ *     console.info(next.value) // Uint8Array(x) [ ... ]
+ *   }
+ * }
+ * ```
+ *
+ * ##### Content-Type
+ *
+ * When fetching `DAG-PB` data, the content type will be set to `application/octet-stream` unless a custom content-type parser is configured.
+ *
+ * #### JSON
+ *
+ * The JSON codec is a very simple codec, a block parseable with this codec is a JSON string encoded into a `Uint8Array`.
+ *
+ * ##### Using the JSON codec
+ *
+ * ```typescript
+ * import * as json from 'multiformats/codecs/json'
+ *
+ * const block = new TextEncoder().encode('{ "hello": "world" }')
+ * const obj = json.decode(block)
+ *
+ * console.info(obj) // { hello: 'world' }
+ * ```
+ *
+ * ##### Content-Type
+ *
+ * When the `JSON` codec is encountered, the `Content-Type` header of the response will be set to `application/json`.
+ *
+ * ### DAG-JSON
+ *
+ * [DAG-JSON](https://ipld.io/docs/codecs/known/dag-json/) expands on the `JSON` codec, adding the ability to contain [CID](https://docs.ipfs.tech/concepts/content-addressing/)s which act as links to other blocks, and byte arrays.
+ *
+ * `CID`s and byte arrays are represented using special object structures with a single `"/"` property.
+ *
+ * Using `DAG-JSON` has two important caveats:
+ *
+ * 1. Your `JSON` structure cannot contain an object with only a `"/"` property, as it will be interpreted as a special type.
+ * 2. Since `JSON` has no technical limit on number sizes, `DAG-JSON` also allows numbers larger than `Number.MAX_SAFE_INTEGER`. JavaScript requires use of `BigInt`s to represent numbers larger than this, and `JSON.parse` does not support them, so precision will be lost.
+ *
+ * Otherwise this codec follows the same rules as the `JSON` codec.
+ *
+ * ##### Using the DAG-JSON codec
+ *
+ * ```typescript
+ * import * as dagJson from '@ipld/dag-json'
+ *
+ * const block = new TextEncoder().encode(`{
+ *   "hello": "world",
+ *   "cid": {
+ *     "/": "baeaaac3imvwgy3zao5xxe3de"
+ *   },
+ *   "buf": {
+ *     "/": {
+ *       "bytes": "AAECAwQ"
+ *     }
+ *   }
+ * }`)
+ *
+ * const obj = dagJson.decode(block)
+ *
+ * console.info(obj)
+ * // {
+ * // hello: 'world',
+ * // cid: CID(baeaaac3imvwgy3zao5xxe3de),
+ * // buf: Uint8Array(5) [ 0, 1, 2, 3, 4 ]
+ * // }
+ * ```
+ *
+ * ##### Content-Type
+ *
+ * When the `DAG-JSON` codec is encountered in the requested CID, the `Content-Type` header of the response will be set to `application/json`.
+ *
+ * `DAG-JSON` data can be parsed from the response by using the `.json()` function, which will return `CID`s/byte arrays as plain `{ "/": ... }` objects:
+ *
+ * ```typescript
+ * import { verifiedFetch } from '@helia/verified-fetch'
+ * import * as dagJson from '@ipld/dag-json'
+ *
+ * const res = await verifiedFetch('ipfs://bafyDAGJSON')
+ *
+ * // either:
+ * const obj = await res.json()
+ * console.info(obj.cid) // { "/": "baeaaac3imvwgy3zao5xxe3de" }
+ * console.info(obj.buf) // { "/": { "bytes": "AAECAwQ" } }
+ * ```
+ *
+ * Alternatively, it can be decoded using the `@ipld/dag-json` module and the `.arrayBuffer()` method, in which case you will get `CID` objects and `Uint8Array`s:
+ *
+ *```typescript
+ * import { verifiedFetch } from '@helia/verified-fetch'
+ * import * as dagJson from '@ipld/dag-json'
+ *
+ * const res = await verifiedFetch('ipfs://bafyDAGJSON')
+ *
+ * // or:
+ * const obj = dagJson.decode<any>(await res.arrayBuffer())
+ * console.info(obj.cid) // CID(baeaaac3imvwgy3zao5xxe3de)
+ * console.info(obj.buf) // Uint8Array(5) [ 0, 1, 2, 3, 4 ]
+ * ```
+ *
+ * #### DAG-CBOR
+ *
+ * [DAG-CBOR](https://ipld.io/docs/codecs/known/dag-cbor/) uses the [Concise Binary Object Representation](https://cbor.io/) format for serialization instead of JSON.
+ *
+ * This supports more datatypes in a safer way than JSON and is smaller on the wire to boot so is usually preferable to JSON or DAG-JSON.
+ *
+ * ##### Content-Type
+ *
+ * Not all data types supported by `DAG-CBOR` can be successfully turned into JSON and back into the same binary form.
+ *
+ * When a decoded block can be round-tripped to JSON, the `Content-Type` will be set to `application/json`. In this case the `.json()` method on the `Response` object can be used to obtain an object representation of the response.
+ *
+ * When it cannot, the `Content-Type` will be `application/octet-stream` - in this case the `@ipld/dag-json` module must be used to deserialize the return value from `.arrayBuffer()`.
+ *
+ * ##### Detecting JSON-safe DAG-CBOR
+ *
+ * If the `Content-Type` header of the response is `application/json`, the `.json()` method may be used to access the response body in object form, otherwise the `.arrayBuffer()` method must be used to decode the raw bytes using the `@ipld/dag-cbor` module.
+ *
+ * ```typescript
+ * import { verifiedFetch } from '@helia/verified-fetch'
+ * import * as dagCbor from '@ipld/dag-cbor'
+ *
+ * const res = await verifiedFetch('ipfs://bafyDagCborCID')
+ * let obj
+ *
+ * if (res.headers.get('Content-Type') === 'application/json') {
+ *   // DAG-CBOR data can be safely decoded as JSON
+ *   obj = await res.json()
+ * } else {
+ *   // response contains non-JSON friendly data types
+ *   obj = dagCbor.decode(await res.arrayBuffer())
+ * }
+ *
+ * console.info(obj) // ...
+ * ```
+ *
+ * ## The `Accept` header
+ *
+ * The `Accept` header can be passed to override certain response processing, or to ensure that the final `Content-Type` of the response is the one that is expected.
+ *
+ * If the final `Content-Type` does not match the `Accept` header, or if the content cannot be represented in the format dictated by the `Accept` header, or you have configured a custom content type parser, and that parser returns a value that isn't in the accept header, a [406: Not Acceptable](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/406) response will be returned:
+ *
+ * ```typescript
+ * import { verifiedFetch } from '@helia/verified-fetch'
+ *
+ * const res = await verifiedFetch('ipfs://bafyJPEGImageCID', {
+ *   headers: {
+ *     accept: 'image/png'
+ *   }
+ * })
+ *
+ * console.info(res.status) // 406 - the image was a JPEG but we specified PNG as the accept header
+ * ```
+ *
+ * It can also be used to skip processing the data from some formats such as `DAG-CBOR` if you wish to handle decoding it yourself:
+ *
+ * ```typescript
+ * import { verifiedFetch } from '@helia/verified-fetch'
+ *
+ * const res = await verifiedFetch('ipfs://bafyDAGCBORCID', {
+ *   headers: {
+ *     accept: 'application/octet-stream'
+ *   }
+ * })
+ *
+ * console.info(res.headers.get('accept')) // application/octet-stream
+ * const buf = await res.arrayBuffer() // raw bytes, not processed as JSON
+ * ```
+ *
  * ## Comparison to fetch
  *
  * This module attempts to act as similarly to the `fetch()` API as possible.
@@ -154,7 +396,7 @@
  * 2. IPNS protocol: `ipns://<peerId>` & `ipns://<publicKey>` & `ipns://<hostUri_Supporting_DnsLink_TxtRecords>`
  * 3. CID instances: An actual CID instance `CID.parse('bafy...')`
  *
- * As well as support for pathing & params for item 1 & 2 above according to [IPFS - Path Gateway Specification](https://specs.ipfs.tech/http-gateways/path-gateway) & [IPFS - Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/). Further refinement of those specifications specifically for web-based scenarios can be found in the [Web Pathing Specification IPIP](https://github.com/ipfs/specs/pull/453).
+ * As well as support for pathing & params for items 1 & 2 above according to [IPFS - Path Gateway Specification](https://specs.ipfs.tech/http-gateways/path-gateway) & [IPFS - Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/). Further refinement of those specifications specifically for web-based scenarios can be found in the [Web Pathing Specification IPIP](https://github.com/ipfs/specs/pull/453).
  *
  * If you pass a CID instance, it assumes you want the content for that specific CID only, and does not support pathing or params for that CID.
  *
@@ -256,7 +498,7 @@ import { createHeliaHTTP } from '@helia/http'
 import { delegatedHTTPRouting } from '@helia/routers'
 import { VerifiedFetch as VerifiedFetchClass } from './verified-fetch.js'
 import type { Helia } from '@helia/interface'
-import type { IPNSRoutingEvents, ResolveDnsLinkProgressEvents, ResolveProgressEvents } from '@helia/ipns'
+import type { DNSResolver, IPNSRoutingEvents, ResolveDnsLinkProgressEvents, ResolveProgressEvents } from '@helia/ipns'
 import type { GetEvents } from '@helia/unixfs'
 import type { CID } from 'multiformats/cid'
 import type { ProgressEvent, ProgressOptions } from 'progress-events'
@@ -266,8 +508,12 @@ import type { ProgressEvent, ProgressOptions } from 'progress-events'
  */
 export type Resource = string | CID
 
+export interface ResourceDetail {
+  resource: Resource
+}
+
 export interface CIDDetail {
-  cid: string
+  cid: CID
   path: string
 }
 
@@ -285,15 +531,31 @@ export interface VerifiedFetch {
  * Instead of passing a Helia instance, you can pass a list of gateways and
  * routers, and a HeliaHTTP instance will be created for you.
  */
-export interface CreateVerifiedFetchOptions {
+export interface CreateVerifiedFetchInit {
   gateways: string[]
   routers?: string[]
 
+  /**
+   * In order to parse DNSLink records, we need to resolve DNS queries. You can
+   * pass a list of DNS resolvers that we will provide to the @helia/ipns
+   * instance for you. You must construct them using the `dnsJsonOverHttps` or
+   * `dnsOverHttps` functions exported from `@helia/ipns/dns-resolvers`.
+   *
+   * We use cloudflare and google's dnsJsonOverHttps resolvers by default.
+   *
+   * @default [dnsJsonOverHttps('https://mozilla.cloudflare-dns.com/dns-query'),dnsJsonOverHttps('https://dns.google/resolve')]
+   */
+  dnsResolvers?: DNSResolver[]
+}
+
+export interface CreateVerifiedFetchOptions {
   /**
    * A function to handle parsing content type from bytes. The function you
    * provide will be passed the first set of bytes we receive from the network,
    * and should return a string that will be used as the value for the
    * `Content-Type` header in the response.
+   *
+   * @default undefined
    */
   contentTypeParser?: ContentTypeParser
 }
@@ -338,11 +600,10 @@ export interface VerifiedFetchInit extends RequestInit, ProgressOptions<BubbledP
 /**
  * Create and return a Helia node
  */
-export async function createVerifiedFetch (init?: Helia | CreateVerifiedFetchOptions): Promise<VerifiedFetch> {
-  let contentTypeParser: ContentTypeParser | undefined
-
+export async function createVerifiedFetch (init?: Helia | CreateVerifiedFetchInit, options?: CreateVerifiedFetchOptions): Promise<VerifiedFetch> {
+  let dnsResolvers: DNSResolver[] | undefined
   if (!isHelia(init)) {
-    contentTypeParser = init?.contentTypeParser
+    dnsResolvers = init?.dnsResolvers
     init = await createHeliaHTTP({
       blockBrokers: [
         trustlessGateway({
@@ -353,7 +614,7 @@ export async function createVerifiedFetch (init?: Helia | CreateVerifiedFetchOpt
     })
   }
 
-  const verifiedFetchInstance = new VerifiedFetchClass({ helia: init }, { contentTypeParser })
+  const verifiedFetchInstance = new VerifiedFetchClass({ helia: init }, { dnsResolvers, ...options })
   async function verifiedFetch (resource: Resource, options?: VerifiedFetchInit): Promise<Response> {
     return verifiedFetchInstance.fetch(resource, options)
   }

package/src/types.ts

@@ -0,0 +1 @@
+export type RequestFormatShorthand = 'raw' | 'car' | 'tar' | 'ipns-record' | 'dag-json' | 'dag-cbor' | 'json' | 'cbor'

package/src/utils/dag-cbor-to-safe-json.ts

@@ -0,0 +1,44 @@
+import { decode } from 'cborg'
+import { encode } from 'cborg/json'
+import { CID } from 'multiformats/cid'
+import type { TagDecoder } from 'cborg'
+
+// https://github.com/ipfs/go-ipfs/issues/3570#issuecomment-273931692
+const CID_CBOR_TAG = 0x2A
+
+function cidDecoder (bytes: Uint8Array): CID {
+  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
+}
+
+/**
+ * Take a `DAG-CBOR` encoded `Uint8Array`, deserialize it as an object and
+ * re-serialize it in a form that can be passed to `JSON.serialize` and then
+ * `JSON.parse` without losing any data.
+ */
+export function dagCborToSafeJSON (buf: Uint8Array): string {
+  const tags: TagDecoder[] = []
+  tags[CID_CBOR_TAG] = cidDecoder
+
+  const obj = decode(buf, {
+    allowIndefinite: false,
+    coerceUndefinedToNull: true,
+    allowNaN: false,
+    allowInfinity: false,
+    strict: true,
+    useMaps: false,
+    rejectDuplicateMapKeys: true,
+    tags,
+
+    // this is different to `DAG-CBOR` - the reason we disallow BigInts is
+    // because we are about to re-encode to `JSON` which does not support
+    // BigInts. Blocks containing large numbers should be deserialized using a
+    // cbor decoder instead
+    allowBigInt: false
+  })
+
+  return new TextDecoder().decode(encode(obj))
+}