stitchkit 0.114.1 → 0.114.2

package/CHANGELOG.md

@@ -15,6 +15,14 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.114.2] - 2026-10-31
+
+### Fixed
+
+- `stitchkit/tools`, `stitchkit/cli` — the guarded fetch behind `view_file`, `mountDownload` and the CLI `--output-dir` download pins every hop to the address that passed the public-address check. It resolved a hostname, validated the answer, then let `fetch` resolve the same name again, so a resolver that answers public and then private could open a private or loopback socket (SSRF rebinding). The connection is now opened to the validated address with the URL's `Host` header and, over TLS, its server name, on every redirect hop; a URL carrying credentials is refused rather than moved to whatever host a redirect names. Streaming, backpressure, the header/body deadlines, the body cap and output-dir containment are unchanged; `allowPrivateHosts` / `allowPrivateDownloadHosts` still widen the address check without a second lookup.
+  **Affects:** `stitchkit/tools` behaviour; `stitchkit/cli` behaviour
+
+
 ## [0.114.1] - 2026-10-31
 
 ### Added

package/dist/entrypoints/cli/publish.js

@@ -15,7 +15,7 @@ import {
   gzipCliAsset,
   decodeCliAsset,
   compareCliVersions2
-} from "../../index-kdnfe0sr.js";
+} from "../../index-912sza5h.js";
 import {
   withExclusiveLock2
 } from "../../index-6b3pcq5z.js";

package/dist/entrypoints/cli.js

@@ -16,7 +16,7 @@ import {
   renderCliView2,
   pollUntilDone2,
   createCli2
-} from "../index-km2qw407.js";
+} from "../index-tnxsq7cw.js";
 import"../index-k42ckyzx.js";
 import"../index-ct75c3at.js";
 import"../index-rhzkndr5.js";
@@ -40,7 +40,7 @@ import {
   checkCliUpdate2,
   applyCliUpdate2,
   rollbackCliUpdate2
-} from "../index-kdnfe0sr.js";
+} from "../index-912sza5h.js";
 import"../index-86nbfysb.js";
 import"../index-ega3yz4c.js";
 import {

package/dist/entrypoints/tools.js

@@ -74,7 +74,7 @@ import {
   WaitTimeoutError,
   runWaitOperation,
   createCli2
-} from "../index-km2qw407.js";
+} from "../index-tnxsq7cw.js";
 import {
   ManagedFilePathSchema2,
   ManagedFileRefSchema2
@@ -110,7 +110,7 @@ import {
   fetchGuarded,
   fetchPinnedDocument,
   readCapped
-} from "../index-t65erk4z.js";
+} from "../index-mgb7r8b8.js";
 import"../index-1bx1xv1k.js";
 import {
   readBoundedChunks,

package/dist/{index-kdnfe0sr.js → index-912sza5h.js}

@@ -5,7 +5,7 @@ import {
   fetchGuarded,
   PrivateAddressRefusal,
   readCapped
-} from "./index-t65erk4z.js";
+} from "./index-mgb7r8b8.js";
 import {
   writeFileAtomicSync2
 } from "./index-07dcf2yn.js";

package/dist/{index-t65erk4z.js → index-mgb7r8b8.js}

@@ -7,9 +7,88 @@ import {
 
 // src/internal/secure-fetch.ts
 import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+// src/internal/pinned-http.ts
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
-import { isIP } from "node:net";
+async function requestPinned(url, resolved, signal, headers = {}) {
+  const transport = url.protocol === "https:" ? httpsRequest : httpRequest;
+  const incoming = await new Promise((resolve, reject) => {
+    let answered = false;
+    const request = transport({
+      protocol: url.protocol,
+      hostname: resolved.address,
+      family: resolved.family,
+      port: url.port || undefined,
+      path: `${url.pathname}${url.search}`,
+      method: "GET",
+      signal,
+      ...url.protocol === "https:" ? { servername: url.hostname } : {},
+      headers: { host: url.host, accept: "*/*", ...headers }
+    }, (response) => {
+      answered = true;
+      resolve(response);
+    });
+    request.once("error", (error) => {
+      if (answered)
+        return;
+      reject(signal?.aborted && signal.reason !== undefined ? signal.reason : error);
+    });
+    request.end();
+  });
+  return pinnedResponse(incoming);
+}
+function pinnedResponse(incoming) {
+  const status = incoming.statusCode ?? 0;
+  const headers = new Headers;
+  for (const [name, value] of Object.entries(incoming.headers)) {
+    if (Array.isArray(value)) {
+      for (const item of value)
+        headers.append(name, item);
+    } else if (value !== undefined) {
+      headers.set(name, value);
+    }
+  }
+  if (status === 204 || status === 205 || status === 304) {
+    incoming.resume();
+    return new Response(null, { status, statusText: incoming.statusMessage, headers });
+  }
+  let done = false;
+  const body = new ReadableStream({
+    start(controller) {
+      incoming.on("data", (chunk) => {
+        if (done)
+          return;
+        controller.enqueue(chunk);
+        if ((controller.desiredSize ?? 1) <= 0)
+          incoming.pause();
+      });
+      incoming.once("end", () => {
+        if (done)
+          return;
+        done = true;
+        controller.close();
+      });
+      incoming.once("error", (error) => {
+        if (done)
+          return;
+        done = true;
+        controller.error(error);
+      });
+    },
+    pull() {
+      incoming.resume();
+    },
+    cancel() {
+      done = true;
+      incoming.destroy();
+    }
+  });
+  return new Response(body, { status, statusText: incoming.statusMessage, headers });
+}
+
+// src/internal/secure-fetch.ts
 var NUMERIC_HOST = /^(0x[0-9a-f]+|[0-9.]+)$/i;
 var MAX_REDIRECTS = 5;
 function assertHttpUrl(url) {
@@ -102,9 +181,10 @@ function isPrivateIp(ip) {
   }
   return false;
 }
-async function assertPublicUrl(url, signal) {
-  await resolvePublicAddress(url, signal);
-}
+var defaultLookup = async (host) => {
+  const records = await lookup(host, { all: true });
+  return Array.isArray(records) ? records : [records];
+};
 async function fetchGuarded(start, allowPrivate, options = {}) {
   const timeoutMs = options.timeoutMs ?? 15000;
   const bodyTimeoutMs = options.bodyTimeoutMs ?? 120000;
@@ -120,15 +200,16 @@ async function fetchGuarded(start, allowPrivate, options = {}) {
     controller.abort(new Error(`fetch did not produce response headers within ${timeoutMs}ms`));
   }, timeoutMs);
   headerTimer.unref?.();
+  const transport = options.transport ?? requestPinned;
   let settled = false;
   try {
     let url = start;
     for (let hop = 0;hop <= MAX_REDIRECTS; hop++) {
-      if (allowPrivate)
-        assertHttpUrl(url);
-      else
-        await assertPublicUrl(url, signal);
-      const res = await fetch(url, { redirect: "manual", signal });
+      if (url.username || url.password) {
+        throw new Error("refusing to fetch a URL that carries credentials");
+      }
+      const resolved = await resolveAddress(url, allowPrivate, signal, options.dns);
+      const res = await transport(url, resolved, signal);
       const location = res.status >= 300 && res.status < 400 ? res.headers.get("location") : null;
       if (location === null) {
         settled = true;
@@ -148,11 +229,27 @@ async function fetchGuarded(start, allowPrivate, options = {}) {
       clearTimeout(headerTimer);
   }
 }
+async function resolveAddress(url, allowPrivate, signal, dns) {
+  if (!allowPrivate)
+    return resolvePublicAddress(url, signal, dns);
+  assertHttpUrl(url);
+  const host = url.hostname.replace(/^\[|\]$/g, "");
+  if (!host)
+    throw new Error("refusing to fetch a URL with no host");
+  const ipFamily = isIP(host);
+  if (ipFamily)
+    return { address: host, family: ipFamily === 6 ? 6 : 4 };
+  const records = await (dns ?? defaultLookup)(host, { all: true });
+  const record = records[0];
+  if (!record)
+    throw new Error("host resolved to no addresses");
+  return { address: record.address, family: record.family === 6 ? 6 : 4 };
+}
 
 class PrivateAddressRefusal extends Error {
   name = "PrivateAddressRefusal";
 }
-async function resolvePublicAddress(url, signal) {
+async function resolvePublicAddress(url, signal, dns) {
   assertHttpUrl(url);
   const host = url.hostname.replace(/^\[|\]$/g, "");
   if (!host)
@@ -169,7 +266,7 @@ async function resolvePublicAddress(url, signal) {
   if (host === "localhost" || host.endsWith(".local") || host.endsWith(".internal")) {
     throw new PrivateAddressRefusal("refusing to fetch an internal host");
   }
-  const pending = lookup(host, { all: true });
+  const pending = (dns ?? defaultLookup)(host, { all: true });
   const records = signal ? await raceAbort(pending, signal) : await pending;
   for (const record of records) {
     if (isPrivateIp(record.address)) {
@@ -202,61 +299,24 @@ async function fetchPinnedDocument(start, options) {
       throw new Error("document URL cannot contain credentials");
     }
     const resolved = await resolvePublicAddress(url, signal);
-    const transport = url.protocol === "https:" ? httpsRequest : httpRequest;
-    const response = await new Promise((resolve, reject) => {
-      const request = transport({
-        protocol: url.protocol,
-        hostname: resolved.address,
-        family: resolved.family,
-        port: url.port || undefined,
-        path: `${url.pathname}${url.search}`,
-        method: "GET",
-        signal,
-        servername: url.hostname,
-        headers: {
-          host: url.host,
-          accept: "application/json",
-          ...options.headers
-        }
-      }, (incoming) => {
-        const headers = new Headers;
-        for (const [name, value] of Object.entries(incoming.headers)) {
-          if (Array.isArray(value)) {
-            for (const item of value)
-              headers.append(name, item);
-          } else if (value !== undefined) {
-            headers.set(name, value);
-          }
-        }
-        const chunks = [];
-        let total = 0;
-        incoming.on("data", (chunk) => {
-          total += chunk.byteLength;
-          if (total > options.maxBytes) {
-            incoming.destroy(new Error("response body exceeds configured byte limit"));
-            return;
-          }
-          chunks.push(chunk);
-        });
-        incoming.once("error", reject);
-        incoming.once("end", () => {
-          const body = new Uint8Array(total);
-          let offset = 0;
-          for (const chunk of chunks) {
-            body.set(chunk, offset);
-            offset += chunk.byteLength;
-          }
-          resolve({ status: incoming.statusCode ?? 0, headers, body, url });
-        });
-      });
-      request.once("error", reject);
-      request.end();
+    const response = await requestPinned(url, resolved, signal, {
+      accept: "application/json",
+      ...options.headers
     });
+    const body = await readCapped(response, options.maxBytes);
+    if (body === null)
+      throw new Error("response body exceeds configured byte limit");
+    const document = {
+      status: response.status,
+      headers: response.headers,
+      body: new Uint8Array(body),
+      url
+    };
     if (response.status < 300 || response.status >= 400)
-      return response;
+      return document;
     const location = response.headers.get("location");
     if (!location)
-      return response;
+      return document;
     url = new URL(location, url);
   }
   throw new Error("too many redirects");

package/dist/{index-km2qw407.js → index-tnxsq7cw.js}

@@ -29,7 +29,7 @@ import {
 import {
   fetchGuarded,
   readCapped
-} from "./index-t65erk4z.js";
+} from "./index-mgb7r8b8.js";
 import {
   isWithinDir2
 } from "./index-5cc6r990.js";

package/dist/internal/pinned-http.d.ts

@@ -0,0 +1,27 @@
+/**
+ * One hop over a socket opened to the address the guard validated.
+ *
+ * The address is given, never looked up here: that is what makes a validated
+ * answer the one the connection uses. The `Host` header keeps the URL's host
+ * and, over TLS, the certificate is verified against it (`servername`), so a
+ * pinned connection is not a weaker one. The body is a Fetch stream over the
+ * socket, with backpressure and cancellation preserved.
+ */
+import type { IncomingMessage } from 'node:http';
+/** One hop, already resolved: open the connection to exactly `address`. */
+export type PinnedTransport = (url: URL, resolved: {
+    address: string;
+    family: 4 | 6;
+}, signal: AbortSignal | undefined) => Promise<Response>;
+/**
+ * One hop over a socket opened to `resolved.address`: the `Host` header keeps
+ * the URL's host and, for TLS, the certificate is verified against it
+ * (`servername`), so a pinned connection is not a weaker connection.
+ */
+export declare function requestPinned(url: URL, resolved: {
+    address: string;
+    family: 4 | 6;
+}, signal: AbortSignal | undefined, headers?: Record<string, string>): Promise<Response>;
+/** An `IncomingMessage` as a streaming Fetch response, keeping backpressure and cancellation. */
+export declare function pinnedResponse(incoming: IncomingMessage): Response;
+//# sourceMappingURL=pinned-http.d.ts.map

package/dist/internal/pinned-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-http.d.ts","sourceRoot":"","sources":["../../src/internal/pinned-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAIjD,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,GAAG,EACR,QAAQ,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAA;CAAE,EAC5C,MAAM,EAAE,WAAW,GAAG,SAAS,KAC5B,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,GAAG,EACR,QAAQ,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAA;CAAE,EAC5C,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACnC,OAAO,CAAC,QAAQ,CAAC,CAgCnB;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,QAAQ,CA6ClE"}

package/dist/internal/secure-fetch.d.ts

@@ -1,3 +1,4 @@
+import type { PinnedTransport } from './pinned-http.js';
 /** True unless the literal belongs to the globally routable unicast Internet. */
 export declare function isPrivateIp(ip: string): boolean;
 /**
@@ -14,13 +15,21 @@ export declare function assertPublicUrl(url: URL, signal?: AbortSignal): Promise
 /**
  * Fetch a URL with the SSRF guard enforced on the initial URL and on every
  * redirect hop — a public host can otherwise `302` to an internal address or a
- * non-http(s) scheme.
- *
- * Note: the DNS resolution here and the resolution `fetch` performs are
- * separate, so a hostile resolver retains a narrow rebinding window. The
- * per-hop re-check is the larger and fully-closed hole; a static private DNS
- * record is rejected outright.
+ * non-http(s) scheme — and with the connection pinned to the address that
+ * passed the check, so a resolver cannot answer public and then connect
+ * somewhere private.
+ */
+/**
+ * The resolver seam: one `lookup` call per hop. Production uses `node:dns`;
+ * a test supplies a controlled answer to prove which address the socket went
+ * to, and that a second answer cannot open another one.
  */
+export type GuardedDnsLookup = (host: string, options: {
+    all: true;
+}) => Promise<Array<{
+    address: string;
+    family: number;
+}>>;
 export interface GuardedFetchOptions {
     /**
      * Deadline for producing the FINAL response headers — DNS, connects and every
@@ -36,6 +45,17 @@ export interface GuardedFetchOptions {
     bodyTimeoutMs?: number;
     /** Optional caller cancellation, combined with both deadlines. */
     signal?: AbortSignal;
+    /**
+     * Test seam: the resolver whose answer the connection is pinned to. Default
+     * `node:dns`. It replaces the name lookup, never the address check.
+     */
+    dns?: GuardedDnsLookup;
+    /**
+     * Test seam: how one resolved hop is opened. Default the pinned
+     * `http`/`https` request. Only the redirect tests replace it; production and
+     * the rebinding test use the default, which is where pinning happens.
+     */
+    transport?: PinnedTransport;
 }
 export declare function fetchGuarded(start: URL, allowPrivate: boolean, options?: GuardedFetchOptions): Promise<Response>;
 export interface PinnedDocumentFetchOptions {

package/dist/internal/secure-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-fetch.d.ts","sourceRoot":"","sources":["../../src/internal/secure-fetch.ts"],"names":[],"mappings":"AAmEA,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA8D/C;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,GAAG,EACV,YAAY,EAAE,OAAO,EACrB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAiDnB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,2BAA2B;CACzC;AA8CD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAkFjC;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGnF"}
+{"version":3,"file":"secure-fetch.d.ts","sourceRoot":"","sources":["../../src/internal/secure-fetch.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAmDrD,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA8D/C;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF;AAED;;;;;;GAMG;AACH;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IAAE,GAAG,EAAE,IAAI,CAAA;CAAE,KACnB,OAAO,CAAC,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAAC;AAQzD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB;;;;OAIG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,GAAG,EACV,YAAY,EAAE,OAAO,EACrB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAuDnB;AAqBD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,2BAA2B;CACzC;AA+CD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CA2CjC;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGnF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.114.1",
+  "version": "0.114.2",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",