@juspay/neurolink 13.8.17 → 13.8.19

package/dist/utils/retryAfter.js

@@ -1,3 +1,10 @@
+/**
+ * Retrieves a header value case-insensitively from either a Headers object or a plain record.
+ *
+ * @param headers - The HTTP headers object or record
+ * @param headerName - The case-insensitive name of the header to retrieve
+ * @returns The header value, or null if not found
+ */
 function getHeader(headers, headerName) {
     if ("get" in headers && typeof headers.get === "function") {
         return headers.get(headerName);
@@ -10,6 +17,128 @@ function getHeader(headers, headerName) {
     }
     return null;
 }
+/**
+ * Parses a duration string (e.g., "6m0s", "30s", "1h30m", "500ms") into milliseconds.
+ *
+ * @param raw - The raw duration string
+ * @returns Duration in milliseconds, or undefined if invalid
+ */
+export function parseDurationMs(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    // Must consist of one or more [number][unit] components
+    const durationPattern = /^(\d+(?:\.\d+)?(?:ms|s|m|h))+$/i;
+    if (!durationPattern.test(trimmed)) {
+        return undefined;
+    }
+    const tokenRegex = /(\d+(?:\.\d+)?)(ms|s|m|h)/gi;
+    let totalMs = 0;
+    let match;
+    let matchedLength = 0;
+    while ((match = tokenRegex.exec(trimmed)) !== null) {
+        matchedLength += match[0].length;
+        const num = parseFloat(match[1]);
+        const unit = match[2].toLowerCase();
+        switch (unit) {
+            case "h":
+                totalMs += num * 3600 * 1000;
+                break;
+            case "m":
+                totalMs += num * 60 * 1000;
+                break;
+            case "s":
+                totalMs += num * 1000;
+                break;
+            case "ms":
+                totalMs += num;
+                break;
+        }
+    }
+    return matchedLength === trimmed.length ? Math.round(totalMs) : undefined;
+}
+/**
+ * Parses a single Retry-After header value into milliseconds.
+ *
+ * Checks in strict order:
+ * 1. Strict numeric seconds (e.g. "5", "120", "1.5") without truncation of dates or durations
+ * 2. HTTP-date or RFC 3339 / ISO 8601 date (e.g. "2026-10-18T12:00:00Z" or "Sun, 18 Oct 2026 12:00:00 GMT")
+ * 3. Duration string (e.g. "6m0s", "30s", "1h30m", "500ms")
+ *
+ * @param value - The header value string
+ * @returns Milliseconds to wait, or undefined if not parseable
+ */
+export function parseRetryAfterHeaderValue(value) {
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    // 1. Strict numeric representation (delta seconds)
+    // Note: Avoid parseInt, which reads leading digits from dates ("2026-10-13..." -> 2026) or durations ("6m0s" -> 6)
+    if (/^\d+(?:\.\d+)?$/.test(trimmed)) {
+        const seconds = Number(trimmed);
+        if (Number.isFinite(seconds) && seconds >= 0) {
+            return Math.round(seconds * 1000);
+        }
+    }
+    // 2. HTTP-date or RFC 3339 / ISO 8601 date
+    const parsedDate = Date.parse(trimmed);
+    if (Number.isFinite(parsedDate)) {
+        return Math.max(0, parsedDate - Date.now());
+    }
+    // 3. Duration string (e.g. "6m0s", "30s", "500ms")
+    const duration = parseDurationMs(trimmed);
+    if (duration !== undefined && duration >= 0) {
+        return duration;
+    }
+    return undefined;
+}
+/**
+ * Parses X-RateLimit-Reset header value into milliseconds until reset.
+ *
+ * Handles:
+ * - Delta seconds when value < 1e9 (e.g. "30", "60")
+ * - Epoch seconds when 1e9 <= value <= 1e12
+ * - Epoch milliseconds when value > 1e12
+ * - Fallback to date or duration strings
+ *
+ * @param value - The X-RateLimit-Reset header value
+ * @returns Milliseconds until reset, or undefined if not parseable
+ */
+export function parseRateLimitResetValue(value) {
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    if (/^\d+(?:\.\d+)?$/.test(trimmed)) {
+        const num = Number(trimmed);
+        if (Number.isFinite(num) && num >= 0) {
+            if (num < 1e9) {
+                // Delta seconds (e.g. 30, 60, 300)
+                return Math.round(num * 1000);
+            }
+            // Unix epoch timestamp
+            const resetTime = num > 1e12 ? num : num * 1000;
+            return Math.max(0, Math.round(resetTime - Date.now()));
+        }
+    }
+    const parsedDate = Date.parse(trimmed);
+    if (Number.isFinite(parsedDate)) {
+        return Math.max(0, parsedDate - Date.now());
+    }
+    const duration = parseDurationMs(trimmed);
+    if (duration !== undefined && duration >= 0) {
+        return duration;
+    }
+    return undefined;
+}
 /**
  * Parse standard and commonly used rate-limit response headers.
  *
@@ -19,21 +148,16 @@ function getHeader(headers, headerName) {
 export function parseRetryAfterMs(headers) {
     const retryAfter = getHeader(headers, "Retry-After");
     if (retryAfter) {
-        const seconds = parseInt(retryAfter, 10);
-        if (!Number.isNaN(seconds)) {
-            return Math.max(0, seconds * 1000);
-        }
-        const retryDate = new Date(retryAfter);
-        if (!Number.isNaN(retryDate.getTime())) {
-            return Math.max(0, retryDate.getTime() - Date.now());
+        const delay = parseRetryAfterHeaderValue(retryAfter);
+        if (delay !== undefined) {
+            return delay;
         }
     }
     const rateLimitReset = getHeader(headers, "X-RateLimit-Reset");
     if (rateLimitReset) {
-        const resetTimestamp = parseInt(rateLimitReset, 10);
-        if (!Number.isNaN(resetTimestamp)) {
-            const resetTime = resetTimestamp > 1e12 ? resetTimestamp : resetTimestamp * 1000;
-            return Math.max(0, resetTime - Date.now());
+        const delay = parseRateLimitResetValue(rateLimitReset);
+        if (delay !== undefined) {
+            return delay;
         }
     }
     if (getHeader(headers, "X-RateLimit-Remaining") === "0") {

package/dist/utils/safeFetch.d.ts

@@ -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
@@ -22,7 +29,19 @@
  *
  * @module utils/safeFetch
  */
-import type { SafeDownloadOptions } from "../types/index.js";
+import type { SafeDownloadOptions, SafeDownloadResult } from "../types/index.js";
+/**
+ * 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 declare function safeDownloadWithMeta(url: string, options: SafeDownloadOptions): Promise<SafeDownloadResult>;
 /**
  * Safely download a binary asset from an external URL.
  *
@@ -30,3 +49,5 @@ import type { SafeDownloadOptions } from "../types/index.js";
  *   is encountered, or the HTTP status indicates failure.
  */
 export declare function safeDownload(url: string, options: SafeDownloadOptions): Promise<Buffer>;
+/** Hop count applied when a caller opts into redirects without naming one. */
+export declare function defaultRedirectHops(follow: boolean): number;

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[];
+};