@dnsid-ai/transport 0.32.0 → 0.33.0

package/README.md

@@ -37,6 +37,30 @@ const result = await fetchJson('https://agent.example/.well-known/dnsid-status.j
 const safeFetch = createSsrfSafeFetch({ dnsServer: process.env.DNSID_DNS_SERVER });
 ```
 
+## Single-send signed-response transport
+
+`createResponseSignatureTransport(config?)` returns the `responseTransport`
+function required by `HttpSignaturesProfile.createSignedFetch` when
+`signing.responseSignature` is present. It accepts a prepared `Request` and returns
+`{ response, peerCert }`. It performs one HTTPS request per call, reuses keep-alive
+connections across calls, never follows redirects or retries, never caches, and
+preserves encoded content bytes without transparent decompression. Request bodies
+are sent with `Content-Length`. The certificate comes from the connection that
+carried the response, so it can satisfy
+`fl=mtls`; the profile still validates its SAN against the expected DNSid agent.
+
+The transport honors the request abort signal and has a 30-second ceiling.
+The signed client supplies a shared finite send/read/verification budget and
+bounded content reads (8 MiB). Standalone transport consumers must also bound
+body reads, cancel rejected responses, and not expose unverified content.
+Protocol upgrades and tunnel establishment reject. HTTP errors and ordinary
+redirect responses are returned to the profile for signature verification.
+
+Custom DNS and CA settings follow `createDnsidFetch`. Like that function, this
+transport does not filter private addresses: callers must select a trusted target
+or inject a transport with their required network-address policy. It is separate
+from WBA's SSRF-safe discovery transport and does not change that profile.
+
 Most Node applications should use this through `@dnsid-ai/sdk/node` or profile defaults.
 
 The default resolver queries the DNS servers returned by Node's `dns.getServers()` in order, using UDP with TCP fallback to capture the recursive server's remaining TXT TTL (capped at one day). `dnsServer` can override this list. On failures or empty answers it falls back to Node's native TXT lookup with TTL `0`, disabling identity caching for that result. Node's server list may omit macOS scoped/split-DNS routing, so even positive wire answers are not guaranteed to match the platform resolver in those setups. Neither path validates DNSSEC (`UNKNOWN`); SERVFAIL is a resolution error. `validated`/`required` DNSSEC modes still need an injected validating resolver. Cached verification still re-fetches status unless `verification.statusCheckInterval` is set.

package/dist/index.cjs

@@ -34,6 +34,7 @@ __export(index_exports, {
   createDnsResolverFromServer: () => createDnsResolverFromServer,
   createDnsidFetch: () => createDnsidFetch,
   createLookup: () => createLookup,
+  createResponseSignatureTransport: () => createResponseSignatureTransport,
   createSsrfSafeFetch: () => createSsrfSafeFetch,
   fetchJson: () => fetchJson,
   formatDnsServer: () => formatDnsServer,
@@ -97,7 +98,7 @@ async function resolveTxtWithTtl(name, host, port, signal) {
 }
 async function query(name, host, port, signal) {
   const id = (0, import_node_crypto.randomInt)(65536);
-  const request = {
+  const request2 = {
     type: "query",
     id,
     flags: import_dns_packet.default.RECURSION_DESIRED,
@@ -113,9 +114,9 @@ async function query(name, host, port, signal) {
       return null;
     }
   };
-  const response = await udp(import_dns_packet.default.encode(request), host, port, signal, valid);
+  const response = await udp(import_dns_packet.default.encode(request2), host, port, signal, valid);
   if (!response.flag_tc) return response;
-  const tcpResponse = valid(await tcp(import_dns_packet.default.streamEncode(request), host, port, signal));
+  const tcpResponse = valid(await tcp(import_dns_packet.default.streamEncode(request2), host, port, signal));
   if (!tcpResponse || tcpResponse.flag_tc) throw badResponse();
   return tcpResponse;
 }
@@ -178,6 +179,15 @@ function tcp(buf, host, port, signal) {
 var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
 var DEFAULT_MAX_RESPONSE_BYTES = 1 * 1024 * 1024;
 var DNSID_USER_AGENT = "dnsid-ts";
+function httpsTransportError(cause) {
+  const err = cause;
+  const isTls = err.code === "DEPTH_ZERO_SELF_SIGNED_CERT" || err.code === "CERT_HAS_EXPIRED" || err.code === "ERR_TLS_CERT_ALTNAME_INVALID" || err.code === "UNABLE_TO_VERIFY_LEAF_SIGNATURE";
+  return new import_protocol2.VerificationError(`HTTPS fetch failed: ${err.message}`, {
+    code: import_protocol2.VerificationCode.TLSError,
+    transient: !isTls,
+    cause
+  });
+}
 function createDnsidFetch(config) {
   if (!config.dnsServer && !config.caBundlePath) {
     return globalThis.fetch.bind(globalThis);
@@ -187,6 +197,76 @@ function createDnsidFetch(config) {
   if (config.caBundlePath) connect2.ca = [...tls.rootCertificates, fs.readFileSync(config.caBundlePath, "utf8")];
   return createFetchWithDispatcher(new import_undici.Agent({ connect: connect2 }));
 }
+function createResponseSignatureTransport(config = {}) {
+  const lookup2 = config.dnsServer ? createLookup(config.dnsServer) : void 0;
+  const ca = config.caBundlePath ? [...tls.rootCertificates, fs.readFileSync(config.caBundlePath, "utf8")] : void 0;
+  const agent = new https.Agent({ keepAlive: true, lookup: lookup2, ca, rejectUnauthorized: true });
+  return async (request2) => {
+    const url = new URL(request2.url);
+    if (url.protocol !== "https:") throw new import_protocol2.ArgumentError("response authentication requires HTTPS");
+    const signal = AbortSignal.any([request2.signal, AbortSignal.timeout(DEFAULT_REQUEST_TIMEOUT_MS * 3)]);
+    const content = request2.body ? Buffer.from(await request2.arrayBuffer()) : null;
+    const headers = Object.fromEntries(request2.headers);
+    if (content) headers["content-length"] = String(content.length);
+    return new Promise((resolve, reject) => {
+      const outgoing = https.request(url, {
+        agent,
+        signal,
+        method: request2.method,
+        headers
+      }, (incoming) => {
+        const cert = incoming.socket.getPeerCertificate();
+        const peerCert = {
+          notAfter: new Date(cert.valid_to),
+          san: (cert.subjectaltname ?? "").split(", ").filter((s) => s.startsWith("DNS:")).map((s) => s.slice(4))
+        };
+        const headers2 = new Headers();
+        for (let i = 0; i < incoming.rawHeaders.length; i += 2) headers2.append(incoming.rawHeaders[i], incoming.rawHeaders[i + 1]);
+        const status = incoming.statusCode;
+        if (status < 200 || status > 599) {
+          incoming.destroy();
+          reject(new import_protocol2.VerificationError("not a final HTTP response", { code: import_protocol2.VerificationCode.SignatureInvalid }));
+          return;
+        }
+        const noBody = request2.method === "HEAD" || [204, 205, 304].includes(status);
+        const iterator = incoming[Symbol.asyncIterator]();
+        let canceled = false;
+        incoming.on("error", () => {
+        });
+        const body = noBody ? null : new ReadableStream({
+          async pull(controller) {
+            try {
+              const { value, done } = await iterator.next();
+              if (canceled) return;
+              if (done) controller.close();
+              else controller.enqueue(new Uint8Array(value));
+            } catch (error) {
+              if (!canceled) controller.error(error);
+            }
+          },
+          cancel() {
+            canceled = true;
+            incoming.destroy();
+            outgoing.destroy();
+          }
+        });
+        if (noBody) incoming.resume();
+        resolve({ response: new Response(body, { status, statusText: incoming.statusMessage, headers: headers2 }), peerCert });
+      });
+      const fail = (cause) => reject(cause instanceof import_protocol2.VerificationError ? cause : httpsTransportError(cause));
+      outgoing.on("error", fail);
+      outgoing.on("upgrade", (_response, socket) => {
+        socket.destroy();
+        fail(new import_protocol2.VerificationError("protocol upgrades are unsupported", { code: import_protocol2.VerificationCode.SignatureInvalid }));
+      });
+      outgoing.on("connect", (_response, socket) => {
+        socket.destroy();
+        fail(new import_protocol2.VerificationError("tunnels are unsupported", { code: import_protocol2.VerificationCode.SignatureInvalid }));
+      });
+      outgoing.end(content ?? void 0);
+    });
+  };
+}
 function createSsrfSafeFetch(config = {}, options = {}) {
   const privateAddressHosts = (options.privateAddressHosts ?? []).map(import_protocol2.normalizePrivateAddressHost);
   const connect2 = { lookup: createSsrfSafeLookup(config.dnsServer, privateAddressHosts) };
@@ -202,21 +282,21 @@ function createSsrfSafeFetch(config = {}, options = {}) {
     }
     if (options.decompress === false) {
       const { url: target, init: normalized } = normalizeFetchArgs(input, { ...init, redirect: "manual" });
-      const request = new Request(target, normalized);
-      const targetUrl = new URL(request.url);
+      const request2 = new Request(target, normalized);
+      const targetUrl = new URL(request2.url);
       const response = await dispatcher.request({
         origin: targetUrl.origin,
         path: targetUrl.pathname + targetUrl.search,
-        method: request.method,
-        headers: Object.fromEntries(request.headers),
-        body: request.body ? import_node_stream.Readable.fromWeb(request.body) : void 0,
-        signal: request.signal
+        method: request2.method,
+        headers: Object.fromEntries(request2.headers),
+        body: request2.body ? import_node_stream.Readable.fromWeb(request2.body) : void 0,
+        signal: request2.signal
       });
       const headers = new Headers();
       for (const [name, value] of Object.entries(response.headers)) {
         for (const item of Array.isArray(value) ? value : value === void 0 ? [] : [value]) headers.append(name, item);
       }
-      const noBody = request.method === "HEAD" || [204, 205, 304].includes(response.statusCode);
+      const noBody = request2.method === "HEAD" || [204, 205, 304].includes(response.statusCode);
       let body = null;
       if (noBody) await response.body.dump();
       else {
@@ -646,14 +726,7 @@ function fetchWithRedirects(url, opts, depth) {
         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_protocol2.VerificationError(`HTTPS fetch failed: ${err.message}`, {
-        code: import_protocol2.VerificationCode.TLSError,
-        transient: !isTls
-      }));
-    });
+    req.on("error", (err) => reject(httpsTransportError(err)));
   });
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -662,6 +735,7 @@ function fetchWithRedirects(url, opts, depth) {
   createDnsResolverFromServer,
   createDnsidFetch,
   createLookup,
+  createResponseSignatureTransport,
   createSsrfSafeFetch,
   fetchJson,
   formatDnsServer,

package/dist/index.d.cts

@@ -70,6 +70,19 @@ interface SsrfSafeFetchOptions {
  * ```
  */
 declare function createDnsidFetch(config: TransportConfig): FetchLike;
+/**
+ * Creates the single-send transport consumed by HTTP signatures' responseTransport option.
+ * Sends HTTPS once per call, without redirects, retries, caches, or content decoding, and
+ * reuses keep-alive connections across calls. Returns the certificate of the connection
+ * that carried this response. Request bodies are buffered and sent with Content-Length.
+ * The signed client bounds body reads to 8 MiB; standalone consumers must also bound reads
+ * and cancel rejected responses. DNS and additional CA settings follow createDnsidFetch;
+ * private addresses are not filtered and proxy environment variables are not used.
+ */
+declare function createResponseSignatureTransport(config?: TransportConfig): (request: Request) => Promise<{
+    response: Response;
+    peerCert: TLSCertificate;
+}>;
 /**
  * Creates a fetch function that rejects connections to private, loopback,
  * link-local, and other non-routable addresses (SSRF protection).
@@ -157,4 +170,4 @@ declare function createLookup(dnsServer: string): NonNullable<https.RequestOptio
  */
 declare function isUnsafeIp(address: string): boolean;
 
-export { type FetchLike, type FetchResult, type HTTPSFetchOptions, type SsrfSafeFetchOptions, createDefaultDnsResolver, createDnsResolverFromServer, createDnsidFetch, createLookup, createSsrfSafeFetch, fetchJson, formatDnsServer, isUnsafeIp, parseDnsServer };
+export { type FetchLike, type FetchResult, type HTTPSFetchOptions, type SsrfSafeFetchOptions, createDefaultDnsResolver, createDnsResolverFromServer, createDnsidFetch, createLookup, createResponseSignatureTransport, createSsrfSafeFetch, fetchJson, formatDnsServer, isUnsafeIp, parseDnsServer };

package/dist/index.d.ts

@@ -70,6 +70,19 @@ interface SsrfSafeFetchOptions {
  * ```
  */
 declare function createDnsidFetch(config: TransportConfig): FetchLike;
+/**
+ * Creates the single-send transport consumed by HTTP signatures' responseTransport option.
+ * Sends HTTPS once per call, without redirects, retries, caches, or content decoding, and
+ * reuses keep-alive connections across calls. Returns the certificate of the connection
+ * that carried this response. Request bodies are buffered and sent with Content-Length.
+ * The signed client bounds body reads to 8 MiB; standalone consumers must also bound reads
+ * and cancel rejected responses. DNS and additional CA settings follow createDnsidFetch;
+ * private addresses are not filtered and proxy environment variables are not used.
+ */
+declare function createResponseSignatureTransport(config?: TransportConfig): (request: Request) => Promise<{
+    response: Response;
+    peerCert: TLSCertificate;
+}>;
 /**
  * Creates a fetch function that rejects connections to private, loopback,
  * link-local, and other non-routable addresses (SSRF protection).
@@ -157,4 +170,4 @@ declare function createLookup(dnsServer: string): NonNullable<https.RequestOptio
  */
 declare function isUnsafeIp(address: string): boolean;
 
-export { type FetchLike, type FetchResult, type HTTPSFetchOptions, type SsrfSafeFetchOptions, createDefaultDnsResolver, createDnsResolverFromServer, createDnsidFetch, createLookup, createSsrfSafeFetch, fetchJson, formatDnsServer, isUnsafeIp, parseDnsServer };
+export { type FetchLike, type FetchResult, type HTTPSFetchOptions, type SsrfSafeFetchOptions, createDefaultDnsResolver, createDnsResolverFromServer, createDnsidFetch, createLookup, createResponseSignatureTransport, createSsrfSafeFetch, fetchJson, formatDnsServer, isUnsafeIp, parseDnsServer };

package/dist/index.js

@@ -55,7 +55,7 @@ async function resolveTxtWithTtl(name, host, port, signal) {
 }
 async function query(name, host, port, signal) {
   const id = randomInt(65536);
-  const request = {
+  const request2 = {
     type: "query",
     id,
     flags: packet.RECURSION_DESIRED,
@@ -71,9 +71,9 @@ async function query(name, host, port, signal) {
       return null;
     }
   };
-  const response = await udp(packet.encode(request), host, port, signal, valid);
+  const response = await udp(packet.encode(request2), host, port, signal, valid);
   if (!response.flag_tc) return response;
-  const tcpResponse = valid(await tcp(packet.streamEncode(request), host, port, signal));
+  const tcpResponse = valid(await tcp(packet.streamEncode(request2), host, port, signal));
   if (!tcpResponse || tcpResponse.flag_tc) throw badResponse();
   return tcpResponse;
 }
@@ -136,6 +136,15 @@ function tcp(buf, host, port, signal) {
 var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
 var DEFAULT_MAX_RESPONSE_BYTES = 1 * 1024 * 1024;
 var DNSID_USER_AGENT = "dnsid-ts";
+function httpsTransportError(cause) {
+  const err = cause;
+  const isTls = err.code === "DEPTH_ZERO_SELF_SIGNED_CERT" || err.code === "CERT_HAS_EXPIRED" || err.code === "ERR_TLS_CERT_ALTNAME_INVALID" || err.code === "UNABLE_TO_VERIFY_LEAF_SIGNATURE";
+  return new VerificationError(`HTTPS fetch failed: ${err.message}`, {
+    code: VerificationCode.TLSError,
+    transient: !isTls,
+    cause
+  });
+}
 function createDnsidFetch(config) {
   if (!config.dnsServer && !config.caBundlePath) {
     return globalThis.fetch.bind(globalThis);
@@ -145,6 +154,76 @@ function createDnsidFetch(config) {
   if (config.caBundlePath) connect2.ca = [...tls.rootCertificates, fs.readFileSync(config.caBundlePath, "utf8")];
   return createFetchWithDispatcher(new Agent2({ connect: connect2 }));
 }
+function createResponseSignatureTransport(config = {}) {
+  const lookup2 = config.dnsServer ? createLookup(config.dnsServer) : void 0;
+  const ca = config.caBundlePath ? [...tls.rootCertificates, fs.readFileSync(config.caBundlePath, "utf8")] : void 0;
+  const agent = new https.Agent({ keepAlive: true, lookup: lookup2, ca, rejectUnauthorized: true });
+  return async (request2) => {
+    const url = new URL(request2.url);
+    if (url.protocol !== "https:") throw new ArgumentError("response authentication requires HTTPS");
+    const signal = AbortSignal.any([request2.signal, AbortSignal.timeout(DEFAULT_REQUEST_TIMEOUT_MS * 3)]);
+    const content = request2.body ? Buffer.from(await request2.arrayBuffer()) : null;
+    const headers = Object.fromEntries(request2.headers);
+    if (content) headers["content-length"] = String(content.length);
+    return new Promise((resolve, reject) => {
+      const outgoing = https.request(url, {
+        agent,
+        signal,
+        method: request2.method,
+        headers
+      }, (incoming) => {
+        const cert = incoming.socket.getPeerCertificate();
+        const peerCert = {
+          notAfter: new Date(cert.valid_to),
+          san: (cert.subjectaltname ?? "").split(", ").filter((s) => s.startsWith("DNS:")).map((s) => s.slice(4))
+        };
+        const headers2 = new Headers();
+        for (let i = 0; i < incoming.rawHeaders.length; i += 2) headers2.append(incoming.rawHeaders[i], incoming.rawHeaders[i + 1]);
+        const status = incoming.statusCode;
+        if (status < 200 || status > 599) {
+          incoming.destroy();
+          reject(new VerificationError("not a final HTTP response", { code: VerificationCode.SignatureInvalid }));
+          return;
+        }
+        const noBody = request2.method === "HEAD" || [204, 205, 304].includes(status);
+        const iterator = incoming[Symbol.asyncIterator]();
+        let canceled = false;
+        incoming.on("error", () => {
+        });
+        const body = noBody ? null : new ReadableStream({
+          async pull(controller) {
+            try {
+              const { value, done } = await iterator.next();
+              if (canceled) return;
+              if (done) controller.close();
+              else controller.enqueue(new Uint8Array(value));
+            } catch (error) {
+              if (!canceled) controller.error(error);
+            }
+          },
+          cancel() {
+            canceled = true;
+            incoming.destroy();
+            outgoing.destroy();
+          }
+        });
+        if (noBody) incoming.resume();
+        resolve({ response: new Response(body, { status, statusText: incoming.statusMessage, headers: headers2 }), peerCert });
+      });
+      const fail = (cause) => reject(cause instanceof VerificationError ? cause : httpsTransportError(cause));
+      outgoing.on("error", fail);
+      outgoing.on("upgrade", (_response, socket) => {
+        socket.destroy();
+        fail(new VerificationError("protocol upgrades are unsupported", { code: VerificationCode.SignatureInvalid }));
+      });
+      outgoing.on("connect", (_response, socket) => {
+        socket.destroy();
+        fail(new VerificationError("tunnels are unsupported", { code: VerificationCode.SignatureInvalid }));
+      });
+      outgoing.end(content ?? void 0);
+    });
+  };
+}
 function createSsrfSafeFetch(config = {}, options = {}) {
   const privateAddressHosts = (options.privateAddressHosts ?? []).map(normalizePrivateAddressHost);
   const connect2 = { lookup: createSsrfSafeLookup(config.dnsServer, privateAddressHosts) };
@@ -160,21 +239,21 @@ function createSsrfSafeFetch(config = {}, options = {}) {
     }
     if (options.decompress === false) {
       const { url: target, init: normalized } = normalizeFetchArgs(input, { ...init, redirect: "manual" });
-      const request = new Request(target, normalized);
-      const targetUrl = new URL(request.url);
+      const request2 = new Request(target, normalized);
+      const targetUrl = new URL(request2.url);
       const response = await dispatcher.request({
         origin: targetUrl.origin,
         path: targetUrl.pathname + targetUrl.search,
-        method: request.method,
-        headers: Object.fromEntries(request.headers),
-        body: request.body ? Readable.fromWeb(request.body) : void 0,
-        signal: request.signal
+        method: request2.method,
+        headers: Object.fromEntries(request2.headers),
+        body: request2.body ? Readable.fromWeb(request2.body) : void 0,
+        signal: request2.signal
       });
       const headers = new Headers();
       for (const [name, value] of Object.entries(response.headers)) {
         for (const item of Array.isArray(value) ? value : value === void 0 ? [] : [value]) headers.append(name, item);
       }
-      const noBody = request.method === "HEAD" || [204, 205, 304].includes(response.statusCode);
+      const noBody = request2.method === "HEAD" || [204, 205, 304].includes(response.statusCode);
       let body = null;
       if (noBody) await response.body.dump();
       else {
@@ -604,14 +683,7 @@ function fetchWithRedirects(url, opts, depth) {
         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 VerificationError(`HTTPS fetch failed: ${err.message}`, {
-        code: VerificationCode.TLSError,
-        transient: !isTls
-      }));
-    });
+    req.on("error", (err) => reject(httpsTransportError(err)));
   });
 }
 export {
@@ -619,6 +691,7 @@ export {
   createDnsResolverFromServer,
   createDnsidFetch,
   createLookup,
+  createResponseSignatureTransport,
   createSsrfSafeFetch,
   fetchJson,
   formatDnsServer,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dnsid-ai/transport",
   "author": "Known Systems AI, Inc.",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Node.js DNS and HTTPS transport implementations for DNSid.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -41,7 +41,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@dnsid-ai/protocol": "^0.32.0",
+    "@dnsid-ai/protocol": "^0.33.0",
     "dns-packet": "5.6.1",
     "undici": "^8.12.3"
   },