@helia/dnslink 0.0.0

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@helia/dnslink",
+  "version": "0.0.0",
+  "description": "DNSLink operations using Helia",
+  "license": "Apache-2.0 OR MIT",
+  "homepage": "https://github.com/ipfs/helia/tree/main/packages/dnslink#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ipfs/helia.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ipfs/helia/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "IPFS"
+  ],
+  "type": "module",
+  "types": "./dist/src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "*",
+        "dist/*",
+        "dist/src/*",
+        "dist/src/*/index"
+      ],
+      "src/*": [
+        "*",
+        "dist/*",
+        "dist/src/*",
+        "dist/src/*/index"
+      ]
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "!dist/test",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "scripts": {
+    "clean": "aegir clean",
+    "lint": "aegir lint",
+    "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
+    "build": "aegir build",
+    "docs": "aegir docs",
+    "generate": "protons ./src/pb/metadata.proto",
+    "test": "aegir test",
+    "test:chrome": "aegir test -t browser --cov",
+    "test:chrome-webworker": "aegir test -t webworker",
+    "test:firefox": "aegir test -t browser -- --browser firefox",
+    "test:firefox-webworker": "aegir test -t webworker -- --browser firefox",
+    "test:node": "aegir test -t node --cov",
+    "test:electron-main": "aegir test -t electron-main"
+  },
+  "dependencies": {
+    "@libp2p/crypto": "^5.1.7",
+    "@helia/interface": "^5.4.0",
+    "@libp2p/interface": "^3.0.2",
+    "@libp2p/kad-dht": "^16.0.5",
+    "@libp2p/keychain": "^6.0.5",
+    "@libp2p/logger": "^6.0.5",
+    "@libp2p/peer-id": "^6.0.3",
+    "@libp2p/utils": "^7.0.5",
+    "@multiformats/dns": "^1.0.9",
+    "interface-datastore": "^9.0.2",
+    "ipns": "^10.1.2",
+    "multiformats": "^13.4.1",
+    "progress-events": "^1.0.1",
+    "protons-runtime": "^5.5.0",
+    "uint8arraylist": "^2.4.8",
+    "uint8arrays": "^5.1.0"
+  },
+  "devDependencies": {
+    "@libp2p/crypto": "^5.1.12",
+    "@types/dns-packet": "^5.6.5",
+    "aegir": "^47.0.22",
+    "datastore-core": "^11.0.2",
+    "it-drain": "^3.0.10",
+    "protons": "^7.6.1",
+    "sinon": "^21.0.0",
+    "sinon-ts": "^2.0.0"
+  },
+  "browser": {
+    "./dist/src/dns-resolvers/resolver.js": "./dist/src/dns-resolvers/resolver.browser.js"
+  },
+  "sideEffects": false
+}

package/src/constants.ts

@@ -0,0 +1 @@
+export const MAX_RECURSIVE_DEPTH = 32

package/src/dnslink.ts

@@ -0,0 +1,146 @@
+import { MAX_RECURSIVE_DEPTH, RecordType } from '@multiformats/dns'
+import { DNSLinkNotFoundError } from './errors.js'
+import { ipfs } from './namespaces/ipfs.ts'
+import { ipns } from './namespaces/ipns.ts'
+import type { DNSLink as DNSLinkInterface, ResolveDNSLinkOptions, DNSLinkOptions, DNSLinkComponents, DNSLinkResult, DNSLinkNamespace } from './index.js'
+import type { Logger } from '@libp2p/interface'
+import type { DNS } from '@multiformats/dns'
+
+export class DNSLink implements DNSLinkInterface {
+  private readonly dns: DNS
+  private readonly log: Logger
+  private readonly namespaces: Record<string, DNSLinkNamespace>
+
+  constructor (components: DNSLinkComponents, init: DNSLinkOptions = {}) {
+    this.dns = components.dns
+    this.log = components.logger.forComponent('helia:dnslink')
+    this.namespaces = {
+      ipfs,
+      ipns,
+      ...init.namespaces
+    }
+  }
+
+  async resolve (domain: string, options: ResolveDNSLinkOptions = {}): Promise<DNSLinkResult> {
+    return this.recursiveResolveDomain(domain, options.maxRecursiveDepth ?? MAX_RECURSIVE_DEPTH, options)
+  }
+
+  async recursiveResolveDomain (domain: string, depth: number, options: ResolveDNSLinkOptions = {}): Promise<DNSLinkResult> {
+    if (depth === 0) {
+      throw new Error('recursion limit exceeded')
+    }
+
+    // the DNSLink spec says records MUST be stored on the `_dnslink.` subdomain
+    // so start looking for records there, we will fall back to the bare domain
+    // if none are found
+    if (!domain.startsWith('_dnslink.')) {
+      domain = `_dnslink.${domain}`
+    }
+
+    try {
+      return await this.recursiveResolveDnslink(domain, depth, options)
+    } catch (err: any) {
+      // If the code is not ENOTFOUND or ERR_DNSLINK_NOT_FOUND or ENODATA then throw the error
+      if (err.code !== 'ENOTFOUND' && err.code !== 'ENODATA' && err.name !== 'DNSLinkNotFoundError' && err.name !== 'NotFoundError') {
+        throw err
+      }
+
+      if (domain.startsWith('_dnslink.')) {
+        // The supplied domain contains a _dnslink component
+        // Check the non-_dnslink domain
+        domain = domain.replace('_dnslink.', '')
+      } else {
+        // Check the _dnslink subdomain
+        domain = `_dnslink.${domain}`
+      }
+
+      // If this throws then we propagate the error
+      return this.recursiveResolveDnslink(domain, depth, options)
+    }
+  }
+
+  async recursiveResolveDnslink (domain: string, depth: number, options: ResolveDNSLinkOptions = {}): Promise<DNSLinkResult> {
+    if (depth === 0) {
+      throw new Error('recursion limit exceeded')
+    }
+
+    this.log('query %s for TXT and CNAME records', domain)
+    const txtRecordsResponse = await this.dns.query(domain, {
+      ...options,
+      types: [
+        RecordType.TXT
+      ]
+    })
+
+    // sort the TXT records to ensure deterministic processing
+    const txtRecords = (txtRecordsResponse?.Answer ?? [])
+      .sort((a, b) => a.data.localeCompare(b.data))
+
+    this.log('found %d TXT records for %s', txtRecords.length, domain)
+
+    for (const answer of txtRecords) {
+      try {
+        let result = answer.data
+
+        // strip leading and trailing " characters
+        if (result.startsWith('"') && result.endsWith('"')) {
+          result = result.substring(1, result.length - 1)
+        }
+
+        if (!result.startsWith('dnslink=')) {
+          // invalid record?
+          continue
+        }
+
+        this.log('%s TXT %s', answer.name, result)
+
+        result = result.replace('dnslink=', '')
+
+        // result is now a `/ipfs/<cid>` or `/ipns/<cid>` string
+        const [, protocol, domainOrCID] = result.split('/') // e.g. ["", "ipfs", "<cid>"]
+
+        if (protocol === 'dnslink') {
+          // if the result was another DNSLink domain, try to follow it
+          return await this.recursiveResolveDomain(domainOrCID, depth - 1, options)
+        }
+
+        const parser = this.namespaces[protocol]
+
+        if (parser == null) {
+          this.log('unknown protocol "%s" in DNSLink record for domain: %s', protocol, domain)
+          continue
+        }
+
+        return parser.parse(result, answer)
+      } catch (err: any) {
+        this.log.error('could not parse DNS link record for domain %s, %s', domain, answer.data, err)
+      }
+    }
+
+    // no dnslink records found, try CNAMEs
+    this.log('no DNSLink records found for %s, falling back to CNAME', domain)
+
+    const cnameRecordsResponse = await this.dns.query(domain, {
+      ...options,
+      types: [
+        RecordType.CNAME
+      ]
+    })
+
+    // sort the CNAME records to ensure deterministic processing
+    const cnameRecords = (cnameRecordsResponse?.Answer ?? [])
+      .sort((a, b) => a.data.localeCompare(b.data))
+
+    this.log('found %d CNAME records for %s', cnameRecords.length, domain)
+
+    for (const cname of cnameRecords) {
+      try {
+        return await this.recursiveResolveDomain(cname.data, depth - 1, options)
+      } catch (err: any) {
+        this.log.error('domain %s cname %s had no DNSLink records - %e', domain, cname.data, err)
+      }
+    }
+
+    throw new DNSLinkNotFoundError(`No DNSLink records found for domain: ${domain}`)
+  }
+}

package/src/errors.ts

@@ -0,0 +1,17 @@
+export class DNSLinkNotFoundError extends Error {
+  static name = 'DNSLinkNotFoundError'
+
+  constructor (message = 'DNSLink not found') {
+    super(message)
+    this.name = 'DNSLinkNotFoundError'
+  }
+}
+
+export class InvalidNamespaceError extends Error {
+  static name = 'InvalidNamespaceError'
+
+  constructor (message = 'Invalid namespace') {
+    super(message)
+    this.name = 'InvalidNamespaceError'
+  }
+}

package/src/index.ts

@@ -0,0 +1,241 @@
+/**
+ * @packageDocumentation
+ *
+ * [DNSLink](https://dnslink.dev/) operations using a Helia node.
+ *
+ * @example Using custom DNS over HTTPS resolvers
+ *
+ * To use custom resolvers, configure Helia's `dns` option:
+ *
+ * ```TypeScript
+ * import { createHelia } from 'helia'
+ * import { dnsLink } from '@helia/dnslink'
+ * import { dns } from '@multiformats/dns'
+ * import { dnsOverHttps } from '@multiformats/dns/resolvers'
+ * import type { DefaultLibp2pServices } from 'helia'
+ * import type { Libp2p } from '@libp2p/interface'
+ *
+ * const node = await createHelia<Libp2p<DefaultLibp2pServices>>({
+ *   dns: dns({
+ *     resolvers: {
+ *       '.': dnsOverHttps('https://private-dns-server.me/dns-query')
+ *     }
+ *   })
+ * })
+ * const name = dnsLink(node)
+ *
+ * const result = name.resolve('some-domain-with-dnslink-entry.com')
+ * ```
+ *
+ * @example Resolving a domain with a dnslink entry
+ *
+ * Calling `resolve` with the `@helia/dnslink` instance:
+ *
+ * ```TypeScript
+ * // resolve a CID from a TXT record in a DNS zone file, using the default
+ * // resolver for the current platform eg:
+ * // > dig _dnslink.ipfs.tech TXT
+ * // ;; ANSWER SECTION:
+ * // _dnslink.ipfs.tech. 60 IN CNAME _dnslink.ipfs-tech.on.fleek.co.
+ * // _dnslink.ipfs-tech.on.fleek.co. 120 IN TXT "dnslink=/ipfs/bafybe..."
+ *
+ * import { createHelia } from 'helia'
+ * import { dnsLink } from '@helia/dnslink'
+ *
+ * const node = await createHelia()
+ * const name = dnsLink(node)
+ *
+ * const { answer } = await name.resolve('blog.ipfs.tech')
+ *
+ * console.info(answer)
+ * // { data: '/ipfs/bafybe...' }
+ * ```
+ *
+ * @example Using DNS-Over-HTTPS
+ *
+ * This example uses the Mozilla provided RFC 1035 DNS over HTTPS service. This
+ * uses binary DNS records so requires extra dependencies to process the
+ * response which can increase browser bundle sizes.
+ *
+ * If this is a concern, use the DNS-JSON-Over-HTTPS resolver instead.
+ *
+ * ```TypeScript
+ * import { createHelia } from 'helia'
+ * import { dnsLink } from '@helia/dnslink'
+ * import { dns } from '@multiformats/dns'
+ * import { dnsOverHttps } from '@multiformats/dns/resolvers'
+ * import type { DefaultLibp2pServices } from 'helia'
+ * import type { Libp2p } from '@libp2p/interface'
+ *
+ * const node = await createHelia<Libp2p<DefaultLibp2pServices>>({
+ *   dns: dns({
+ *     resolvers: {
+ *       '.': dnsOverHttps('https://mozilla.cloudflare-dns.com/dns-query')
+ *     }
+ *   })
+ * })
+ * const name = dnsLink(node)
+ *
+ * const result = await name.resolve('blog.ipfs.tech')
+ * ```
+ *
+ * @example Using DNS-JSON-Over-HTTPS
+ *
+ * DNS-JSON-Over-HTTPS resolvers use the RFC 8427 `application/dns-json` and can
+ * result in a smaller browser bundle due to the response being plain JSON.
+ *
+ * ```TypeScript
+ * import { createHelia } from 'helia'
+ * import { dnsLink } from '@helia/dnslink'
+ * import { dns } from '@multiformats/dns'
+ * import { dnsJsonOverHttps } from '@multiformats/dns/resolvers'
+ * import type { DefaultLibp2pServices } from 'helia'
+ * import type { Libp2p } from '@libp2p/interface'
+ *
+ * const node = await createHelia<Libp2p<DefaultLibp2pServices>>({
+ *   dns: dns({
+ *     resolvers: {
+ *       '.': dnsJsonOverHttps('https://mozilla.cloudflare-dns.com/dns-query')
+ *     }
+ *   })
+ * })
+ * const name = dnsLink(node)
+ *
+ * const result = await name.resolve('blog.ipfs.tech')
+ * ```
+ */
+
+import { DNSLink as DNSLinkClass } from './dnslink.js'
+import type { AbortOptions, ComponentLogger, PeerId } from '@libp2p/interface'
+import type { Answer, DNS, ResolveDnsProgressEvents } from '@multiformats/dns'
+import type { CID } from 'multiformats/cid'
+import type { ProgressOptions } from 'progress-events'
+
+export interface ResolveDNSLinkOptions extends AbortOptions, ProgressOptions<ResolveDnsProgressEvents> {
+  /**
+   * Do not query the network for the IPNS record
+   *
+   * @default false
+   */
+  offline?: boolean
+
+  /**
+   * Do not use cached DNS entries
+   *
+   * @default false
+   */
+  nocache?: boolean
+
+  /**
+   * When resolving DNSLink records that resolve to other DNSLink records, limit
+   * how many times we will recursively resolve them.
+   *
+   * @default 32
+   */
+  maxRecursiveDepth?: number
+}
+
+export interface DNSLinkIPFSResult {
+  /**
+   * The resolved record
+   */
+  answer: Answer
+
+  /**
+   * The IPFS namespace
+   */
+  namespace: 'ipfs'
+
+  /**
+   * The resolved value
+   */
+  cid: CID
+
+  /**
+   * If the resolved value is an IPFS path, it will be present here
+   */
+  path: string
+}
+
+export interface DNSLinkIPNSResult {
+  /**
+   * The resolved record
+   */
+  answer: Answer
+
+  /**
+   * The IPFS namespace
+   */
+  namespace: 'ipns'
+
+  /**
+   * The resolved value
+   */
+  peerId: PeerId
+
+  /**
+   * If the resolved value is an IPFS path, it will be present here
+   */
+  path: string
+}
+
+export interface DNSLinkOtherResult {
+  /**
+   * The resolved record
+   */
+  answer: Answer
+
+  /**
+   * The IPFS namespace
+   */
+  namespace: string
+}
+
+export type DNSLinkResult = DNSLinkIPFSResult | DNSLinkIPNSResult | DNSLinkOtherResult
+
+export interface DNSLinkNamespace {
+  /**
+   * Return a result parsed from a DNSLink value
+   */
+  parse(value: string, answer: Answer): DNSLinkResult
+}
+
+export interface DNSLink {
+  /**
+   * Resolve a CID from a dns-link style IPNS record
+   *
+   * @example
+   *
+   * ```TypeScript
+   * import { createHelia } from 'helia'
+   * import { dnsLink } from '@helia/dnslink'
+   *
+   * const helia = await createHelia()
+   * const name = dnsLink(helia)
+   *
+   * const result = await name.resolve('ipfs.io', {
+   *   signal: AbortSignal.timeout(5_000)
+   * })
+   *
+   * console.info(result) // { answer: ..., value: ... }
+   * ```
+   */
+  resolve(domain: string, options?: ResolveDNSLinkOptions): Promise<DNSLinkResult>
+}
+
+export interface DNSLinkComponents {
+  dns: DNS
+  logger: ComponentLogger
+}
+
+export interface DNSLinkOptions {
+  /**
+   * By default `/ipfs/...`, `/ipns/...` and `/dnslink/...` record values are
+   * supported - to support other prefixes pass other value parsers here
+   */
+  namespaces?: Record<string, DNSLinkNamespace>
+}
+
+export function dnsLink (components: DNSLinkComponents, options: DNSLinkOptions = {}): DNSLink {
+  return new DNSLinkClass(components, options)
+}

package/src/namespaces/ipfs.ts

@@ -0,0 +1,22 @@
+import { CID } from 'multiformats/cid'
+import { InvalidNamespaceError } from '../errors.ts'
+import type { DNSLinkResult, DNSLinkNamespace } from '../index.js'
+import type { Answer } from '@multiformats/dns'
+
+export const ipfs: DNSLinkNamespace = {
+  parse: (value: string, answer: Answer): DNSLinkResult => {
+    const [, protocol, cid, ...rest] = value.split('/')
+
+    if (protocol !== 'ipfs') {
+      throw new InvalidNamespaceError(`Namespace ${protocol} was not "ipfs"`)
+    }
+
+    // if the result is a CID, we've reached the end of the recursion
+    return {
+      namespace: 'ipfs',
+      cid: CID.parse(cid),
+      path: rest.length > 0 ? `/${rest.join('/')}` : '',
+      answer
+    }
+  }
+}

package/src/namespaces/ipns.ts

@@ -0,0 +1,22 @@
+import { peerIdFromString } from '@libp2p/peer-id'
+import { InvalidNamespaceError } from '../errors.ts'
+import type { DNSLinkResult, DNSLinkNamespace } from '../index.js'
+import type { Answer } from '@multiformats/dns'
+
+export const ipns: DNSLinkNamespace = {
+  parse: (value: string, answer: Answer): DNSLinkResult => {
+    const [, protocol, peerId, ...rest] = value.split('/')
+
+    if (protocol !== 'ipns') {
+      throw new InvalidNamespaceError(`Namespace ${protocol} was not "ipns"`)
+    }
+
+    // if the result is a CID, we've reached the end of the recursion
+    return {
+      namespace: 'ipns',
+      peerId: peerIdFromString(peerId),
+      path: rest.length > 0 ? `/${rest.join('/')}` : '',
+      answer
+    }
+  }
+}