pompelmi 0.35.3 → 0.35.5

package/README.md

@@ -1,54 +1,100 @@
+<!-- ════════════════════════════════════════════════════════════════════
+     PIVOT NOTICE — read before using this package
+     ════════════════════════════════════════════════════════════════════ -->
+> [!CAUTION]
+> **v0.x is an experimental prototype. Do NOT use it in production.**
+>
+> Pompelmi v0.x has **known Event Loop blocking issues** and makes overreaching
+> "scanner" claims that it cannot keep. This version is in **soft maintenance
+> only** — no new features, security patches only.
+>
+> ---
+>
+> **Pompelmi is pivoting for v1.0.**
+>
+> The new identity is a **dead-simple, one-line utility wrapper** for Node.js
+> file uploads — not an "ultimate malware scanner". v1.0 will bundle standard,
+> well-understood checks (size limits, magic bytes, basic heuristics) into a
+> single convenient call that returns a traffic-light verdict:
+>
+> ```js
+> const result = await pompelmi.scan(file);
+> // returns 'green', 'suspicious', or 'malicious'
+> ```
+>
+> No magic promises. No impossible guarantees. Just saved developer time.
+>
+> Follow the pivot → [GitHub Issues](https://github.com/pompelmi/pompelmi/issues) · [Discussions](https://github.com/pompelmi/pompelmi/discussions)
+
+---
+
 <div align="center">
-  <img src="./assets/logo.svg" alt="Pompelmi logo" width="144" />
+  <img src="./assets/logo.svg" alt="Pompelmi logo" width="120" />
 
   <h1>Pompelmi</h1>
 
-  <p><strong>Route-level upload security for Node.js.</strong></p>
-
-  <p>Inspect untrusted uploads before storage.</p>
+  <p><strong>Secure file uploads in Node.js before storage.</strong></p>
 
   <p>
-    MIME and extension spoofing · archive abuse · risky document and binary
-    signals · optional YARA
+    Open-source route-level upload security for Node.js teams that need to
+    inspect untrusted files before disk, object storage, previews, or
+    downstream parsers.
   </p>
 
   <p><code>clean</code> · <code>suspicious</code> · <code>malicious</code></p>
 
   <p>
-    <sub>Express · Next.js · NestJS · Fastify · Koa · Nuxt/Nitro · S3 quarantine flows · CI/CD</sub>
+    MIME spoofing · risky archives · document and binary signals · optional
+    YARA
   </p>
 
-  <p><sub>Open-source core · MIT · Node.js 18+</sub></p>
+  <p>
+    <sub>Express · Next.js · NestJS · Fastify · Koa · Nuxt/Nitro · S3 quarantine flows · CI/CD</sub>
+  </p>
 
   <p>
     <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm version" src="https://img.shields.io/npm/v/pompelmi" /></a>
+    <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm total downloads" src="https://img.shields.io/npm/dt/pompelmi" /></a>
     <a href="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/pompelmi/pompelmi/ci.yml?label=ci" /></a>
     <a href="https://codecov.io/gh/pompelmi/pompelmi"><img alt="codecov" src="https://codecov.io/gh/pompelmi/pompelmi/graph/badge.svg" /></a>
     <a href="https://github.com/pompelmi/pompelmi/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/pompelmi/pompelmi?style=social" /></a>
-    <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm weekly downloads" src="https://img.shields.io/npm/dw/pompelmi" /></a>
-    <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm monthly downloads" src="https://img.shields.io/npm/dm/pompelmi" /></a>
+    <a href="https://github.com/pompelmi/pompelmi/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-green.svg" /></a>
+    <a href="https://nodejs.org"><img alt="Node.js 18+" src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" /></a>
   </p>
 
+  > If Pompelmi fits how you think about upload security at the route
+  > level, starring the repo helps other Node.js teams find it.
+  > [★ Star on GitHub](https://github.com/pompelmi/pompelmi/stargazers)
+
   <p>
-    <a href="https://pompelmi.github.io/pompelmi/getting-started/"><strong>Getting started</strong></a>
+    <a href="https://pompelmi.app/"><strong>Docs</strong></a>
+    ·
+    <a href="https://pompelmi.app/getting-started/"><strong>Getting started</strong></a>
     ·
-    <a href="https://pompelmi.github.io/pompelmi/#browser-preview"><strong>Browser preview</strong></a>
+    <a href="https://pompelmi.app/#browser-preview"><strong>Browser preview</strong></a>
     ·
     <a href="./examples/demo"><strong>Express demo</strong></a>
     ·
     <a href="./examples/README.md"><strong>Examples</strong></a>
   </p>
+
+  <p><sub>Node.js 18+ · MIT</sub></p>
 </div>
 
 <p align="center">
-  Mentioned by <a href="https://nodeweekly.com/issues/594">Node Weekly</a>,
+  <strong>Mentioned by</strong>
+  <a href="https://nodeweekly.com/issues/594">Node Weekly</a>,
   <a href="https://stackoverflow.blog/2026/02/23/defense-against-uploads-oss-file-scanner-pompelmi/">Stack Overflow</a>,
   <a href="https://www.helpnetsecurity.com/2026/02/02/pompelmi-open-source-secure-file-upload-scanning-node-js/">Help Net Security</a>,
   <a href="https://github.com/sorrycc/awesome-javascript">Awesome JavaScript</a>,
+  <a href="https://github.com/dzharii/awesome-typescript">Awesome TypeScript</a>,
+  <a href="https://bytes.dev/archives/429">Bytes</a>,
   and
-  <a href="https://github.com/dzharii/awesome-typescript">Awesome TypeScript</a>.
+  <a href="https://www.detectionengineering.net/p/det-eng-weekly-124">Detection Engineering Weekly</a>
 </p>
 
+> Upload endpoints are part of your attack surface. Pompelmi helps Node.js teams scan files before storage and make the decision while the route still has context: accept, quarantine, or reject.
+
 ## Quick Start
 
 Install the core package:
@@ -57,7 +103,7 @@ Install the core package:
 npm install pompelmi
 ```
 
-Minimal route-level example:
+This is the core pattern: inspect bytes, get a verdict, and only store clean files.
 
 ```ts
 import { scanBytes, STRICT_PUBLIC_UPLOAD } from 'pompelmi';
@@ -80,104 +126,98 @@ if (report.verdict !== 'clean') {
 return res.status(200).json({ verdict: report.verdict });
 ```
 
-Start with [Getting started](https://pompelmi.github.io/pompelmi/getting-started/) for a local scan in under a minute, open the [browser preview](https://pompelmi.github.io/pompelmi/#browser-preview) to inspect the verdict flow without sending files anywhere, or run the minimal [Express demo](./examples/demo).
+Start with [Getting started](https://pompelmi.app/getting-started/) for a local scan in under a minute, open the [browser preview](https://pompelmi.app/#browser-preview) to inspect the verdict flow without sending files anywhere, or run the minimal [Express demo](./examples/demo).
 
-If Pompelmi matches how you want upload security to work, star the repo so more Node.js teams can find it.
+## Why teams use Pompelmi
 
-## Why It Exists
+- File upload endpoints are not just form validation. Files can become risky after storage, extraction, rendering, or downstream parsing.
+- Pompelmi keeps the first trust decision inside the application path, where the route still knows the file class, trust level, storage path, and failure mode.
+- It gives Node.js teams a practical way to build secure file uploads with route-level decisions instead of bolting checks on after persistence.
 
-Upload endpoints are part of your attack surface. A file can look harmless at the form layer and become dangerous only after storage, extraction, rendering, or downstream parsing.
+File upload vulnerabilities are the root cause of real CVEs across web frameworks. Application-layer inspection is the earliest point where the route still has full policy context — file class, trust level, storage path, and failure mode. Waiting until after storage removes most of that context and limits what the application can decide.
 
-Pompelmi keeps the first decision inside the application path, where the route still knows the file class, trust level, storage path, and failure mode.
+## What it checks
 
-## What It Checks
+- MIME sniffing, magic-byte validation, and extension mismatch detection
+- Risky archives such as ZIP bombs, traversal attempts, deep nesting, and entry-count abuse
+- Risky document and binary signals such as PDF actions, Office macro hints, PE headers, and polyglot files
+- Optional YARA-based matches when you want malware scanning uploads as part of the flow
+- Verdicts and reasons you can use for fail-closed routes, quarantine flows, and auditability
 
-- MIME sniffing, magic-byte validation, and extension allowlists
-- risky archive structures such as traversal, deep nesting, entry-count abuse, and ZIP bomb-style expansion
-- suspicious document and binary signals such as risky PDF actions, Office macro hints, PE headers, and polyglot files
-- optional YARA or other scanner matches
-- route-level verdicts that support reject, quarantine, or promote workflows
+## Where it fits in the upload pipeline
 
-## Where It Fits
+1. Receive the upload into memory or an isolated staging or quarantine area.
+2. Scan the bytes with a route policy.
+3. Act on the verdict: `clean`, `suspicious`, or `malicious`.
+4. Persist, quarantine, or reject based on the route's rules.
 
-- public or semi-trusted upload endpoints that should inspect first and store later
-- memory-backed multipart routes in Express, Next.js, NestJS, Fastify, and Koa
-- quarantine and promotion workflows for S3 or other object storage
-- document, image, and archive routes that need different policies
-- CI/CD or internal artifact scanning before promotion
+That inspect-first, store-later shape is where Pompelmi is strongest.
 
-## Why Not Just X?
+## What it is and isn't
 
 | Approach | Useful for | What it misses |
 | --- | --- | --- |
-| Browser MIME and extension checks | Fast client-side hints and UX feedback | Filenames and client-reported MIME are easy to spoof |
-| Simple file-type or magic-byte checks | Confirming the file appears to be the claimed type | Risky internal structure, archive abuse, and route policy decisions |
-| Antivirus-only thinking | Known malicious matches and signature-based detection | Route context, spoofing checks, storage decisions, and non-signature risk signals |
-| Pompelmi at the upload route | Inspect-first, store-later decisions with policy, structure checks, and optional YARA | It is not a full antivirus replacement on its own |
-
-## Integrations
+| Browser MIME and extension checks | Fast client-side hints and UX feedback | Client MIME and filenames are easy to spoof |
+| File-type or magic-byte validation only | Confirming a file looks like the claimed type | Archive abuse, risky internal structure, and route policy decisions |
+| Antivirus or YARA only | Known malicious matches and signature-style detection | Route context, spoofing checks, and before-storage handling |
+| Pompelmi at the upload route | Node.js file upload security, scan files before storage, and verdict-driven workflow decisions | It is not a full antivirus replacement on its own |
 
-- Express: [Docs](https://pompelmi.github.io/pompelmi/how-to/express/) · [Minimal example](./examples/express-minimal) · [Demo](./examples/demo)
-- Next.js: [Docs](https://pompelmi.github.io/pompelmi/how-to/nextjs/) · [Example](./examples/next-app-router)
-- NestJS: [Docs](https://pompelmi.github.io/pompelmi/how-to/nestjs/) · [Example app](./examples/nestjs-app)
-- Fastify: [Docs](https://pompelmi.github.io/pompelmi/how-to/fastify/) · [Package](./packages/fastify-plugin)
-- Koa: [Docs](https://pompelmi.github.io/pompelmi/how-to/koa/) · [Package](./packages/koa-middleware)
-- Nuxt/Nitro: [Docs](https://pompelmi.github.io/pompelmi/how-to/nuxt-nitro/)
-- S3 / object storage: [Tutorial](https://pompelmi.github.io/pompelmi/tutorials/secure-s3-presigned-uploads-with-malware-scanning/) · [Use case](https://pompelmi.github.io/pompelmi/use-cases/s3-presigned-upload-security/)
-- CI/CD: [Use case](https://pompelmi.github.io/pompelmi/use-cases/cicd-artifact-scanning/) · [Blog](https://pompelmi.github.io/pompelmi/blog/cicd-scan-build-artifacts/)
+<!-- search: file upload security Node.js, MIME spoofing protection, archive bomb defense -->
 
-## Demo, Preview, and Examples
+## Supported frameworks and workflows
 
-![Pompelmi upload security demo](assets/malware-detection-node-demo.gif)
+| Stack or workflow | Links |
+| --- | --- |
+| Express | [Docs](https://pompelmi.app/how-to/express/) · [Minimal example](./examples/express-minimal) · [Demo](./examples/demo) |
+| Next.js | [Docs](https://pompelmi.app/how-to/nextjs/) · [Example](./examples/next-app-router) · [Package](./packages/next-upload) |
+| NestJS | [Docs](https://pompelmi.app/how-to/nestjs/) · [Package](./packages/nestjs) · [Example app](./examples/nestjs-app) |
+| Fastify | [Docs](https://pompelmi.app/how-to/fastify/) · [Package](./packages/fastify-plugin) |
+| Koa | [Docs](https://pompelmi.app/how-to/koa/) · [Package](./packages/koa-middleware) |
+| Nuxt/Nitro | [Docs](https://pompelmi.app/how-to/nuxt-nitro/) · [Example](./examples/nuxt-nitro) |
+| S3 / object storage | [Tutorial](https://pompelmi.app/tutorials/secure-s3-presigned-uploads-with-malware-scanning/) · [Use case](https://pompelmi.app/use-cases/object-storage-promotion-workflows/) |
+| CI/CD | [Use case](https://pompelmi.app/use-cases/cicd-artifact-scanning/) · [Blog](https://pompelmi.app/blog/cicd-scan-build-artifacts/) |
 
-- [Browser preview](https://pompelmi.github.io/pompelmi/#browser-preview) for a fast local evaluation of the verdict UX
-- [Demo](./examples/demo) for a tiny Express upload gate that returns `clean`, `suspicious`, or `malicious` before storage
-- [Examples index](./examples/README.md) for framework-specific and production-oriented examples
+## Demo, preview, and examples
 
-## Docs
-
-- [Docs home](https://pompelmi.github.io/pompelmi/)
-- [Getting started](https://pompelmi.github.io/pompelmi/getting-started/)
-- [Use cases](https://pompelmi.github.io/pompelmi/use-cases/)
-- [Comparisons](https://pompelmi.github.io/pompelmi/comparisons/)
-- [Tutorials](https://pompelmi.github.io/pompelmi/tutorials/)
-- [Featured in](https://pompelmi.github.io/pompelmi/featured-in/)
-- [Translations](https://pompelmi.github.io/pompelmi/translations/)
+![Pompelmi upload security demo](assets/malware-detection-node-demo.gif)
 
-## Enterprise and Commercial Support
+- [Browser preview](https://pompelmi.app/#browser-preview) for a fast local look at the verdict UX without uploading files anywhere
+- [Express demo](./examples/demo) for a tiny upload gate that returns `clean`, `suspicious`, or `malicious` before storage
+- [Examples index](./examples/README.md) for framework-specific and production-oriented patterns
+- [Docs home](https://pompelmi.app/) for guides, comparisons, use cases, and tutorials
 
-The MIT core remains the primary path. Teams that need private rollout help, architecture review, or policy tuning can use the existing [enterprise support path](https://pompelmi.github.io/pompelmi/enterprise/).
+Listed in Awesome JavaScript and Awesome TypeScript, and featured by Node Weekly, Stack Overflow, Help Net Security, Bytes, and Detection Engineering Weekly.
 
 <!-- MENTIONS:START -->
 
-## Featured In
-
-Full page: [pompelmi.github.io/pompelmi/featured-in](https://pompelmi.github.io/pompelmi/featured-in/)
-
-*Last updated: March 20, 2026*
-
-### Awesome Lists & Curated Collections
+## Mentioned by
 
-- [Awesome JavaScript](https://github.com/sorrycc/awesome-javascript) — sorrycc
-- [Awesome TypeScript](https://github.com/dzharii/awesome-typescript) — dzharii
+- [Node Weekly](https://nodeweekly.com/issues/594)
+- [Defense against uploads: Q&A with OSS file scanner, pompelmi](https://stackoverflow.blog/2026/02/23/defense-against-uploads-oss-file-scanner-pompelmi/) — Stack Overflow
+- [Pompelmi: Open-source secure file upload scanning for Node.js](https://www.helpnetsecurity.com/2026/02/02/pompelmi-open-source-secure-file-upload-scanning-node-js/) — Help Net Security
+- [Awesome JavaScript](https://github.com/sorrycc/awesome-javascript)
+- [Awesome TypeScript](https://github.com/dzharii/awesome-typescript)
+- [Bytes #429](https://bytes.dev/archives/429) — bytes.dev (2025-10-03)
+- [Det. Eng. Weekly #124](https://www.detectionengineering.net/p/det-eng-weekly-124) — detectionengineering.net (2025-08-13)
+- [The Overflow #319](https://stackoverflow.blog/2026/03/04/the-overflow-319/) — stackoverflow.blog (2026-03-04)
+- [Hottest OSS tools Feb 2026](https://www.helpnetsecurity.com/2026/02/26/hottest-oss-tools-feb-2026/) — helpnetsecurity.com (2026-02-26)
+- [See all mentions](https://pompelmi.app/featured-in/)
 
-### Newsletters & Roundups
-
-- [The Overflow Issue 319: Dogfooding your SDLC](https://stackoverflow.blog/newsletter/issue-319-dogfooding-your-sdlc/) — Stack Overflow (2026-03-04)
-- [Hottest cybersecurity open-source tools of the month: February 2026](https://www.helpnetsecurity.com/2026/02/26/hottest-cybersecurity-open-source-tools-of-the-month-february-2026/) — Help Net Security (2026-02-26)
-- [Bytes #429](https://bytes.dev/archives/429) — Bytes (2025-10-03)
-- [Node Weekly Issue 594](https://nodeweekly.com/issues/594) — Node Weekly (2025-09-30)
-- [Det. Eng. Weekly Issue #124 - The DEFCON hangover is real](https://www.detectionengineering.net/p/det-eng-weekly-issue-124-the-defcon) — Detection Engineering (2025-08-13)
-
-### Other Mentions
+<!-- MENTIONS:END -->
 
-- [Defense against uploads: Q&A with OSS file scanner, pompelmi](https://stackoverflow.blog/2026/02/23/defense-against-uploads-oss-file-scanner-pompelmi/) — Stack Overflow (2026-02-23)
-- [Pompelmi: Open-source secure file upload scanning for Node.js](https://www.helpnetsecurity.com/2026/02/02/pompelmi-open-source-secure-file-upload-scanning-node-js/) — Help Net Security (2026-02-02)
+## Docs
 
+- [Getting started](https://pompelmi.app/getting-started/)
+- [Use cases](https://pompelmi.app/use-cases/)
+- [Comparisons](https://pompelmi.app/comparisons/)
+- [Tutorials](https://pompelmi.app/tutorials/)
+- [Browser preview](https://pompelmi.app/#browser-preview)
+- [Featured in](https://pompelmi.app/featured-in/)
+- [Translations](https://pompelmi.app/translations/)
 
-*Found 9 mentions. To update, run `npm run mentions:update`.*
+## Commercial support
 
-<!-- MENTIONS:END -->
+The MIT core remains the primary path. Teams that need private rollout help, architecture review, or policy tuning can use the existing [enterprise support path](https://pompelmi.app/enterprise/).
 
 ## Project
 

package/dist/pompelmi.browser.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var crypto = require('crypto');
+var zlib = require('zlib');
 
 const MB$1 = 1024 * 1024;
 const DEFAULT_POLICY = {
@@ -1053,12 +1054,15 @@ async function scanFiles(files, opts = {}) {
     return out;
 }
 
+const ARCHIVE_BOMB_DETECTED = "ARCHIVE_BOMB_DETECTED";
+const SIG_LFH = 0x04034b50;
 const SIG_CEN = 0x02014b50;
 const DEFAULTS = {
     maxEntries: 1000,
     maxTotalUncompressedBytes: 500 * 1024 * 1024,
+    maxPerEntryUncompressedBytes: 100 * 1024 * 1024,
     maxEntryNameLength: 255,
-    maxCompressionRatio: 1000,
+    maxCompressionRatio: 100,
     eocdSearchWindow: 70000,
 };
 function r16(buf, off) {
@@ -1068,7 +1072,6 @@ function r32(buf, off) {
     return buf.readUInt32LE(off);
 }
 function isZipLike(buf) {
-    // local file header at start is common
     return (buf.length >= 4 && buf[0] === 0x50 && buf[1] === 0x4b && buf[2] === 0x03 && buf[3] === 0x04);
 }
 function lastIndexOfEOCD(buf, window) {
@@ -1080,6 +1083,47 @@ function lastIndexOfEOCD(buf, window) {
 function hasTraversal(name) {
     return (name.includes("../") || name.includes("..\\") || name.startsWith("/") || /^[A-Za-z]:/.test(name));
 }
+function makeBombError() {
+    return Object.assign(new Error("Archive bomb detected: decompression limits exceeded"), {
+        code: ARCHIVE_BOMB_DETECTED,
+    });
+}
+/**
+ * Feeds `compressed` into a raw DEFLATE inflate stream and counts the actual
+ * output bytes. Resolves with bombed=true and aborts early if any limit fires:
+ *   - decompressed bytes > maxPerEntry
+ *   - totalSoFar + decompressed > maxTotal
+ *   - decompressed / compressed > maxRatio  (ratio measured on real bytes, not headers)
+ *
+ * Malformed DEFLATE is treated as safe (bombed=false, decompressed=0).
+ */
+function streamInflate(compressed, maxPerEntry, maxTotal, alreadySeen, maxRatio) {
+    return new Promise((resolve) => {
+        const inf = zlib.createInflateRaw();
+        let out = 0;
+        const compBytes = compressed.length;
+        let done = false;
+        const finish = (bombed) => {
+            if (done)
+                return;
+            done = true;
+            inf.destroy();
+            resolve({ decompressed: out, bombed });
+        };
+        inf.on("data", (chunk) => {
+            out += chunk.length;
+            if (out > maxPerEntry ||
+                alreadySeen + out > maxTotal ||
+                (compBytes > 0 && out / compBytes > maxRatio)) {
+                finish(true);
+            }
+        });
+        inf.on("end", () => finish(false));
+        // Malformed DEFLATE stream → not a bomb, just corrupt
+        inf.on("error", () => finish(false));
+        inf.end(compressed);
+    });
+}
 function createZipBombGuard(opts = {}) {
     const cfg = { ...DEFAULTS, ...opts };
     return {
@@ -1088,43 +1132,36 @@ function createZipBombGuard(opts = {}) {
             const matches = [];
             if (!isZipLike(buf))
                 return matches;
-            // Find EOCD near the end
+            // ── 1. Locate EOCD ──────────────────────────────────────────────────────
             const eocdPos = lastIndexOfEOCD(buf, cfg.eocdSearchWindow);
             if (eocdPos < 0 || eocdPos + 22 > buf.length) {
-                // ZIP but no EOCD — malformed or polyglot → suspicious
                 matches.push({ rule: "zip_eocd_not_found", severity: "medium" });
                 return matches;
             }
             const totalEntries = r16(buf, eocdPos + 10);
             const cdSize = r32(buf, eocdPos + 12);
             const cdOffset = r32(buf, eocdPos + 16);
-            // Bounds check
             if (cdOffset + cdSize > buf.length) {
                 matches.push({ rule: "zip_cd_out_of_bounds", severity: "medium" });
                 return matches;
             }
-            // Iterate central directory entries
+            const lfhIndex = [];
             let ptr = cdOffset;
             let seen = 0;
-            let sumComp = 0;
-            let sumUnc = 0;
             while (ptr + 46 <= cdOffset + cdSize && seen < totalEntries) {
-                const sig = r32(buf, ptr);
-                if (sig !== SIG_CEN)
-                    break; // stop if structure breaks
-                const compSize = r32(buf, ptr + 20);
-                const uncSize = r32(buf, ptr + 24);
+                if (r32(buf, ptr) !== SIG_CEN)
+                    break;
+                const cdCompSize = r32(buf, ptr + 20);
                 const fnLen = r16(buf, ptr + 28);
                 const exLen = r16(buf, ptr + 30);
                 const cmLen = r16(buf, ptr + 32);
-                const nameStart = ptr + 46;
-                const nameEnd = nameStart + fnLen;
+                const lfhOffset = r32(buf, ptr + 42);
+                const nameEnd = ptr + 46 + fnLen;
                 if (nameEnd > buf.length)
                     break;
-                const name = buf.toString("utf8", nameStart, nameEnd);
-                sumComp += compSize;
-                sumUnc += uncSize;
+                const name = buf.toString("utf8", ptr + 46, nameEnd);
                 seen++;
+                lfhIndex.push({ lfhOffset, cdCompSize });
                 if (name.length > cfg.maxEntryNameLength) {
                     matches.push({
                         rule: "zip_entry_name_too_long",
@@ -1135,48 +1172,67 @@ function createZipBombGuard(opts = {}) {
                 if (hasTraversal(name)) {
                     matches.push({ rule: "zip_path_traversal_entry", severity: "medium", meta: { name } });
                 }
-                // move to next entry
                 ptr = nameEnd + exLen + cmLen;
             }
             if (seen !== totalEntries) {
-                // central dir truncated/odd, still report what we found
                 matches.push({
                     rule: "zip_cd_truncated",
                     severity: "medium",
                     meta: { seen, totalEntries },
                 });
             }
-            // Heuristics thresholds
             if (seen > cfg.maxEntries) {
                 matches.push({
                     rule: "zip_too_many_entries",
                     severity: "medium",
                     meta: { seen, limit: cfg.maxEntries },
                 });
+                // Return early — decompressing thousands of entries would be a DoS vector
+                return matches;
             }
-            if (sumUnc > cfg.maxTotalUncompressedBytes) {
-                matches.push({
-                    rule: "zip_total_uncompressed_too_large",
-                    severity: "medium",
-                    meta: { totalUncompressed: sumUnc, limit: cfg.maxTotalUncompressedBytes },
-                });
-            }
-            if (sumComp === 0 && sumUnc > 0) {
-                matches.push({
-                    rule: "zip_suspicious_ratio",
-                    severity: "medium",
-                    meta: { ratio: Infinity },
-                });
-            }
-            else if (sumComp > 0) {
-                const ratio = sumUnc / Math.max(1, sumComp);
-                if (ratio >= cfg.maxCompressionRatio) {
-                    matches.push({
-                        rule: "zip_suspicious_ratio",
-                        severity: "medium",
-                        meta: { ratio, limit: cfg.maxCompressionRatio },
-                    });
+            // ── 3. True streaming decompression — archive bomb detection ────────────
+            // For every DEFLATE entry (method=8) we feed the raw compressed bytes into
+            // zlib.createInflateRaw() and count the bytes that come OUT.  We abort the
+            // moment any limit fires; we NEVER trust the header-reported uncompressed
+            // size for the ratio decision.
+            //
+            // For STORED entries (method=0) compressed == uncompressed by spec, so the
+            // byte count is immediate.
+            let totalDecompressed = 0;
+            for (const { lfhOffset, cdCompSize } of lfhIndex) {
+                if (lfhOffset + 30 > buf.length)
+                    continue;
+                if (r32(buf, lfhOffset) !== SIG_LFH)
+                    continue;
+                const gpbf = r16(buf, lfhOffset + 6);
+                const method = r16(buf, lfhOffset + 8);
+                let lfhCompSz = r32(buf, lfhOffset + 18);
+                const fnLen = r16(buf, lfhOffset + 26);
+                const exLen = r16(buf, lfhOffset + 28);
+                const dataOff = lfhOffset + 30 + fnLen + exLen;
+                // If the data-descriptor flag is set (GPBF bit 3), the LFH sizes are 0.
+                // Fall back to the CD size purely for navigation — not for bomb detection.
+                if ((gpbf & 0x08) !== 0 && lfhCompSz === 0) {
+                    lfhCompSz = cdCompSize;
+                }
+                if (dataOff + lfhCompSz > buf.length)
+                    continue; // truncated entry — skip
+                if (method === 8 /* DEFLATE */) {
+                    const compressed = buf.slice(dataOff, dataOff + lfhCompSz);
+                    const { decompressed, bombed } = await streamInflate(compressed, cfg.maxPerEntryUncompressedBytes, cfg.maxTotalUncompressedBytes, totalDecompressed, cfg.maxCompressionRatio);
+                    if (bombed)
+                        throw makeBombError();
+                    totalDecompressed += decompressed;
+                }
+                else if (method === 0 /* STORED */) {
+                    // Compressed == uncompressed for stored entries
+                    if (lfhCompSz > cfg.maxPerEntryUncompressedBytes)
+                        throw makeBombError();
+                    totalDecompressed += lfhCompSz;
+                    if (totalDecompressed > cfg.maxTotalUncompressedBytes)
+                        throw makeBombError();
                 }
+                // Other methods (bzip2=12, lzma=14, zstd=93, …) — skip; no built-in support
             }
             return matches;
         },