@juspay/neurolink 9.87.1 → 9.87.3

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,11 +21,21 @@ 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) => {
@@ -37,15 +47,13 @@ function buildPinnedAgent(hostname, ip, family) {
                 }
                 // Node ≥20 enables autoSelectFamily (Happy Eyeballs) by default, and
                 // its lookup contract passes `all: true` expecting an address ARRAY.
-                // Answering with the string form there fails the connection with
-                // "Invalid IP address: undefined" — which broke every safeDownload
-                // (Replicate / Runway / Kling asset fetches) on modern Node while
-                // plain curl of the same URL succeeded.
+                // Hand it every validated address so it can race families and fall
+                // back when one is unroutable.
                 if (options?.all) {
-                    callback(null, [{ address: ip, family }]);
+                    callback(null, addresses.map((a) => ({ address: a.ip, family: a.family })));
                     return;
                 }
-                callback(null, ip, family);
+                callback(null, primary.ip, primary.family);
             },
         },
     });
@@ -57,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/server/routes/claudeProxyRoutes.d.ts

@@ -11,8 +11,9 @@
  */
 import { buildTranslationOptions } from "../../proxy/proxyTranslationEngine.js";
 import type { ModelRouter } from "../../proxy/modelRouter.js";
+import { ProxyTracer } from "../../proxy/proxyTracer.js";
 import { isPermanentRefreshFailure } from "../../proxy/tokenRefresh.js";
-import type { AccountAllowlist, AccountCooldownPlan, AccountQuota, ParsedClaudeError, ProxyPassthroughAccount, RouteGroup, RuntimeAccountState, StreamTerminalOutcome } from "../../types/index.js";
+import type { AccountAllowlist, AccountCooldownPlan, AccountQuota, AnthropicAttemptLogger, AnthropicAuthRetryResult, AnthropicLoopState, AnthropicSuccessResult, AnthropicUpstreamFetchResult, ClaudeFinalRequestLogger, ClaudeRequest, ParsedClaudeError, ProxyBodyCaptureLogger, ProxyPassthroughAccount, RouteGroup, RuntimeAccountState, ServerContext, StreamTerminalOutcome } from "../../types/index.js";
 /** Resolve the configured primary's stable key to its current index in the
  *  request's enabledAccounts list. Returns 0 (insertion-order fallback) when
  *  no key is configured or the key cannot be matched (account disabled/
@@ -24,6 +25,9 @@ declare function resolveHomeIndex(enabledAccounts: ProxyPassthroughAccount[]): n
  *  account once its rate limit window expires. Called at the start of each
  *  request. Home is resolved fresh per call via resolveHomeIndex. */
 declare function maybeResetPrimaryToHome(enabledAccounts: ProxyPassthroughAccount[]): void;
+declare function claimTransientRateLimitRetry(accountKey: string, coolingUntil: number, now?: number): number | undefined;
+declare function claimTransientCooldownAdmission(accountKey: string, coolingUntil: number, now?: number): number | undefined;
+declare function waitForTransientAccountAvailability(orderedAccounts: ProxyPassthroughAccount[]): Promise<ProxyPassthroughAccount[]>;
 /** Convert an Anthropic unified-window reset (Unix epoch SECONDS, per the
  *  `anthropic-ratelimit-unified-*-reset` headers) into epoch-ms. Tolerates a
  *  value already expressed in ms (some intermediaries normalise it). Returns
@@ -77,11 +81,109 @@ declare function trackUpstreamReadableStream(source: ReadableStream<Uint8Array>)
     stream: ReadableStream<Uint8Array>;
     outcome: Promise<StreamTerminalOutcome>;
 };
+declare function handleAnthropicStreamingSuccessResponse(args: {
+    ctx: ServerContext;
+    body: ClaudeRequest;
+    account: ProxyPassthroughAccount;
+    accountState: RuntimeAccountState;
+    response: Response;
+    responseHeaders: Record<string, string>;
+    tracer?: ProxyTracer;
+    requestStartTime: number;
+    fetchStartMs: number;
+    attemptNumber: number;
+    finalBodyStr: string;
+    upstreamSpan?: import("@opentelemetry/api").Span;
+    logProxyBody: ProxyBodyCaptureLogger;
+    logFinalRequest: (status: number, accountLabel: string, accountType: string, errorType?: string, errorMessage?: string, extra?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheCreationTokens?: number;
+        cacheReadTokens?: number;
+    }) => void;
+}): Promise<AnthropicSuccessResult>;
 declare function getStreamFailureDetails(outcome: StreamTerminalOutcome): {
     status: number;
     errorType: string;
     message: string;
 } | undefined;
+declare function handleAnthropicAuthRetry(args: {
+    ctx: ServerContext;
+    body: ClaudeRequest;
+    account: ProxyPassthroughAccount;
+    accountState: RuntimeAccountState;
+    headers: Record<string, string>;
+    buildUpstreamBody: (token: string) => {
+        bodyStr: string;
+        sessionId?: string;
+    };
+    enabledAccounts: ProxyPassthroughAccount[];
+    orderedAccounts: ProxyPassthroughAccount[];
+    response: Response;
+    tracer?: ProxyTracer;
+    requestStartTime: number;
+    fetchStartMs: number;
+    attemptNumber: number;
+    finalBodyStr: string;
+    upstreamSpan?: import("@opentelemetry/api").Span;
+    logAttempt: (status: number, errorType?: string, errorMessage?: string, extra?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheCreationTokens?: number;
+        cacheReadTokens?: number;
+    }) => void;
+    logProxyBody: ProxyBodyCaptureLogger;
+    logFinalRequest: (status: number, accountLabel: string, accountType: string, errorType?: string, errorMessage?: string, extra?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheCreationTokens?: number;
+        cacheReadTokens?: number;
+    }) => void;
+    lastError: unknown;
+    authFailureMessage: string | null;
+    sawRateLimit: boolean;
+    sawTransientFailure: boolean;
+    sawNetworkError: boolean;
+}): Promise<AnthropicAuthRetryResult>;
+declare function finalizeAnthropicTerminalFetchError(args: {
+    terminalError: NonNullable<AnthropicUpstreamFetchResult["terminalError"]>;
+    account: ProxyPassthroughAccount;
+    tracer?: ProxyTracer;
+    requestStartTime: number;
+    attemptNumber: number;
+    logProxyBody: ProxyBodyCaptureLogger;
+    logFinalRequest: ClaudeFinalRequestLogger;
+}): Response | unknown;
+/**
+ * Detect Anthropic's anti-abuse / request-construction 429.
+ *
+ * The subscription/OAuth path rejects requests it does not recognise as genuine
+ * Claude Code traffic with a 429 `rate_limit_error` whose message is literally
+ * "Error" and which carries NONE of the real rate-limit headers (no retry-after,
+ * no anthropic-ratelimit-*). This is NOT a capacity limit — retrying or rotating
+ * accounts cannot fix it and only burns quota, so the caller must fail fast and
+ * return a non-retryable request error instead of "all accounts rate-limited".
+ */
+declare function isAntiAbuseConstruction429(headers: Record<string, string>, body: string): boolean;
+declare function fetchAnthropicAccountResponse(args: {
+    url: string;
+    headers: Record<string, string>;
+    finalBodyStr: string;
+    account: ProxyPassthroughAccount;
+    accountState: RuntimeAccountState;
+    enabledAccounts: ProxyPassthroughAccount[];
+    orderedAccounts: ProxyPassthroughAccount[];
+    tracer?: ProxyTracer;
+    logAttempt: AnthropicAttemptLogger;
+    logProxyBody: ProxyBodyCaptureLogger;
+    fetchStartMs: number;
+    attemptNumber: number;
+    currentLastError: unknown;
+    currentSawRateLimit: boolean;
+    currentSawNetworkError: boolean;
+    upstreamSpan?: import("@opentelemetry/api").Span;
+}): Promise<AnthropicUpstreamFetchResult>;
+declare function shouldAttemptClaudeFallback(loopState: AnthropicLoopState): boolean;
 /**
  * Create Claude-compatible proxy routes.
  *
@@ -94,6 +196,7 @@ declare function getStreamFailureDetails(outcome: StreamTerminalOutcome): {
  */
 export declare function createClaudeProxyRoutes(modelRouter?: ModelRouter, basePath?: string, accountStrategy?: "round-robin" | "fill-first", passthroughMode?: boolean, primaryAccountKey?: string, accountAllowlist?: AccountAllowlist): RouteGroup;
 export declare function getTransientSameAccountRetryDelayMs(retryNumber: number): number;
+declare function describeTransportError(error: unknown): string;
 /**
  * Parse a Claude error payload when available.
  */
@@ -132,5 +235,19 @@ export declare const __testHooks: {
     getPrimaryAccountIndex: () => number;
     setAccountRuntimeState: (key: string, state: Partial<RuntimeAccountState>) => void;
     resetAllRuntimeState: () => void;
+    polyfillOAuthBody: (bodyStr: string, isClaudeClientRequest: boolean) => {
+        bodyStr: string;
+        sessionId?: string;
+    };
+    isAntiAbuseConstruction429: typeof isAntiAbuseConstruction429;
+    fetchAnthropicAccountResponse: typeof fetchAnthropicAccountResponse;
+    finalizeAnthropicTerminalFetchError: typeof finalizeAnthropicTerminalFetchError;
+    handleAnthropicAuthRetry: typeof handleAnthropicAuthRetry;
+    handleAnthropicStreamingSuccessResponse: typeof handleAnthropicStreamingSuccessResponse;
+    claimTransientRateLimitRetry: typeof claimTransientRateLimitRetry;
+    claimTransientCooldownAdmission: typeof claimTransientCooldownAdmission;
+    waitForTransientAccountAvailability: typeof waitForTransientAccountAvailability;
+    describeTransportError: typeof describeTransportError;
+    shouldAttemptClaudeFallback: typeof shouldAttemptClaudeFallback;
 };
 export {};