@helia/verified-fetch 2.2.2 → 2.3.1

package/src/index.ts

@@ -5,7 +5,12 @@
  *
  * 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.
+ * By default, providers for CIDs are found using [delegated routing endpoints](https://docs.ipfs.tech/concepts/public-utilities/#delegated-routing).
+ *
+ * Data is retrieved using the following strategies:
+ * - Directly from providers, using [Bitswap](https://docs.ipfs.tech/concepts/bitswap/) over WebSockets and WebRTC if available.
+ * - Directly from providers exposing a [trustless gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/) over HTTPS.
+ * - As a fallback, if no providers reachable from a browser are found, data is retrieved using recursive gateways, e.g. `trustless-gateway.link` which can be configured.
  *
  * 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.
  *
@@ -189,6 +194,25 @@
  *   }
  * })
  * ```
+ * ### Custom Hashers
+ *
+ * By default, `@helia/verified-fetch` supports `sha256`, `sha512`, and `identity` hashers.
+ *
+ * If you need to use a different hasher, you can provide a [custom `hasher` function](https://multiformats.github.io/js-multiformats/interfaces/hashes_interface.MultihashHasher.html) as an option to `createVerifiedFetch`.
+ *
+ * @example Passing a custom hashing function
+ *
+ * ```typescript
+ * import { createVerifiedFetch } from '@helia/verified-fetch'
+ * import { blake2b256 } from '@multiformats/blake2/blake2b'
+ *
+ * const verifiedFetch = await createVerifiedFetch({
+ *   gateways: ['https://ipfs.io'],
+ *   hashers: [blake2b256]
+ * })
+ *
+ * const resp = await verifiedFetch('ipfs://cid-using-blake2b256')
+ * ```
  *
  * ### IPLD codec handling
  *
@@ -602,8 +626,9 @@ 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 { createHelia, type HeliaInit } from 'helia'
 import { createLibp2p, type Libp2pOptions } from 'libp2p'
+import { type ContentTypeParser } from './types.js'
 import { getLibp2pConfig } from './utils/libp2p-defaults.js'
 import { VerifiedFetch as VerifiedFetchClass } from './verified-fetch.js'
 import type { GetBlockProgressEvents, Helia, Routing } from '@helia/interface'
@@ -612,7 +637,6 @@ import type { DNSResolver } from '@multiformats/dns/resolvers'
 import type { ExporterProgressEvents } from 'ipfs-unixfs-exporter'
 import type { CID } from 'multiformats/cid'
 import type { ProgressEvent, ProgressOptions } from 'progress-events'
-
 /**
  * The types for the first argument of the `verifiedFetch` function.
  */
@@ -657,6 +681,13 @@ export interface CreateVerifiedFetchInit {
    */
   dnsResolvers?: DNSResolver[] | DNSResolvers
 
+  /**
+   * By default sha256, sha512 and identity hashes are supported for
+   * retrieval operations. To retrieve blocks by CIDs using other hashes
+   * pass appropriate MultihashHashers here.
+   */
+  hashers?: HeliaInit['hashers']
+
   /**
    * By default we will not connect to any HTTP Gateways providers over local or
    * loopback addresses, this is because they are typically running on remote
@@ -721,19 +752,7 @@ export interface CreateVerifiedFetchOptions {
   sessionTTLms?: number
 }
 
-/**
- * A ContentTypeParser attempts to return the mime type of a given file. It
- * receives the first chunk of the file data and the file name, if it is
- * available.  The function can be sync or async and if it returns/resolves to
- * `undefined`, `application/octet-stream` will be used.
- */
-export interface ContentTypeParser {
-  /**
-   * Attempt to determine a mime type, either via of the passed bytes or the
-   * filename if it is available.
-   */
-  (bytes: Uint8Array, fileName?: string): Promise<string | undefined> | string | undefined
-}
+export type { ContentTypeParser } from './types.js'
 
 export type BubbledProgressEvents =
   // unixfs-exporter
@@ -838,7 +857,8 @@ export async function createVerifiedFetch (init?: Helia | CreateVerifiedFetchIni
       libp2p,
       blockBrokers,
       dns,
-      routers
+      routers,
+      hashers: init?.hashers
     })
     init.logger.forComponent('helia:verified-fetch').trace('created verified-fetch with libp2p config: %j', libp2pConfig)
   }

package/src/types.ts

@@ -30,3 +30,17 @@ export interface FetchHandlerFunctionArg {
    */
   resource: string
 }
+
+/**
+ * A ContentTypeParser attempts to return the mime type of a given file. It
+ * receives the first chunk of the file data and the file name, if it is
+ * available.  The function can be sync or async and if it returns/resolves to
+ * `undefined`, `application/octet-stream` will be used.
+ */
+export interface ContentTypeParser {
+  /**
+   * Attempt to determine a mime type, either via of the passed bytes or the
+   * filename if it is available.
+   */
+  (bytes: Uint8Array, fileName?: string): Promise<string | undefined> | string | undefined
+}

package/src/utils/set-content-type.ts

@@ -0,0 +1,38 @@
+import { type Logger } from '@libp2p/interface'
+import { type ContentTypeParser } from '../types.js'
+import { isPromise } from './type-guards.js'
+
+export interface SetContentTypeOptions {
+  bytes: Uint8Array
+  path: string
+  response: Response
+  defaultContentType?: string
+  contentTypeParser: ContentTypeParser | undefined
+  log: Logger
+}
+
+export async function setContentType ({ bytes, path, response, contentTypeParser, log, defaultContentType = 'application/octet-stream' }: SetContentTypeOptions): Promise<void> {
+  let contentType: string | undefined
+
+  if (contentTypeParser != null) {
+    try {
+      let fileName = path.split('/').pop()?.trim()
+      fileName = fileName === '' ? undefined : fileName
+      const parsed = contentTypeParser(bytes, fileName)
+
+      if (isPromise(parsed)) {
+        const result = await parsed
+
+        if (result != null) {
+          contentType = result
+        }
+      } else if (parsed != null) {
+        contentType = parsed
+      }
+    } catch (err) {
+      log.error('error parsing content type', err)
+    }
+  }
+  log.trace('setting content type to "%s"', contentType ?? defaultContentType)
+  response.headers.set('content-type', contentType ?? defaultContentType)
+}

package/src/utils/type-guards.ts

@@ -0,0 +1,3 @@
+export function isPromise <T> (p?: any): p is Promise<T> {
+  return p?.then != null
+}

package/src/utils/walk-path.ts

@@ -19,7 +19,7 @@ export interface PathWalkerFn {
   (blockstore: ReadableStorage, path: string, options?: PathWalkerOptions): Promise<PathWalkerResponse>
 }
 
-export async function walkPath (blockstore: ReadableStorage, path: string, options?: PathWalkerOptions): Promise<PathWalkerResponse> {
+async function walkPath (blockstore: ReadableStorage, path: string, options?: PathWalkerOptions): Promise<PathWalkerResponse> {
   const ipfsRoots: CID[] = []
   let terminalElement: UnixFSEntry | undefined
 

package/src/verified-fetch.ts

@@ -6,7 +6,7 @@ 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 { Key } from 'interface-datastore'
-import { exporter } from 'ipfs-unixfs-exporter'
+import { exporter, type ObjectNode } from 'ipfs-unixfs-exporter'
 import toBrowserReadableStream from 'it-to-browser-readablestream'
 import { LRUCache } from 'lru-cache'
 import { type CID } from 'multiformats/cid'
@@ -32,12 +32,12 @@ import { resourceToSessionCacheKey } from './utils/resource-to-cache-key.js'
 import { setCacheControlHeader, setIpfsRoots } from './utils/response-headers.js'
 import { badRequestResponse, movedPermanentlyResponse, notAcceptableResponse, notSupportedResponse, okResponse, badRangeResponse, okRangeResponse, badGatewayResponse, notFoundResponse } from './utils/responses.js'
 import { selectOutputType } from './utils/select-output-type.js'
+import { setContentType } from './utils/set-content-type.js'
 import { handlePathWalking, isObjectNode } from './utils/walk-path.js'
 import type { CIDDetail, ContentTypeParser, CreateVerifiedFetchOptions, Resource, ResourceDetail, VerifiedFetchInit as VerifiedFetchOptions } from './index.js'
 import type { FetchHandlerFunctionArg, RequestFormatShorthand } from './types.js'
 import type { Helia, SessionBlockstore } from '@helia/interface'
 import type { Blockstore } from 'interface-blockstore'
-import type { ObjectNode } from 'ipfs-unixfs-exporter'
 
 const SESSION_CACHE_MAX_SIZE = 100
 const SESSION_CACHE_TTL_MS = 60 * 1000
@@ -398,7 +398,7 @@ export class VerifiedFetch {
         redirected
       })
 
-      await this.setContentType(firstChunk, path, response)
+      await setContentType({ bytes: firstChunk, path, response, contentTypeParser: this.contentTypeParser, log: this.log })
       setIpfsRoots(response, ipfsRoots)
 
       return response
@@ -434,37 +434,11 @@ export class VerifiedFetch {
     // if the user has specified an `Accept` header that corresponds to a raw
     // type, honour that header, so for example they don't request
     // `application/vnd.ipld.raw` but get `application/octet-stream`
-    await this.setContentType(result, path, response, getOverridenRawContentType({ headers: options?.headers, accept }))
+    await setContentType({ bytes: result, path, response, defaultContentType: getOverridenRawContentType({ headers: options?.headers, accept }), contentTypeParser: this.contentTypeParser, log: this.log })
 
     return response
   }
 
-  private async setContentType (bytes: Uint8Array, path: string, response: Response, defaultContentType = 'application/octet-stream'): Promise<void> {
-    let contentType: string | undefined
-
-    if (this.contentTypeParser != null) {
-      try {
-        let fileName = path.split('/').pop()?.trim()
-        fileName = fileName === '' ? undefined : fileName
-        const parsed = this.contentTypeParser(bytes, fileName)
-
-        if (isPromise(parsed)) {
-          const result = await parsed
-
-          if (result != null) {
-            contentType = result
-          }
-        } else if (parsed != null) {
-          contentType = parsed
-        }
-      } catch (err) {
-        this.log.error('error parsing content type', err)
-      }
-    }
-    this.log.trace('setting content type to "%s"', contentType ?? defaultContentType)
-    response.headers.set('content-type', contentType ?? defaultContentType)
-  }
-
   /**
    * If the user has not specified an Accept header or format query string arg,
    * use the CID codec to choose an appropriate handler for the block data.
@@ -614,7 +588,3 @@ export class VerifiedFetch {
     await this.helia.stop()
   }
 }
-
-function isPromise <T> (p?: any): p is Promise<T> {
-  return p?.then != null
-}