pompelmi 0.29.0 → 0.30.0

package/README.md

@@ -34,11 +34,8 @@
   <br/>
   <a href="https://www.producthunt.com/products/pompelmi"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1010722&theme=light" alt="pompelmi - Secure File Upload Scanning for Node.js | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></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>
-  <a href="https://nodeweekly.com/issues/594"><img alt="Featured in Node Weekly #594" src="https://img.shields.io/badge/featured-Node%20Weekly%20%23594-FF6600?logo=node.js"></a>
-  <a href="https://bytes.dev/archives/429"><img alt="Featured in Bytes #429" src="https://img.shields.io/badge/featured-Bytes%20%23429-111111"></a>
-  <a href="https://app.daily.dev/posts/pompelmi"><img alt="Featured on daily.dev" src="https://img.shields.io/badge/featured-daily.dev-CE3DF3?logo=dailydotdev"></a>
-  <a href="https://dev.to/sonotommy/secure-nodejs-file-uploads-in-minutes-with-pompelmi-3jfe"><img alt="Featured on DEV.to" src="https://img.shields.io/badge/featured-DEV.to-0A0A0A?logo=devdotto"></a>
+  <a href="https://www.helpnetsecurity.com/2026/02/02/pompelmi-open-source-secure-file-upload-scanning-node-js/"><img alt="Featured on HelpNet Security" src="https://img.shields.io/badge/🔒_FEATURED-HelpNet%20Security-FF6B35?style=for-the-badge"></a>
+  <a href="https://snyk.io/test/github/pompelmi/pompelmi"><img alt="Secured by Snyk" src="https://img.shields.io/badge/🛡️_SECURED_BY-Snyk-4C4A73?style=for-the-badge&logo=snyk"></a>
   <br/>
   <a href="https://github.com/sorrycc/awesome-javascript"><img alt="Mentioned in Awesome JavaScript" src="https://awesome.re/mentioned-badge.svg"></a>
   <a href="https://github.com/dzharii/awesome-typescript"><img alt="Mentioned in Awesome TypeScript" src="https://awesome.re/mentioned-badge-flat.svg"></a>
@@ -58,13 +55,11 @@
 </p>
 
 <p align="center">
-  Scan files before they hit disk • Keep user data private • Zero cloud dependencies
+  Scan files before they hit disk • <strong>Keep user data private</strong> • <strong>Zero cloud dependencies</strong>
 </p>
 
 ---
 
----
-
 <!-- Badges Section -->
 <p align="center">
   <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm version" src="https://img.shields.io/npm/v/pompelmi?label=version&color=0a7ea4&logo=npm"></a>
@@ -108,7 +103,7 @@
 
 ## 🎬 Demo
 
-> *(Demo GIF coming soon — showing Express + pompelmi scanning a file upload)*
+![Pompelmi Demo](./assets/malware-detection-node-demo.gif)
 
 **Want to try it now?** Check out our [live examples](./examples/) or install and run locally:
 
@@ -122,8 +117,8 @@ npm i pompelmi @pompelmi/express-middleware
 
 **pompelmi** provides enterprise-grade file scanning for Node.js applications:
 
-- **🔒 Privacy-First Architecture** — All scanning happens in-process. No cloud calls, no data leaks. Your files never leave your infrastructure.
-- **⚡ Lightning Fast** — In-process scanning with zero network latency. Configurable concurrency for high-throughput scenarios.
+- **🔒 Privacy-First Architecture** — All scanning happens in-process. **No cloud calls, no data leaks.** Your files never leave your infrastructure.
+- **⚡ Lightning Fast** — In-process scanning with **zero network latency**. Configurable concurrency for high-throughput scenarios.
 - **🧩 Composable Scanners** — Mix heuristics + signatures; set `stopOn` and timeouts. Bring your own YARA rules.
 - **📦 Deep ZIP Inspection** — Traversal/bomb guards, polyglot & macro hints, nested archive scanning with configurable depth limits.
 - **🔌 Framework Adapters** — Drop-in middleware for Express, Koa, Fastify, Next.js, Nuxt/Nitro, and **NestJS** with first-class TypeScript support.
@@ -135,28 +130,75 @@ npm i pompelmi @pompelmi/express-middleware
 
 ---
 
+## ⚡ Quick Start
+
+Get secure file upload scanning running in **under 5 minutes**.
+
+### Express Integration
+
+```ts
+import express from 'express';
+import multer from 'multer';
+import { createUploadGuard } from '@pompelmi/express-middleware';
+import { CommonHeuristicsScanner, createZipBombGuard, composeScanners } from 'pompelmi';
+
+const app = express();
+const upload = multer({ storage: multer.memoryStorage() });
+
+// Configure your security policy
+const scanner = composeScanners(
+  [
+    ['zipGuard', createZipBombGuard({ maxEntries: 512, maxCompressionRatio: 12 })],
+    ['heuristics', CommonHeuristicsScanner],
+  ],
+  { parallel: false, stopOn: 'suspicious', timeoutMsPerScanner: 1500 }
+);
+
+app.post('/upload',
+  upload.single('file'),
+  createUploadGuard({
+    includeExtensions: ['pdf', 'zip', 'png', 'jpg'],
+    allowedMimeTypes: ['application/pdf', 'application/zip', 'image/png', 'image/jpeg'],
+    maxFileSizeBytes: 20 * 1024 * 1024, // 20MB
+    scanner,
+    failClosed: true
+  }),
+  (req, res) => {
+    // File is safe - proceed with your logic
+    res.json({ success: true, message: 'File uploaded successfully' });
+  }
+);
+
+app.listen(3000, () => console.log('🚀 Server running on http://localhost:3000'));
+```
+
+**Test it:**
+```bash
+curl -X POST http://localhost:3000/upload -F "file=@test.pdf"
+```
+
+✅ **Done!** Your app now blocks malicious uploads before they hit disk.
+
+👉 **[Explore full documentation →](https://pompelmi.github.io/pompelmi/)** | **[See more examples →](./examples/)**
+
+---
+
 ## Table of Contents
 
-- [Overview](#overview)
-- [Highlights](#highlights)
+- [Features](#features)
+- [Quick Start](#quick-start)
 - [Why pompelmi](#why-pompelmi)
-- [How it compares](#how-it-compares)
-- [What Developers Say](#what-developers-say)
-- [What Makes pompelmi Special](#what-makes-pompelmi-special)
 - [Use Cases](#use-cases)
 - [Installation](#installation)
-- [Quick Start](#quick-start)
-  - [Minimal Node usage](#minimal-node-usage)
-  - [Express](#express)
-  - [Koa](#koa)
-  - [Next.js (App Router)](#nextjs-app-router)
+- [Getting Started](#getting-started)
+- [Code Examples](#code-examples)
 - [Adapters](#adapters)
 - [GitHub Action](#github-action)
 - [Configuration](#configuration)
 - [YARA Getting Started](#yara-getting-started)
 - [Security Notes](#security-notes)
-
-- [Testing & Development](#testing--development)
+- [Production Checklist](#production-checklist)
+- [Community & Recognition](#community--recognition)
 - [FAQ](#faq)
 - [Contributing](#contributing)
 - [License](#license)
@@ -182,55 +224,11 @@ pompelmi documentation is available in multiple languages to help developers wor
 
 ---
 
-## 🚀 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.
-
-### 🎯 Key Features
-
-**🔒 Private by design** — no outbound calls; bytes never leave your process
-
-**🧩 Composable scanners** — mix heuristics + signatures; set `stopOn` and timeouts
-
-**📦 ZIP hardening** — traversal/bomb guards, polyglot & macro hints
-
-**🔌 Drop-in adapters** — Express, Koa, Fastify, Next.js, Nuxt/Nitro, **NestJS**
-
-**🌊 Stream-based scanning** — memory-efficient processing with configurable buffer limits
-
-**⚙️ CLI for CI/CD** — standalone command-line tool for scanning files and directories
-
-**🔍 Polyglot detection** — advanced magic bytes analysis and embedded script detection
-
-**📘 Typed & tiny** — modern TS, minimal surface, tree-shakeable
-
-**⚡ Zero dependencies** — core library has minimal deps, fast installation
-
-## ✨ 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.
-
-**🔍 Built‑in scanners** — drop‑in **CommonHeuristicsScanner** (PDF risky actions, Office macros, PE header) and **Zip‑bomb Guard**; add your own or YARA via a tiny `{ scan(bytes) }` contract.
-
-**🔬 Polyglot & embedded script detection** — advanced magic bytes analysis detects mixed-format files and embedded scripts with **30+ file signatures**.
-
-**🌊 Memory-efficient streaming** — scan large files without loading them entirely into memory with automatic stream routing.
-
-**⚙️ Compose scanning** — run multiple scanners in parallel or sequentially with timeouts and short‑circuiting via `composeScanners()`.
-
-**🏗️ Framework integrations** — native modules for **NestJS**, Express, Koa, Next.js, Nuxt/Nitro, and Fastify with first-class TypeScript support.
-
-**🔧 Production-ready CLI** — standalone tool for CI/CD pipelines with watch mode, multiple output formats (JSON, table, minimal).
-
-**☁️ Zero cloud** — scans run in‑process. Keep bytes private. Perfect for GDPR/HIPAA compliance.
-
-**👨‍💻 DX first** — TypeScript types, ESM/CJS builds, tiny API, adapters for popular web frameworks.
+## 🧠 Why pompelmi?
 
-> **SEO Keywords:** file upload security, malware detection, virus scanner, Node.js security, Express middleware, YARA integration, ZIP bomb protection, file validation, upload sanitization, threat detection, security scanner, antivirus Node.js, file scanning library, TypeScript security, Next.js security, Nuxt security, Nitro security, Koa middleware, server-side validation, file integrity check, malware prevention, secure file upload
+pompelmi delivers **Privacy-First** malware detection with **Zero Cloud Dependencies** — keeping your data secure and your latency zero.
 
-## 🧠 Why pompelmi?
+### Why Choose Pompelmi?
 
 - **On‑device, private scanning** – no outbound calls, no data sharing.
 - **Blocks early** – runs _before_ you write to disk or persist anything.
@@ -244,45 +242,25 @@ pompelmi documentation is available in multiple languages to help developers wor
 - Apps that need predictable, low‑latency decisions inline.
 - Developers who want simple, typed building blocks instead of a daemon.
 
-## 🔍 How it compares
-
-| Capability | pompelmi | ClamAV / node‑clam | Cloud AV APIs |
-| --- | --- | --- | --- |
-| Runs fully in‑process | ✅ | ❌ (separate daemon) | ❌ (network calls) |
-| Bytes stay private | ✅ | ✅ | ❌ |
-| Deep ZIP limits & MIME sniff | ✅ | ✅ (archive scan) | ❓ varies |
-| YARA integration | ✅ optional | ❌* | ❓ varies |
-| Framework adapters | ✅ Express/Koa/Next.js | ❌ | ❌ |
-| Works in CI on artifacts | ✅ | ✅ | ❓ varies |
-| Licensing | MIT | GPL (engine) | Proprietary |
-
-\* You can run YARA alongside ClamAV, but it’s not built‑in.
-
----
-## 💬 What Developers Say
-
-> "pompelmi made it incredibly easy to add malware scanning to our Express API. The TypeScript support is fantastic!"
-> — Developer using pompelmi in production
-
-> "Finally, a file scanning solution that doesn't require sending our users' data to third parties. Perfect for GDPR compliance."
-> — Security Engineer at a healthcare startup
-
-> "The YARA integration is seamless. We went from prototype to production in less than a week."
-> — DevSecOps Engineer
-
-_Want to share your experience? [Open a discussion](https://github.com/pompelmi/pompelmi/discussions)!_
-
----
+### Comparison Table
 
-## 🌟 What Makes pompelmi Special?
+| Feature | **Pompelmi** | ClamAV | Cloud APIs (VirusTotal, etc.) |
+|---------|-------------|---------|-------------------------------|
+| **Setup Time** | ⚡ Seconds (`npm install`) | ⏱️ Complex (daemon setup) | ⏱️ API keys + integration |
+| **Privacy** | ✅ **In-process** (data never leaves) | ✅ Local (separate daemon) | ❌ **External** (data sent to cloud) |
+| **Latency** | ⚡ **Zero** (no network calls) | 🔄 IPC overhead | 🌐 **High** (network roundtrip) |
+| **Cost** | 💰 **Free** (MIT license) | 💰 Free (GPL) | 💸 **Pay-per-scan** |
+| **Framework Integration** | ✅ Express, Koa, Next.js, NestJS | ❌ Manual integration | ❌ Manual integration |
+| **TypeScript Support** | ✅ First-class | ❌ Community types | ❓ Varies |
+| **YARA Integration** | ✅ Built-in | ⚙️ Manual setup | ❓ Limited |
 
 ### 🎯 Developer Experience
 
-Built with developers in mind from day one. Simple API, comprehensive TypeScript types, and excellent documentation mean you can integrate secure file scanning in minutes, not days. Hot module replacement support and detailed error messages make debugging a breeze.
+Built with developers in mind from day one. Simple API, comprehensive TypeScript types, and excellent documentation mean you can integrate secure file scanning in minutes, not days.
 
 ### 🚀 Performance First
 
-Optimized for high-throughput scenarios with configurable concurrency, streaming support, and minimal memory overhead. Process thousands of files without breaking a sweat. Scans run in-process with no IPC overhead.
+Optimized for high-throughput scenarios with configurable concurrency, streaming support, and minimal memory overhead. Scans run in-process with no IPC overhead.
 
 ### 🔐 Security Without Compromise
 
@@ -320,8 +298,6 @@ Validate user-generated content uploads (images, videos, documents) before proce
 
 ---
 
----
-
 ## 📦 Installation
 
 **pompelmi** is a privacy-first Node.js library for local file scanning.
@@ -719,18 +695,7 @@ Use the adapter that matches your web framework. All adapters share the same pol
 
 See the [📘 Code Examples](#-code-examples) section above for integration examples.
 
----
-
-| Framework | Package | Status |
-| --- | --- | --- |
-| Express | `@pompelmi/express-middleware` | ✅ alpha |
-| Koa | `@pompelmi/koa-middleware` | ✅ alpha |
-| Next.js (App Router) | `@pompelmi/next-upload` | ✅ alpha |
-| Fastify | `@pompelmi/fastify-plugin` | 🚧 alpha |
-| NestJS | nestjs | 📋 planned |
-| Remix | remix | 📋 planned |
-| hapi | hapi plugin | 📋 planned |
-| SvelteKit | sveltekit | 📋 planned |
+👉 **[View adapter documentation →](https://pompelmi.github.io/pompelmi/)** | **[Browse all examples →](./examples/)**
 
 ---
 
@@ -1057,39 +1022,105 @@ You should see an HTTP **422 Unprocessable Entity** (blocked by policy). Clean f
 
 ---
 
-##  Releases & security
+##  Releases & Security
 
 - **Changelog / releases:** see [GitHub Releases](https://github.com/pompelmi/pompelmi/releases).
 - **Security disclosures:** please use [GitHub Security Advisories](https://github.com/pompelmi/pompelmi/security/advisories). We’ll coordinate a fix before public disclosure.
 - **Production users:** open a [Discussion](https://github.com/pompelmi/pompelmi/discussions) to share requirements or request adapters.
 
-## ⭐ Star history
+---
 
-[![Star History Chart](https://api.star-history.com/svg?repos=pompelmi/pompelmi&type=Date)](https://star-history.com/#pompelmi/pompelmi&Date)
+## 🏆 Community & Recognition
 
----
+pompelmi has been featured in **leading security and developer publications** and is trusted by teams worldwide for secure file upload handling.
 
----
+### 🌟 Featured In High-Authority Publications
 
-## 🏆 Community & Recognition
+<table>
+<tr>
+<td align="center" width="200">
+  <a href="https://www.helpnetsecurity.com/2026/02/02/pompelmi-open-source-secure-file-upload-scanning-node-js/">
+    <img src="https://img.shields.io/badge/🔒-HelpNet%20Security-FF6B35?style=for-the-badge" alt="HelpNet Security"/>
+  </a>
+  <br/>
+  <strong>HelpNet Security</strong>
+  <br/>
+  <em>Leading Cybersecurity News</em>
+</td>
+<td align="center" width="200">
+  <a href="https://snyk.io/test/github/pompelmi/pompelmi">
+    <img src="https://img.shields.io/badge/🛡️-Snyk-4C4A73?style=for-the-badge&logo=snyk" alt="Snyk"/>
+  </a>
+  <br/>
+  <strong>Snyk</strong>
+  <br/>
+  <em>Security Verified</em>
+</td>
+<td align="center" width="200">
+  <a href="https://www.detectionengineering.net/p/det-eng-weekly-issue-124-the-defcon">
+    <img src="https://img.shields.io/badge/📡-Detection%20Engineering-0A84FF?style=for-the-badge&logo=substack" alt="Detection Engineering"/>
+  </a>
+  <br/>
+  <strong>Detection Engineering Weekly</strong>
+  <br/>
+  <em>Issue #124</em>
+</td>
+</tr>
+<tr>
+<td align="center" width="200">
+  <a href="https://nodeweekly.com/issues/594">
+    <img src="https://img.shields.io/badge/⚡-Node%20Weekly-FF6600?style=for-the-badge&logo=node.js" alt="Node Weekly"/>
+  </a>
+  <br/>
+  <strong>Node Weekly</strong>
+  <br/>
+  <em>Issue #594</em>
+</td>
+<td align="center" width="200">
+  <a href="https://bytes.dev/archives/429">
+    <img src="https://img.shields.io/badge/📬-Bytes-111111?style=for-the-badge" alt="Bytes"/>
+  </a>
+  <br/>
+  <strong>Bytes Newsletter</strong>
+  <br/>
+  <em>Issue #429</em>
+</td>
+<td align="center" width="200">
+  <a href="https://app.daily.dev/posts/pompelmi">
+    <img src="https://img.shields.io/badge/📰-daily.dev-CE3DF3?style=for-the-badge&logo=dailydotdev" alt="daily.dev"/>
+  </a>
+  <br/>
+  <strong>daily.dev</strong>
+  <br/>
+  <em>Featured Article</em>
+</td>
+</tr>
+</table>
 
-pompelmi has been featured in leading developer publications and is trusted by teams worldwide for secure file upload handling.
+### 🎖️ Mentioned In Awesome Lists
 
 <p align="center">
-  <img src="https://img.shields.io/badge/Featured%20in-Detection%20Engineering%20Weekly-0A84FF?style=for-the-badge&logo=substack" alt="Detection Engineering">
-  <img src="https://img.shields.io/badge/Featured%20in-Node%20Weekly-FF6600?style=for-the-badge&logo=node.js" alt="Node Weekly">
-  <img src="https://img.shields.io/badge/Featured%20in-Bytes-111111?style=for-the-badge" alt="Bytes">
+  <a href="https://github.com/sorrycc/awesome-javascript"><img src="https://awesome.re/mentioned-badge.svg" alt="Awesome JavaScript"/></a>
+  <a href="https://github.com/dzharii/awesome-typescript"><img src="https://awesome.re/mentioned-badge.svg" alt="Awesome TypeScript"/></a>
+  <a href="https://github.com/sbilly/awesome-security"><img src="https://awesome.re/mentioned-badge.svg" alt="Awesome Security"/></a>
+  <a href="https://github.com/sindresorhus/awesome-nodejs"><img src="https://awesome.re/mentioned-badge.svg" alt="Awesome Node.js"/></a>
 </p>
 
 <!-- MENTIONS:START -->
+<!-- MENTIONS:END -->
 
-## 🌟 Featured In
+### 💬 What Developers Say
 
-*Last updated: January 24, 2026*
+> "pompelmi made it incredibly easy to add malware scanning to our Express API. The TypeScript support is fantastic!"
+> — Developer using pompelmi in production
 
-*No mentions found yet. Run `npm run mentions:find` to discover mentions.*
+> "Finally, a file scanning solution that doesn't require sending our users' data to third parties. Perfect for GDPR compliance."
+> — Security Engineer at a healthcare startup
 
-<!-- MENTIONS:END -->
+> "The YARA integration is seamless. We went from prototype to production in less than a week."
+> — DevSecOps Engineer
+
+_Want to share your experience? [Open a discussion](https://github.com/pompelmi/pompelmi/discussions)!_
 
 ### 🤝 Community & Support
 
@@ -1113,16 +1144,6 @@ pompelmi has been featured in leading developer publications and is trusted by t
 
 ---
 
-## 📊 Star History
-
-<p align="center">
-  <a href="https://star-history.com/#pompelmi/pompelmi&Date">
-    <img src="https://api.star-history.com/svg?repos=pompelmi/pompelmi&type=Date" alt="Star History Chart" />
-  </a>
-</p>
-
----
-
 ## 🎖️ Contributors
 
 Thanks to all the amazing contributors who have helped make pompelmi better!
@@ -1139,6 +1160,16 @@ Thanks to all the amazing contributors who have helped make pompelmi better!
 
 ---
 
+## ⭐ Star History
+
+<p align="center">
+  <a href="https://star-history.com/#pompelmi/pompelmi&Date">
+    <img src="https://api.star-history.com/svg?repos=pompelmi/pompelmi&type=Date" alt="Star History Chart" width="600" />
+  </a>
+</p>
+
+---
+
 ## 💬 FAQ
 
 **Do I need YARA?**  
@@ -1192,25 +1223,9 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
 - [Examples](./examples/) — Real-world integration examples
 - [Security Guide](./SECURITY.md) — Security best practices and disclosure policy
 
-### 🎥 Tutorials & Articles
-
-- **File Upload Security in Node.js** — Best practices guide (coming soon)
-- **Integrating YARA with pompelmi** — Advanced detection setup (coming soon)
-- **Zero-Trust File Uploads** — Architecture patterns (coming soon)
-
 ### 🛠️ Tools & Integrations
 
 - [GitHub Action](https://github.com/pompelmi/pompelmi/tree/main/.github/actions/pompelmi-scan) — CI/CD scanning
-- [Docker Images](https://hub.docker.com/r/pompelmi/pompelmi) — Containerized scanning (coming soon)
-- [Cloud Functions](https://github.com/pompelmi/cloud-functions) — Serverless examples (coming soon)
-
----
-
-## 📊 Project Stats
-
-<p align="center">
-  <img src="https://repobeats.axiom.co/api/embed/YOUR_EMBED_ID.svg" alt="Repobeats analytics" />
-</p>
 
 ---
 
@@ -1224,19 +1239,6 @@ pompelmi stands on the shoulders of giants. Special thanks to:
 
 ---
 
-## 📞 Support
-
-Need help? We're here for you!
-
-- 📖 [Documentation](https://pompelmi.github.io/pompelmi/)
-- 💬 [GitHub Discussions](https://github.com/pompelmi/pompelmi/discussions)
-- 🐛 [Issue Tracker](https://github.com/pompelmi/pompelmi/issues)
-- 🔒 [Security](https://github.com/pompelmi/pompelmi/security) (for vulnerabilities)
-
-For commercial support and consulting, contact the maintainers.
-
----
-
 <p align="right"><a href="#pompelmi">↑ Back to top</a></p>
 
 ## 📜 License

package/dist/pompelmi.cjs

@@ -65,7 +65,7 @@ function createPresetScanner(preset, opts = {}) {
                     });
                     scanners.push(binjaScanner);
                 }).catch(() => {
-                    // Binary Ninja engine not available
+                    // Binary Ninja engine not available - silently skip
                 });
             }
             catch {
@@ -85,7 +85,7 @@ function createPresetScanner(preset, opts = {}) {
                     });
                     scanners.push(ghidraScanner);
                 }).catch(() => {
-                    // Ghidra engine not available
+                    // Ghidra engine not available - silently skip
                 });
             }
             catch {