@juspay/neurolink 10.12.4 → 10.12.6

package/dist/lib/proxy/requestLogger.js

@@ -700,61 +700,71 @@ export async function logStreamError(entry) {
  * Non-fatal — proxy keeps working even if cleanup fails.
  */
 export function cleanupLogs(maxAgeDays = 7, maxSizeMb = 500) {
-    if (!logDir || !existsSync(logDir)) {
+    if (!logDir) {
         return;
     }
     try {
-        const activeLogDir = logDir;
-        const files = collectManagedLogFiles(activeLogDir).sort((a, b) => a.mtime - b.mtime); // oldest first
-        const currentDate = new Date().toISOString().split("T")[0];
-        const currentMetadataLogs = new Set(["proxy", "proxy-attempts", "proxy-debug", "proxy-lifecycle"].map((prefix) => join(activeLogDir, `${prefix}-${currentDate}.jsonl`)));
-        const canDelete = (file) => !currentMetadataLogs.has(file.path);
-        const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
-        let deletedCount = 0;
-        let freedBytes = 0;
-        // Pass 1: delete files older than maxAgeDays
-        const remaining = [];
-        for (const file of files) {
-            if (file.mtime < cutoff && canDelete(file)) {
-                unlinkSync(file.path);
-                deletedCount++;
-                freedBytes += file.size;
-            }
-            else {
-                remaining.push(file);
-            }
-        }
-        const bodiesDir = join(logDir, "bodies");
-        if (existsSync(bodiesDir)) {
-            pruneEmptyDirectories(bodiesDir, bodiesDir);
-        }
-        // Pass 2: if total size exceeds maxSizeMb, delete oldest until under limit
-        const maxBytes = maxSizeMb * 1024 * 1024;
-        let totalSize = remaining.reduce((sum, f) => sum + f.size, 0);
-        const deletionCandidates = remaining.filter(canDelete);
-        // Current-day metadata is the only reliable source for final-request,
-        // attempt, lifecycle, and body-index reconciliation. Keep those indexes
-        // intact during size cleanup; body artifacts and older indexes remain
-        // eligible for eviction.
-        while (totalSize > maxBytes && deletionCandidates.length > 0) {
-            const oldest = deletionCandidates.shift();
-            if (!oldest) {
-                break;
-            }
-            unlinkSync(oldest.path);
-            totalSize -= oldest.size;
+        cleanupLogsAt(logDir, maxAgeDays, maxSizeMb);
+    }
+    catch {
+        // Non-fatal for legacy in-process callers.
+    }
+}
+/**
+ * Path-scoped retention implementation used by the proxy cleanup worker.
+ * This function is intentionally synchronous: callers must run it outside the
+ * request-serving process when the directory can contain many artifacts.
+ */
+export function cleanupLogsAt(activeLogDir, maxAgeDays = 7, maxSizeMb = 500) {
+    if (!existsSync(activeLogDir)) {
+        return;
+    }
+    const files = collectManagedLogFiles(activeLogDir).sort((a, b) => a.mtime - b.mtime); // oldest first
+    const currentDate = new Date().toISOString().split("T")[0];
+    const currentMetadataLogs = new Set(["proxy", "proxy-attempts", "proxy-debug", "proxy-lifecycle"].map((prefix) => join(activeLogDir, `${prefix}-${currentDate}.jsonl`)));
+    const canDelete = (file) => !currentMetadataLogs.has(file.path);
+    const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+    let deletedCount = 0;
+    let freedBytes = 0;
+    // Pass 1: delete files older than maxAgeDays
+    const remaining = [];
+    for (const file of files) {
+        if (file.mtime < cutoff && canDelete(file)) {
+            unlinkSync(file.path);
             deletedCount++;
-            freedBytes += oldest.size;
+            freedBytes += file.size;
         }
-        if (existsSync(bodiesDir)) {
-            pruneEmptyDirectories(bodiesDir, bodiesDir);
+        else {
+            remaining.push(file);
         }
-        if (deletedCount > 0) {
-            logger.info(`[proxy] log cleanup: deleted ${deletedCount} file(s), freed ${(freedBytes / 1024 / 1024).toFixed(1)} MB`);
+    }
+    const bodiesDir = join(activeLogDir, "bodies");
+    if (existsSync(bodiesDir)) {
+        pruneEmptyDirectories(bodiesDir, bodiesDir);
+    }
+    // Pass 2: if total size exceeds maxSizeMb, delete oldest until under limit
+    const maxBytes = maxSizeMb * 1024 * 1024;
+    let totalSize = remaining.reduce((sum, f) => sum + f.size, 0);
+    const deletionCandidates = remaining.filter(canDelete);
+    // Current-day metadata is the only reliable source for final-request,
+    // attempt, lifecycle, and body-index reconciliation. Keep those indexes
+    // intact during size cleanup; body artifacts and older indexes remain
+    // eligible for eviction.
+    while (totalSize > maxBytes && deletionCandidates.length > 0) {
+        const oldest = deletionCandidates.shift();
+        if (!oldest) {
+            break;
         }
+        unlinkSync(oldest.path);
+        totalSize -= oldest.size;
+        deletedCount++;
+        freedBytes += oldest.size;
     }
-    catch {
-        // Non-fatal
+    if (existsSync(bodiesDir)) {
+        pruneEmptyDirectories(bodiesDir, bodiesDir);
+    }
+    if (deletedCount > 0) {
+        logger.info(`[proxy] log cleanup: deleted ${deletedCount} file(s), freed ${(freedBytes / 1024 / 1024).toFixed(1)} MB`);
     }
 }
 //# sourceMappingURL=requestLogger.js.map

package/dist/lib/proxy/rollingWorkerSupervisor.d.ts

@@ -14,6 +14,7 @@ export declare class RollingWorkerSupervisor {
     private replacement;
     private rejectedSockets;
     private failedTransfers;
+    private readonly recentEvents;
     private lastFailure;
     private closed;
     private shutdownPromise;
@@ -38,5 +39,6 @@ export declare class RollingWorkerSupervisor {
     private describeTransferError;
     private extractLifecycleFailureDetails;
     private recordFailure;
+    private recordEvent;
     private publishState;
 }

package/dist/lib/proxy/rollingWorkerSupervisor.js

@@ -3,6 +3,7 @@ const DEFAULT_READY_TIMEOUT_MS = 30_000;
 const DEFAULT_SOCKET_QUEUE_LIMIT = 1_024;
 const DEFAULT_SOCKET_QUEUE_TIMEOUT_MS = 30_000;
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
+const MAX_RECENT_SUPERVISOR_EVENTS = 100;
 /**
  * Owns worker generations while the caller owns the public listening socket.
  * Sockets are transferred once to the active worker, so response bytes never
@@ -18,6 +19,7 @@ export class RollingWorkerSupervisor {
     replacement = null;
     rejectedSockets = 0;
     failedTransfers = 0;
+    recentEvents = [];
     lastFailure = null;
     closed = false;
     shutdownPromise = null;
@@ -56,6 +58,7 @@ export class RollingWorkerSupervisor {
             queuedSockets: this.queuedSockets.length,
             rejectedSockets: this.rejectedSockets,
             failedTransfers: this.failedTransfers,
+            recentEvents: [...this.recentEvents],
             lastFailure: this.lastFailure,
         };
     }
@@ -302,6 +305,11 @@ export class RollingWorkerSupervisor {
                     this.maybeDrainWorker(previous);
                 }
                 this.options.log?.(`[proxy-supervisor] activated generation=${generation} pid=${handle.pid} version=${expectedVersion}`);
+                this.recordEvent({
+                    type: "activated",
+                    generation,
+                    version: expectedVersion,
+                });
                 this.publishState();
                 finish();
             });
@@ -410,6 +418,13 @@ export class RollingWorkerSupervisor {
     handleTransferFailure(worker, socket, error) {
         this.failedTransfers += 1;
         const detail = this.describeTransferError(error);
+        this.recordEvent({
+            type: "failed_transfer",
+            generation: worker.generation,
+            version: worker.version,
+            phase: "transfer",
+            reason: detail,
+        });
         const lifecycle = this.extractLifecycleFailureDetails(error, worker.handle.pid);
         this.recordFailure(worker.generation, worker.version, "transfer", `worker ${worker.handle.pid} failed to accept a transferred socket: ${detail}`, {
             ...lifecycle.details,
@@ -432,10 +447,16 @@ export class RollingWorkerSupervisor {
             }
             this.publishState();
         }
-        this.rejectSocket(socket);
+        this.rejectSocket(socket, worker.generation, worker.version, "transfer_failure");
     }
-    rejectSocket(socket) {
+    rejectSocket(socket, generation = this.active?.generation ?? null, version = this.active?.version ?? null, reason = "unavailable") {
         this.rejectedSockets += 1;
+        this.recordEvent({
+            type: "rejected_socket",
+            generation,
+            version,
+            reason,
+        });
         socket.destroy();
         this.publishState();
     }
@@ -479,6 +500,23 @@ export class RollingWorkerSupervisor {
             message: message.slice(0, 1_000),
             ...details,
         };
+        this.recordEvent({
+            type: "failure",
+            generation,
+            version,
+            phase,
+            reason: message,
+        });
+    }
+    recordEvent(event) {
+        this.recentEvents.push({
+            at: new Date().toISOString(),
+            ...event,
+            ...(event.reason ? { reason: event.reason.slice(0, 1_000) } : {}),
+        });
+        if (this.recentEvents.length > MAX_RECENT_SUPERVISOR_EVENTS) {
+            this.recentEvents.splice(0, this.recentEvents.length - MAX_RECENT_SUPERVISOR_EVENTS);
+        }
     }
     publishState() {
         try {

package/dist/lib/server/routes/claudeProxyRoutes.d.ts

@@ -310,6 +310,7 @@ declare function shouldAttemptClaudeFallback(loopState: AnthropicLoopState): boo
 export declare function createClaudeProxyRoutes(modelRouter?: ModelRouterInterface, basePath?: string, accountStrategy?: "round-robin" | "fill-first", passthroughMode?: boolean, primaryAccountKey?: string, accountAllowlistOrRuntimeOptions?: AccountAllowlist | ClaudeProxyRouteRuntimeOptions): RouteGroup;
 declare function reconcileEligibleAccountRuntimeState(account: ProxyPassthroughAccount): void;
 export declare function getTransientSameAccountRetryDelayMs(retryNumber: number): number;
+export declare function getOverloadRotationDelayMs(attemptNumber: number): number;
 declare function describeTransportError(error: unknown): string;
 /**
  * Determine whether a POST can be retried without risking duplicate provider
@@ -400,6 +401,7 @@ export declare const __testHooks: {
     describeTransportError: typeof describeTransportError;
     redactProviderErrorMessage: typeof redactProviderErrorMessage;
     isUpstreamOverload: typeof isUpstreamOverload;
+    getOverloadRotationDelayMs: typeof getOverloadRotationDelayMs;
     shouldAttemptClaudeFallback: typeof shouldAttemptClaudeFallback;
     executeClaudeFallbackWithRetry: typeof executeClaudeFallbackWithRetry;
     buildClaudeAnthropicFailureResponse: typeof buildClaudeAnthropicFailureResponse;

package/dist/lib/server/routes/claudeProxyRoutes.js

@@ -63,6 +63,7 @@ let lastKnownAccountCount = 0;
 const MAX_AUTH_RETRIES = 5;
 const MAX_TRANSIENT_SAME_ACCOUNT_RETRIES = 2;
 const TRANSIENT_SAME_ACCOUNT_RETRY_DELAYS_MS = [250, 1_000];
+const OVERLOAD_ACCOUNT_ROTATION_DELAYS_MS = [250, 500, 1_000, 2_000];
 const MAX_FALLBACK_NETWORK_RETRIES = 1;
 const FALLBACK_STREAM_IDLE_TIMEOUT_MS = 2 * 60 * 1000;
 /** Maximum upstream 429 attempts per account before rotating — for a TRANSIENT
@@ -2883,7 +2884,13 @@ async function handleAnthropicStreamingSuccessResponse(args) {
         });
         return {
             retryNextAccount: true,
-            failure: { message: preflight.message, rateLimit: isRateLimit },
+            failure: {
+                message: preflight.message,
+                rateLimit: isRateLimit,
+                ...(preflight.errorType === "overloaded_error"
+                    ? { retryDelayMs: getOverloadRotationDelayMs(attemptNumber) }
+                    : {}),
+            },
         };
     }
     logAttempt(response.status, undefined, undefined, {
@@ -3484,6 +3491,9 @@ async function handleAnthropicAuthRetry(args) {
                     const failure = successResult.failure;
                     return {
                         continueLoop: true,
+                        ...(failure?.retryDelayMs
+                            ? { retryDelayMs: failure.retryDelayMs }
+                            : {}),
                         lastError: failure?.message ?? currentLastError,
                         authFailureMessage: currentAuthFailureMessage,
                         sawRateLimit: currentSawRateLimit || Boolean(failure?.rateLimit),
@@ -3941,6 +3951,9 @@ async function handleAnthropicNonOkResponse(args) {
         return {
             continueLoop: true,
             retrySameAccount: !upstreamOverload,
+            ...(upstreamOverload
+                ? { retryDelayMs: getOverloadRotationDelayMs(attemptNumber) }
+                : {}),
             lastError: currentLastError,
             authFailureMessage: currentAuthFailureMessage,
             sawTransientFailure: currentSawTransientFailure,
@@ -4553,7 +4566,8 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         effectiveAccounts.every((account) => !isAccountAdmissionAvailable(account.key, accountAdmissionCapacity))) {
         queuedAccountAdmission = await acquireFirstAvailableAccountAdmission(effectiveAccounts.map((account) => account.key), accountAdmissionCapacity, ctx.abortSignal);
     }
-    accountLoop: for (const account of effectiveAccounts) {
+    accountLoop: for (const [accountIndex, account,] of effectiveAccounts.entries()) {
+        const hasNextAccount = accountIndex < effectiveAccounts.length - 1;
         const accountState = getOrCreateRuntimeState(account.key);
         let transientSameAccountRetries = 0;
         let rateLimitSameAccountRetries = 0;
@@ -4763,6 +4777,10 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                         return authRetryResult.response;
                     }
                     if (authRetryResult.continueLoop) {
+                        if (hasNextAccount && authRetryResult.retryDelayMs) {
+                            logger.always(`[proxy] pacing cross-account SSE overload rotation for ${authRetryResult.retryDelayMs}ms after auth refresh`);
+                            await sleep(authRetryResult.retryDelayMs);
+                        }
                         continue accountLoop;
                     }
                 }
@@ -4804,6 +4822,10 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                         if (nonOkResult.retrySameAccount) {
                             logger.always(`[proxy] exhausted transient same-account retries for account=${account.label}; rotating`);
                         }
+                        if (hasNextAccount && nonOkResult.retryDelayMs) {
+                            logger.always(`[proxy] pacing cross-account overload rotation for ${nonOkResult.retryDelayMs}ms`);
+                            await sleep(nonOkResult.retryDelayMs);
+                        }
                         continue accountLoop;
                     }
                     break accountLoop;
@@ -4845,6 +4867,10 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                         loopState.lastError = successResult.failure.message;
                         loopState.sawRateLimit ||= successResult.failure.rateLimit;
                         loopState.sawTransientFailure ||= !successResult.failure.rateLimit;
+                        if (hasNextAccount && successResult.failure.retryDelayMs) {
+                            logger.always(`[proxy] pacing cross-account SSE overload rotation for ${successResult.failure.retryDelayMs}ms`);
+                            await sleep(successResult.failure.retryDelayMs);
+                        }
                     }
                     continue accountLoop;
                 }
@@ -5315,6 +5341,10 @@ export function getTransientSameAccountRetryDelayMs(retryNumber) {
     const index = Math.min(Math.max(retryNumber - 1, 0), TRANSIENT_SAME_ACCOUNT_RETRY_DELAYS_MS.length - 1);
     return TRANSIENT_SAME_ACCOUNT_RETRY_DELAYS_MS[index] ?? 0;
 }
+export function getOverloadRotationDelayMs(attemptNumber) {
+    const index = Math.min(Math.max(attemptNumber - 1, 0), OVERLOAD_ACCOUNT_ROTATION_DELAYS_MS.length - 1);
+    return jitteredDelay(OVERLOAD_ACCOUNT_ROTATION_DELAYS_MS[index] ?? 250);
+}
 async function sleep(ms) {
     await new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -5586,6 +5616,7 @@ export const __testHooks = {
     describeTransportError,
     redactProviderErrorMessage,
     isUpstreamOverload,
+    getOverloadRotationDelayMs,
     shouldAttemptClaudeFallback,
     executeClaudeFallbackWithRetry,
     buildClaudeAnthropicFailureResponse,

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

@@ -774,6 +774,21 @@ export type ArchiveDecompressionResult = {
  * perfectly well-formed, and telling the user it is damaged would send them to
  * re-create a file that was never broken.
  */
+/**
+ * The slice of an adm-zip entry the bounded reader depends on.
+ *
+ * Structural rather than adm-zip's own `IZipEntry` so the reader states what it
+ * actually needs — the compressed bytes and the header fields it refuses to
+ * trust — instead of importing a library type it would then have to satisfy in
+ * full when building a test double.
+ */
+export type BoundedZipEntry = {
+    getCompressedData: () => Buffer;
+    header: {
+        method: number;
+        crc: number;
+    };
+};
 export type ArchiveEntryReadResult = {
     readonly status: "ok";
     readonly buffer: Buffer;

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

@@ -646,6 +646,7 @@ export type AnthropicSuccessResult = {
     failure?: {
         message: string;
         rateLimit: boolean;
+        retryDelayMs?: number;
     };
 } | {
     response: Response | unknown;
@@ -702,6 +703,8 @@ export type AnthropicAuthRetryResult = {
     response?: Response | unknown;
     holdsAccountAdmission?: boolean;
     continueLoop: boolean;
+    /** Failure-path pacing before rotating after provider-wide overload. */
+    retryDelayMs?: number;
     lastError: unknown;
     authFailureMessage: string | null;
     sawRateLimit: boolean;
@@ -713,6 +716,8 @@ export type AnthropicNonOkResult = {
     response?: Response | unknown;
     continueLoop: boolean;
     retrySameAccount?: boolean;
+    /** Failure-path pacing before rotating after provider-wide overload. */
+    retryDelayMs?: number;
     lastError: unknown;
     authFailureMessage: string | null;
     sawTransientFailure: boolean;
@@ -1457,6 +1462,9 @@ export type ProxyAnalysisReport = {
         attemptLatency: boolean;
         cacheUsage: boolean;
         routingDecisions: boolean;
+        /** True only when every stream needed for cross-stream request/attempt
+         * reconciliation begins at or before the requested analysis window. */
+        comparableRequestAttempts: boolean;
     };
     dataQuality: {
         linesRead: number;
@@ -1468,6 +1476,8 @@ export type ProxyAnalysisReport = {
             observedFrom: string | null;
             observedTo: string | null;
             startsAtOrBeforeRequestedWindow: boolean;
+            /** Whether this stream can support claims covering the full window. */
+            completeWindow: boolean;
         }>;
         bodyArtifacts: {
             capturesIndexed: number;
@@ -2073,6 +2083,14 @@ export type RollingWorkerFailureDetails = {
     workerExitSignal?: string | null;
     supervisorAction?: "none" | "sigkill_after_transfer_failure";
 };
+export type RollingWorkerSupervisorEvent = {
+    at: string;
+    type: "activated" | "failure" | "failed_transfer" | "rejected_socket";
+    generation: number | null;
+    version: string | null;
+    phase?: "startup" | "activation" | "runtime" | "transfer";
+    reason?: string;
+};
 export type RollingWorkerSupervisorSnapshot = {
     generation: number;
     active: {
@@ -2093,6 +2111,8 @@ export type RollingWorkerSupervisorSnapshot = {
     queuedSockets: number;
     rejectedSockets: number;
     failedTransfers: number;
+    /** Bounded generation-scoped evidence for attributing lifetime counters. */
+    recentEvents: RollingWorkerSupervisorEvent[];
     lastFailure: ({
         at: string;
         generation: number;
@@ -2305,7 +2325,18 @@ export type ProxyNeurolinkRuntime = {
     neurolink: {
         getToolRegistry(): MCPToolRegistry;
     };
-    cleanupLogs: (daysToKeep?: number, maxFiles?: number) => void;
+    logsDir: string;
+};
+/** Data passed to the isolated proxy log-retention worker. */
+export type ProxyLogCleanupWorkerData = {
+    logsDir: string;
+    maxAgeDays: number;
+    maxSizeMb: number;
+};
+/** Lifecycle handle for non-blocking proxy log retention. */
+export type ProxyLogCleanupScheduler = {
+    trigger: () => boolean;
+    stop: () => Promise<void>;
 };
 /** Hono app + readiness state created by the proxy start command. */
 export type ProxyStartApp = {

package/dist/processors/archive/ArchiveProcessor.js

@@ -37,6 +37,7 @@
  */
 import * as path from "path";
 import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
+import { isDecompressionBoundExceeded, readZipEntryWithinLimit, } from "./zipEntryReader.js";
 import { SIZE_LIMITS_MB } from "../config/index.js";
 import { FileErrorCode } from "../errors/index.js";
 // =============================================================================
@@ -159,71 +160,6 @@ const SINGLE_STREAM_TOOLS = {
     xz: "xz",
     zst: "zstd",
 };
-/**
- * Read one ZIP entry's bytes without trusting the size it declares.
- *
- * `entry.getData()` cannot be used for this. It sizes its output buffer from
- * the central-directory `size` field, which the archive author chooses, and
- * adm-zip only arms its own guard when that field is positive:
- *
- *   const option = version >= 15 && expectedLength > 0
- *     ? { maxOutputLength: expectedLength } : {};
- *
- * So an entry declaring 0 disables the bound and the caller's `size > maxSize`
- * check in one move — `0 > 5MB` is false, and the inflate then runs uncapped.
- * The declared size is the attack, so nothing here may depend on it: the cap
- * comes from our own limit and is handed to the decoder.
- *
- * CRC is verified on both paths rather than dropped, so bypassing `getData()`
- * does not also quietly lose its corruption check — a STORED entry is copied
- * out rather than decoded, but it can be damaged just the same. It detects
- * damage, not malice — the CRC field is attacker-controlled too.
- */
-function readZipEntryWithinLimit(entry, maxBytes, zlibModule) {
-    const compressed = entry.getCompressedData();
-    const matchesCrc = (data) => (zlibModule.crc32(data) >>> 0) === (entry.header.crc >>> 0);
-    // STORED: the bytes are already the payload, so its own length is the bound.
-    if (entry.header.method === ZIP_METHOD_STORED) {
-        if (compressed.length > maxBytes) {
-            return { status: "too-large" };
-        }
-        return matchesCrc(compressed)
-            ? { status: "ok", buffer: compressed }
-            : { status: "corrupt" };
-    }
-    if (entry.header.method !== ZIP_METHOD_DEFLATED) {
-        return { status: "unsupported-method" };
-    }
-    let inflated;
-    try {
-        inflated = zlibModule.inflateRawSync(compressed, {
-            maxOutputLength: maxBytes,
-        });
-    }
-    catch (error) {
-        if (isDecompressionBoundExceeded(error)) {
-            return { status: "too-large" };
-        }
-        return { status: "corrupt" };
-    }
-    return matchesCrc(inflated)
-        ? { status: "ok", buffer: inflated }
-        : { status: "corrupt" };
-}
-/** ZIP compression methods this reader handles (APPNOTE 4.4.5). */
-const ZIP_METHOD_STORED = 0;
-const ZIP_METHOD_DEFLATED = 8;
-/**
- * Whether a zlib rejection is the output bound firing rather than bad input.
- *
- * `maxOutputLength` aborts an inflate the moment its output would pass the cap,
- * which is the whole point — but it surfaces as a plain `RangeError`, and a
- * bomb reported as "failed to decompress" reads as a corrupt upload and invites
- * the user to send it again. It will fail identically every time.
- *
- * Keyed on `code`, not the message: the message embeds a byte count.
- */
-const isDecompressionBoundExceeded = (error) => error?.code === "ERR_BUFFER_TOO_LARGE";
 /** File extensions recognized as archive formats */
 const SUPPORTED_ARCHIVE_EXTENSIONS = [".zip", ".tar", ".gz", ".tgz", ".bz2", ".tbz2", ".jar", ".xz", ".txz", ".zst", ".tzst"];
 // =============================================================================
@@ -1419,6 +1355,7 @@ export class ArchiveProcessor extends BaseFileProcessor {
                 .sort((a, b) => a.uncompressedSize - b.uncompressedSize);
             let totalExtracted = 0;
             let extractCount = 0;
+            const zlibModule = await import("zlib");
             for (const entry of candidates) {
                 if (extractCount >= ARCHIVE_CONFIG.MAX_EXTRACT_ENTRIES) {
                     break;
@@ -1431,8 +1368,17 @@ export class ArchiveProcessor extends BaseFileProcessor {
                     if (!zipEntry) {
                         continue;
                     }
-                    const data = zipEntry.getData();
-                    if (!data || data.length === 0) {
+                    // This path was already bounded, but only by coincidence: entries
+                    // declaring 0 are dropped above, oversized declarations are dropped
+                    // above, and adm-zip caps everything else at the size it declares.
+                    // That leaves the ceiling resting on library internals we do not
+                    // trust anywhere else in this file, so it is spelled out here.
+                    const read = readZipEntryWithinLimit(zipEntry, Math.min(ARCHIVE_CONFIG.MAX_EXTRACT_ENTRY_SIZE, ARCHIVE_CONFIG.MAX_TOTAL_EXTRACT_SIZE - totalExtracted), zlibModule);
+                    if (read.status !== "ok") {
+                        continue;
+                    }
+                    const data = read.buffer;
+                    if (data.length === 0) {
                         continue;
                     }
                     // Simple binary detection: check for null bytes in first 512 bytes

package/dist/processors/archive/zipEntryReader.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Bounded ZIP entry reading, shared by every processor that opens a ZIP.
+ *
+ * Extracted from ArchiveProcessor because the Office formats are ZIPs too:
+ * .pptx and .odt read their entries directly and so can be handed the same
+ * bomb, and need the same refusal. One implementation rather than three means
+ * a correction to the guard lands everywhere at once.
+ *
+ * .docx and .xlsx deliberately do NOT use this. mammoth and exceljs unzip for
+ * themselves and were measured refusing a 400MB bomb at 46MB and 53MB peak,
+ * so wrapping them in a pre-scan bought no safety and roughly tripled the cost
+ * of every ordinary document.
+ *
+ * @module processors/archive/zipEntryReader
+ */
+import type { ArchiveEntryReadResult, BoundedZipEntry } from "../../types/index.js";
+/** ZIP compression methods this reader handles (APPNOTE 4.4.5). */
+export declare const ZIP_METHOD_STORED = 0;
+export declare const ZIP_METHOD_DEFLATED = 8;
+/**
+ * Whether a zlib rejection is the output bound firing rather than bad input.
+ *
+ * `maxOutputLength` aborts an inflate the moment its output would pass the cap,
+ * which is the whole point — but it surfaces as a plain `RangeError`, and a
+ * bomb reported as "failed to decompress" reads as a corrupt upload and invites
+ * the user to send it again. It will fail identically every time.
+ *
+ * Keyed on `code`, not the message: the message embeds a byte count.
+ */
+export declare const isDecompressionBoundExceeded: (error: unknown) => boolean;
+/**
+ * Read one ZIP entry's bytes without trusting the size it declares.
+ *
+ * `entry.getData()` cannot be used for this. It sizes its output buffer from
+ * the central-directory `size` field, which the archive author chooses, and
+ * adm-zip only arms its own guard when that field is positive:
+ *
+ *   const option = version >= 15 && expectedLength > 0
+ *     ? { maxOutputLength: expectedLength } : {};
+ *
+ * So an entry declaring 0 disables the bound and the caller's `size > maxSize`
+ * check in one move — `0 > 5MB` is false, and the inflate then runs uncapped.
+ * The declared size is the attack, so nothing here may depend on it: the cap
+ * comes from our own limit and is handed to the decoder.
+ *
+ * CRC is verified on both paths rather than dropped, so bypassing `getData()`
+ * does not also quietly lose its corruption check — a STORED entry is copied
+ * out rather than decoded, but it can be damaged just the same. It detects
+ * damage, not malice — the CRC field is attacker-controlled too.
+ */
+export declare function readZipEntryWithinLimit(entry: BoundedZipEntry, maxBytes: number, zlibModule: typeof import("zlib")): ArchiveEntryReadResult;