@dnsid-ai/transport 0.20.1

package/dist/index.cjs

@@ -0,0 +1,496 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createDefaultDnsResolver: () => createDefaultDnsResolver,
+  createDnsResolverFromServer: () => createDnsResolverFromServer,
+  createDnsidFetch: () => createDnsidFetch,
+  createLookup: () => createLookup,
+  createSsrfSafeFetch: () => createSsrfSafeFetch,
+  fetchJson: () => fetchJson,
+  formatDnsServer: () => formatDnsServer,
+  isUnsafeIp: () => isUnsafeIp,
+  parseDnsServer: () => parseDnsServer
+});
+module.exports = __toCommonJS(index_exports);
+var dnsPromises = __toESM(require("dns/promises"), 1);
+var fs = __toESM(require("fs"), 1);
+var https = __toESM(require("https"), 1);
+var net = __toESM(require("net"), 1);
+var tls = __toESM(require("tls"), 1);
+var import_undici = require("undici");
+var import_protocol = require("@dnsid-ai/protocol");
+var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_RESPONSE_BYTES = 1 * 1024 * 1024;
+var DNSID_USER_AGENT = "dnsid-ts";
+function createDnsidFetch(config) {
+  if (!config.dnsServer && !config.caBundlePath) {
+    return globalThis.fetch.bind(globalThis);
+  }
+  const connect = {};
+  if (config.dnsServer) connect.lookup = createLookup(config.dnsServer);
+  if (config.caBundlePath) connect.ca = [...tls.rootCertificates, fs.readFileSync(config.caBundlePath, "utf8")];
+  return createFetchWithDispatcher(new import_undici.Agent({ connect }));
+}
+function createSsrfSafeFetch(config = {}, options = {}) {
+  const allowedUnsafeHosts = new Set((options.allowedUnsafeHosts ?? []).map(normalizeAllowedUnsafeHost));
+  const connect = { lookup: createSsrfSafeLookup(config.dnsServer, allowedUnsafeHosts) };
+  if (config.caBundlePath) connect.ca = [...tls.rootCertificates, fs.readFileSync(config.caBundlePath, "utf8")];
+  const fetchWithSafeLookup = createFetchWithDispatcher(new import_undici.Agent({ connect }));
+  return async (input, init) => {
+    const url = new URL(input instanceof Request ? input.url : input);
+    if (isUnsafeIp(url.hostname) && !(allowedUnsafeHosts.has(url.hostname) && isPrivateOrLoopbackIp(url.hostname))) {
+      throw new import_protocol.VerificationError(`unsafe target IP address: ${url.hostname}`, {
+        code: import_protocol.VerificationCode.TLSError
+      });
+    }
+    return fetchWithSafeLookup(input, { ...init, redirect: "manual" });
+  };
+}
+function createFetchWithDispatcher(dispatcher) {
+  return async (input, init) => {
+    const { url, init: normalizedInit } = normalizeFetchArgs(input, init);
+    const fetchInit = { ...normalizedInit, dispatcher };
+    const fetchWithDispatcher = import_undici.fetch;
+    return fetchWithDispatcher(url, fetchInit);
+  };
+}
+function createDefaultDnsResolver(config) {
+  return config.dnsServer ? createDnsResolverFromServer(config.dnsServer) : createSystemDnsResolver();
+}
+function createDnsResolverFromServer(server) {
+  const parsed = parseDnsServer(server);
+  if (!parsed || net.isIP(parsed.host)) {
+    const resolver = new dnsPromises.Resolver();
+    resolver.setServers([server]);
+    return createSystemDnsResolver(resolver);
+  }
+  let resolverPromise = null;
+  return {
+    async fetchTXT(name) {
+      resolverPromise ??= (async () => {
+        const { address } = await dnsPromises.lookup(parsed.host);
+        const resolver = new dnsPromises.Resolver();
+        resolver.setServers([formatDnsServer(address, parsed.port)]);
+        return resolver;
+      })();
+      return fetchTxtViaSystem(name, await resolverPromise);
+    }
+  };
+}
+function fetchJson(url, opts) {
+  return fetchWithRedirects(url, opts ?? {}, 0);
+}
+function parseDnsServer(server) {
+  const bracket = server.match(/^\[([^\]]+)](?::(\d+))?$/);
+  if (bracket) return { host: bracket[1], port: bracket[2] };
+  const idx = server.lastIndexOf(":");
+  if (idx > -1 && server.indexOf(":") === idx) {
+    return { host: server.slice(0, idx), port: server.slice(idx + 1) };
+  }
+  return { host: server };
+}
+function formatDnsServer(address, port) {
+  const host = net.isIP(address) === 6 ? `[${address}]` : address;
+  return port ? `${host}:${port}` : host;
+}
+function createLookup(dnsServer) {
+  let resolverPromise = null;
+  async function resolver() {
+    resolverPromise ??= (async () => {
+      const parsed = parseDnsServer(dnsServer);
+      const server = parsed && !net.isIP(parsed.host) ? formatDnsServer((await dnsPromises.lookup(parsed.host)).address, parsed.port) : dnsServer;
+      const r = new dnsPromises.Resolver();
+      r.setServers([server]);
+      return r;
+    })();
+    return resolverPromise;
+  }
+  return (hostname, opts, cb) => {
+    const family = typeof opts === "object" ? opts.family : opts;
+    const all = typeof opts === "object" && opts.all;
+    void (async () => {
+      const r = await resolver();
+      const addresses = family === 6 ? (await r.resolve6(hostname)).map((address) => ({ address, family: 6 })) : family === 4 ? (await r.resolve4(hostname)).map((address) => ({ address, family: 4 })) : [
+        ...(await r.resolve4(hostname).catch(() => [])).map((address) => ({ address, family: 4 })),
+        ...(await r.resolve6(hostname).catch(() => [])).map((address) => ({ address, family: 6 }))
+      ];
+      if (addresses.length === 0) throw new Error(`no A/AAAA records for ${hostname}`);
+      if (all) cb(null, addresses);
+      else {
+        const first = addresses[0];
+        cb(null, first.address, first.family);
+      }
+    })().catch((err) => cb(err, "", 0));
+  };
+}
+function createSsrfSafeLookup(dnsServer, allowedUnsafeHosts = /* @__PURE__ */ new Set()) {
+  let resolverPromise = null;
+  async function customResolver() {
+    if (!dnsServer) throw new Error("no custom DNS server configured");
+    resolverPromise ??= (async () => {
+      const parsed = parseDnsServer(dnsServer);
+      const server = parsed && !net.isIP(parsed.host) ? formatDnsServer((await dnsPromises.lookup(parsed.host)).address, parsed.port) : dnsServer;
+      const r = new dnsPromises.Resolver();
+      r.setServers([server]);
+      return r;
+    })();
+    return resolverPromise;
+  }
+  return (hostname, opts, cb) => {
+    const rawFamily = typeof opts === "object" ? opts.family : opts;
+    const family = rawFamily === "IPv4" ? 4 : rawFamily === "IPv6" ? 6 : rawFamily;
+    const all = typeof opts === "object" && opts.all;
+    void (async () => {
+      const addresses = await resolveAddresses(hostname, family, dnsServer ? await customResolver() : void 0);
+      const unsafe = addresses.find(({ address }) => isUnsafeIp(address));
+      if (unsafe && !(allowedUnsafeHosts.has(hostname) && addresses.every(({ address }) => isPrivateOrLoopbackIp(address)))) {
+        throw new import_protocol.VerificationError(`unsafe resolved IP address for ${hostname}: ${unsafe.address}`, {
+          code: import_protocol.VerificationCode.TLSError
+        });
+      }
+      if (all) cb(null, addresses);
+      else {
+        const first = addresses[0];
+        cb(null, first.address, first.family);
+      }
+    })().catch((err) => cb(err, "", 0));
+  };
+}
+function normalizeAllowedUnsafeHost(host) {
+  let parsed;
+  try {
+    parsed = new URL(`https://${host}`);
+  } catch {
+    throw new TypeError(`invalid allowed unsafe hostname: ${host}`);
+  }
+  if (!host || parsed.username || parsed.password || parsed.port || parsed.pathname !== "/" || parsed.search || parsed.hash) {
+    throw new TypeError(`invalid allowed unsafe hostname: ${host}`);
+  }
+  return parsed.hostname;
+}
+async function resolveAddresses(hostname, family, resolver) {
+  const ipFamily = net.isIP(hostname);
+  if (ipFamily === 4 || ipFamily === 6) return [{ address: hostname, family: ipFamily }];
+  if (!resolver) {
+    const records = await dnsPromises.lookup(hostname, { all: true, family: family === 4 || family === 6 ? family : 0 });
+    if (records.length === 0) throw new Error(`no A/AAAA records for ${hostname}`);
+    return records.map(({ address, family: recordFamily }) => ({ address, family: recordFamily }));
+  }
+  const addresses = family === 6 ? (await resolver.resolve6(hostname)).map((address) => ({ address, family: 6 })) : family === 4 ? (await resolver.resolve4(hostname)).map((address) => ({ address, family: 4 })) : [
+    ...(await resolver.resolve4(hostname).catch(() => [])).map((address) => ({ address, family: 4 })),
+    ...(await resolver.resolve6(hostname).catch(() => [])).map((address) => ({ address, family: 6 }))
+  ];
+  if (addresses.length === 0) throw new Error(`no A/AAAA records for ${hostname}`);
+  return addresses;
+}
+function isUnsafeIp(address) {
+  let host = address;
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+  const zoneIndex = host.indexOf("%");
+  const normalized = zoneIndex === -1 ? host : host.slice(0, zoneIndex);
+  const family = net.isIP(normalized);
+  if (family === 4) return isUnsafeIpv4(normalized);
+  if (family === 6) return isUnsafeIpv6(normalized);
+  return false;
+}
+function isPrivateOrLoopbackIp(address) {
+  let host = address;
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+  const zoneIndex = host.indexOf("%");
+  const normalized = zoneIndex === -1 ? host : host.slice(0, zoneIndex);
+  const family = net.isIP(normalized);
+  if (family === 4) {
+    const [a, b] = normalized.split(".").map(Number);
+    return a === 10 || a === 127 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168;
+  }
+  if (family !== 6) return false;
+  const bytes = ipv6ToBytes(normalized);
+  if (!bytes) return false;
+  const mapped = ipv4FromMappedIpv6(bytes) ?? ipv4FromCompatibleIpv6(bytes);
+  if (mapped) return isPrivateOrLoopbackIp(mapped);
+  const loopback = bytes.slice(0, 15).every((byte) => byte === 0) && bytes[15] === 1;
+  return loopback || (bytes[0] & 254) === 252;
+}
+function isUnsafeIpv4(address) {
+  const octets = address.split(".").map((part) => Number(part));
+  if (octets.length !== 4 || octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) return true;
+  const [a, b, c] = octets;
+  return a === 0 || a === 10 || a === 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 100 && b >= 64 && b <= 127 || a === 192 && b === 0 && c === 0 || a === 192 && b === 0 && c === 2 || a === 198 && (b === 18 || b === 19) || a === 198 && b === 51 && c === 100 || a === 203 && b === 0 && c === 113 || a >= 224 && a <= 239 || a >= 240;
+}
+function isUnsafeIpv6(address) {
+  const bytes = ipv6ToBytes(address);
+  if (!bytes) return true;
+  const mapped = ipv4FromMappedIpv6(bytes);
+  if (mapped) return isUnsafeIpv4(mapped);
+  const compatible = ipv4FromCompatibleIpv6(bytes);
+  if (compatible) return isUnsafeIpv4(compatible);
+  const first = bytes[0];
+  const second = bytes[1];
+  const allZero = bytes.every((byte) => byte === 0);
+  const loopback = bytes.slice(0, 15).every((byte) => byte === 0) && bytes[15] === 1;
+  return allZero || loopback || (first & 254) === 252 || first === 254 && (second & 192) === 128 || first === 255 || first === 32 && second === 1 && bytes[2] === 13 && bytes[3] === 184 || first === 32 && second === 2 || first === 32 && second === 1 && bytes[2] === 0 && bytes[3] === 0;
+}
+function ipv4FromMappedIpv6(bytes) {
+  const isMapped = bytes.slice(0, 10).every((byte) => byte === 0) && bytes[10] === 255 && bytes[11] === 255;
+  if (!isMapped) return null;
+  return bytes.slice(12, 16).join(".");
+}
+function ipv4FromCompatibleIpv6(bytes) {
+  const isCompatible = bytes.slice(0, 12).every((byte) => byte === 0);
+  if (!isCompatible) return null;
+  return bytes.slice(12, 16).join(".");
+}
+function ipv6ToBytes(address) {
+  let normalized = address;
+  const embeddedIpv4Start = address.lastIndexOf(":");
+  if (embeddedIpv4Start !== -1) {
+    const embeddedIpv4 = address.slice(embeddedIpv4Start + 1);
+    if (embeddedIpv4.includes(".")) {
+      const octets = embeddedIpv4.split(".").map((part) => Number(part));
+      if (octets.length !== 4 || octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) return null;
+      normalized = `${address.slice(0, embeddedIpv4Start + 1)}${(octets[0] << 8 | octets[1]).toString(16)}:${(octets[2] << 8 | octets[3]).toString(16)}`;
+    }
+  }
+  const halves = normalized.split("::");
+  if (halves.length > 2) return null;
+  const left = halves[0] ? halves[0].split(":").filter(Boolean) : [];
+  const right = halves[1] ? halves[1].split(":").filter(Boolean) : [];
+  const missing = halves.length === 2 ? 8 - left.length - right.length : 0;
+  const groups = halves.length === 2 ? [...left, ...Array(missing).fill("0"), ...right] : left;
+  if (missing < 0 || groups.length !== 8) return null;
+  const bytes = [];
+  for (const group of groups) {
+    if (!/^[0-9a-fA-F]{1,4}$/.test(group)) return null;
+    const value = Number.parseInt(group, 16);
+    bytes.push(value >> 8 & 255, value & 255);
+  }
+  return bytes;
+}
+function normalizeFetchArgs(input, init) {
+  if (input instanceof Request) {
+    const normalized = {
+      method: input.method,
+      headers: input.headers,
+      body: input.body,
+      cache: input.cache,
+      credentials: input.credentials,
+      integrity: input.integrity,
+      keepalive: input.keepalive,
+      mode: input.mode,
+      redirect: input.redirect,
+      referrer: input.referrer,
+      referrerPolicy: input.referrerPolicy,
+      signal: input.signal,
+      ...init
+    };
+    if (normalized.body) normalized.duplex = "half";
+    return { url: input.url, init: normalized };
+  }
+  return { url: input, init: init ?? {} };
+}
+function createSystemDnsResolver(resolver = dnsPromises) {
+  return {
+    async fetchTXT(name) {
+      return fetchTxtViaSystem(name, resolver);
+    }
+  };
+}
+async function fetchTxtViaSystem(name, resolver) {
+  try {
+    const records = await resolver.resolveTxt(name);
+    return [records.map((strings) => ({ strings, ttl: 0 })), import_protocol.DNSSECState.UNKNOWN];
+  } catch (err) {
+    const nodeErr = err;
+    switch (nodeErr.code) {
+      case "ENODATA":
+      case "ENOTFOUND":
+        return [[], import_protocol.DNSSECState.UNKNOWN];
+      case "ESERVFAIL":
+        return [[], import_protocol.DNSSECState.FAILED];
+      default:
+        throw err;
+    }
+  }
+}
+function hostAllowed(host, allowedHost, domainBoundary = false) {
+  return host === allowedHost || domainBoundary && host.endsWith(`.${allowedHost}`);
+}
+var protocolAgent = new https.Agent({ keepAlive: true, maxCachedSessions: 0 });
+function fetchWithRedirects(url, opts, depth) {
+  if (depth > 5) {
+    return Promise.reject(new import_protocol.VerificationError("too many redirects", { code: import_protocol.VerificationCode.TLSError }));
+  }
+  let urlObj;
+  try {
+    urlObj = new URL(url);
+  } catch {
+    return Promise.reject(new import_protocol.VerificationError(`invalid URL: ${url}`, { code: import_protocol.VerificationCode.TLSError }));
+  }
+  if (urlObj.protocol !== "https:") {
+    return Promise.reject(new import_protocol.VerificationError("only HTTPS URLs are permitted", { code: import_protocol.VerificationCode.TLSError }));
+  }
+  if (opts.allowedHost && !hostAllowed(urlObj.hostname, opts.allowedHost, opts.domainBoundary)) {
+    return Promise.reject(new import_protocol.VerificationError(
+      `URL host not permitted: expected ${opts.allowedHost}, got ${urlObj.hostname}`,
+      { code: import_protocol.VerificationCode.TLSError }
+    ));
+  }
+  if (isUnsafeIp(urlObj.hostname)) {
+    return Promise.reject(new import_protocol.VerificationError(`unsafe HTTPS target IP address: ${urlObj.hostname}`, {
+      code: import_protocol.VerificationCode.TLSError
+    }));
+  }
+  return new Promise((resolve, reject) => {
+    const requestOptions = {
+      agent: protocolAgent,
+      signal: opts.signal,
+      rejectUnauthorized: true,
+      headers: {
+        "User-Agent": DNSID_USER_AGENT
+      },
+      lookup: createSsrfSafeLookup(opts.dnsServer, new Set((opts.allowedUnsafeHosts ?? []).map(normalizeAllowedUnsafeHost)))
+    };
+    if (opts.caBundlePath) requestOptions.ca = [...tls.rootCertificates, fs.readFileSync(opts.caBundlePath, "utf8")];
+    const req = https.get(url, requestOptions, (res) => {
+      if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400) {
+        const location = res.headers.location;
+        if (!location) {
+          res.resume();
+          return reject(new import_protocol.VerificationError("redirect with no Location header", { code: import_protocol.VerificationCode.TLSError }));
+        }
+        let redirectUrl;
+        try {
+          redirectUrl = new URL(location, url);
+        } catch {
+          res.resume();
+          return reject(new import_protocol.VerificationError(`invalid redirect URL: ${location}`, { code: import_protocol.VerificationCode.TLSError }));
+        }
+        if (redirectUrl.protocol !== "https:") {
+          res.resume();
+          return reject(new import_protocol.VerificationError("redirect to non-HTTPS URL", { code: import_protocol.VerificationCode.TLSError }));
+        }
+        if (opts.allowedHost && !hostAllowed(redirectUrl.hostname, opts.allowedHost, opts.domainBoundary)) {
+          res.resume();
+          return reject(new import_protocol.VerificationError(
+            `redirect changes host: expected ${opts.allowedHost}, got ${redirectUrl.hostname}`,
+            { code: import_protocol.VerificationCode.TLSError }
+          ));
+        }
+        res.resume();
+        return fetchWithRedirects(redirectUrl.toString(), opts, depth + 1).then(resolve, reject);
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new import_protocol.VerificationError(
+          `unexpected HTTP status ${res.statusCode}`,
+          { code: import_protocol.VerificationCode.TLSError, transient: (res.statusCode ?? 0) >= 500 }
+        ));
+      }
+      const socket = res.socket;
+      const peerCert = socket.getPeerCertificate();
+      const san = [];
+      if (peerCert.subjectaltname) {
+        for (const part of peerCert.subjectaltname.split(", ")) {
+          if (part.startsWith("DNS:")) san.push(part.slice(4));
+        }
+      }
+      const tlsCert = { notAfter: new Date(peerCert.valid_to), san };
+      const maxBodyBytes = opts.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+      const contentLength = Number(res.headers["content-length"]);
+      if (Number.isFinite(contentLength) && contentLength > maxBodyBytes) {
+        res.resume();
+        return reject(new import_protocol.VerificationError(
+          `response body exceeds ${maxBodyBytes} byte limit`,
+          { code: import_protocol.VerificationCode.TLSError }
+        ));
+      }
+      let body = "";
+      let bodyBytes = 0;
+      let tooLarge = false;
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => {
+        if (tooLarge) return;
+        bodyBytes += Buffer.byteLength(chunk, "utf8");
+        if (bodyBytes > maxBodyBytes) {
+          tooLarge = true;
+          req.destroy();
+          return reject(new import_protocol.VerificationError(
+            `response body exceeds ${maxBodyBytes} byte limit`,
+            { code: import_protocol.VerificationCode.TLSError }
+          ));
+        }
+        body += chunk;
+      });
+      res.on("end", () => {
+        try {
+          resolve({ data: JSON.parse(body), tlsCert });
+        } catch {
+          reject(new import_protocol.VerificationError("response body is not valid JSON", { code: import_protocol.VerificationCode.RecordInvalid }));
+        }
+      });
+      res.on("error", (err) => {
+        reject(new import_protocol.VerificationError(`response stream error: ${err.message}`, {
+          code: import_protocol.VerificationCode.TLSError,
+          transient: true
+        }));
+      });
+    });
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      reject(new import_protocol.VerificationError(`request timed out after ${timeoutMs}ms`, {
+        code: import_protocol.VerificationCode.TLSError,
+        transient: true
+      }));
+    });
+    req.on("error", (err) => {
+      const nodeErr = err;
+      const isTls = nodeErr.code === "DEPTH_ZERO_SELF_SIGNED_CERT" || nodeErr.code === "CERT_HAS_EXPIRED" || nodeErr.code === "ERR_TLS_CERT_ALTNAME_INVALID" || nodeErr.code === "UNABLE_TO_VERIFY_LEAF_SIGNATURE";
+      reject(new import_protocol.VerificationError(`HTTPS fetch failed: ${err.message}`, {
+        code: import_protocol.VerificationCode.TLSError,
+        transient: !isTls
+      }));
+    });
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDefaultDnsResolver,
+  createDnsResolverFromServer,
+  createDnsidFetch,
+  createLookup,
+  createSsrfSafeFetch,
+  fetchJson,
+  formatDnsServer,
+  isUnsafeIp,
+  parseDnsServer
+});

package/dist/index.d.cts

@@ -0,0 +1,160 @@
+import * as https from 'node:https';
+import { TLSCertificate, TransportConfig, DNSResolver } from '@dnsid-ai/protocol';
+export { TransportConfig } from '@dnsid-ai/protocol';
+
+/** Minimal WHATWG-fetch-compatible function signature returned by the fetch factories. */
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/** Result of {@link fetchJson}: the parsed body plus the TLS certificate presented by the peer. */
+interface FetchResult {
+    /** JSON-decoded response body. */
+    data: unknown;
+    /** Peer certificate details (expiry and DNS SANs) captured from the TLS session. */
+    tlsCert: TLSCertificate;
+}
+/** Options controlling {@link fetchJson}. */
+interface HTTPSFetchOptions {
+    /** Shared verification deadline/cancellation, including redirects. */
+    signal?: AbortSignal;
+    /** If set, the URL host (and every redirect host) must match this host exactly. */
+    allowedHost?: string;
+    /** With `allowedHost`, also accept subdomains of the allowed host (`*.allowedHost`). */
+    domainBoundary?: boolean;
+    /** Request timeout in milliseconds. Defaults to 10 000. */
+    timeoutMs?: number;
+    /** Path to a PEM CA bundle appended to the system root certificates. */
+    caBundlePath?: string;
+    /** Custom DNS server (`host`, `host:port`, or `[ipv6]:port`) used to resolve the target. */
+    dnsServer?: string;
+    /** Maximum accepted response body size in bytes. Defaults to 1 MiB. */
+    maxResponseBytes?: number;
+    /**
+     * Hostnames whose resolved private or loopback addresses may be contacted. For trusted test and
+     * private deployments only; public defaults use none.
+     */
+    allowedUnsafeHosts?: readonly string[];
+}
+
+/** Explicit exceptions for trusted test/private deployments using {@link createSsrfSafeFetch}. */
+interface SsrfSafeFetchOptions {
+    /**
+     * Hostnames whose resolved RFC 1918/ULA private or loopback addresses may be contacted.
+     * Link-local and other unsafe ranges remain blocked. Matching is exact after
+     * URL hostname normalization; public defaults use no exceptions.
+     */
+    allowedUnsafeHosts?: readonly string[];
+}
+/**
+ * Creates a fetch function honoring the transport configuration.
+ *
+ * With no custom DNS server or CA bundle this returns the global `fetch`
+ * unchanged. Otherwise it returns an undici-backed fetch whose connections
+ * resolve hostnames via the configured DNS server and/or trust the extra CA
+ * bundle in addition to the system roots. Unlike {@link createSsrfSafeFetch},
+ * the returned fetch applies no private-address filtering.
+ *
+ * @param config - DNS server and/or CA bundle overrides.
+ * @returns A {@link FetchLike} suitable for passing to core verification APIs.
+ *
+ * @example
+ * ```ts
+ * import { createDnsidFetch, createDefaultDnsResolver } from '@dnsid-ai/transport';
+ *
+ * const config = { dnsServer: '1.1.1.1' };
+ * const fetchImpl = createDnsidFetch(config);
+ * const dnsResolver = createDefaultDnsResolver(config);
+ *
+ * const res = await fetchImpl('https://agent.example.com/.well-known/jwks.json');
+ * const [records, dnssec] = await dnsResolver.fetchTXT('_dnsid.agent.example.com');
+ * ```
+ */
+declare function createDnsidFetch(config: TransportConfig): FetchLike;
+/**
+ * Creates a fetch function that rejects connections to private, loopback,
+ * link-local, and other non-routable addresses (SSRF protection).
+ *
+ * Every hostname is resolved (via the configured DNS server, or the system
+ * resolver otherwise) and each resulting address is checked with
+ * {@link isUnsafeIp} before connecting; requests resolving to an unsafe
+ * address fail with a VerificationError (TLSError, surfaced through the
+ * fetch rejection). Redirects are returned to the caller instead of followed
+ * automatically so each destination can be explicitly policy-checked.
+ *
+ * @param config - Optional DNS server and/or CA bundle overrides.
+ * @param options - Explicit hostname-scoped private-address exceptions for trusted test/private deployments.
+ * @returns A {@link FetchLike} with address filtering applied on every lookup.
+ */
+declare function createSsrfSafeFetch(config?: TransportConfig, options?: SsrfSafeFetchOptions): FetchLike;
+/**
+ * Creates the DNS resolver used to fetch DNSid identity records (TXT).
+ *
+ * Uses the configured DNS server when present, otherwise the system resolver.
+ * Either way the underlying lookup cannot observe DNSSEC validation, so
+ * results carry `DNSSECState.UNKNOWN` (or `FAILED` when the query SERVFAILs).
+ * Node's TXT API omits TTLs, so results use TTL 0 to disable SDK caching.
+ */
+declare function createDefaultDnsResolver(config: Pick<TransportConfig, 'dnsServer'>): DNSResolver;
+/**
+ * Creates a {@link DNSResolver} that queries a specific DNS server.
+ *
+ * Accepts `host`, `host:port`, or `[ipv6]:port`. A hostname (rather than an
+ * IP literal) is resolved once via the system resolver on first use, then
+ * cached for the resolver's lifetime. TXT answers are returned with TTL 0
+ * (no SDK caching) and `DNSSECState.UNKNOWN`; `ENODATA`/`ENOTFOUND` yield an empty
+ * record set, `ESERVFAIL` yields `DNSSECState.FAILED`, and other DNS errors
+ * are rethrown as-is.
+ *
+ * @param server - DNS server address, optionally with port.
+ */
+declare function createDnsResolverFromServer(server: string): DNSResolver;
+/**
+ * Fetches a JSON document over HTTPS with strict transport checks, returning
+ * the parsed body together with the peer TLS certificate.
+ *
+ * Enforces: HTTPS-only URLs, optional host pinning via `allowedHost` (with
+ * optional subdomain boundary), SSRF-safe address resolution, at most 5
+ * same-policy HTTPS redirects, an expected 200 status, and a bounded response
+ * body size. All lookups route through `opts.dnsServer` when provided.
+ *
+ * @param url - Absolute HTTPS URL to fetch.
+ * @param opts - Transport constraints; see {@link HTTPSFetchOptions}.
+ * @returns The parsed JSON body and captured TLS certificate.
+ * @throws VerificationError with `VerificationCode.TLSError` for policy or
+ *   transport failures (non-HTTPS URL, disallowed or unsafe host, redirect
+ *   violations, non-200 status, oversized body, timeout, TLS/connection
+ *   errors); with `VerificationCode.RecordInvalid` when the body is not valid
+ *   JSON. Network-shaped failures are marked `transient`.
+ */
+declare function fetchJson(url: string, opts?: HTTPSFetchOptions): Promise<FetchResult>;
+/**
+ * Splits a DNS server string into host and optional port.
+ *
+ * Supports `host`, `host:port`, and `[ipv6]:port`. Unbracketed strings
+ * containing multiple colons (bare IPv6 literals) are returned whole as
+ * `host`, which callers pass through to Node unchanged.
+ */
+declare function parseDnsServer(server: string): {
+    host: string;
+    port?: string;
+} | null;
+/** Formats a resolved address (bracketing IPv6) with an optional port for `Resolver.setServers`. */
+declare function formatDnsServer(address: string, port?: string): string;
+/**
+ * Creates a Node `lookup` function that resolves A/AAAA records via the given
+ * DNS server instead of the system resolver.
+ *
+ * A hostname-form server is itself resolved once via the system resolver and
+ * cached. Suitable for `https.RequestOptions.lookup` or an undici connect
+ * option. The callback receives an `Error` when no A/AAAA records exist.
+ *
+ * @param dnsServer - DNS server address (`host`, `host:port`, or `[ipv6]:port`).
+ */
+declare function createLookup(dnsServer: string): NonNullable<https.RequestOptions['lookup']>;
+/**
+ * True if an IP address must not be contacted by SSRF-safe transports:
+ * private, loopback, link-local, CGN, documentation, multicast, reserved,
+ * 6to4/Teredo, and IPv4-mapped/compatible IPv6 forms of any of these.
+ * Malformed IP-shaped input is treated as unsafe; non-IP strings return false.
+ */
+declare function isUnsafeIp(address: string): boolean;
+
+export { type FetchLike, type FetchResult, type HTTPSFetchOptions, type SsrfSafeFetchOptions, createDefaultDnsResolver, createDnsResolverFromServer, createDnsidFetch, createLookup, createSsrfSafeFetch, fetchJson, formatDnsServer, isUnsafeIp, parseDnsServer };