pompelmi 0.15.0 → 0.15.2

package/README.md

@@ -1,11 +1,12 @@
+<!-- HERO START -->
 
 <p align="center">
 
 <br/>
-<a href="https://www.producthunt.com/products/pompelmi?embed=true&utm_source=badge-featured&utm_medium=badge&utm_source=badge-pompelmi" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1010722&theme=light&t=1756653468504" alt="pompelmi - free&#0044;&#0032;open&#0045;source&#0032;file&#0032;scanner | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
+<a href="https://www.producthunt.com/products/pompelmi?embed=true&utm_source=badge-pompelmi&utm_medium=badge" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1010722&theme=light&t=1756653468504" alt="pompelmi - free&#0044;&#0032;open&#0045;source&#0032;file&#0032;scanner | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
 <br/>
   <a href="https://github.com/pompelmi/pompelmi" target="_blank" rel="noopener noreferrer">
-    <img src="https://raw.githubusercontent.com/pompelmi/pompelmi/refs/heads/main/assets/logo.svg" alt="pompelmi logo" width="360" height="280" />
+    <img src="https://raw.githubusercontent.com/pompelmi/pompelmi/refs/heads/main/assets/logo.svg" alt="pompelmi logo" width="360" />
   </a>
   <br/>
   <a href="https://www.detectionengineering.net/p/det-eng-weekly-issue-124-the-defcon"><img alt="Featured in Detection Engineering Weekly #124" src="https://img.shields.io/badge/featured-Detection%20Engineering%20Weekly-0A84FF?logo=substack"></a>
@@ -18,9 +19,11 @@
 
 
 <p align="center">
-<video src="assets/video.mp4" width="920" autoplay loop muted playsinline controls></video>
-<br/>
-<strong>Fast file‑upload malware scanning for Node.js</strong> — optional <strong>YARA</strong> integration, ZIP deep‑inspection, and drop‑in adapters for <em>Express</em>, <em>Koa</em>, and <em>Next.js</em>. Private by design. Typed. Tiny.</p>
+
+<strong>Fast file‑upload malware scanning for Node.js</strong> — optional <strong>YARA</strong> integration, ZIP deep‑inspection, and drop‑in adapters for <em>Express</em>, <em>Koa</em>, and <em>Next.js</em>. Private by design. Typed. Tiny.
+</p>
+
+
 
 <p align="center">
   <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm version" src="https://img.shields.io/npm/v/pompelmi?label=pompelmi&color=0a7ea4"></a>
@@ -46,14 +49,16 @@
   <a href="#configuration">Config</a> ·
   <a href="#production-checklist">Production checklist</a> ·
   <a href="#yara-getting-started">YARA</a> ·
-  <a href="#quick-test-eicar">Quick test</a> ·
+  <a href="#quick-test-no-eicar">Quick test</a> ·
   <a href="#security-notes">Security</a> ·
   <a href="#faq">FAQ</a>
 </p>
 
+<!-- HERO END -->
+
 ---
 
-## Overview
+## 🚀 Overview
 
 **pompelmi** scans untrusted file uploads **before** they hit disk. A tiny, TypeScript-first toolkit for Node.js with composable scanners, deep ZIP inspection, and optional signature engines.
 
@@ -63,7 +68,7 @@
 - **Drop-in adapters** — Express, Koa, Fastify, Next.js
 - **Typed & tiny** — modern TS, minimal surface
 
-## Highlights
+## ✨ Highlights
 
 - **Block risky uploads early** — classify uploads as _clean_, _suspicious_, or _malicious_ and stop them at the edge.
 - **Real guards** — extension allow‑list, server‑side MIME sniff (magic bytes), per‑file size caps, and **deep ZIP** traversal with anti‑bomb limits.
@@ -76,7 +81,7 @@
 
 ---
 
-## Installation
+## 🔧 Installation
 
 ```bash
 # core library
@@ -95,7 +100,7 @@ yarn add pompelmi
 
 ---
 
-## Quick‑start
+## ⚡ Quick‑start
 
 **At a glance (policy + scanners)**
 
@@ -177,7 +182,7 @@ export const POST = createNextUploadHandler({ ...policy, scanner });
 
 ---
 
-## GitHub Action
+## 🤖 GitHub Action
 
 Run **pompelmi** in CI to scan repository files or built artifacts.
 
@@ -223,7 +228,7 @@ jobs:
 
 ---
 
-## Adapters
+## 🧩 Adapters
 
 Use the adapter that matches your web framework. All adapters share the same policy options and scanning contract.
 
@@ -240,7 +245,7 @@ Use the adapter that matches your web framework. All adapters share the same pol
 
 ---
 
-## Diagrams
+## 🗺️ Diagrams
 
 ### Upload scanning flow
 ```mermaid
@@ -366,7 +371,7 @@ flowchart LR
 
 ---
 
-## Configuration
+## ⚙️ Configuration
 
 All adapters accept a common set of options:
 
@@ -394,7 +399,7 @@ failClosed: true,
 
 ---
 
-## Production checklist
+## ✅ Production checklist
 
 - [ ] **Limit file size** aggressively (`maxFileSizeBytes`).
 - [ ] **Restrict extensions & MIME** to what your app truly needs.
@@ -409,7 +414,7 @@ failClosed: true,
 
 ---
 
-## YARA Getting Started
+## 🧬 YARA Getting Started
 
 YARA lets you detect suspicious or malicious content using pattern‑matching rules.  
 **pompelmi** treats YARA matches as signals that you can map to your own verdicts  
@@ -527,7 +532,7 @@ export const scanner = composeScanners(
 
 Combine YARA with MIME sniffing, ZIP safety limits, and strict size/time caps.
 
-## Quick test (no EICAR)
+## 🧪 Quick test (no EICAR)
 
 Use the examples above, then send a **minimal PDF** that contains risky tokens (this triggers the built‑in heuristics).
 
@@ -554,7 +559,7 @@ You should see an HTTP **422 Unprocessable Entity** (blocked by policy). Clean f
 
 ---
 
-## Security notes
+## 🔒 Security notes
 
 - The library **reads** bytes; it never executes files.
 - YARA detections depend on the **rules you provide**; expect some false positives/negatives.
@@ -563,13 +568,13 @@ You should see an HTTP **422 Unprocessable Entity** (blocked by policy). Clean f
 
 ---
 
-## Star history
+## ⭐ Star history
 
 [![Star History Chart](https://api.star-history.com/svg?repos=pompelmi/pompelmi&type=Date)](https://star-history.com/#pompelmi/pompelmi&Date)
 
 ---
 
-## FAQ
+## 💬 FAQ
 
 **Do I need YARA?**  
 No. `scanner` is pluggable. The examples use a minimal scanner for clarity; you can call out to a YARA engine or any other detector you prefer.
@@ -585,7 +590,7 @@ Archives are traversed with limits to reduce archive‑bomb risk. Keep your size
 
 ---
 
-## Tests & Coverage
+## 🧪 Tests & Coverage
 
 Run tests locally with coverage:
 
@@ -601,7 +606,7 @@ If you integrate Codecov in CI, upload `coverage/lcov.info` and you can use this
 [![codecov](https://codecov.io/gh/pompelmi/pompelmi/branch/main/graph/badge.svg?flag=core)](https://codecov.io/gh/pompelmi/pompelmi)
 ```
 
-## Contributing
+## 🤝 Contributing
 
 PRs and issues welcome! Start with:
 
@@ -612,6 +617,8 @@ pnpm -r lint
 
 ---
 
-## License
+<p align="right"><a href="#pompelmi">↑ Back to top</a></p>
+
+## 📜 License
 
 [MIT](./LICENSE) © 2025‑present pompelmi contributors

package/dist/pompelmi.esm.js

@@ -1,137 +1,28 @@
-const SIG_CEN = 0x02014b50;
-const DEFAULTS = {
-    maxEntries: 1000,
-    maxTotalUncompressedBytes: 500 * 1024 * 1024,
-    maxEntryNameLength: 255,
-    maxCompressionRatio: 1000,
-    eocdSearchWindow: 70000,
-};
-function r16(buf, off) {
-    return buf.readUInt16LE(off);
-}
-function r32(buf, off) {
-    return buf.readUInt32LE(off);
-}
-function isZipLike$1(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) {
-    const sig = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
-    const start = Math.max(0, buf.length - window);
-    const idx = buf.lastIndexOf(sig, Math.min(buf.length - sig.length, buf.length - 1));
-    return idx >= start ? idx : -1;
+function toScanFn(s) {
+    return (typeof s === "function" ? s : s.scan);
 }
-function hasTraversal(name) {
-    return name.includes('../') || name.includes('..\\') || name.startsWith('/') || /^[A-Za-z]:/.test(name);
-}
-function createZipBombGuard(opts = {}) {
-    const cfg = { ...DEFAULTS, ...opts };
-    return {
-        async scan(input) {
-            const buf = Buffer.from(input);
-            const matches = [];
-            if (!isZipLike$1(buf))
-                return matches;
-            // Find EOCD near the end
-            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
-            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);
-                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;
-                if (nameEnd > buf.length)
-                    break;
-                const name = buf.toString('utf8', nameStart, nameEnd);
-                sumComp += compSize;
-                sumUnc += uncSize;
-                seen++;
-                if (name.length > cfg.maxEntryNameLength) {
-                    matches.push({ rule: 'zip_entry_name_too_long', severity: 'medium', meta: { name, length: name.length } });
-                }
-                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 } });
-            }
-            if (sumUnc > cfg.maxTotalUncompressedBytes) {
-                matches.push({
-                    rule: 'zip_total_uncompressed_too_large',
-                    severity: 'medium',
-                    meta: { totalUncompressed: sumUnc, limit: cfg.maxTotalUncompressedBytes }
-                });
+function composeScanners(...scanners) {
+    return async (input, ctx) => {
+        const all = [];
+        for (const s of scanners) {
+            try {
+                const out = await toScanFn(s)(input, ctx);
+                if (Array.isArray(out))
+                    all.push(...out);
             }
-            if (sumComp === 0 && sumUnc > 0) {
-                matches.push({ rule: 'zip_suspicious_ratio', severity: 'medium', meta: { ratio: Infinity } });
+            catch {
+                // ignore individual scanner failures
             }
-            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 } });
-                }
-            }
-            return matches;
         }
+        return all;
     };
 }
-
-/** Risolve uno Scanner (fn o oggetto con .scan) in una funzione */
-function asScanFn(s) {
-    return typeof s === 'function' ? s : s.scan;
-}
-/** Composizione sequenziale: concatena tutti i match degli scanner */
-function composeScanners(scanners) {
-    return async (input, ctx) => {
-        const out = [];
-        for (const s of scanners) {
-            const res = await Promise.resolve(asScanFn(s)(input, ctx));
-            if (Array.isArray(res) && res.length)
-                out.push(...res);
-        }
-        return out;
+function createPresetScanner(_preset, _opts = {}) {
+    // TODO: wire to real preset registry
+    return async (_input, _ctx) => {
+        return [];
     };
 }
-/** Ritorna uno ScanFn pronto all'uso, oggi con zip-bomb guard */
-function createPresetScanner(_name = 'zip-basic', _opts = {}) {
-    // Al momento un solo preset "zip-basic"
-    const scanners = [
-        createZipBombGuard(), // usa i default interni
-    ];
-    return composeScanners(scanners);
-}
 
 /** Mappa veloce estensione -> mime (basic) */
 function guessMimeByExt(name) {
@@ -168,14 +59,14 @@ function toYaraMatches(ms) {
 /** Scan di bytes (browser/node) usando preset (default: zip-basic) */
 async function scanBytes(input, opts = {}) {
     const t0 = Date.now();
-    const preset = opts.preset ?? 'zip-basic';
+    opts.preset ?? 'zip-basic';
     const ctx = {
         ...opts.ctx,
         mimeType: opts.ctx?.mimeType ?? guessMimeByExt(opts.ctx?.filename),
         size: opts.ctx?.size ?? input.byteLength,
     };
-    const scanFn = createPresetScanner(preset);
-    const matchesH = await scanFn(input, ctx);
+    const scanFn = createPresetScanner();
+    const matchesH = await (typeof scanFn === "function" ? scanFn : scanFn.scan)(input, ctx);
     const matches = toYaraMatches(matchesH);
     const verdict = computeVerdict(matches);
     const durationMs = Date.now() - t0;
@@ -3188,7 +3079,7 @@ function isOleCfb(buf) {
     const sig = [0xD0, 0xCF, 0x11, 0xE0, 0xA1, 0xB1, 0x1A, 0xE1];
     return startsWith(buf, sig);
 }
-function isZipLike(buf) {
+function isZipLike$1(buf) {
     // PK\x03\x04
     return startsWith(buf, [0x50, 0x4b, 0x03, 0x04]);
 }
@@ -3198,7 +3089,7 @@ function isPeExecutable(buf) {
 }
 /** OOXML macro hint via filename token in ZIP container */
 function hasOoxmlMacros(buf) {
-    if (!isZipLike(buf))
+    if (!isZipLike$1(buf))
         return false;
     return hasAsciiToken(buf, 'vbaProject.bin');
 }
@@ -3237,6 +3128,116 @@ const CommonHeuristicsScanner = {
     }
 };
 
+const SIG_CEN = 0x02014b50;
+const DEFAULTS = {
+    maxEntries: 1000,
+    maxTotalUncompressedBytes: 500 * 1024 * 1024,
+    maxEntryNameLength: 255,
+    maxCompressionRatio: 1000,
+    eocdSearchWindow: 70000,
+};
+function r16(buf, off) {
+    return buf.readUInt16LE(off);
+}
+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) {
+    const sig = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
+    const start = Math.max(0, buf.length - window);
+    const idx = buf.lastIndexOf(sig, Math.min(buf.length - sig.length, buf.length - 1));
+    return idx >= start ? idx : -1;
+}
+function hasTraversal(name) {
+    return name.includes('../') || name.includes('..\\') || name.startsWith('/') || /^[A-Za-z]:/.test(name);
+}
+function createZipBombGuard(opts = {}) {
+    const cfg = { ...DEFAULTS, ...opts };
+    return {
+        async scan(input) {
+            const buf = Buffer.from(input);
+            const matches = [];
+            if (!isZipLike(buf))
+                return matches;
+            // Find EOCD near the end
+            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
+            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);
+                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;
+                if (nameEnd > buf.length)
+                    break;
+                const name = buf.toString('utf8', nameStart, nameEnd);
+                sumComp += compSize;
+                sumUnc += uncSize;
+                seen++;
+                if (name.length > cfg.maxEntryNameLength) {
+                    matches.push({ rule: 'zip_entry_name_too_long', severity: 'medium', meta: { name, length: name.length } });
+                }
+                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 } });
+            }
+            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 } });
+                }
+            }
+            return matches;
+        }
+    };
+}
+
 const MB = 1024 * 1024;
 const DEFAULT_POLICY = {
     includeExtensions: ['zip', 'png', 'jpg', 'jpeg', 'pdf'],