@dnsid-ai/transport 0.21.0 → 0.22.0

package/README.md

@@ -41,4 +41,4 @@ Most Node applications should use this through `@dnsid-ai/sdk/node` or profile d
 
 Node's TXT lookup API exposes neither remaining TTLs nor DNSSEC validation state. Both system and configured-server resolvers therefore return TTL `0` and `DNSSECState.UNKNOWN`: fresh verification works in `auto` mode, but SDK identity caching is disabled and `validated`/`required` modes reject the unknown DNSSEC state. To enable caching, inject a `DNSResolver` that supplies real remaining TTLs; the published zone TTL is not a safe substitute for a recursive resolver's remaining TTL.
 
-`createSsrfSafeFetch()` enforces unsafe-address rejection in the lookup used by the outgoing socket and returns redirects without following them automatically. Trusted test/private deployments may pass an exact `allowedUnsafeHosts` list; only RFC 1918/ULA private and loopback results are then accepted for those hosts, while link-local and other unsafe ranges remain blocked. Profile packages that accept a custom `fetch` cannot force equivalent behavior on arbitrary implementations, so custom fetch injection remains trusted infrastructure.
+`createSsrfSafeFetch()` enforces unsafe-address rejection in the lookup used by the outgoing socket and returns redirects without following them automatically. Trusted test/private deployments may pass `privateAddressHosts`: exact hostnames or leading-dot suffixes such as `.test` (label-bounded, case-insensitive); only RFC 1918/ULA private and loopback results are then accepted for matching hosts, while link-local, mixed public/private, and IP-literal URLs remain blocked. Nothing is allowed by default, not even `.test`; a local `dnsid` stack needs `privateAddressHosts: ['.test']` (or `DNSID_PRIVATE_HOSTS=.test` through `configFromEnvironment`). Profile packages that accept a custom `fetch` cannot force equivalent behavior on arbitrary implementations, so custom fetch injection remains trusted infrastructure.

package/dist/index.cjs

@@ -61,13 +61,13 @@ function createDnsidFetch(config) {
   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) };
+  const privateAddressHosts = (options.privateAddressHosts ?? []).map(import_protocol.normalizePrivateAddressHost);
+  const connect = { lookup: createSsrfSafeLookup(config.dnsServer, privateAddressHosts) };
   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))) {
+    if (isUnsafeIp(url.hostname)) {
       throw new import_protocol.VerificationError(`unsafe target IP address: ${url.hostname}`, {
         code: import_protocol.VerificationCode.TLSError
       });
@@ -152,7 +152,7 @@ function createLookup(dnsServer) {
     })().catch((err) => cb(err, "", 0));
   };
 }
-function createSsrfSafeLookup(dnsServer, allowedUnsafeHosts = /* @__PURE__ */ new Set()) {
+function createSsrfSafeLookup(dnsServer, privateAddressHosts = []) {
   let resolverPromise = null;
   async function customResolver() {
     if (!dnsServer) throw new Error("no custom DNS server configured");
@@ -172,7 +172,7 @@ function createSsrfSafeLookup(dnsServer, allowedUnsafeHosts = /* @__PURE__ */ ne
     void (async () => {
       const addresses = await resolveAddresses(hostname, family, dnsServer ? await customResolver() : void 0);
       const unsafe = addresses.find(({ address }) => isUnsafeIp(address));
-      if (unsafe && !(unsafeHostAllowed(hostname, allowedUnsafeHosts) && addresses.every(({ address }) => isPrivateOrLoopbackIp(address)))) {
+      if (unsafe && !(privateAddressHostMatches(hostname, privateAddressHosts) && addresses.every(({ address }) => isPrivateOrLoopbackIp(address)))) {
         throw new import_protocol.VerificationError(`unsafe resolved IP address for ${hostname}: ${unsafe.address}`, {
           code: import_protocol.VerificationCode.TLSError
         });
@@ -185,21 +185,9 @@ function createSsrfSafeLookup(dnsServer, allowedUnsafeHosts = /* @__PURE__ */ ne
     })().catch((err) => cb(err, "", 0));
   };
 }
-function unsafeHostAllowed(hostname, allowedUnsafeHosts) {
+function privateAddressHostMatches(hostname, privateAddressHosts) {
   const host = hostname.toLowerCase().replace(/\.$/, "");
-  return allowedUnsafeHosts.has(hostname) || host === "test" || host.endsWith(".test");
-}
-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;
+  return privateAddressHosts.some((entry) => entry.startsWith(".") ? host === entry.slice(1) || host.endsWith(entry) : host === entry);
 }
 async function resolveAddresses(hostname, family, resolver) {
   const ipFamily = net.isIP(hostname);
@@ -381,7 +369,7 @@ function fetchWithRedirects(url, opts, depth) {
       headers: {
         "User-Agent": DNSID_USER_AGENT
       },
-      lookup: createSsrfSafeLookup(opts.dnsServer, new Set((opts.allowedUnsafeHosts ?? []).map(normalizeAllowedUnsafeHost)))
+      lookup: createSsrfSafeLookup(opts.dnsServer, (opts.privateAddressHosts ?? []).map(import_protocol.normalizePrivateAddressHost))
     };
     if (opts.caBundlePath) requestOptions.ca = [...tls.rootCertificates, fs.readFileSync(opts.caBundlePath, "utf8")];
     const req = https.get(url, requestOptions, (res) => {

package/dist/index.d.cts

@@ -27,21 +27,19 @@ interface HTTPSFetchOptions {
     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[];
+    /** Same as `TransportConfig.privateAddressHosts`: hostnames or `.suffix` entries that may resolve to loopback/private addresses. */
+    privateAddressHosts?: 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.
+     * Hostnames, or leading-dot suffixes such as `.test`, whose resolved RFC 1918/ULA private or
+     * loopback addresses may be contacted. Link-local and other unsafe ranges remain blocked, IP-literal
+     * URLs are never exempted, and nothing is allowed by default. Same semantics as
+     * `TransportConfig.privateAddressHosts`.
      */
-    allowedUnsafeHosts?: readonly string[];
+    privateAddressHosts?: readonly string[];
 }
 /**
  * Creates a fetch function honoring the transport configuration.

package/dist/index.d.ts

@@ -27,21 +27,19 @@ interface HTTPSFetchOptions {
     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[];
+    /** Same as `TransportConfig.privateAddressHosts`: hostnames or `.suffix` entries that may resolve to loopback/private addresses. */
+    privateAddressHosts?: 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.
+     * Hostnames, or leading-dot suffixes such as `.test`, whose resolved RFC 1918/ULA private or
+     * loopback addresses may be contacted. Link-local and other unsafe ranges remain blocked, IP-literal
+     * URLs are never exempted, and nothing is allowed by default. Same semantics as
+     * `TransportConfig.privateAddressHosts`.
      */
-    allowedUnsafeHosts?: readonly string[];
+    privateAddressHosts?: readonly string[];
 }
 /**
  * Creates a fetch function honoring the transport configuration.

package/dist/index.js

@@ -5,7 +5,7 @@ import * as https from "https";
 import * as net from "net";
 import * as tls from "tls";
 import { Agent as Agent2, fetch as undiciFetch } from "undici";
-import { DNSSECState, VerificationCode, VerificationError } from "@dnsid-ai/protocol";
+import { DNSSECState, VerificationCode, VerificationError, normalizePrivateAddressHost } from "@dnsid-ai/protocol";
 var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
 var DEFAULT_MAX_RESPONSE_BYTES = 1 * 1024 * 1024;
 var DNSID_USER_AGENT = "dnsid-ts";
@@ -19,13 +19,13 @@ function createDnsidFetch(config) {
   return createFetchWithDispatcher(new Agent2({ connect }));
 }
 function createSsrfSafeFetch(config = {}, options = {}) {
-  const allowedUnsafeHosts = new Set((options.allowedUnsafeHosts ?? []).map(normalizeAllowedUnsafeHost));
-  const connect = { lookup: createSsrfSafeLookup(config.dnsServer, allowedUnsafeHosts) };
+  const privateAddressHosts = (options.privateAddressHosts ?? []).map(normalizePrivateAddressHost);
+  const connect = { lookup: createSsrfSafeLookup(config.dnsServer, privateAddressHosts) };
   if (config.caBundlePath) connect.ca = [...tls.rootCertificates, fs.readFileSync(config.caBundlePath, "utf8")];
   const fetchWithSafeLookup = createFetchWithDispatcher(new Agent2({ 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))) {
+    if (isUnsafeIp(url.hostname)) {
       throw new VerificationError(`unsafe target IP address: ${url.hostname}`, {
         code: VerificationCode.TLSError
       });
@@ -110,7 +110,7 @@ function createLookup(dnsServer) {
     })().catch((err) => cb(err, "", 0));
   };
 }
-function createSsrfSafeLookup(dnsServer, allowedUnsafeHosts = /* @__PURE__ */ new Set()) {
+function createSsrfSafeLookup(dnsServer, privateAddressHosts = []) {
   let resolverPromise = null;
   async function customResolver() {
     if (!dnsServer) throw new Error("no custom DNS server configured");
@@ -130,7 +130,7 @@ function createSsrfSafeLookup(dnsServer, allowedUnsafeHosts = /* @__PURE__ */ ne
     void (async () => {
       const addresses = await resolveAddresses(hostname, family, dnsServer ? await customResolver() : void 0);
       const unsafe = addresses.find(({ address }) => isUnsafeIp(address));
-      if (unsafe && !(unsafeHostAllowed(hostname, allowedUnsafeHosts) && addresses.every(({ address }) => isPrivateOrLoopbackIp(address)))) {
+      if (unsafe && !(privateAddressHostMatches(hostname, privateAddressHosts) && addresses.every(({ address }) => isPrivateOrLoopbackIp(address)))) {
         throw new VerificationError(`unsafe resolved IP address for ${hostname}: ${unsafe.address}`, {
           code: VerificationCode.TLSError
         });
@@ -143,21 +143,9 @@ function createSsrfSafeLookup(dnsServer, allowedUnsafeHosts = /* @__PURE__ */ ne
     })().catch((err) => cb(err, "", 0));
   };
 }
-function unsafeHostAllowed(hostname, allowedUnsafeHosts) {
+function privateAddressHostMatches(hostname, privateAddressHosts) {
   const host = hostname.toLowerCase().replace(/\.$/, "");
-  return allowedUnsafeHosts.has(hostname) || host === "test" || host.endsWith(".test");
-}
-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;
+  return privateAddressHosts.some((entry) => entry.startsWith(".") ? host === entry.slice(1) || host.endsWith(entry) : host === entry);
 }
 async function resolveAddresses(hostname, family, resolver) {
   const ipFamily = net.isIP(hostname);
@@ -339,7 +327,7 @@ function fetchWithRedirects(url, opts, depth) {
       headers: {
         "User-Agent": DNSID_USER_AGENT
       },
-      lookup: createSsrfSafeLookup(opts.dnsServer, new Set((opts.allowedUnsafeHosts ?? []).map(normalizeAllowedUnsafeHost)))
+      lookup: createSsrfSafeLookup(opts.dnsServer, (opts.privateAddressHosts ?? []).map(normalizePrivateAddressHost))
     };
     if (opts.caBundlePath) requestOptions.ca = [...tls.rootCertificates, fs.readFileSync(opts.caBundlePath, "utf8")];
     const req = https.get(url, requestOptions, (res) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dnsid-ai/transport",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Node.js DNS and HTTPS transport implementations for DNSid.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -38,7 +38,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@dnsid-ai/protocol": "^0.21.0",
+    "@dnsid-ai/protocol": "^0.22.0",
     "undici": "^8.10.2"
   },
   "publishConfig": {