@juspay/neurolink 13.8.16 → 13.8.18

package/dist/utils/safeFetch.js

@@ -14,6 +14,13 @@
  * Use this for **every** download of an external (caller-supplied or
  * third-party-returned) URL. Direct `fetch(url)` of such URLs is unsafe.
  *
+ * Redirects are refused by default. A caller that opts in (`maxRedirects`)
+ * gets each hop validated and pinned exactly like the first request, and the
+ * caller's `headers` are sent to the first host only — a credential meant for
+ * one origin is never replayed to the one it redirects to. `allowInsecure`
+ * and `allowPrivateNetwork` relax the URL policy for SDK callers that have
+ * said so explicitly; the server path never passes them.
+ *
  * When the environment configures a proxy for the URL (HTTPS_PROXY / ALL_PROXY,
  * and the host is not in NO_PROXY) the download goes through that proxy and
  * nowhere else: there is no fallback to a direct connection. The proxy resolves
@@ -86,6 +93,12 @@ function isBoundedBufferResponse(value) {
         candidate.headers !== null &&
         typeof candidate.headers.get === "function");
 }
+/**
+ * Hop limit when a caller opts into redirects but names no number.
+ */
+const DEFAULT_MAX_REDIRECTS = 5;
+/** Ceiling on the hop count, whatever the caller asks for. */
+const MAX_REDIRECTS_CEILING = 10;
 /**
  * Check the response the same way for both transports, then read it under the
  * size cap.
@@ -97,6 +110,12 @@ async function readDownloadResponse(response, url, options) {
     if (!response.ok) {
         throw new Error(`safeDownload(${options.label}) failed: HTTP ${response.status} for ${url}`);
     }
+    if (options.method === "HEAD") {
+        // A HEAD has no body to read; drain whatever the transport queued so the
+        // connection is released, and hand back nothing.
+        await response.body?.cancel().catch(() => undefined);
+        return Buffer.alloc(0);
+    }
     // readBoundedBuffer expects a Response that exposes Content-Length and
     // arrayBuffer(). undici Response satisfies both.
     if (!isBoundedBufferResponse(response)) {
@@ -105,51 +124,118 @@ async function readDownloadResponse(response, url, options) {
     return readBoundedBuffer(response, options.maxBytes, options.label);
 }
 /**
- * Safely download a binary asset from an external URL.
- *
- * @throws {Error} if the URL is unsafe, the response is too large, a redirect
- *   is encountered, or the HTTP status indicates failure.
+ * Vet `url` for the chosen transport and return the dispatcher to send it
+ * through. Through a proxy the proxy resolves the name, so only the URL text
+ * can be vetted; without one the connection is pinned to the addresses the
+ * guard cleared. Runs once per hop so a redirect gets the same treatment as
+ * the request that produced it.
  */
-export async function safeDownload(url, options) {
-    // Dynamic imports keep undici and the proxy module off the package's static
-    // import graph — they are only needed once a download actually happens. See
-    // test/continuous-test-suite-import-cost.ts.
+async function prepareHop(url, options) {
     const { getProxyDispatcherForUrl } = await import("../proxy/proxyFetch.js");
     const proxyDispatcher = await getProxyDispatcherForUrl(url);
-    const { fetch: undiciFetch } = await import("undici");
-    // Resolve and vet the destination, and pick the transport. Through a proxy
-    // the proxy resolves the name, so only the URL text can be vetted; without
-    // one the connection is pinned to the addresses the guard cleared.
-    let validatedUrl;
-    let dispatcher;
-    let closeDispatcher = false;
+    const guard = {
+        allowInsecure: options.allowInsecure === true,
+        allowPrivateNetwork: options.allowPrivateNetwork === true,
+    };
     if (proxyDispatcher) {
-        assertSafeUrlForProxy(url);
-        validatedUrl = url;
-        dispatcher = proxyDispatcher;
+        assertSafeUrlForProxy(url, guard);
+        return { dispatcher: proxyDispatcher, owned: false };
     }
-    else {
-        const resolved = await validateAndResolveUrl(url);
-        validatedUrl = resolved.url;
-        const hostname = new URL(validatedUrl).hostname.replace(/^\[|\]$/g, "");
-        dispatcher = await buildPinnedAgent(hostname, resolved.addresses);
-        closeDispatcher = true;
+    const resolved = await validateAndResolveUrl(url, guard);
+    const hostname = new URL(resolved.url).hostname.replace(/^\[|\]$/g, "");
+    return {
+        dispatcher: await buildPinnedAgent(hostname, resolved.addresses),
+        owned: true,
+    };
+}
+/**
+ * Resolve a `Location` header against the URL that produced it, refusing
+ * anything that is not an absolute HTTP(S) URL after resolution.
+ */
+function resolveRedirectTarget(location, from, label, status) {
+    if (!location) {
+        throw new Error(`safeDownload(${label}): HTTP ${status} redirect without a Location header (for ${from})`);
     }
+    let target;
+    try {
+        target = new URL(location, from);
+    }
+    catch {
+        throw new Error(`safeDownload(${label}): HTTP ${status} redirect to an unparseable Location (for ${from})`);
+    }
+    // Strip any userinfo a redirect tries to smuggle in; credentials never
+    // travel on the URL here.
+    target.username = "";
+    target.password = "";
+    return target.toString();
+}
+/**
+ * Safely download an external URL and report what came back.
+ *
+ * Same guarantees as {@link safeDownload}; additionally returns the final
+ * response's `Content-Type`/`Content-Encoding`, the URL that produced the body
+ * and how many redirect hops were taken.
+ *
+ * @throws {Error} if any URL on the way is unsafe, the response is too large,
+ *   a redirect is encountered beyond what `maxRedirects` allows, or the HTTP
+ *   status indicates failure.
+ */
+export async function safeDownloadWithMeta(url, options) {
+    // Dynamic imports keep undici off the package's static import graph — it is
+    // only needed once a download actually happens. See
+    // test/continuous-test-suite-import-cost.ts.
+    const { fetch: undiciFetch } = await import("undici");
+    const maxRedirects = Math.min(Math.max(0, Math.floor(options.maxRedirects ?? 0)), MAX_REDIRECTS_CEILING);
     const timeoutCtrl = new AbortController();
     const timeoutId = setTimeout(() => timeoutCtrl.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
     const composedSignal = options.signal
         ? AbortSignal.any([options.signal, timeoutCtrl.signal])
         : timeoutCtrl.signal;
+    let currentUrl = url;
+    let hops = 0;
     try {
-        const response = await undiciFetch(validatedUrl, {
-            method: "GET",
-            signal: composedSignal,
-            redirect: "manual", // a 3xx → private-IP redirect would bypass the guard
-            dispatcher,
-        });
-        // fetch resolves at the headers. Keep the same deadline and abort signal
-        // active while the bounded reader drains the response body as well.
-        return await readDownloadResponse(response, url, options);
+        for (;;) {
+            const { dispatcher, owned } = await prepareHop(currentUrl, options);
+            try {
+                const response = await undiciFetch(currentUrl, {
+                    method: options.method ?? "GET",
+                    // The caller's headers ride on the FIRST request only. A redirect
+                    // target is a different authority as far as a credential is
+                    // concerned, even when the host name happens to match.
+                    headers: hops === 0 && options.headers ? options.headers : undefined,
+                    signal: composedSignal,
+                    redirect: "manual", // a 3xx → private-IP redirect would bypass the guard
+                    dispatcher,
+                });
+                if (response.status >= 300 &&
+                    response.status < 400 &&
+                    hops < maxRedirects) {
+                    const next = resolveRedirectTarget(response.headers.get("location"), currentUrl, options.label, response.status);
+                    // Release the redirect response before the next hop.
+                    await response.body?.cancel().catch(() => undefined);
+                    hops += 1;
+                    currentUrl = next;
+                    continue;
+                }
+                // fetch resolves at the headers. Keep the same deadline and abort
+                // signal active while the bounded reader drains the body as well.
+                const buffer = await readDownloadResponse(response, currentUrl, options);
+                return {
+                    buffer,
+                    contentType: response.headers.get("content-type") ?? "",
+                    contentEncoding: response.headers.get("content-encoding") ?? "",
+                    finalUrl: currentUrl,
+                    redirects: hops,
+                };
+            }
+            finally {
+                if (owned) {
+                    // Close the per-hop agent so the pinned connection isn't pooled.
+                    // The proxy agent is shared process-wide and stays open.
+                    dispatcher.close().catch(() => undefined);
+                }
+            }
+        }
     }
     catch (error) {
         // A status/size rejection may happen before the body is consumed. Stop
@@ -160,10 +246,18 @@ export async function safeDownload(url, options) {
     }
     finally {
         clearTimeout(timeoutId);
-        if (closeDispatcher) {
-            // Close the per-request agent so the pinned connection isn't pooled.
-            // The proxy agent is shared process-wide and stays open.
-            dispatcher.close().catch(() => undefined);
-        }
     }
 }
+/**
+ * Safely download a binary asset from an external URL.
+ *
+ * @throws {Error} if the URL is unsafe, the response is too large, a redirect
+ *   is encountered, or the HTTP status indicates failure.
+ */
+export async function safeDownload(url, options) {
+    return (await safeDownloadWithMeta(url, options)).buffer;
+}
+/** Hop count applied when a caller opts into redirects without naming one. */
+export function defaultRedirectHops(follow) {
+    return follow ? DEFAULT_MAX_REDIRECTS : 0;
+}

package/dist/utils/safeStoreId.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shape check for an id that becomes a file name or a key segment.
+ *
+ * The same rule `isSafeArtifactId` applies to model-supplied artifact ids,
+ * widened by `.` for host-registered skill ids: one leading alphanumeric, then
+ * up to 127 of `[A-Za-z0-9._-]`. Nothing that could be a path separator, a
+ * traversal segment (a leading `.` is refused, so `..` cannot start one), a
+ * glob metacharacter or a line break gets through.
+ *
+ * @module utils/safeStoreId
+ */
+/** Whether `id` may be joined into a path or a key. */
+export declare function isSafeStoreId(id: string): boolean;
+/**
+ * Refuse an unsafe id.
+ *
+ * @throws {Error} with `code: "INVALID_STORE_ID"`
+ */
+export declare function assertSafeStoreId(id: string, label: string): void;

package/dist/utils/safeStoreId.js

@@ -0,0 +1,29 @@
+/**
+ * Shape check for an id that becomes a file name or a key segment.
+ *
+ * The same rule `isSafeArtifactId` applies to model-supplied artifact ids,
+ * widened by `.` for host-registered skill ids: one leading alphanumeric, then
+ * up to 127 of `[A-Za-z0-9._-]`. Nothing that could be a path separator, a
+ * traversal segment (a leading `.` is refused, so `..` cannot start one), a
+ * glob metacharacter or a line break gets through.
+ *
+ * @module utils/safeStoreId
+ */
+const SAFE_STORE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** Whether `id` may be joined into a path or a key. */
+export function isSafeStoreId(id) {
+    return SAFE_STORE_ID.test(id);
+}
+/**
+ * Refuse an unsafe id.
+ *
+ * @throws {Error} with `code: "INVALID_STORE_ID"`
+ */
+export function assertSafeStoreId(id, label) {
+    if (isSafeStoreId(id)) {
+        return;
+    }
+    const error = new Error(`${label} "${String(id).slice(0, 64)}" is not a valid id: use 1-128 characters of letters, digits, '.', '_' or '-', starting with a letter or digit`);
+    error.code = "INVALID_STORE_ID";
+    throw error;
+}

package/dist/utils/schemaConversion.d.ts

@@ -1,4 +1,4 @@
-import type { ZodUnknownSchema } from "../types/index.js";
+import type { SchemaRegexDrop, ZodUnknownSchema } from "../types/index.js";
 /**
  * Inline a JSON Schema by recursively resolving all $ref references.
  * zodToJsonSchema with 'name' option produces schemas with $ref pointing to definitions.
@@ -59,7 +59,34 @@ export declare function isZodSchema(value: unknown): boolean;
  */
 export declare function isZod4Schema(value: unknown): boolean;
 /**
- * Convert JSON Schema to Zod schema format using official json-schema-to-zod library
- * This ensures complete preservation of all schema structure and validation rules
+ * Convert a JSON Schema object to a Zod schema.
+ *
+ * Built directly from the schema object — no generated source, no
+ * `new Function` — so a hostile `description`, `pattern`, `default`, `const`,
+ * `enum` or property name is data, never code. Covers the subset tool
+ * schemas use: object/array/string/number/integer/boolean/null, `enum`,
+ * `const`, `anyOf`/`oneOf`/`allOf`, type unions, local `$ref`s, `nullable`,
+ * `required`, `additionalProperties`, `description`, `default` and the common
+ * length/range bounds. A `pattern` is compiled only after `vetRegexPattern`
+ * accepts it; a pattern that could stall the process is dropped from the
+ * schema and reported once at warn level. Unknown constructs validate as
+ * `unknown` rather than failing the conversion.
+ *
+ * Returns `z.object({}).passthrough()` for input that is not a schema object,
+ * exactly as the previous implementation did on any failure.
  */
 export declare function convertJsonSchemaToZod(jsonSchema: Record<string, unknown>): ZodUnknownSchema;
+/**
+ * Remove from a JSON Schema every `pattern` and every `patternProperties` key
+ * that `vetRegexPattern` refuses, so a validator built from the result (the
+ * `@cfworker/json-schema` validator compiles each with `new RegExp` on every
+ * check) cannot be stalled by a schema a remote server chose.
+ *
+ * Returns the input object itself when nothing had to be removed, so the
+ * common case costs one walk and no allocation. Otherwise a deep copy with the
+ * offending keywords left out, and `drops` names each one. Never throws.
+ */
+export declare function stripUnsafeRegexPatterns(schema: Record<string, unknown>): {
+    schema: Record<string, unknown>;
+    drops: SchemaRegexDrop[];
+};