@juspay/neurolink 9.87.0 → 9.87.2

package/dist/lib/types/safeFetch.d.ts

@@ -3,6 +3,15 @@
  *
  * Runtime helper lives in `src/lib/utils/safeFetch.ts`.
  */
+/**
+ * One validated address the pinned connect layer is allowed to dial.
+ * Produced by `ssrfGuard.ts:validateAndResolveUrl`, consumed by
+ * `safeFetch.ts:buildPinnedAgent`.
+ */
+export type PinnedAddress = {
+    ip: string;
+    family: 4 | 6;
+};
 export type SafeDownloadOptions = {
     /** Hard cap on response size in bytes. Pass MAX_VIDEO_BYTES/MAX_AUDIO_BYTES/MAX_IMAGE_BYTES from sizeGuard. */
     maxBytes: number;

package/dist/lib/utils/safeFetch.d.ts

@@ -4,9 +4,9 @@
  * Combines:
  *   - `assertSafeUrl` (validates and rejects blocked IPs)
  *   - undici `Agent` with custom `connect.lookup` so the actual connection
- *     uses the IP we validated (closes the DNS-rebinding window where the
- *     resolver returns a public IP for the guard but a private IP for the
- *     real request).
+ *     only ever dials addresses we validated (closes the DNS-rebinding window
+ *     where the resolver returns a public IP for the guard but a private IP
+ *     for the real request).
  *   - `readBoundedBuffer` for size cap.
  *   - `redirect: "manual"` so a 3xx → private-IP redirect can't bypass
  *     the guard.

package/dist/lib/utils/safeFetch.js

@@ -4,9 +4,9 @@
  * Combines:
  *   - `assertSafeUrl` (validates and rejects blocked IPs)
  *   - undici `Agent` with custom `connect.lookup` so the actual connection
- *     uses the IP we validated (closes the DNS-rebinding window where the
- *     resolver returns a public IP for the guard but a private IP for the
- *     real request).
+ *     only ever dials addresses we validated (closes the DNS-rebinding window
+ *     where the resolver returns a public IP for the guard but a private IP
+ *     for the real request).
  *   - `readBoundedBuffer` for size cap.
  *   - `redirect: "manual"` so a 3xx → private-IP redirect can't bypass
  *     the guard.
@@ -21,21 +21,39 @@ import { readBoundedBuffer } from "./sizeGuard.js";
 import { validateAndResolveUrl } from "./ssrfGuard.js";
 const DEFAULT_TIMEOUT_MS = 60_000;
 /**
- * Build a once-off undici Agent whose connect lookup resolves `hostname` to a
- * fixed IP. This pins the actual TCP connection to the IP we validated,
- * removing the DNS-rebinding window.
+ * Build a once-off undici Agent whose connect lookup resolves `hostname` to
+ * the validated address set. The actual TCP connection can only ever go to
+ * an address the SSRF guard cleared, removing the DNS-rebinding window.
+ *
+ * The full set (IPv4 first) matters: pinning a single address turns one
+ * unroutable family into a hard connect timeout. On IPv4-only networks where
+ * the OS resolver prefers AAAA, that broke every safeDownload (Replicate /
+ * Runway / Kling asset fetches) while plain curl of the same URL succeeded —
+ * curl races both families (Happy Eyeballs); a one-address pin cannot.
  */
-function buildPinnedAgent(hostname, ip, family) {
+function buildPinnedAgent(hostname, addresses) {
+    const primary = addresses[0];
+    if (!primary) {
+        throw new Error(`safeFetch: no validated addresses to pin for "${hostname}"`);
+    }
     return new Agent({
         connect: {
-            lookup: (host, _options, callback) => {
+            lookup: (host, options, callback) => {
                 if (host.toLowerCase() !== hostname.toLowerCase()) {
                     // The host the connect layer asks for differs from the URL host —
                     // this happens for absolute Host headers etc. Reject defensively.
                     callback(new Error(`safeFetch: refusing to resolve "${host}" — expected "${hostname}"`), "", 0);
                     return;
                 }
-                callback(null, ip, family);
+                // Node ≥20 enables autoSelectFamily (Happy Eyeballs) by default, and
+                // its lookup contract passes `all: true` expecting an address ARRAY.
+                // Hand it every validated address so it can race families and fall
+                // back when one is unroutable.
+                if (options?.all) {
+                    callback(null, addresses.map((a) => ({ address: a.ip, family: a.family })));
+                    return;
+                }
+                callback(null, primary.ip, primary.family);
             },
         },
     });
@@ -47,10 +65,10 @@ function buildPinnedAgent(hostname, ip, family) {
  *   is encountered, or the HTTP status indicates failure.
  */
 export async function safeDownload(url, options) {
-    const { url: validatedUrl, ip, family } = await validateAndResolveUrl(url);
+    const { url: validatedUrl, addresses } = await validateAndResolveUrl(url);
     const parsed = new URL(validatedUrl);
     const hostname = parsed.hostname.replace(/^\[|\]$/g, "");
-    const agent = buildPinnedAgent(hostname, ip, family);
+    const agent = buildPinnedAgent(hostname, addresses);
     const timeoutCtrl = new AbortController();
     const timeoutId = setTimeout(() => timeoutCtrl.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     const composedSignal = options.signal

package/dist/lib/utils/ssrfGuard.d.ts

@@ -24,6 +24,7 @@
  *
  * @module utils/ssrfGuard
  */
+import type { PinnedAddress } from "../types/index.js";
 /**
  * Assert that `url` is safe to fetch server-side.
  *
@@ -35,12 +36,18 @@
  */
 export declare function assertSafeUrl(url: string): Promise<void>;
 /**
- * Validate `url` and return the resolved IP that should be used for the
- * actual fetch (companion to `safeFetch.ts:safeDownload`).
+ * Validate `url` and return the resolved address set that should be used for
+ * the actual fetch (companion to `safeFetch.ts:safeDownload`).
  *
- * For IP-literal hosts, returns the normalised IP and family. For hostnames,
- * returns the first acceptable IP from the resolver. Same throw semantics as
- * {@link assertSafeUrl}.
+ * For IP-literal hosts, `addresses` is the normalised IP as a singleton. For
+ * hostnames it is **every** validated address, IPv4 first, so the connect
+ * layer can race families (Happy Eyeballs). Pinning a single OS-preferred
+ * address breaks every download on IPv4-only networks whenever the resolver
+ * prefers AAAA: the pinned connection has no second address to fall back to,
+ * so it times out where plain `curl` (which races both families) succeeds.
+ * `ip`/`family` mirror the first entry for callers that need a single pin.
+ *
+ * Same throw semantics as {@link assertSafeUrl}.
  *
  * This is the canonical entry point for binary downloads where DNS-rebinding
  * pinning matters — see `safeFetch.ts`.
@@ -49,4 +56,5 @@ export declare function validateAndResolveUrl(url: string): Promise<{
     url: string;
     ip: string;
     family: 4 | 6;
+    addresses: readonly PinnedAddress[];
 }>;

package/dist/lib/utils/ssrfGuard.js

@@ -306,6 +306,17 @@ export async function assertSafeUrl(url) {
     }
     // Hostname — resolve BOTH A and AAAA. Reject if either family yields a
     // blocked address (closes off the "publish AAAA public, A private" attack).
+    await resolveAndValidateHost(url, host);
+}
+/**
+ * Resolve `host` (both A and AAAA) and validate every returned address
+ * against the block lists. Returns the full validated set so callers that
+ * pin connections can offer the connect layer more than one address.
+ *
+ * @throws {Error} when resolution fails entirely or any address is blocked
+ *   (all-must-pass — the caller may connect to any address in the set).
+ */
+async function resolveAndValidateHost(url, host) {
     const [a, aaaa] = await Promise.allSettled([
         lookup(host, { family: 4, all: true }),
         lookup(host, { family: 6, all: true }),
@@ -354,14 +365,21 @@ export async function assertSafeUrl(url) {
             throw new Error(`URL "${url}" rejected: hostname ${host} resolves to ${addr} (IPv6 ${reason})`);
         }
     }
+    return { v4: v4Addresses, v6: v6Addresses };
 }
 /**
- * Validate `url` and return the resolved IP that should be used for the
- * actual fetch (companion to `safeFetch.ts:safeDownload`).
+ * Validate `url` and return the resolved address set that should be used for
+ * the actual fetch (companion to `safeFetch.ts:safeDownload`).
+ *
+ * For IP-literal hosts, `addresses` is the normalised IP as a singleton. For
+ * hostnames it is **every** validated address, IPv4 first, so the connect
+ * layer can race families (Happy Eyeballs). Pinning a single OS-preferred
+ * address breaks every download on IPv4-only networks whenever the resolver
+ * prefers AAAA: the pinned connection has no second address to fall back to,
+ * so it times out where plain `curl` (which races both families) succeeds.
+ * `ip`/`family` mirror the first entry for callers that need a single pin.
  *
- * For IP-literal hosts, returns the normalised IP and family. For hostnames,
- * returns the first acceptable IP from the resolver. Same throw semantics as
- * {@link assertSafeUrl}.
+ * Same throw semantics as {@link assertSafeUrl}.
  *
  * This is the canonical entry point for binary downloads where DNS-rebinding
  * pinning matters — see `safeFetch.ts`.
@@ -384,7 +402,7 @@ export async function validateAndResolveUrl(url) {
         if (isBlockedIPv4(v4)) {
             throw new Error(`URL "${url}" rejected: IPv4 ${host} → ${v4} is in a blocked range`);
         }
-        return { url, ip: v4, family: 4 };
+        return { url, ip: v4, family: 4, addresses: [{ ip: v4, family: 4 }] };
     }
     if (host.includes(":")) {
         const v4FromMapped = extractIPv4FromMapped(host);
@@ -392,7 +410,12 @@ export async function validateAndResolveUrl(url) {
             if (isBlockedIPv4(v4FromMapped)) {
                 throw new Error(`URL "${url}" rejected: IPv4-mapped IPv6 ${host} → ${v4FromMapped} is in a blocked range`);
             }
-            return { url, ip: v4FromMapped, family: 4 };
+            return {
+                url,
+                ip: v4FromMapped,
+                family: 4,
+                addresses: [{ ip: v4FromMapped, family: 4 }],
+            };
         }
         const expanded = expandIPv6(host);
         if (!expanded) {
@@ -401,11 +424,23 @@ export async function validateAndResolveUrl(url) {
         if (isBlockedIPv6(expanded)) {
             throw new Error(`URL "${url}" rejected: IPv6 ${host} is in a blocked range`);
         }
-        return { url, ip: host, family: 6 };
-    }
-    // Hostname — resolve and pick a safe address
-    await assertSafeUrl(url);
-    const result = await lookup(host);
-    return { url, ip: result.address, family: result.family };
+        return { url, ip: host, family: 6, addresses: [{ ip: host, family: 6 }] };
+    }
+    // Hostname — resolve once, validate every address, and return the whole
+    // set. Validating the same answer we hand to the connect layer also
+    // removes the rebinding window the previous separate `lookup()` left
+    // between validation and pinning.
+    const { v4: v4Addresses, v6: v6Addresses } = await resolveAndValidateHost(url, host);
+    const addresses = [
+        ...v4Addresses.map((ip) => ({ ip, family: 4 })),
+        ...v6Addresses.map((ip) => ({ ip, family: 6 })),
+    ];
+    const first = addresses[0];
+    if (!first) {
+        // Both lookups "succeeded" but returned zero addresses — treat exactly
+        // like a resolution failure rather than pinning nothing.
+        throw new Error(`URL "${url}" rejected: hostname ${host} resolved to an empty address set`);
+    }
+    return { url, ip: first.ip, family: first.family, addresses };
 }
 //# sourceMappingURL=ssrfGuard.js.map

package/dist/types/safeFetch.d.ts

@@ -3,6 +3,15 @@
  *
  * Runtime helper lives in `src/lib/utils/safeFetch.ts`.
  */
+/**
+ * One validated address the pinned connect layer is allowed to dial.
+ * Produced by `ssrfGuard.ts:validateAndResolveUrl`, consumed by
+ * `safeFetch.ts:buildPinnedAgent`.
+ */
+export type PinnedAddress = {
+    ip: string;
+    family: 4 | 6;
+};
 export type SafeDownloadOptions = {
     /** Hard cap on response size in bytes. Pass MAX_VIDEO_BYTES/MAX_AUDIO_BYTES/MAX_IMAGE_BYTES from sizeGuard. */
     maxBytes: number;

package/dist/utils/safeFetch.d.ts

@@ -4,9 +4,9 @@
  * Combines:
  *   - `assertSafeUrl` (validates and rejects blocked IPs)
  *   - undici `Agent` with custom `connect.lookup` so the actual connection
- *     uses the IP we validated (closes the DNS-rebinding window where the
- *     resolver returns a public IP for the guard but a private IP for the
- *     real request).
+ *     only ever dials addresses we validated (closes the DNS-rebinding window
+ *     where the resolver returns a public IP for the guard but a private IP
+ *     for the real request).
  *   - `readBoundedBuffer` for size cap.
  *   - `redirect: "manual"` so a 3xx → private-IP redirect can't bypass
  *     the guard.

package/dist/utils/safeFetch.js

@@ -4,9 +4,9 @@
  * Combines:
  *   - `assertSafeUrl` (validates and rejects blocked IPs)
  *   - undici `Agent` with custom `connect.lookup` so the actual connection
- *     uses the IP we validated (closes the DNS-rebinding window where the
- *     resolver returns a public IP for the guard but a private IP for the
- *     real request).
+ *     only ever dials addresses we validated (closes the DNS-rebinding window
+ *     where the resolver returns a public IP for the guard but a private IP
+ *     for the real request).
  *   - `readBoundedBuffer` for size cap.
  *   - `redirect: "manual"` so a 3xx → private-IP redirect can't bypass
  *     the guard.
@@ -21,21 +21,39 @@ import { readBoundedBuffer } from "./sizeGuard.js";
 import { validateAndResolveUrl } from "./ssrfGuard.js";
 const DEFAULT_TIMEOUT_MS = 60_000;
 /**
- * Build a once-off undici Agent whose connect lookup resolves `hostname` to a
- * fixed IP. This pins the actual TCP connection to the IP we validated,
- * removing the DNS-rebinding window.
+ * Build a once-off undici Agent whose connect lookup resolves `hostname` to
+ * the validated address set. The actual TCP connection can only ever go to
+ * an address the SSRF guard cleared, removing the DNS-rebinding window.
+ *
+ * The full set (IPv4 first) matters: pinning a single address turns one
+ * unroutable family into a hard connect timeout. On IPv4-only networks where
+ * the OS resolver prefers AAAA, that broke every safeDownload (Replicate /
+ * Runway / Kling asset fetches) while plain curl of the same URL succeeded —
+ * curl races both families (Happy Eyeballs); a one-address pin cannot.
  */
-function buildPinnedAgent(hostname, ip, family) {
+function buildPinnedAgent(hostname, addresses) {
+    const primary = addresses[0];
+    if (!primary) {
+        throw new Error(`safeFetch: no validated addresses to pin for "${hostname}"`);
+    }
     return new Agent({
         connect: {
-            lookup: (host, _options, callback) => {
+            lookup: (host, options, callback) => {
                 if (host.toLowerCase() !== hostname.toLowerCase()) {
                     // The host the connect layer asks for differs from the URL host —
                     // this happens for absolute Host headers etc. Reject defensively.
                     callback(new Error(`safeFetch: refusing to resolve "${host}" — expected "${hostname}"`), "", 0);
                     return;
                 }
-                callback(null, ip, family);
+                // Node ≥20 enables autoSelectFamily (Happy Eyeballs) by default, and
+                // its lookup contract passes `all: true` expecting an address ARRAY.
+                // Hand it every validated address so it can race families and fall
+                // back when one is unroutable.
+                if (options?.all) {
+                    callback(null, addresses.map((a) => ({ address: a.ip, family: a.family })));
+                    return;
+                }
+                callback(null, primary.ip, primary.family);
             },
         },
     });
@@ -47,10 +65,10 @@ function buildPinnedAgent(hostname, ip, family) {
  *   is encountered, or the HTTP status indicates failure.
  */
 export async function safeDownload(url, options) {
-    const { url: validatedUrl, ip, family } = await validateAndResolveUrl(url);
+    const { url: validatedUrl, addresses } = await validateAndResolveUrl(url);
     const parsed = new URL(validatedUrl);
     const hostname = parsed.hostname.replace(/^\[|\]$/g, "");
-    const agent = buildPinnedAgent(hostname, ip, family);
+    const agent = buildPinnedAgent(hostname, addresses);
     const timeoutCtrl = new AbortController();
     const timeoutId = setTimeout(() => timeoutCtrl.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     const composedSignal = options.signal

package/dist/utils/ssrfGuard.d.ts

@@ -24,6 +24,7 @@
  *
  * @module utils/ssrfGuard
  */
+import type { PinnedAddress } from "../types/index.js";
 /**
  * Assert that `url` is safe to fetch server-side.
  *
@@ -35,12 +36,18 @@
  */
 export declare function assertSafeUrl(url: string): Promise<void>;
 /**
- * Validate `url` and return the resolved IP that should be used for the
- * actual fetch (companion to `safeFetch.ts:safeDownload`).
+ * Validate `url` and return the resolved address set that should be used for
+ * the actual fetch (companion to `safeFetch.ts:safeDownload`).
  *
- * For IP-literal hosts, returns the normalised IP and family. For hostnames,
- * returns the first acceptable IP from the resolver. Same throw semantics as
- * {@link assertSafeUrl}.
+ * For IP-literal hosts, `addresses` is the normalised IP as a singleton. For
+ * hostnames it is **every** validated address, IPv4 first, so the connect
+ * layer can race families (Happy Eyeballs). Pinning a single OS-preferred
+ * address breaks every download on IPv4-only networks whenever the resolver
+ * prefers AAAA: the pinned connection has no second address to fall back to,
+ * so it times out where plain `curl` (which races both families) succeeds.
+ * `ip`/`family` mirror the first entry for callers that need a single pin.
+ *
+ * Same throw semantics as {@link assertSafeUrl}.
  *
  * This is the canonical entry point for binary downloads where DNS-rebinding
  * pinning matters — see `safeFetch.ts`.
@@ -49,4 +56,5 @@ export declare function validateAndResolveUrl(url: string): Promise<{
     url: string;
     ip: string;
     family: 4 | 6;
+    addresses: readonly PinnedAddress[];
 }>;

package/dist/utils/ssrfGuard.js

@@ -306,6 +306,17 @@ export async function assertSafeUrl(url) {
     }
     // Hostname — resolve BOTH A and AAAA. Reject if either family yields a
     // blocked address (closes off the "publish AAAA public, A private" attack).
+    await resolveAndValidateHost(url, host);
+}
+/**
+ * Resolve `host` (both A and AAAA) and validate every returned address
+ * against the block lists. Returns the full validated set so callers that
+ * pin connections can offer the connect layer more than one address.
+ *
+ * @throws {Error} when resolution fails entirely or any address is blocked
+ *   (all-must-pass — the caller may connect to any address in the set).
+ */
+async function resolveAndValidateHost(url, host) {
     const [a, aaaa] = await Promise.allSettled([
         lookup(host, { family: 4, all: true }),
         lookup(host, { family: 6, all: true }),
@@ -354,14 +365,21 @@ export async function assertSafeUrl(url) {
             throw new Error(`URL "${url}" rejected: hostname ${host} resolves to ${addr} (IPv6 ${reason})`);
         }
     }
+    return { v4: v4Addresses, v6: v6Addresses };
 }
 /**
- * Validate `url` and return the resolved IP that should be used for the
- * actual fetch (companion to `safeFetch.ts:safeDownload`).
+ * Validate `url` and return the resolved address set that should be used for
+ * the actual fetch (companion to `safeFetch.ts:safeDownload`).
+ *
+ * For IP-literal hosts, `addresses` is the normalised IP as a singleton. For
+ * hostnames it is **every** validated address, IPv4 first, so the connect
+ * layer can race families (Happy Eyeballs). Pinning a single OS-preferred
+ * address breaks every download on IPv4-only networks whenever the resolver
+ * prefers AAAA: the pinned connection has no second address to fall back to,
+ * so it times out where plain `curl` (which races both families) succeeds.
+ * `ip`/`family` mirror the first entry for callers that need a single pin.
  *
- * For IP-literal hosts, returns the normalised IP and family. For hostnames,
- * returns the first acceptable IP from the resolver. Same throw semantics as
- * {@link assertSafeUrl}.
+ * Same throw semantics as {@link assertSafeUrl}.
  *
  * This is the canonical entry point for binary downloads where DNS-rebinding
  * pinning matters — see `safeFetch.ts`.
@@ -384,7 +402,7 @@ export async function validateAndResolveUrl(url) {
         if (isBlockedIPv4(v4)) {
             throw new Error(`URL "${url}" rejected: IPv4 ${host} → ${v4} is in a blocked range`);
         }
-        return { url, ip: v4, family: 4 };
+        return { url, ip: v4, family: 4, addresses: [{ ip: v4, family: 4 }] };
     }
     if (host.includes(":")) {
         const v4FromMapped = extractIPv4FromMapped(host);
@@ -392,7 +410,12 @@ export async function validateAndResolveUrl(url) {
             if (isBlockedIPv4(v4FromMapped)) {
                 throw new Error(`URL "${url}" rejected: IPv4-mapped IPv6 ${host} → ${v4FromMapped} is in a blocked range`);
             }
-            return { url, ip: v4FromMapped, family: 4 };
+            return {
+                url,
+                ip: v4FromMapped,
+                family: 4,
+                addresses: [{ ip: v4FromMapped, family: 4 }],
+            };
         }
         const expanded = expandIPv6(host);
         if (!expanded) {
@@ -401,10 +424,22 @@ export async function validateAndResolveUrl(url) {
         if (isBlockedIPv6(expanded)) {
             throw new Error(`URL "${url}" rejected: IPv6 ${host} is in a blocked range`);
         }
-        return { url, ip: host, family: 6 };
-    }
-    // Hostname — resolve and pick a safe address
-    await assertSafeUrl(url);
-    const result = await lookup(host);
-    return { url, ip: result.address, family: result.family };
+        return { url, ip: host, family: 6, addresses: [{ ip: host, family: 6 }] };
+    }
+    // Hostname — resolve once, validate every address, and return the whole
+    // set. Validating the same answer we hand to the connect layer also
+    // removes the rebinding window the previous separate `lookup()` left
+    // between validation and pinning.
+    const { v4: v4Addresses, v6: v6Addresses } = await resolveAndValidateHost(url, host);
+    const addresses = [
+        ...v4Addresses.map((ip) => ({ ip, family: 4 })),
+        ...v6Addresses.map((ip) => ({ ip, family: 6 })),
+    ];
+    const first = addresses[0];
+    if (!first) {
+        // Both lookups "succeeded" but returned zero addresses — treat exactly
+        // like a resolution failure rather than pinning nothing.
+        throw new Error(`URL "${url}" rejected: hostname ${host} resolved to an empty address set`);
+    }
+    return { url, ip: first.ip, family: first.family, addresses };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.87.0",
+  "version": "9.87.2",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (58+ servers), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {