@juspay/neurolink 9.63.1 → 9.65.0

package/dist/utils/schemaConversion.js

@@ -1,7 +1,25 @@
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { jsonSchemaToZod } from "json-schema-to-zod";
+import * as zodModule from "zod";
 import { z } from "zod";
 import { logger } from "./logger.js";
+// Zod 4 ships a built-in `z.toJSONSchema(...)`. Zod 3 does not — it returned
+// nothing of the sort and we relied entirely on `zod-to-json-schema`. The
+// `zod-to-json-schema` package only understands Zod 3's internal `_def`
+// shape, so feeding it a Zod 4 schema yields an empty `{}` (it silently
+// produces `definitions: { ToolParameters: {} }`). When this happens
+// downstream callers send an empty `responseSchema` to the model and get
+// back arbitrary JSON, which is exactly how the Vertex Structured-Output
+// regressions surfaced. Detect the Zod 4 helper at module load and prefer
+// it for actual Zod schemas.
+// Zod 4 spells the OpenAPI target as "openapi-3.0" (with a dot) while the
+// third-party zod-to-json-schema package uses "openApi3". Internally we use
+// the latter for backwards compatibility with existing call sites; this map
+// translates to the dialect Zod 4 actually accepts. The Zod4Native* types
+// live in src/lib/types/aliases.ts per project rule 2.
+const zodToJsonSchemaV4 = typeof zodModule.toJSONSchema === "function"
+    ? zodModule.toJSONSchema
+    : undefined;
 /**
  * Resolve a deep JSON pointer path within a schema.
  * Handles paths like "#/definitions/ToolParameters/properties/foo/properties/bar"
@@ -96,7 +114,12 @@ export function inlineJsonSchema(schema, definitions, visited = new Set(), rootS
             visited.delete(refPath);
             return inlined;
         }
-        logger.debug(`[SCHEMA-INLINE] Could not resolve $ref: ${refPath}`);
+        // Unresolved $ref: warn and preserve the original node verbatim. Falling
+        // through to the copy loop below would strip the $ref key and silently
+        // turn a ref-only node into an empty {}, which broadens validation
+        // instead of failing closed.
+        logger.warn(`[SCHEMA-INLINE] Could not resolve $ref: ${refPath}`);
+        return { ...schema };
     }
     // Create result without $ref and definitions
     const result = {};
@@ -279,7 +302,12 @@ export function ensureNestedSchemaTypes(schema) {
  * 2. AI SDK `jsonSchema()` wrappers (have `.jsonSchema` property) -- extracted directly
  * 3. Plain JSON Schema objects (have `type`/`properties` but no `_def`) -- returned as-is
  */
-export function convertZodToJsonSchema(zodSchema) {
+export function convertZodToJsonSchema(zodSchema, 
+// Default to JSON Schema draft-07 so non-Vertex consumers (Bedrock, MCP
+// tool registration, etc.) keep their pre-migration dialect. Vertex/Gemini
+// callers opt into "openApi3" explicitly to get `nullable: true` instead
+// of `anyOf: [..., {type: "null"}]`.
+target = "jsonSchema7") {
     const schema = zodSchema;
     if (!schema || typeof schema !== "object") {
         return { type: "object", properties: {} };
@@ -295,14 +323,41 @@ export function convertZodToJsonSchema(zodSchema) {
     if (!isZodSchema(schema)) {
         return ensureNestedSchemaTypes(ensureTypeField(schema));
     }
-    // Actual Zod schema — convert via zod-to-json-schema
+    // Actual Zod schema — prefer Zod 4's native `z.toJSONSchema` when
+    // available (the runtime version of `zod` here is Zod 4), then fall
+    // back to `zod-to-json-schema` for Zod 3 schemas that external callers
+    // might still pass in.
+    //
+    // Translate our `target` to Zod 4's native dialect identifier so the
+    // openApi3 path emits the OpenAPI 3 schema shape Vertex/Gemini expect
+    // (and not the default draft-07 anyOf/null union).
+    if (zodToJsonSchemaV4) {
+        const nativeTarget = target === "openApi3" ? "openapi-3.0" : "draft-07";
+        try {
+            const native = zodToJsonSchemaV4(zodSchema, {
+                target: nativeTarget,
+            });
+            // Drop the $schema metadata Vertex/Gemini doesn't need, then walk to
+            // backfill any missing nested types (Zod 4's output is already flat
+            // — no $defs/$ref by default — but the helper is cheap and matches
+            // the Zod 3 path's contract).
+            const flat = { ...native };
+            delete flat.$schema;
+            const inlined = inlineJsonSchema(flat);
+            return ensureNestedSchemaTypes(ensureTypeField(inlined));
+        }
+        catch (error) {
+            logger.warn("Native z.toJSONSchema failed; falling back to zod-to-json-schema", { error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    // Zod 3 fallback path
     try {
         // Zod 4→3 boundary: zodToJsonSchema types reference Zod 3's ZodSchema via zod/v3.
         // Runtime compatible — cast through unknown at this third-party boundary only.
         const zodV3Schema = zodSchema;
         const jsonSchema = zodToJsonSchema(zodV3Schema, {
             name: "ToolParameters",
-            target: "openApi3", // Use OpenAPI 3.0 for nullable: true instead of anyOf with null (required for Vertex AI)
+            target,
             errorMessages: true,
         });
         // zodToJsonSchema with 'name' produces { $ref: "#/definitions/ToolParameters", definitions: {...} }

package/dist/utils/sizeGuard.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Size Guard Utility
+ *
+ * Provides bounded binary downloads to prevent OOM when fetching generated
+ * media from external providers. Applies a Content-Length pre-check and a
+ * post-buffer guard so multi-GB responses are rejected before they fully
+ * materialise in process memory.
+ *
+ * @module utils/sizeGuard
+ */
+/** 256 MiB — suitable for video output (MP4). */
+export declare const MAX_VIDEO_BYTES: number;
+/** 50 MiB — suitable for audio output (MP3/WAV). */
+export declare const MAX_AUDIO_BYTES: number;
+/** 25 MiB — suitable for image output (PNG/JPEG/WebP). */
+export declare const MAX_IMAGE_BYTES: number;
+/**
+ * Download the body of a {@link Response} into a {@link Buffer}, enforcing an
+ * upper-bound on the number of bytes consumed.
+ *
+ * Two checks are performed:
+ * 1. If the response includes a `Content-Length` header that exceeds
+ *    `maxBytes`, the download is rejected immediately (no data is read).
+ * 2. After buffering, the actual buffer size is verified against `maxBytes`.
+ *    This catches chunked transfers where no `Content-Length` was provided.
+ *
+ * @param response  The fetch {@link Response} to drain.
+ * @param maxBytes  Maximum number of bytes allowed.
+ * @param label     Human-readable identifier used in error messages
+ *                  (e.g. "Kling video", "D-ID result").
+ * @returns         The response body as a {@link Buffer}.
+ * @throws          {@link Error} when either size check fails.
+ */
+export declare function readBoundedBuffer(response: Response, maxBytes: number, label: string): Promise<Buffer>;

package/dist/utils/sizeGuard.js

@@ -0,0 +1,44 @@
+/**
+ * Size Guard Utility
+ *
+ * Provides bounded binary downloads to prevent OOM when fetching generated
+ * media from external providers. Applies a Content-Length pre-check and a
+ * post-buffer guard so multi-GB responses are rejected before they fully
+ * materialise in process memory.
+ *
+ * @module utils/sizeGuard
+ */
+/** 256 MiB — suitable for video output (MP4). */
+export const MAX_VIDEO_BYTES = 256 * 1024 * 1024;
+/** 50 MiB — suitable for audio output (MP3/WAV). */
+export const MAX_AUDIO_BYTES = 50 * 1024 * 1024;
+/** 25 MiB — suitable for image output (PNG/JPEG/WebP). */
+export const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
+/**
+ * Download the body of a {@link Response} into a {@link Buffer}, enforcing an
+ * upper-bound on the number of bytes consumed.
+ *
+ * Two checks are performed:
+ * 1. If the response includes a `Content-Length` header that exceeds
+ *    `maxBytes`, the download is rejected immediately (no data is read).
+ * 2. After buffering, the actual buffer size is verified against `maxBytes`.
+ *    This catches chunked transfers where no `Content-Length` was provided.
+ *
+ * @param response  The fetch {@link Response} to drain.
+ * @param maxBytes  Maximum number of bytes allowed.
+ * @param label     Human-readable identifier used in error messages
+ *                  (e.g. "Kling video", "D-ID result").
+ * @returns         The response body as a {@link Buffer}.
+ * @throws          {@link Error} when either size check fails.
+ */
+export async function readBoundedBuffer(response, maxBytes, label) {
+    const contentLength = parseInt(response.headers.get("content-length") ?? "0", 10);
+    if (contentLength > 0 && contentLength > maxBytes) {
+        throw new Error(`${label} download too large: ${contentLength} bytes (max ${maxBytes})`);
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.length > maxBytes) {
+        throw new Error(`${label} download exceeded size cap after fetch: ${buffer.length} bytes (max ${maxBytes})`);
+    }
+    return buffer;
+}

package/dist/utils/ssrfGuard.d.ts

@@ -0,0 +1,52 @@
+/**
+ * SSRF Guard — Safe URL Validation Utility
+ *
+ * Prevents Server-Side Request Forgery by:
+ *  1. Enforcing HTTPS-only (no plain HTTP).
+ *  2. Normalising encoded IPv4 forms (octal, hex, decimal integer, IPv4-mapped IPv6)
+ *     to canonical dotted-decimal before rangechecking.
+ *  3. Resolving the hostname for **both** A and AAAA families and rejecting
+ *     requests to RFC 1918 private ranges, loopback, link-local, CGNAT,
+ *     IPv6 link-local/ULA, and cloud metadata endpoints
+ *     (AWS / GCP / Azure / Alibaba).
+ *  4. Re-throwing on DNS failure rather than silently allowing the request.
+ *
+ * **DNS rebinding residual race:** `assertSafeUrl` validates the IP at the
+ * moment of the lookup. If the resolver returns a public IP here and a private
+ * IP at the actual `fetch()` call, the guard is bypassed. To eliminate the
+ * race, use the companion `safeDownload` helper in `safeFetch.ts` which pins
+ * the resolved IP onto the request via an undici Agent dispatcher.
+ *
+ * Usage:
+ *   await assertSafeUrl(url);
+ *   // ... or, for actual downloads: ...
+ *   await safeDownload(url, { maxBytes, label });
+ *
+ * @module utils/ssrfGuard
+ */
+/**
+ * Assert that `url` is safe to fetch server-side.
+ *
+ * @throws {Error} when the URL is non-HTTPS, parses as a blocked IP literal,
+ *   or resolves (A or AAAA) to a blocked IP. **Also throws on DNS lookup
+ *   failure** (the previous behaviour of silently allowing was a bypass —
+ *   an attacker-controlled resolver could force NXDOMAIN here and a private
+ *   IP at the actual fetch).
+ */
+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`).
+ *
+ * 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}.
+ *
+ * This is the canonical entry point for binary downloads where DNS-rebinding
+ * pinning matters — see `safeFetch.ts`.
+ */
+export declare function validateAndResolveUrl(url: string): Promise<{
+    url: string;
+    ip: string;
+    family: 4 | 6;
+}>;

package/dist/utils/ssrfGuard.js

@@ -0,0 +1,410 @@
+/**
+ * SSRF Guard — Safe URL Validation Utility
+ *
+ * Prevents Server-Side Request Forgery by:
+ *  1. Enforcing HTTPS-only (no plain HTTP).
+ *  2. Normalising encoded IPv4 forms (octal, hex, decimal integer, IPv4-mapped IPv6)
+ *     to canonical dotted-decimal before rangechecking.
+ *  3. Resolving the hostname for **both** A and AAAA families and rejecting
+ *     requests to RFC 1918 private ranges, loopback, link-local, CGNAT,
+ *     IPv6 link-local/ULA, and cloud metadata endpoints
+ *     (AWS / GCP / Azure / Alibaba).
+ *  4. Re-throwing on DNS failure rather than silently allowing the request.
+ *
+ * **DNS rebinding residual race:** `assertSafeUrl` validates the IP at the
+ * moment of the lookup. If the resolver returns a public IP here and a private
+ * IP at the actual `fetch()` call, the guard is bypassed. To eliminate the
+ * race, use the companion `safeDownload` helper in `safeFetch.ts` which pins
+ * the resolved IP onto the request via an undici Agent dispatcher.
+ *
+ * Usage:
+ *   await assertSafeUrl(url);
+ *   // ... or, for actual downloads: ...
+ *   await safeDownload(url, { maxBytes, label });
+ *
+ * @module utils/ssrfGuard
+ */
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+/**
+ * Blocked IPv4 CIDRs.
+ *
+ * Each entry is a `[network, prefix]` pair. Membership is computed by
+ * bitwise comparison of the 32-bit address vs the masked network.
+ */
+const BLOCKED_V4_CIDRS = [
+    ["0.0.0.0", 8], // "this network"
+    ["10.0.0.0", 8], // RFC 1918
+    ["100.64.0.0", 10], // CGNAT (RFC 6598)
+    ["127.0.0.0", 8], // loopback
+    ["169.254.0.0", 16], // link-local (AWS/GCP/Azure metadata + APIPA)
+    ["172.16.0.0", 12], // RFC 1918
+    ["192.0.0.0", 24], // protocol assignments
+    ["192.168.0.0", 16], // RFC 1918
+    ["198.18.0.0", 15], // benchmarking
+    ["100.100.100.200", 32], // Alibaba Cloud metadata (NOT in 100.64/10 CGNAT)
+    ["224.0.0.0", 4], // multicast
+    ["240.0.0.0", 4], // reserved
+];
+/**
+ * Blocked IPv6 prefixes.
+ *
+ * Compared by lowercase prefix match on the expanded address form.
+ * (`expandIPv6` normalizes `::1` to `0000:0000:...:0001` for unambiguous
+ * prefix matching.)
+ */
+const BLOCKED_V6_PREFIXES = [
+    "0000:0000:0000:0000:0000:0000:0000:0000", // :: (unspecified)
+    "0000:0000:0000:0000:0000:0000:0000:0001", // ::1 (loopback)
+    "fc", // fc00::/7 unique-local (covers fc and fd prefixes)
+    "fd", // fd00::/8
+    "fe8", // fe80::/10 link-local (covers fe8/fe9/fea/feb)
+    "fe9",
+    "fea",
+    "feb",
+];
+function parseOctet(s) {
+    if (s.length === 0) {
+        return null;
+    }
+    if (/^0x[0-9a-f]+$/i.test(s)) {
+        return parseInt(s.slice(2), 16);
+    }
+    // Plain "0" is valid decimal zero; leading-zero forms (`0177`) are octal
+    if (s.length > 1 && s.startsWith("0") && /^0[0-7]+$/.test(s)) {
+        return parseInt(s.slice(1), 8);
+    }
+    if (/^\d+$/.test(s)) {
+        return parseInt(s, 10);
+    }
+    return null;
+}
+/**
+ * Normalize any IPv4-like host string to canonical dotted-decimal form, or
+ * return `null` if it's not parseable as IPv4.
+ *
+ * Handles:
+ *   - 127.0.0.1            (canonical)
+ *   - 0177.0.0.1           (octal octets)
+ *   - 0x7f.0.0.1           (hex octets)
+ *   - 0x7f000001           (hex integer)
+ *   - 2130706433           (decimal integer)
+ *   - 0177.0.0.1           (mixed encodings)
+ */
+function normalizeIPv4(host) {
+    if (host.length === 0) {
+        return null;
+    }
+    const parts = host.split(".");
+    if (parts.length === 4) {
+        const octets = parts.map(parseOctet);
+        if (octets.some((o) => o === null || o < 0 || o > 255)) {
+            return null;
+        }
+        return octets.join(".");
+    }
+    // Single integer form: 2130706433 or 0x7f000001
+    if (parts.length === 1) {
+        let n;
+        if (/^0x[0-9a-f]+$/i.test(host)) {
+            n = parseInt(host.slice(2), 16);
+        }
+        else if (/^\d+$/.test(host)) {
+            n = parseInt(host, 10);
+        }
+        else {
+            return null;
+        }
+        if (Number.isNaN(n) || n < 0 || n > 0xffffffff) {
+            return null;
+        }
+        return [
+            (n >>> 24) & 0xff,
+            (n >>> 16) & 0xff,
+            (n >>> 8) & 0xff,
+            n & 0xff,
+        ].join(".");
+    }
+    return null;
+}
+/**
+ * Expand a compressed IPv6 address (`::1`) to full 8-group form
+ * (`0000:0000:0000:0000:0000:0000:0000:0001`) for unambiguous prefix matching.
+ *
+ * Returns the expanded lowercased string, or `null` if `host` isn't IPv6.
+ */
+function expandIPv6(host) {
+    if (isIP(host) !== 6) {
+        return null;
+    }
+    // Handle IPv4-mapped IPv6: ::ffff:127.0.0.1 → expand the IPv4 part to two groups
+    const v4MappedMatch = host.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+    let groups;
+    if (v4MappedMatch) {
+        const v4 = normalizeIPv4(v4MappedMatch[1]);
+        if (!v4) {
+            return null;
+        }
+        const v4Octets = v4.split(".").map((n) => parseInt(n, 10));
+        const high = ((v4Octets[0] << 8) | v4Octets[1]).toString(16);
+        const low = ((v4Octets[2] << 8) | v4Octets[3]).toString(16);
+        groups = ["0", "0", "0", "0", "0", "ffff", high, low];
+    }
+    else {
+        const [head, tail = ""] = host.split("::");
+        const headParts = head ? head.split(":") : [];
+        const tailParts = tail ? tail.split(":") : [];
+        const missing = 8 - headParts.length - tailParts.length;
+        if (missing < 0) {
+            return null;
+        }
+        groups = [...headParts, ...Array(missing).fill("0"), ...tailParts];
+    }
+    if (groups.length !== 8) {
+        return null;
+    }
+    return groups.map((g) => g.toLowerCase().padStart(4, "0")).join(":");
+}
+/**
+ * If `host` is an IPv4-mapped IPv6 address, return the embedded IPv4 in
+ * canonical dotted-decimal form, or `null` otherwise.
+ *
+ * Handles both forms:
+ *   - dotted-decimal IPv4 part: `::ffff:127.0.0.1`
+ *   - hex-encoded IPv4 part:    `::ffff:7f00:1` / `::ffff:7f00:0001`
+ *
+ * Node's `URL` parser normalises bracketed `::ffff:127.0.0.1` to
+ * `[::ffff:7f00:1]`, so the hex form is the one we actually receive after
+ * `URL.hostname` + bracket stripping. Both paths must be covered.
+ */
+function extractIPv4FromMapped(host) {
+    // Form 1: `::ffff:127.0.0.1`
+    const dottedMatch = host.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+    if (dottedMatch) {
+        return normalizeIPv4(dottedMatch[1]);
+    }
+    // Form 2: `::ffff:7f00:1` (two hex groups, optionally zero-padded)
+    const hexMatch = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+    if (hexMatch) {
+        const high = parseInt(hexMatch[1], 16);
+        const low = parseInt(hexMatch[2], 16);
+        if (Number.isNaN(high) ||
+            Number.isNaN(low) ||
+            high > 0xffff ||
+            low > 0xffff) {
+            return null;
+        }
+        return [
+            (high >> 8) & 0xff,
+            high & 0xff,
+            (low >> 8) & 0xff,
+            low & 0xff,
+        ].join(".");
+    }
+    return null;
+}
+function ipv4ToInt(ip) {
+    const [a, b, c, d] = ip.split(".").map((n) => parseInt(n, 10));
+    return ((a << 24) | (b << 16) | (c << 8) | d) >>> 0;
+}
+function isBlockedIPv4(ip) {
+    const ipInt = ipv4ToInt(ip);
+    for (const [network, prefix] of BLOCKED_V4_CIDRS) {
+        const netInt = ipv4ToInt(network);
+        const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+        if ((ipInt & mask) === (netInt & mask)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isBlockedIPv6(expanded) {
+    return BLOCKED_V6_PREFIXES.some((prefix) => {
+        if (prefix.length === 39) {
+            // full-form exact match
+            return expanded === prefix;
+        }
+        return expanded.startsWith(prefix);
+    });
+}
+/**
+ * Strip the IPv6 brackets that `URL.hostname` returns for IPv6 hosts
+ * (Node behaviour varies — sometimes `[::1]`, sometimes `::1`).
+ */
+function stripBrackets(host) {
+    if (host.startsWith("[") && host.endsWith("]")) {
+        return host.slice(1, -1);
+    }
+    return host;
+}
+/**
+ * Internal check: given a host string (already bracket-stripped, lowercased),
+ * return a reject reason or null if safe.
+ *
+ * Detects IP literals via every encoded form. Does NOT do DNS — that's the
+ * caller's job.
+ */
+function checkHostLiteral(host) {
+    // IPv4 (including encoded forms)
+    const v4 = normalizeIPv4(host);
+    if (v4) {
+        if (isBlockedIPv4(v4)) {
+            return `IPv4 ${host} → ${v4} is in a blocked range`;
+        }
+        return null;
+    }
+    // IPv6 (including IPv4-mapped)
+    if (host.includes(":")) {
+        // First, check IPv4-mapped: convert and re-check via v4 path
+        const v4FromMapped = extractIPv4FromMapped(host);
+        if (v4FromMapped) {
+            if (isBlockedIPv4(v4FromMapped)) {
+                return `IPv4-mapped IPv6 ${host} → ${v4FromMapped} is in a blocked range`;
+            }
+            return null;
+        }
+        const expanded = expandIPv6(host);
+        if (!expanded) {
+            return `IPv6 ${host} could not be parsed`;
+        }
+        if (isBlockedIPv6(expanded)) {
+            return `IPv6 ${host} is in a blocked range`;
+        }
+        return null;
+    }
+    // Not an IP literal — caller should fall through to DNS resolution
+    return "not-an-ip";
+}
+/**
+ * Assert that `url` is safe to fetch server-side.
+ *
+ * @throws {Error} when the URL is non-HTTPS, parses as a blocked IP literal,
+ *   or resolves (A or AAAA) to a blocked IP. **Also throws on DNS lookup
+ *   failure** (the previous behaviour of silently allowing was a bypass —
+ *   an attacker-controlled resolver could force NXDOMAIN here and a private
+ *   IP at the actual fetch).
+ */
+export async function assertSafeUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid URL: "${url}"`);
+    }
+    if (parsed.protocol !== "https:") {
+        throw new Error(`Only HTTPS URLs are permitted; got "${parsed.protocol}//" in "${url}"`);
+    }
+    const host = stripBrackets(parsed.hostname).toLowerCase();
+    // First, try as an IP literal (covers encoded forms + IPv4-mapped IPv6).
+    const literalCheck = checkHostLiteral(host);
+    if (literalCheck === null) {
+        return; // routable IP literal — safe
+    }
+    if (literalCheck !== "not-an-ip") {
+        throw new Error(`URL "${url}" rejected: ${literalCheck}`);
+    }
+    // Hostname — resolve BOTH A and AAAA. Reject if either family yields a
+    // blocked address (closes off the "publish AAAA public, A private" attack).
+    const [a, aaaa] = await Promise.allSettled([
+        lookup(host, { family: 4, all: true }),
+        lookup(host, { family: 6, all: true }),
+    ]);
+    const v4Addresses = [];
+    const v6Addresses = [];
+    let hadAnySuccess = false;
+    if (a.status === "fulfilled") {
+        hadAnySuccess = true;
+        for (const entry of a.value) {
+            v4Addresses.push(entry.address);
+        }
+    }
+    if (aaaa.status === "fulfilled") {
+        hadAnySuccess = true;
+        for (const entry of aaaa.value) {
+            v6Addresses.push(entry.address);
+        }
+    }
+    if (!hadAnySuccess) {
+        // BOTH lookups failed — the host doesn't resolve at all. Re-throw with
+        // a clear message rather than silently allowing the fetch (the prior
+        // behaviour, which is the DNS-rebinding bypass).
+        const aErr = a.status === "rejected"
+            ? a.reason instanceof Error
+                ? a.reason.message
+                : String(a.reason)
+            : "ok";
+        const aaaaErr = aaaa.status === "rejected"
+            ? aaaa.reason instanceof Error
+                ? aaaa.reason.message
+                : String(aaaa.reason)
+            : "ok";
+        throw new Error(`URL "${url}" rejected: hostname ${host} could not be resolved (A: ${aErr}; AAAA: ${aaaaErr})`);
+    }
+    for (const addr of v4Addresses) {
+        if (isBlockedIPv4(addr)) {
+            throw new Error(`URL "${url}" rejected: hostname ${host} resolves to ${addr} (IPv4 in blocked range)`);
+        }
+    }
+    for (const addr of v6Addresses) {
+        // Re-use the literal check pipeline for IPv6 so IPv4-mapped resolved
+        // addresses are caught.
+        const reason = checkHostLiteral(addr.toLowerCase());
+        if (reason && reason !== "not-an-ip") {
+            throw new Error(`URL "${url}" rejected: hostname ${host} resolves to ${addr} (IPv6 ${reason})`);
+        }
+    }
+}
+/**
+ * Validate `url` and return the resolved IP 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}.
+ *
+ * This is the canonical entry point for binary downloads where DNS-rebinding
+ * pinning matters — see `safeFetch.ts`.
+ */
+export async function validateAndResolveUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid URL: "${url}"`);
+    }
+    if (parsed.protocol !== "https:") {
+        throw new Error(`Only HTTPS URLs are permitted; got "${parsed.protocol}//" in "${url}"`);
+    }
+    const host = stripBrackets(parsed.hostname).toLowerCase();
+    // IP literal — normalise + check, return canonical form
+    const v4 = normalizeIPv4(host);
+    if (v4) {
+        if (isBlockedIPv4(v4)) {
+            throw new Error(`URL "${url}" rejected: IPv4 ${host} → ${v4} is in a blocked range`);
+        }
+        return { url, ip: v4, family: 4 };
+    }
+    if (host.includes(":")) {
+        const v4FromMapped = extractIPv4FromMapped(host);
+        if (v4FromMapped) {
+            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 };
+        }
+        const expanded = expandIPv6(host);
+        if (!expanded) {
+            throw new Error(`URL "${url}" rejected: IPv6 ${host} could not be parsed`);
+        }
+        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 };
+}