pompelmi 0.35.4 → 0.35.5

package/README.md

@@ -1,3 +1,33 @@
+<!-- ════════════════════════════════════════════════════════════════════
+     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="120" />
 
@@ -24,11 +54,18 @@
 
   <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://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.app/"><strong>Docs</strong></a>
     ·
@@ -50,12 +87,10 @@
   <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>
-</p>
-
-<p align="center">
-  <sub>If you want upload security to start at the route boundary instead of after storage, consider starring the repo.</sub>
+  <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.
@@ -99,6 +134,8 @@ Start with [Getting started](https://pompelmi.app/getting-started/) for a local
 - 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.
 
+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.
+
 ## What it checks
 
 - MIME sniffing, magic-byte validation, and extension mismatch detection
@@ -125,6 +162,8 @@ That inspect-first, store-later shape is where Pompelmi is strongest.
 | 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 |
 
+<!-- search: file upload security Node.js, MIME spoofing protection, archive bomb defense -->
+
 ## Supported frameworks and workflows
 
 | Stack or workflow | Links |
@@ -147,9 +186,7 @@ That inspect-first, store-later shape is where Pompelmi is strongest.
 - [Examples index](./examples/README.md) for framework-specific and production-oriented patterns
 - [Docs home](https://pompelmi.app/) for guides, comparisons, use cases, and tutorials
 
-## Why star this repo
-
-Pompelmi is focused on a real gap in most Node.js stacks: secure file uploads that make a decision before storage, not after. If that matches how you want upload security to work, star the repo to follow the project and help more teams discover the inspect-before-storage model.
+Listed in Awesome JavaScript and Awesome TypeScript, and featured by Node Weekly, Stack Overflow, Help Net Security, Bytes, and Detection Engineering Weekly.
 
 <!-- MENTIONS:START -->
 
@@ -160,6 +197,10 @@ Pompelmi is focused on a real gap in most Node.js stacks: secure file uploads th
 - [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/)
 
 <!-- MENTIONS:END -->

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;
         },