@helia/verified-fetch 2.1.2 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helia/verified-fetch",
-  "version": "2.1.2",
+  "version": "2.2.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-verified-fetch/tree/main/packages/verified-fetch#readme",
@@ -142,52 +142,55 @@
     "release": "aegir release"
   },
   "dependencies": {
-    "@helia/block-brokers": "^4.0.0",
-    "@helia/car": "^4.0.0",
-    "@helia/http": "^2.0.0",
-    "@helia/interface": "^5.0.0",
-    "@helia/ipns": "^8.0.0",
-    "@helia/routers": "^2.0.0",
-    "@helia/unixfs": "^4.0.0",
+    "@helia/block-brokers": "^4.0.2",
+    "@helia/car": "^4.0.1",
+    "@helia/delegated-routing-v1-http-api-client": "^4.2.1",
+    "@helia/interface": "^5.1.0",
+    "@helia/ipns": "^8.0.1",
+    "@helia/routers": "^2.2.0",
+    "@helia/unixfs": "^4.0.1",
     "@ipld/dag-cbor": "^9.2.1",
     "@ipld/dag-json": "^10.2.2",
     "@ipld/dag-pb": "^4.1.2",
-    "@libp2p/interface": "^2.1.3",
-    "@libp2p/kad-dht": "^14.0.1",
-    "@libp2p/peer-id": "^5.0.5",
+    "@libp2p/interface": "^2.2.1",
+    "@libp2p/kad-dht": "^14.1.3",
+    "@libp2p/peer-id": "^5.0.8",
+    "@libp2p/webrtc": "^5.0.16",
+    "@libp2p/websockets": "^9.0.11",
     "@multiformats/dns": "^1.0.6",
     "cborg": "^4.2.4",
     "hashlru": "^2.3.0",
+    "helia": "^5.1.0",
     "interface-blockstore": "^5.3.1",
     "interface-datastore": "^8.3.1",
     "ipfs-unixfs-exporter": "^13.6.1",
+    "ipns": "^10.0.0",
     "it-map": "^3.1.1",
     "it-pipe": "^3.0.1",
     "it-tar": "^6.0.5",
     "it-to-browser-readablestream": "^2.0.9",
+    "libp2p": "^2.2.1",
     "lru-cache": "^11.0.2",
-    "multiformats": "^13.3.0",
+    "multiformats": "^13.3.1",
     "progress-events": "^1.0.1",
     "uint8arrays": "^5.1.0"
   },
   "devDependencies": {
-    "@helia/dag-cbor": "^4.0.0",
-    "@helia/dag-json": "^4.0.0",
-    "@helia/json": "^4.0.0",
-    "@helia/utils": "^1.0.0",
+    "@helia/dag-cbor": "^4.0.1",
+    "@helia/dag-json": "^4.0.1",
+    "@helia/http": "^2.0.1",
+    "@helia/json": "^4.0.1",
     "@ipld/car": "^5.3.2",
-    "@libp2p/crypto": "^5.0.5",
-    "@libp2p/interface-compliance-tests": "^6.1.6",
-    "@libp2p/logger": "^5.1.1",
+    "@libp2p/crypto": "^5.0.7",
+    "@libp2p/logger": "^5.1.4",
     "@sgtpooki/file-type": "^1.0.1",
     "@types/sinon": "^17.0.3",
     "aegir": "^45.0.1",
     "blockstore-core": "^5.0.2",
     "browser-readablestream-to-it": "^2.0.7",
     "datastore-core": "^10.0.2",
-    "helia": "^5.0.0",
+    "helia": "^5.1.1",
     "ipfs-unixfs-importer": "^15.3.1",
-    "ipns": "^10.0.0",
     "it-all": "^3.0.6",
     "it-drain": "^3.0.7",
     "it-last": "^3.0.6",
@@ -197,5 +200,8 @@
     "sinon": "^18.0.0",
     "sinon-ts": "^2.0.0"
   },
+  "browser": {
+    "./dist/src/utils/libp2p-defaults.js": "./dist/src/utils/libp2p-defaults.browser.js"
+  },
   "sideEffects": false
 }

package/src/index.ts

@@ -3,11 +3,13 @@
  *
  * `@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. By default, CIDs are retrieved over HTTP from [trustless gateways](https://specs.ipfs.tech/http-gateways/trustless-gateway/).
+ * 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, providers for CIDs are found with delegated routers and retrieved over HTTP from [trustless gateways](https://specs.ipfs.tech/http-gateways/trustless-gateway/), and WebTransport and WebRTC providers if available.
  *
  * 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.
  *
- * A `verifiedFetch` function is exported to get up and running quickly, and a `createVerifiedFetch` function is also available that allows customizing the underlying [Helia](https://helia.io/) node for complete control over how content is retrieved.
+ * A `verifiedFetch` function is exported to get up and running quickly, and a `createVerifiedFetch` function is also available that allows customizing the underlying [Helia](https://ipfs.github.io/helia/) node for complete control over how content is retrieved.
  *
  * Browser-cache-friendly [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects are returned which should be instantly familiar to web developers.
  *
@@ -90,7 +92,7 @@
  *
  * The [helia](https://www.npmjs.com/package/helia) module is configured with a libp2p node that is suited for decentralized applications, alternatively [@helia/http](https://www.npmjs.com/package/@helia/http) is available which uses HTTP gateways for all network operations.
  *
- * You can see variations of Helia and js-libp2p configuration options at <https://helia.io/interfaces/helia.index.HeliaInit.html>.
+ * You can see variations of Helia and js-libp2p configuration options at <https://ipfs.github.io/helia/interfaces/helia.HeliaInit.html>.
  *
  * ```typescript
  * import { trustlessGateway } from '@helia/block-brokers'
@@ -594,13 +596,17 @@
  * 4. `AbortError` - If the content request is aborted due to user aborting provided AbortSignal. Note that this is a `AbortError` from `@libp2p/interface` and not the standard `AbortError` from the Fetch API.
  */
 
-import { trustlessGateway } from '@helia/block-brokers'
-import { createHeliaHTTP } from '@helia/http'
-import { delegatedHTTPRouting, httpGatewayRouting } from '@helia/routers'
+import { bitswap, trustlessGateway } from '@helia/block-brokers'
+import { createDelegatedRoutingV1HttpApiClient } from '@helia/delegated-routing-v1-http-api-client'
+import { type ResolveDNSLinkProgressEvents } from '@helia/ipns'
+import { httpGatewayRouting, libp2pRouting } from '@helia/routers'
+import { type Libp2p, type ServiceMap } from '@libp2p/interface'
 import { dns } from '@multiformats/dns'
+import { createHelia } from 'helia'
+import { createLibp2p, type Libp2pOptions } from 'libp2p'
+import { getLibp2pConfig } from './utils/libp2p-defaults.js'
 import { VerifiedFetch as VerifiedFetchClass } from './verified-fetch.js'
-import type { GetBlockProgressEvents, Helia } from '@helia/interface'
-import type { ResolveDNSLinkProgressEvents } from '@helia/ipns'
+import type { GetBlockProgressEvents, Helia, Routing } from '@helia/interface'
 import type { DNSResolvers, DNS } from '@multiformats/dns'
 import type { DNSResolver } from '@multiformats/dns/resolvers'
 import type { ExporterProgressEvents } from 'ipfs-unixfs-exporter'
@@ -675,6 +681,16 @@ export interface CreateVerifiedFetchInit {
    * @default false
    */
   allowInsecure?: boolean
+
+  /**
+   * We will instantiate a libp2p node for you, but if you want to override the libp2p configuration,
+   * you can pass it here.
+   *
+   * **WARNING**: We use Object.assign to merge the default libp2p configuration from Helia with the one you pass here,
+   * which results in a shallow merge. If you need a deep merge, you should do it yourself before passing the
+   * configuration here.
+   */
+  libp2pConfig?: Partial<Libp2pOptions<ServiceMap>>
 }
 
 export interface CreateVerifiedFetchOptions {
@@ -788,21 +804,41 @@ export interface VerifiedFetchInit extends RequestInit, ProgressOptions<BubbledP
  * Create and return a Helia node
  */
 export async function createVerifiedFetch (init?: Helia | CreateVerifiedFetchInit, options?: CreateVerifiedFetchOptions): Promise<VerifiedFetch> {
+  let libp2p: Libp2p<any> | undefined
   if (!isHelia(init)) {
-    init = await createHeliaHTTP({
-      blockBrokers: [
-        trustlessGateway({
-          allowInsecure: init?.allowInsecure,
-          allowLocal: init?.allowLocal
-        })
-      ],
-      routers: [
-        ...(init?.routers ?? ['https://delegated-ipfs.dev']).map((routerUrl) => delegatedHTTPRouting(routerUrl)),
-        httpGatewayRouting({
-          gateways: init?.gateways ?? ['https://trustless-gateway.link']
-        })
-      ],
-      dns: createDns(init?.dnsResolvers)
+    const dns = createDns(init?.dnsResolvers)
+
+    const libp2pConfig = getLibp2pConfig()
+    libp2pConfig.dns = dns
+
+    const delegatedRouters = init?.routers ?? ['https://delegated-ipfs.dev']
+    for (let index = 0; index < delegatedRouters.length; index++) {
+      const routerUrl = delegatedRouters[index]
+      libp2pConfig.services[`delegatedRouting${index}`] = () => createDelegatedRoutingV1HttpApiClient(routerUrl)
+    }
+    // merge any passed options from init.libp2pConfig into libp2pConfig if it exists
+    if (init?.libp2pConfig != null) {
+      Object.assign(libp2pConfig, init.libp2pConfig)
+    }
+    libp2p = await createLibp2p(libp2pConfig)
+
+    const blockBrokers = [
+      bitswap()
+    ]
+    const routers: Array<Partial<Routing>> = [
+      libp2pRouting(libp2p)
+    ]
+    if (init?.gateways == null || init.gateways.length > 0) {
+      // if gateways is null, or set to a non-empty array, use trustless gateways.
+      blockBrokers.push(trustlessGateway({ allowInsecure: init?.allowInsecure, allowLocal: init?.allowLocal }))
+      routers.push(httpGatewayRouting({ gateways: init?.gateways ?? ['https://trustless-gateway.link'] }))
+    }
+
+    init = await createHelia({
+      libp2p,
+      blockBrokers,
+      dns,
+      routers
     })
   }
 
@@ -810,8 +846,8 @@ export async function createVerifiedFetch (init?: Helia | CreateVerifiedFetchIni
   async function verifiedFetch (resource: Resource, options?: VerifiedFetchInit): Promise<Response> {
     return verifiedFetchInstance.fetch(resource, options)
   }
-  verifiedFetch.stop = verifiedFetchInstance.stop.bind(verifiedFetchInstance)
   verifiedFetch.start = verifiedFetchInstance.start.bind(verifiedFetchInstance)
+  verifiedFetch.stop = verifiedFetchInstance.stop.bind(verifiedFetchInstance)
 
   return verifiedFetch
 }

package/src/utils/get-peer-id-from-string.ts

@@ -0,0 +1,12 @@
+import { peerIdFromCID, peerIdFromString } from '@libp2p/peer-id'
+import { CID } from 'multiformats/cid'
+import type { PeerId } from '@libp2p/interface'
+
+export function getPeerIdFromString (peerIdString: string): PeerId {
+  if (peerIdString.charAt(0) === '1' || peerIdString.charAt(0) === 'Q') {
+    return peerIdFromString(peerIdString)
+  }
+
+  // try resolving as a base36 CID
+  return peerIdFromCID(CID.parse(peerIdString))
+}

package/src/utils/libp2p-defaults.browser.ts

@@ -0,0 +1,28 @@
+import { webRTCDirect } from '@libp2p/webrtc'
+import { webSockets } from '@libp2p/websockets'
+import { libp2pDefaults, type DefaultLibp2pServices } from 'helia'
+import type { ServiceFactoryMap } from './libp2p-types'
+import type { Libp2pOptions } from 'libp2p'
+
+type ServiceMap = Pick<DefaultLibp2pServices, 'dcutr' | 'identify' | 'keychain' | 'ping'>
+
+export function getLibp2pConfig (): Libp2pOptions & Required<Pick<Libp2pOptions, 'services'>> {
+  const libp2pDefaultOptions = libp2pDefaults()
+
+  libp2pDefaultOptions.start = false
+  libp2pDefaultOptions.addresses = { listen: [] }
+  libp2pDefaultOptions.transports = [webRTCDirect(), webSockets()]
+
+  const services: ServiceFactoryMap<ServiceMap> = {
+    dcutr: libp2pDefaultOptions.services.dcutr,
+    identify: libp2pDefaultOptions.services.identify,
+    keychain: libp2pDefaultOptions.services.keychain,
+    ping: libp2pDefaultOptions.services.ping
+  }
+
+  return {
+    ...libp2pDefaultOptions,
+    start: false,
+    services
+  }
+}

package/src/utils/libp2p-defaults.ts

@@ -0,0 +1,38 @@
+import { kadDHT } from '@libp2p/kad-dht'
+import { libp2pDefaults, type DefaultLibp2pServices } from 'helia'
+import { ipnsSelector } from 'ipns/selector'
+import { ipnsValidator } from 'ipns/validator'
+import type { ServiceFactoryMap } from './libp2p-types'
+import type { Libp2pOptions } from 'libp2p'
+
+type ServiceMap = Pick<DefaultLibp2pServices, 'autoNAT' | 'dcutr' | 'dht' | 'identify' | 'keychain' | 'ping' | 'upnp'>
+
+export function getLibp2pConfig (): Libp2pOptions & Required<Pick<Libp2pOptions, 'services'>> {
+  const libp2pDefaultOptions = libp2pDefaults()
+
+  libp2pDefaultOptions.start = false
+
+  const services: ServiceFactoryMap<ServiceMap> = {
+    autoNAT: libp2pDefaultOptions.services.autoNAT,
+    dcutr: libp2pDefaultOptions.services.dcutr,
+    dht: kadDHT({
+      clientMode: true,
+      validators: {
+        ipns: ipnsValidator
+      },
+      selectors: {
+        ipns: ipnsSelector
+      }
+    }),
+    identify: libp2pDefaultOptions.services.identify,
+    keychain: libp2pDefaultOptions.services.keychain,
+    ping: libp2pDefaultOptions.services.ping,
+    upnp: libp2pDefaultOptions.services.upnp
+  }
+
+  return {
+    ...libp2pDefaultOptions,
+    start: false,
+    services
+  }
+}

package/src/utils/libp2p-types.ts

@@ -0,0 +1,8 @@
+import type { DelegatedRoutingV1HttpApiClient } from '@helia/delegated-routing-v1-http-api-client'
+import type { ServiceMap } from '@libp2p/interface'
+
+type DelegatedRoutingServices = Record<`delegatedRouting${number}`, ((components?: unknown) => DelegatedRoutingV1HttpApiClient)>
+
+export type ServiceFactoryMap<T extends ServiceMap = ServiceMap> = {
+  [Property in keyof T]: (components: any & T) => T[Property]
+} & DelegatedRoutingServices

package/src/utils/parse-url-string.ts

@@ -1,5 +1,5 @@
-import { peerIdFromCID, peerIdFromString } from '@libp2p/peer-id'
 import { CID } from 'multiformats/cid'
+import { getPeerIdFromString } from './get-peer-id-from-string.js'
 import { TLRU } from './tlru.js'
 import type { RequestFormatShorthand } from '../types.js'
 import type { DNSLinkResolveResult, IPNS, IPNSResolveResult, IPNSRoutingEvents, ResolveDNSLinkProgressEvents, ResolveProgressEvents, ResolveResult } from '@helia/ipns'
@@ -178,12 +178,7 @@ export async function parseUrlString ({ urlString, ipns, logger }: ParseUrlStrin
       try {
         // try resolving as an IPNS name
 
-        if (cidOrPeerIdOrDnsLink.charAt(0) === '1' || cidOrPeerIdOrDnsLink.charAt(0) === 'Q') {
-          peerId = peerIdFromString(cidOrPeerIdOrDnsLink)
-        } else {
-          // try resolving as a base36 CID
-          peerId = peerIdFromCID(CID.parse(cidOrPeerIdOrDnsLink))
-        }
+        peerId = getPeerIdFromString(cidOrPeerIdOrDnsLink)
         if (peerId.publicKey == null) {
           throw new TypeError('cidOrPeerIdOrDnsLink contains no public key')
         }

package/src/verified-fetch.ts

@@ -5,12 +5,11 @@ import * as ipldDagJson from '@ipld/dag-json'
 import { code as dagPbCode } from '@ipld/dag-pb'
 import { type AbortOptions, type Logger, type PeerId } from '@libp2p/interface'
 import { Record as DHTRecord } from '@libp2p/kad-dht'
-import { peerIdFromCID, peerIdFromString } from '@libp2p/peer-id'
 import { Key } from 'interface-datastore'
 import { exporter } from 'ipfs-unixfs-exporter'
 import toBrowserReadableStream from 'it-to-browser-readablestream'
 import { LRUCache } from 'lru-cache'
-import { CID } from 'multiformats/cid'
+import { type CID } from 'multiformats/cid'
 import { code as jsonCode } from 'multiformats/codecs/json'
 import { code as rawCode } from 'multiformats/codecs/raw'
 import { identity } from 'multiformats/hashes/identity'
@@ -22,6 +21,7 @@ import { ByteRangeContext } from './utils/byte-range-context.js'
 import { dagCborToSafeJSON } from './utils/dag-cbor-to-safe-json.js'
 import { getContentDispositionFilename } from './utils/get-content-disposition-filename.js'
 import { getETag } from './utils/get-e-tag.js'
+import { getPeerIdFromString } from './utils/get-peer-id-from-string.js'
 import { getResolvedAcceptHeader } from './utils/get-resolved-accept-header.js'
 import { getStreamFromAsyncIterable } from './utils/get-stream-from-async-iterable.js'
 import { tarStream } from './utils/get-tar-stream.js'
@@ -159,19 +159,11 @@ export class VerifiedFetch {
       if (resource.startsWith('ipns://')) {
         const peerIdString = resource.replace('ipns://', '')
         this.log.trace('trying to parse peer id from "%s"', peerIdString)
-        peerId = peerIdFromString(peerIdString)
+        peerId = getPeerIdFromString(peerIdString)
       } else {
         const peerIdString = resource.split('.ipns.')[0].split('://')[1]
         this.log.trace('trying to parse peer id from "%s"', peerIdString)
-        let cid: CID
-        try {
-          cid = CID.parse(peerIdString)
-        } catch (err: any) {
-          this.log.error('could not construct CID from peerId string "%s"', resource, err)
-          return badRequestResponse(resource, err)
-        }
-
-        peerId = peerIdFromCID(cid)
+        peerId = getPeerIdFromString(peerIdString)
       }
     } catch (err: any) {
       this.log.error('could not parse peer id from IPNS url %s', resource, err)